@erclx/canon 5.66.0 → 5.68.0

package/src/take/encode.ts

@@ -0,0 +1,207 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+
+/**
+ * Joins a take's frames into an H.264 clip through the system FFmpeg. Canon
+ * ships no encoder, so FFmpeg is a setup step a target runs, and its absence is
+ * refused up front rather than after a take has been filmed.
+ */
+
+export class FfmpegMissing extends Error {}
+
+/** H.264 in yuv420p plays in every browser and editor HyperFrames reads from. */
+const OUTPUT = [
+  '-c:v',
+  'libx264',
+  '-preset',
+  'medium',
+  '-crf',
+  '16',
+  '-pix_fmt',
+  'yuv420p',
+  '-movflags',
+  '+faststart',
+]
+
+/** Resolves when `ffmpeg` runs, and throws `FfmpegMissing` when it does not. */
+export async function requireFfmpeg(): Promise<void> {
+  const proc = spawn('ffmpeg', ['-version'], { stdio: 'ignore' })
+  try {
+    await finished(proc)
+  } catch (error) {
+    throw new FfmpegMissing(
+      `ffmpeg did not run: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}
+
+export interface FrameEncoder {
+  /** Appends one JPEG frame, waiting while FFmpeg catches up. */
+  write(jpeg: Buffer): Promise<void>
+  /** Ends the stream and resolves once the clip is written. */
+  close(): Promise<void>
+  /** Stops FFmpeg and leaves whatever it wrote. */
+  abort(): void
+}
+
+/**
+ * Streams JPEG frames into one clip at `fps`, so a 4K take never lands on disk
+ * as a folder of stills.
+ */
+export function openFrameEncoder(out: string, fps: number): FrameEncoder {
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-y',
+      '-loglevel',
+      'error',
+      '-f',
+      'image2pipe',
+      '-framerate',
+      String(fps),
+      '-c:v',
+      'mjpeg',
+      '-i',
+      '-',
+      // A JPEG is full range and H.264 is read as TV range, so without this the
+      // levels pass through unscaled and a player crushes the blacks and whites.
+      '-vf',
+      'scale=in_range=full:out_range=tv',
+      ...OUTPUT,
+      out,
+    ],
+    { stdio: ['pipe', 'ignore', 'pipe'] },
+  )
+  const done = finished(proc)
+  // Held so a failure while frames are still being written surfaces at close
+  // rather than as an unhandled rejection.
+  done.catch(() => {})
+
+  return {
+    write: (jpeg) =>
+      new Promise((resolve, reject) => {
+        const stdin = proc.stdin
+        if (!stdin || stdin.destroyed) {
+          reject(new Error('ffmpeg stopped reading frames'))
+          return
+        }
+        if (stdin.write(jpeg)) resolve()
+        else stdin.once('drain', resolve)
+      }),
+    close: async () => {
+      proc.stdin?.end()
+      await done
+    },
+    abort: () => {
+      proc.kill('SIGKILL')
+    },
+  }
+}
+
+/** Re-encodes a recorded clip to the same H.264 output at a constant `fps`. */
+export async function transcode(
+  input: string,
+  out: string,
+  fps: number,
+): Promise<void> {
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-y',
+      '-loglevel',
+      'error',
+      '-i',
+      input,
+      '-r',
+      String(fps),
+      ...OUTPUT,
+      out,
+    ],
+    { stdio: ['ignore', 'ignore', 'pipe'] },
+  )
+  await finished(proc)
+}
+
+/**
+ * Counts a clip's frames, which a real-time take cannot know in advance and a
+ * camera track has to match one for one.
+ */
+export async function probeFrames(clip: string): Promise<number> {
+  const proc = spawn(
+    'ffprobe',
+    [
+      '-v',
+      'error',
+      '-select_streams',
+      'v:0',
+      '-count_packets',
+      '-show_entries',
+      'stream=nb_read_packets',
+      '-of',
+      'csv=p=0',
+      clip,
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+  let stdout = ''
+  proc.stdout?.on('data', (chunk: Buffer) => {
+    stdout += chunk.toString()
+  })
+  await finished(proc)
+  const frames = Number.parseInt(stdout.trim(), 10)
+  if (!Number.isFinite(frames)) {
+    throw new Error(`ffprobe read no frame count from ${clip}`)
+  }
+  return frames
+}
+
+/**
+ * Reads the clip's closing frame as one JPEG. It selects the frame by index
+ * rather than seeking from the end, since a seek lands on whichever frame
+ * the container's timing puts nearest, which was measured missing the last.
+ */
+export async function lastFrame(clip: string, frames: number): Promise<Buffer> {
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-v',
+      'error',
+      '-i',
+      clip,
+      '-vf',
+      `select=eq(n\\,${frames - 1})`,
+      '-frames:v',
+      '1',
+      '-q:v',
+      '2',
+      '-f',
+      'image2pipe',
+      '-c:v',
+      'mjpeg',
+      '-',
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+  const chunks: Buffer[] = []
+  proc.stdout?.on('data', (chunk: Buffer) => chunks.push(chunk))
+  await finished(proc)
+  const jpeg = Buffer.concat(chunks)
+  if (jpeg.length === 0) {
+    throw new Error(`ffmpeg read no frame ${frames - 1} from ${clip}`)
+  }
+  return jpeg
+}
+
+export function finished(proc: ChildProcess): Promise<void> {
+  let stderr = ''
+  proc.stderr?.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString()
+  })
+  return new Promise((resolve, reject) => {
+    proc.on('error', reject)
+    proc.on('close', (code) => {
+      if (code === 0) resolve()
+      else
+        reject(new Error(`ffmpeg exited ${code}: ${stderr.trim().slice(-400)}`))
+    })
+  })
+}

package/src/take/film.ts

@@ -0,0 +1,211 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { isBrowserMissing, isServerUnreachable } from '@/browser/engine'
+import { cameraTrack } from '@/take/camera'
+import { FfmpegMissing, requireFfmpeg } from '@/take/encode'
+import {
+  FPS,
+  LOG_VERSION,
+  type LogEvent,
+  type TakeLog,
+  VIEWPORT,
+} from '@/take/log'
+import { TargetMissing } from '@/take/perform'
+import type { Beat, Route, TakePlan } from '@/take/plan'
+import { filmScreencast } from '@/take/screencast'
+import { ShellMissing, findShell } from '@/take/shell'
+import { StepperStalled, filmStepped } from '@/take/stepper'
+
+/**
+ * Films every beat of a plan into its own folder and writes the record the
+ * edit reads. Each beat opens the page fresh, so a beat starts from the state
+ * its setup reaches rather than wherever the last one left the page.
+ */
+
+export const TAKE_VERSION = 1
+
+export type TakeRefusal =
+  | 'ffmpeg-missing'
+  | 'browser-missing'
+  | 'server-unreachable'
+  | 'target-missing'
+  | 'take-failed'
+
+export interface FilmedBeat {
+  readonly name: string
+  /** The beat's folder, relative to the take's. */
+  readonly dir: string
+  readonly requested: Route
+  readonly route: Route
+  /** Why a `step` beat was filmed by screencast instead, when it was. */
+  readonly fallback?: string
+  readonly frames: number
+  readonly seconds: number
+  readonly clip: string
+  readonly log: string
+  readonly camera: string
+  /** The clip's closing frame, as a JPEG. */
+  readonly still: string
+}
+
+export type TakeResult =
+  | {
+      readonly status: 'filmed'
+      readonly out: string
+      readonly beats: readonly FilmedBeat[]
+      readonly durationMs: number
+    }
+  | {
+      readonly status: 'failed'
+      readonly reason: TakeRefusal
+      readonly message: string
+      readonly beat?: string
+    }
+
+export interface TakeRequest {
+  readonly url: string
+  readonly plan: TakePlan
+  readonly out: string
+  readonly env?: NodeJS.ProcessEnv
+}
+
+const REACH_TIMEOUT_MS = 5000
+
+export async function take(request: TakeRequest): Promise<TakeResult> {
+  const started = Date.now()
+  const out = resolve(request.out)
+
+  try {
+    await requireFfmpeg()
+  } catch (error) {
+    if (error instanceof FfmpegMissing) return failed('ffmpeg-missing', error)
+    throw error
+  }
+
+  let executable = ''
+  if (request.plan.beats.some((beat) => beat.route === 'step')) {
+    try {
+      executable = findShell(request.env)
+    } catch (error) {
+      if (error instanceof ShellMissing) return failed('browser-missing', error)
+      throw error
+    }
+  }
+
+  // Probes the origin rather than the address, since an address can carry a
+  // single-use ticket that a probe would spend before the browser opens it.
+  try {
+    await fetch(new URL(request.url).origin, {
+      signal: AbortSignal.timeout(REACH_TIMEOUT_MS),
+    })
+  } catch (error) {
+    return failed('server-unreachable', error)
+  }
+
+  mkdirSync(out, { recursive: true })
+  const beats: FilmedBeat[] = []
+  for (const [index, beat] of request.plan.beats.entries()) {
+    const dir = `${String(index + 1).padStart(2, '0')}-${slug(beat.name)}`
+    mkdirSync(join(out, dir), { recursive: true })
+    try {
+      beats.push(await filmBeat(request.url, beat, out, dir, executable))
+    } catch (error) {
+      return failed(classify(error), error, beat.name)
+    }
+  }
+
+  writeFileSync(
+    join(out, 'take.json'),
+    `${JSON.stringify({ version: TAKE_VERSION, url: request.url, beats }, null, 2)}\n`,
+  )
+  return { status: 'filmed', out, beats, durationMs: Date.now() - started }
+}
+
+async function filmBeat(
+  url: string,
+  beat: Beat,
+  out: string,
+  dir: string,
+  executable: string,
+): Promise<FilmedBeat> {
+  const clip = join(dir, 'clip.mp4')
+  const target = join(out, clip)
+
+  let route: Route = beat.route
+  let fallback: string | undefined
+  let filmed: { frames: number; events: readonly LogEvent[]; still: Buffer }
+  if (beat.route === 'step') {
+    try {
+      filmed = await filmStepped({ executable, url, beat, clip: target })
+    } catch (error) {
+      if (!(error instanceof StepperStalled)) throw error
+      route = 'screencast'
+      fallback = error.message
+      filmed = await filmScreencast({ url, beat, clip: target })
+    }
+  } else {
+    filmed = await filmScreencast({ url, beat, clip: target })
+  }
+
+  const log: TakeLog = {
+    version: LOG_VERSION,
+    viewport: VIEWPORT,
+    fps: FPS,
+    route,
+    frames: filmed.frames,
+    events: filmed.events,
+  }
+  const logPath = join(dir, 'log.json')
+  writeFileSync(join(out, logPath), `${JSON.stringify(log, null, 2)}\n`)
+  // One line, since it carries a row per frame and nobody reads it by eye.
+  const cameraPath = join(dir, 'camera.json')
+  writeFileSync(join(out, cameraPath), `${JSON.stringify(cameraTrack(log))}\n`)
+  const stillPath = join(dir, 'still.jpg')
+  writeFileSync(join(out, stillPath), filmed.still)
+
+  return {
+    name: beat.name,
+    dir,
+    requested: beat.route,
+    route,
+    ...(fallback ? { fallback } : {}),
+    frames: filmed.frames,
+    seconds: Number((filmed.frames / FPS).toFixed(2)),
+    clip,
+    log: logPath,
+    camera: cameraPath,
+    still: stillPath,
+  }
+}
+
+function classify(error: unknown): TakeRefusal {
+  if (error instanceof TargetMissing) return 'target-missing'
+  if (error instanceof ShellMissing || isBrowserMissing(error)) {
+    return 'browser-missing'
+  }
+  if (isServerUnreachable(error)) return 'server-unreachable'
+  return 'take-failed'
+}
+
+function failed(
+  reason: TakeRefusal,
+  error: unknown,
+  beat?: string,
+): TakeResult {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+    ...(beat ? { beat } : {}),
+  }
+}
+
+function slug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '')
+      .slice(0, 40) || 'beat'
+  )
+}

package/src/take/fixtures/fade.html

@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Fade</title>
+    <!--
+      A band that fades from black to white over exactly one second of page
+      time once the button is pressed, so its brightness frame by frame reads
+      how much page time each frame of a take advanced.
+    -->
+    <style>
+      body {
+        margin: 0;
+        background: #808080;
+      }
+
+      #go {
+        position: absolute;
+        left: 100px;
+        top: 100px;
+        width: 200px;
+        height: 60px;
+      }
+
+      #band {
+        position: absolute;
+        left: 0;
+        top: 300px;
+        width: 1920px;
+        height: 780px;
+        background-color: #000;
+        transition: background-color 1000ms linear;
+      }
+
+      #band.lit {
+        background-color: #fff;
+      }
+    </style>
+  </head>
+  <body>
+    <button id="go">Go</button>
+    <div id="band"></div>
+    <script>
+      document.getElementById('go').addEventListener('click', () => {
+        document.getElementById('band').classList.add('lit')
+      })
+    </script>
+  </body>
+</html>

package/src/take/fixtures/fetch.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Fetch</title>
+    <!--
+      A button whose press starts a fetch the server answers slowly, the way
+      a page switch in an app loads what the next view shows. A take must keep
+      stepping frames while the fetch is in flight.
+    -->
+    <style>
+      body {
+        margin: 0;
+        background: #808080;
+      }
+
+      #go {
+        position: absolute;
+        left: 100px;
+        top: 100px;
+        width: 200px;
+        height: 60px;
+      }
+    </style>
+  </head>
+  <body>
+    <button id="go">Load</button>
+    <p id="status">idle</p>
+    <script>
+      document.getElementById('go').addEventListener('click', () => {
+        document.getElementById('status').textContent = 'loading'
+        fetch('/slow').then(() => {
+          document.getElementById('status').textContent = 'loaded'
+        })
+      })
+    </script>
+  </body>
+</html>

package/src/take/log.ts

@@ -0,0 +1,109 @@
+import type { Route } from '@/take/plan'
+
+/**
+ * The click log a take writes beside its clip, and the pointer path both
+ * capture routes move along and the camera reads back. Every coordinate is in
+ * CSS pixels of the page, and every time is in milliseconds on the clip's own
+ * clock, so frame `n` sits at `n * 1000 / FPS` whatever route filmed it.
+ *
+ * The path lives here rather than in a capture route because the edit draws the
+ * cursor from this log, so the route moving the real pointer and the reader
+ * redrawing it have to agree on one curve.
+ */
+
+export const LOG_VERSION = 1
+
+export const FPS = 60
+
+/** The page a take films, in CSS pixels. The stepper renders it at twice this. */
+export const VIEWPORT = { width: 1920, height: 1080 } as const
+
+export interface Point {
+  readonly x: number
+  readonly y: number
+}
+
+export interface Box {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+export type LogEvent =
+  | {
+      readonly t: number
+      readonly kind: 'move'
+      readonly from: Point
+      readonly to: Point
+      readonly ms: number
+    }
+  | {
+      readonly t: number
+      readonly kind: 'click'
+      readonly at: Point
+      readonly box: Box
+    }
+  | {
+      readonly t: number
+      readonly kind: 'type'
+      readonly at: Point
+      readonly box: Box
+      readonly chars: number
+      /** From the first key to the last, so the camera holds for the burst. */
+      readonly ms: number
+    }
+  | {
+      readonly t: number
+      readonly kind: 'scroll'
+      readonly at: Point
+      readonly dx: number
+      readonly dy: number
+      readonly ms: number
+    }
+
+export interface TakeLog {
+  readonly version: typeof LOG_VERSION
+  readonly viewport: { readonly width: number; readonly height: number }
+  readonly fps: number
+  /** The route that filmed the clip, which can differ from the one asked for. */
+  readonly route: Route
+  readonly frames: number
+  readonly events: readonly LogEvent[]
+}
+
+/** Where the pointer rests before a take's first move. */
+export const START: Point = { x: VIEWPORT.width / 2, y: VIEWPORT.height / 2 }
+
+/**
+ * How long the pointer takes to travel, slower for longer reaches and never so
+ * quick that a viewer loses it. Carried over from the groundwork takes the
+ * camera presets were judged on.
+ */
+export function travelMs(from: Point, to: Point): number {
+  return Math.min(
+    1200,
+    Math.max(300, Math.hypot(to.x - from.x, to.y - from.y) * 0.9),
+  )
+}
+
+export function easeInOutCubic(t: number): number {
+  const x = Math.max(0, Math.min(1, t))
+  return x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2
+}
+
+export function along(from: Point, to: Point, progress: number): Point {
+  const k = easeInOutCubic(progress)
+  return { x: from.x + (to.x - from.x) * k, y: from.y + (to.y - from.y) * k }
+}
+
+/** The pointer's position at a time on the clip's clock, read off the moves. */
+export function cursorAt(events: readonly LogEvent[], ms: number): Point {
+  let position = START
+  for (const event of events) {
+    if (event.kind !== 'move') continue
+    if (ms < event.t) break
+    position = along(event.from, event.to, (ms - event.t) / event.ms)
+  }
+  return position
+}