@outerlayer/cli 0.34.0-next.20261026184303 → 0.34.0-next.20261026214534

package/dist/{chunk-ELO5XEES.js → chunk-K3ACC2CV.js}

@@ -1,23 +1,25 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import { readNewestDemo } from './chunk-ER6KQCVJ.js';
-import { runEmitArtifact } from './chunk-XL2MPORM.js';
+import { runEmitArtifact } from './chunk-QWXBWOVV.js';
 import { VoiceDownloadError, downloadPinned, sha256OfFile } from './chunk-2PGI6RDE.js';
+import { compareVersions } from './chunk-TQMI335S.js';
 import { VOICE_PACK_FILES, VOICE_PACK_VERSION } from './chunk-4UPET3R7.js';
 import { detectActiveSession } from './chunk-IP7BIBXJ.js';
-import { autoConnect } from './chunk-IO2BBKG4.js';
+import { autoConnect } from './chunk-OKGHWCSK.js';
 import { C } from './chunk-ANPNT6PM.js';
 import { defaultFetch, resolveGatewayCredentials } from './chunk-7QAJQDHS.js';
-import { resolveRepoIdentity } from './chunk-Z7WMU3RA.js';
+import { resolveRepoIdentity } from './chunk-OOD5NDQA.js';
+import { resolvePackageVersion } from './chunk-RA3O54FC.js';
 import { launchedItemForSession } from './chunk-T2Q7ISPE.js';
-import { ARTIFACT_MAX_BYTES, ARTIFACT_MAX_CAPTION_LENGTH, DEMO_RECORD_MEDIA_TYPE, ARTIFACT_MAX_REPLACES_TARGETS, DemoManifestSchema, ARTIFACT_KINDS } from './chunk-EOTMDIYC.js';
+import { ARTIFACT_MAX_BYTES, ARTIFACT_MAX_CAPTION_LENGTH, DEMO_RECORD_MEDIA_TYPE, ARTIFACT_MAX_REPLACES_TARGETS, DEMO_MANIFEST_LATEST_VERSION, DemoManifestSchema, ARTIFACT_KINDS } from './chunk-DINRXUQA.js';
 import { homeFromEnv } from './chunk-VNVZDWO3.js';
 import { __commonJS, __require, __toESM } from './chunk-Z5GEFMRW.js';
 import { createHash } from 'crypto';
-import { mkdtempSync, writeFileSync, statSync, readFileSync, rmSync, mkdirSync, accessSync, constants, realpathSync, existsSync, createReadStream, createWriteStream } from 'fs';
+import { mkdtempSync, writeFileSync, statSync, readFileSync, rmSync, mkdirSync, existsSync, copyFileSync, realpathSync, accessSync, constants, createReadStream, createWriteStream } from 'fs';
 import { tmpdir } from 'os';
 import { resolve, dirname, join, relative, sep, isAbsolute, delimiter, normalize } from 'path';
-import { execFileSync } from 'child_process';
+import { execFileSync, spawn } from 'child_process';
 import { createRequire as createRequire$1 } from 'module';
 import { createGunzip } from 'zlib';
 
@@ -2286,8 +2288,154 @@ function missingProgramMessage(name, narrated) {
   const base = `install ${hint}, then run the command again`;
   return name === "espeak-ng" && narrated ? `espeak-ng is not on PATH \u2014 ${base}, or pass --no-narration to store the clips without speech` : `${name} is not on PATH \u2014 ${base}`;
 }
+var MOTION_FPS = 10;
+var WIDTH = 320;
+var HEIGHT = 200;
+var PIXEL_STEP = 8;
+var MOVING_PIXELS = 3;
+function changedPixels(a, b) {
+  let changed = 0;
+  for (let index = 0; index < a.length; index++) if (Math.abs(a[index] - b[index]) > PIXEL_STEP) changed++;
+  return changed;
+}
+async function readMotion(frames, size = WIDTH * HEIGHT) {
+  const moving = [];
+  let previous;
+  let pending = Buffer.alloc(0);
+  for await (const chunk of frames) {
+    pending = Buffer.concat([pending, chunk]);
+    while (pending.length >= size) {
+      const frame = new Uint8Array(pending.subarray(0, size));
+      moving.push(previous === void 0 || changedPixels(frame, previous) >= MOVING_PIXELS);
+      previous = frame;
+      pending = pending.subarray(size);
+    }
+  }
+  return moving;
+}
+function motionArgs(video) {
+  return ["-v", "error", "-i", video, "-vf", `fps=${MOTION_FPS},scale=${WIDTH}:${HEIGHT}:flags=area,format=gray`, "-f", "rawvideo", "-"];
+}
+async function motionMap(video, ffmpeg = "ffmpeg", spawnImpl = spawn) {
+  const child = spawnImpl(ffmpeg, motionArgs(video), { stdio: ["ignore", "pipe", "pipe"] });
+  let errors = "";
+  child.stderr.on("data", (chunk) => {
+    errors += chunk.toString();
+  });
+  const exited = new Promise((resolve3, reject) => {
+    child.on("error", reject);
+    child.on("close", resolve3);
+  });
+  const moving = await readMotion(child.stdout);
+  const code = await exited;
+  if (code !== 0) throw new Error(`ffmpeg could not read ${video}: ${errors.trim() || `exit ${code}`}`);
+  return { fps: MOTION_FPS, moving };
+}
+function frozenSpans(map, minSeconds) {
+  const spans = [];
+  let runStart;
+  const close = (index) => {
+    if (runStart === void 0) return;
+    const start = runStart / map.fps;
+    const end = index / map.fps;
+    if (end - start >= minSeconds) spans.push({ start, end });
+    runStart = void 0;
+  };
+  map.moving.forEach((moves, index) => {
+    if (moves) close(index);
+    else runStart ??= index;
+  });
+  close(map.moving.length);
+  return spans;
+}
+var DEAD_TRIM_MIN_SECONDS = 1.6;
+var DEAD_KEEP_SECONDS = 0.4;
+var MIN_PART_SECONDS = 0.8;
+function keepParts(beat, speech, map) {
+  const parts = [];
+  let partStart = beat.start;
+  const first = Math.ceil(beat.start * map.fps);
+  const last = Math.floor(beat.end * map.fps);
+  let runStart;
+  const dead = (index) => {
+    const at = index / map.fps;
+    const spoken = speech !== void 0 && at >= speech.start && at <= speech.end;
+    return !spoken && map.moving[index] === false;
+  };
+  const ms = (seconds) => Math.round(seconds * 1e3) / 1e3;
+  const closeRun = (endIndex) => {
+    if (runStart === void 0) return;
+    const frames = endIndex - runStart;
+    const runFrom = runStart / map.fps;
+    const runTo = endIndex / map.fps;
+    runStart = void 0;
+    if (frames < Math.round(DEAD_TRIM_MIN_SECONDS * map.fps)) return;
+    const cutFrom = ms(Math.max(runFrom + DEAD_KEEP_SECONDS, partStart + MIN_PART_SECONDS));
+    const cutTo = ms(Math.min(runTo - DEAD_KEEP_SECONDS, beat.end - MIN_PART_SECONDS));
+    if (Math.round((cutTo - cutFrom) * 1e3) < 600) return;
+    parts.push({ start: partStart, end: cutFrom });
+    partStart = cutTo;
+  };
+  for (let index = first; index <= last; index++) {
+    if (dead(index)) runStart ??= index;
+    else closeRun(index);
+  }
+  closeRun(last + 1);
+  parts.push({ start: partStart, end: beat.end });
+  return parts;
+}
+
+// src/demo/measure.ts
+var DEAD_AIR_MAX_SECONDS = 2;
+var SPOKEN_SHARE_MIN = 0.6;
+function parseSpans(log, startKey, endKey, duration) {
+  const spans = [];
+  let open;
+  for (const line of log.split("\n")) {
+    const start = new RegExp(`${startKey}[:=]\\s*(-?[0-9.]+)`).exec(line);
+    if (start) open = Math.max(0, Number(start[1]));
+    const end = new RegExp(`${endKey}[:=]\\s*(-?[0-9.]+)`).exec(line);
+    if (end && open !== void 0) {
+      spans.push({ start: open, end: Number(end[1]) });
+      open = void 0;
+    }
+  }
+  if (open !== void 0) spans.push({ start: open, end: duration });
+  return spans;
+}
+function intersect(a, b) {
+  const both = [];
+  for (const x of a) {
+    for (const y of b) {
+      const start = Math.max(x.start, y.start);
+      const end = Math.min(x.end, y.end);
+      if (end > start) both.push({ start, end });
+    }
+  }
+  return both.sort((p, q) => q.end - q.start - (p.end - p.start));
+}
+var total = (spans) => spans.reduce((sum, span) => sum + (span.end - span.start), 0);
+function summarize(duration, frozen, silent, hasAudio) {
+  const quiet = hasAudio ? silent : [{ start: 0, end: duration }];
+  return { duration, frozen: total(frozen), spoken: Math.max(0, duration - total(quiet)), deadAir: intersect(frozen, quiet) };
+}
+function deadAirProblems(measure) {
+  return measure.deadAir.filter((span) => span.end - span.start > DEAD_AIR_MAX_SECONDS).map((span) => `the screen is frozen with nothing said for ${(span.end - span.start).toFixed(1)} s, from ${span.start.toFixed(1)} s`);
+}
+function speechNote(measure, narrated) {
+  if (!narrated || measure.spoken >= SPOKEN_SHARE_MIN * measure.duration) return void 0;
+  return `speech covers ${Math.round(measure.spoken / measure.duration * 100)}% of the demo, under ${Math.round(SPOKEN_SHARE_MIN * 100)}%`;
+}
+async function measureDemo(video, duration, tools) {
+  const hasAudio = tools.run(tools.ffprobe, ["-v", "error", "-select_streams", "a", "-show_entries", "stream=codec_type", "-of", "csv=p=0", video]).trim() !== "";
+  const log = hasAudio ? tools.run(tools.ffmpeg, ["-hide_banner", "-nostats", "-v", "error", "-i", video, "-vn", "-af", "silencedetect=n=-42dB:d=0.5,ametadata=mode=print:file=-", "-f", "null", "-"]) : "";
+  const silent = parseSpans(log, "lavfi\\.silence_start", "lavfi\\.silence_end", duration);
+  const frozen = frozenSpans(await tools.motion(video), 0.5);
+  return summarize(duration, frozen, silent, hasAudio);
+}
 
 // src/demo/media.ts
+var SEGMENT_FPS = 25;
 function encodeArgs(duration, output) {
   return [
     "-c:v",
@@ -2322,57 +2470,64 @@ function encodeArgs(duration, output) {
 function tempoStage(tempo) {
   return tempo === 1 ? "" : `atempo=${tempo.toFixed(4)},`;
 }
-function clipArgs(plan) {
-  const duration = plan.end - plan.start;
-  const audio = plan.audio;
-  const pad = `apad=whole_dur=${duration.toFixed(3)}`;
-  const audioInput = audio === void 0 ? [] : audio === "silence" ? ["-f", "lavfi", "-t", duration.toFixed(3), "-i", "anullsrc=channel_layout=mono:sample_rate=48000"] : ["-i", audio.wavPath];
-  const audioFilter = audio === void 0 ? void 0 : audio === "silence" ? `[1:a]${pad}[speech]` : `[1:a]${tempoStage(audio.tempo)}adelay=${Math.round(audio.delaySeconds * 1e3)}:all=1,aresample=48000,${pad}[speech]`;
-  const speech = audioFilter === void 0 ? [] : ["-filter_complex", audioFilter, "-map", "[speech]", "-c:a", "libopus", "-b:a", "48k"];
+var KEY_FRAME_LEAD_SECONDS = 0.1;
+function segmentsArgs(plan) {
+  const count = plan.spans.length;
+  const parts = plan.spans.map((_, index) => `[p${index}]`).join("");
+  const crop = plan.crop === void 0 ? "" : `crop=${plan.crop.width}:${plan.crop.height}:0:0,`;
+  const video = [`[0:v]${crop}fps=${SEGMENT_FPS},format=yuv420p,split=${count}${parts}`];
+  for (const [index, span] of plan.spans.entries()) {
+    video.push(`[p${index}]trim=start=${span.start.toFixed(3)}:end=${span.end.toFixed(3)},setpts=PTS-STARTPTS[s${index}]`);
+  }
+  let joined = "[s0]";
+  for (let index = 1; index < count; index++) {
+    const label = index === count - 1 ? "[vout]" : `[x${index}]`;
+    video.push(`${joined}[s${index}]xfade=transition=fade:duration=${plan.crossfade.toFixed(3)}:offset=${plan.outStarts[index].toFixed(3)}${label}`);
+    joined = label;
+  }
+  if (count === 1) video.push("[s0]null[vout]");
+  const pad = `apad=whole_dur=${plan.duration.toFixed(3)}`;
+  const audio = plan.speech.map(
+    (speech, index) => `[${index + 1}:a]${tempoStage(speech.tempo)}adelay=${Math.round(speech.delaySeconds * 1e3)}:all=1[line${index}]`
+  );
+  if (plan.narrated) {
+    audio.push(
+      plan.speech.length === 0 ? `anullsrc=channel_layout=mono:sample_rate=48000,${pad}[speech]` : plan.speech.length === 1 ? `[line0]aresample=48000,${pad}[speech]` : `${plan.speech.map((_, index) => `[line${index}]`).join("")}amix=inputs=${plan.speech.length}:normalize=0,aresample=48000,${pad}[speech]`
+    );
+  }
+  const keyFrames = plan.chapterStarts.map((at) => at - KEY_FRAME_LEAD_SECONDS).filter((at) => at > 0);
   return [
     "-y",
     "-v",
     "error",
-    // The cut sits before the input and the clip is re-encoded, so it starts on the exact frame, not the nearest key frame.
-    "-ss",
-    plan.start.toFixed(3),
-    "-t",
-    duration.toFixed(3),
     "-i",
     plan.video,
-    ...audioInput,
+    ...plan.speech.flatMap((speech) => ["-i", speech.wavPath]),
+    "-filter_complex",
+    [...video, ...audio].join(";"),
     "-map",
-    "0:v:0",
-    ...audio === void 0 ? ["-an"] : speech,
-    ...encodeArgs(duration, plan.output)
+    "[vout]",
+    ...plan.narrated ? ["-map", "[speech]", "-c:a", "libopus", "-b:a", "48k"] : ["-an"],
+    ...keyFrames.length > 0 ? ["-force_key_frames", keyFrames.map((at) => at.toFixed(3)).join(",")] : [],
+    ...encodeArgs(plan.duration, plan.output)
   ];
 }
-var KEY_FRAME_LEAD_SECONDS = 0.1;
-function demoArgs(plan) {
+function rangeArgs(plan) {
   const duration = plan.end - plan.start;
-  const pad = `apad=whole_dur=${duration.toFixed(3)}`;
-  const stages = plan.speech.map(
-    (speech, index) => `[${index + 1}:a]${tempoStage(speech.tempo)}adelay=${Math.round(speech.delaySeconds * 1e3)}:all=1[line${index}]`
-  );
-  const mixed = plan.speech.length === 0 ? `anullsrc=channel_layout=mono:sample_rate=48000,${pad}[speech]` : plan.speech.length === 1 ? `[line0]aresample=48000,${pad}[speech]` : `${plan.speech.map((_, index) => `[line${index}]`).join("")}amix=inputs=${plan.speech.length}:normalize=0,aresample=48000,${pad}[speech]`;
-  const filter = [...stages, mixed].join(";");
-  const keyFrames = plan.chapterStarts.map((at) => at - plan.start - KEY_FRAME_LEAD_SECONDS).filter((at) => at > 0);
   return [
     "-y",
     "-v",
     "error",
-    // The cut sits before the input and the demo is re-encoded, so it starts on the exact frame, not the nearest key frame.
+    // The cut sits before the input and the chapter is encoded again, so it starts on the exact frame, not the nearest key frame.
     "-ss",
     plan.start.toFixed(3),
     "-t",
     duration.toFixed(3),
     "-i",
     plan.video,
-    ...plan.speech.flatMap((speech) => ["-i", speech.wavPath]),
     "-map",
     "0:v:0",
-    ...plan.narrated ? ["-filter_complex", filter, "-map", "[speech]", "-c:a", "libopus", "-b:a", "48k"] : ["-an"],
-    ...keyFrames.length > 0 ? ["-force_key_frames", keyFrames.map((at) => at.toFixed(3)).join(",")] : [],
+    ...plan.narrated ? ["-map", "0:a:0", "-c:a", "libopus", "-b:a", "48k"] : ["-an"],
     ...encodeArgs(duration, plan.output)
   ];
 }
@@ -2385,7 +2540,7 @@ function durationFromProbe(formatDuration, lastPacketLines) {
   return last[0] + (Number.isFinite(last[1]) ? last[1] : 0);
 }
 var TOOL_TIMEOUT_MS = 10 * 60 * 1e3;
-function createMediaTools(env, exec = execFileSync) {
+function createMediaTools(env, exec = execFileSync, spawnImpl = spawn) {
   const ffmpeg = findProgram("ffmpeg", env) ?? "ffmpeg";
   const ffprobe = findProgram("ffprobe", env) ?? "ffprobe";
   const run = (program, args) => exec(program, args, {
@@ -2405,11 +2560,17 @@ function createMediaTools(env, exec = execFileSync) {
       if (duration === void 0) throw new Error(`cannot read the length of ${video}`);
       return duration;
     },
-    renderClip(plan) {
-      run(ffmpeg, clipArgs(plan));
+    renderSegments(plan) {
+      run(ffmpeg, segmentsArgs(plan));
+    },
+    renderRange(plan) {
+      run(ffmpeg, rangeArgs(plan));
     },
-    renderDemo(plan) {
-      run(ffmpeg, demoArgs(plan));
+    motion(video) {
+      return motionMap(video, ffmpeg, spawnImpl);
+    },
+    measure(video, duration) {
+      return measureDemo(video, duration, { ffmpeg, ffprobe, run, motion: (sampled) => motionMap(sampled, ffmpeg, spawnImpl) });
     }
   };
 }
@@ -2485,6 +2646,75 @@ function recordedFrame(chapter, stored) {
   if (frame === void 0 || stored.screenshot === void 0) return {};
   return { screenshot: { artifactId: stored.screenshot.artifactId, check: frame.check, sha256: frame.sha256, fullPage: frame.fullPage, masked: frame.masked } };
 }
+var RECORDER_PACKAGE = "@outerlayer/playwright";
+function installedRecorderVersion(dir) {
+  for (let current = dir; ; current = dirname(current)) {
+    let real;
+    try {
+      real = realpathSync(join(current, "node_modules", "@outerlayer", "playwright"));
+    } catch {
+      real = void 0;
+    }
+    if (real !== void 0) {
+      if (!real.split(sep).includes("node_modules")) return void 0;
+      try {
+        const version = JSON.parse(readFileSync(join(real, "package.json"), "utf8")).version;
+        return typeof version === "string" ? version : void 0;
+      } catch {
+        return void 0;
+      }
+    }
+    if (dirname(current) === current) return void 0;
+  }
+}
+function recorderVersionNote(recorder, cli) {
+  if (recorder === void 0) return void 0;
+  const order = compareVersions(recorder, cli);
+  if (order === void 0 || order === 0) return void 0;
+  return order < 0 ? `this demo was recorded with ${RECORDER_PACKAGE} ${recorder}, and this CLI is ${cli}: install ${RECORDER_PACKAGE}@${cli}, which releases with this CLI` : `this demo was recorded with ${RECORDER_PACKAGE} ${recorder}, newer than this CLI (${cli}): update the CLI to ${recorder}`;
+}
+
+// src/demo/timeline.ts
+var JOIN_GAP = 0.25;
+var CROSSFADE = 0.3;
+function shownParts(chapter) {
+  if (chapter.beats === void 0 || chapter.beats.length === 0) return [{ start: chapter.start, end: chapter.end }];
+  return chapter.beats.map((beat) => ({ start: beat.start, end: beat.end }));
+}
+var millis = (seconds) => Math.round(seconds * 1e3) / 1e3;
+function planTimeline(chapters) {
+  const spans = [];
+  for (const chapter of chapters) {
+    for (const part of shownParts(chapter)) {
+      const last = spans.at(-1);
+      if (last !== void 0 && part.start - last.end < JOIN_GAP) last.end = Math.max(last.end, part.end);
+      else spans.push({ ...part });
+    }
+  }
+  const outStarts = [];
+  let cursor = 0;
+  for (const [index, span] of spans.entries()) {
+    const start = index === 0 ? 0 : millis(cursor - CROSSFADE);
+    outStarts.push(start);
+    cursor = millis(start + (span.end - span.start));
+  }
+  const duration = cursor;
+  const recorded = spans.length === 0 ? 0 : spans.at(-1).end - spans[0].start;
+  const shown = spans.reduce((sum, span) => sum + (span.end - span.start), 0);
+  const placed = { spans, outStarts };
+  const chapterRanges = chapters.map((chapter) => {
+    const parts = shownParts(chapter);
+    return { start: mapTime(placed, parts[0].start), end: mapTime(placed, parts.at(-1).end) };
+  });
+  return { spans, outStarts, duration, chapters: chapterRanges, leftOut: recorded - shown };
+}
+function mapTime(timeline, at) {
+  for (const [index, span] of timeline.spans.entries()) {
+    if (at <= span.end + 1e-6) return timeline.outStarts[index] + Math.max(0, at - span.start);
+  }
+  const last = timeline.spans.length - 1;
+  return last < 0 ? 0 : timeline.outStarts[last] + (timeline.spans[last].end - timeline.spans[last].start);
+}
 var PUNCTUATION = ';:,.!?\xA1\xBF\u2014\u2026"\xAB\xBB\u201C\u201D(){}[]';
 var PUNCTUATION_RUN = new RegExp(`(\\s*[${PUNCTUATION.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}]+\\s*)+`, "g");
 function splitYear(text) {
@@ -2831,6 +3061,12 @@ function parseManifest(path, options) {
   } catch (err) {
     throw new EmitDemoError(`the manifest "${path}" is not valid JSON: ${String(err)}`);
   }
+  const version = typeof raw === "object" && raw !== null ? raw.schemaVersion : void 0;
+  if (typeof version === "number" && version > DEMO_MANIFEST_LATEST_VERSION) {
+    throw new EmitDemoError(
+      `the manifest "${path}" is version ${version}, and this CLI reads versions 1 to ${DEMO_MANIFEST_LATEST_VERSION}: update the CLI to the version of the recorder that wrote it`
+    );
+  }
   const parsed = DemoManifestSchema.safeParse(raw);
   if (!parsed.success) {
     const issue = parsed.error.issues[0];
@@ -2856,13 +3092,16 @@ async function runEmitDemo(opts) {
   };
   const manifestPath = resolve(cwd, opts.manifest);
   const { manifest, videoPath, text: manifestText } = parseManifest(manifestPath, { needVideo: true });
+  const recorderNote = recorderVersionNote(installedRecorderVersion(dirname(manifestPath)), opts.cliVersion ?? resolvePackageVersion());
+  if (recorderNote !== void 0) say(`${C.yellow}!${C.reset} ${recorderNote}`);
   const comparisons = compareRuns({ first: { manifest, dir: dirname(manifestPath) }, firstPath: manifestPath, secondPath: opts.compare === void 0 ? void 0 : resolve(cwd, opts.compare) });
-  const narrated = opts.noNarration !== true && manifest.chapters.some((chapter) => chapter.narration.trim() !== "");
+  const narrated = opts.noNarration !== true && manifest.chapters.some((chapter) => chapter.narration.trim() !== "" || (beatsOf(chapter) ?? []).some((beat) => beat.narration.trim() !== ""));
   for (const program of narrated ? ["ffmpeg", "ffprobe", "espeak-ng"] : ["ffmpeg", "ffprobe"]) {
     if (findProgram(program, env) === void 0) throw new EmitDemoError(missingProgramMessage(program, narrated));
   }
   const fetchImpl = opts.fetchImpl ?? defaultFetch;
   const media = opts.media ?? createMediaTools(env);
+  if (opts.output !== void 0) return renderOnly({ opts, manifest, manifestPath, videoPath, narrated, env, home, media, say, output: resolve(cwd, opts.output) });
   const item = resolveItem({ opts, env, cwd, home });
   const retiring = opts.replaces === void 0 ? void 0 : await readRetiring({ opts, item, env, cwd, home, fetchImpl });
   const proofs = await recordedCriteria({ opts, item, env, cwd, home, fetchImpl, say });
@@ -2885,66 +3124,24 @@ async function runEmitDemo(opts) {
       writeFileSync(path, frame.bytes);
       return path;
     });
-    const speaker = narrated ? opts.speaker ?? await realSpeaker({ env, home, work, say, installedRoot: opts.installedVoiceRoot }) : void 0;
-    const spoken = [];
-    for (const [index, chapter] of manifest.chapters.entries()) {
-      if (speaker === void 0 || chapter.narration.trim() === "") continue;
-      let speech;
-      try {
-        speech = await speaker(chapter.narration);
-      } catch (err) {
-        throw new EmitDemoError(`${chapterLabel(index, chapter.title)}: the narration could not be spoken: ${err instanceof Error ? err.message : String(err)}`);
-      }
-      const fit = fitSpeech(speech.seconds, chapter.end - chapter.start);
-      if (!fit.ok) {
-        throw new EmitDemoError(
-          `${chapterLabel(index, chapter.title)}: the narration runs ${fit.overrunSeconds.toFixed(1)} s too long even at 1.3 times speed \u2014 shorten the line or lengthen the chapter`
-        );
-      }
-      spoken.push({ index, wavPath: speech.wavPath, tempo: fit.tempo });
-    }
-    const first = manifest.chapters[0];
-    const last = manifest.chapters[manifest.chapters.length - 1];
-    const wholePlan = {
-      video: videoPath,
-      start: first.start,
-      end: last.end,
-      chapterStarts: manifest.chapters.map((chapter) => chapter.start),
-      output: join(work, "demo.webm"),
-      narrated: speaker !== void 0,
-      speech: spoken.map((line) => ({
-        wavPath: line.wavPath,
-        tempo: line.tempo,
-        delaySeconds: manifest.chapters[line.index].start - first.start + SPEECH_LEAD_IN
-      }))
-    };
-    try {
-      media.renderDemo(wholePlan);
-    } catch (err) {
-      throw new EmitDemoError(`ffmpeg could not cut the demo: ${String(err)}`);
-    }
+    const speakerFor = lazySpeaker(opts, { env, home, work, say });
+    const whole = await renderWhole({ manifest, manifestDir, videoPath, work, speakerFor, narrated, media });
+    const deadAir = deadAirProblems(whole.measure);
+    if (deadAir.length > 0) throw new EmitDemoError(deadAirRefusal(deadAir));
+    const note = speechNote(whole.measure, narrated);
+    if (note !== void 0) say(`${C.yellow}!${C.reset} ${note}: tell each step as a beat with demo.say()`);
+    const wholePlan = { output: whole.output };
     const wholeBytes = statSync(wholePlan.output).size;
     const wholeFits = wholeBytes <= ARTIFACT_MAX_BYTES;
     const clipPlans = [];
     if (!wholeFits) {
-      for (const [index, chapter] of manifest.chapters.entries()) {
-        const clipStart = index === 0 ? chapter.start : manifest.chapters[index - 1].end;
-        const line = spoken.find((entry) => entry.index === index);
-        clipPlans.push({
-          video: videoPath,
-          start: clipStart,
-          end: chapter.end,
-          output: join(work, `chapter-${String(index + 1).padStart(2, "0")}.webm`),
-          ...line !== void 0 ? { audio: { wavPath: line.wavPath, tempo: line.tempo, delaySeconds: chapter.start - clipStart + SPEECH_LEAD_IN } } : (
-            // A chapter with no line still carries a track in a narrated demo, so every clip of the demo has audio.
-            speaker !== void 0 ? { audio: "silence" } : {}
-          )
-        });
+      for (const [index, range] of whole.ranges.entries()) {
+        clipPlans.push({ video: whole.output, start: range.start, end: range.end, output: join(work, `chapter-${String(index + 1).padStart(2, "0")}.webm`), narrated });
       }
       for (const [index, plan] of clipPlans.entries()) {
         const chapter = manifest.chapters[index];
         try {
-          media.renderClip(plan);
+          media.renderRange(plan);
         } catch (err) {
           throw new EmitDemoError(`${chapterLabel(index, chapter.title)}: ffmpeg could not cut the clip: ${String(err)}`);
         }
@@ -2963,16 +3160,16 @@ async function runEmitDemo(opts) {
     let stored;
     if (wholeFits) {
       video = { artifactId: idFor("video", wholePlan.output) };
-      stored = manifest.chapters.map((chapter, index) => ({
+      stored = manifest.chapters.map((_chapter, index) => ({
         artifactId: idFor(`chapter-${index + 1}`, wholePlan.output),
-        range: { start: chapter.start - first.start, end: chapter.end - first.start },
+        range: whole.ranges[index],
         bound: bound[index]
       }));
     } else {
       video = { omitted: "size", bytes: wholeBytes };
-      stored = manifest.chapters.map((chapter, index) => ({
+      stored = manifest.chapters.map((_chapter, index) => ({
         artifactId: idFor(`clip-${index + 1}`, clipPlans[index].output),
-        range: { start: chapter.start - clipPlans[index].start, end: chapter.end - clipPlans[index].start },
+        range: { start: 0, end: Number((clipPlans[index].end - clipPlans[index].start).toFixed(3)) },
         bound: bound[index]
       }));
     }
@@ -3005,11 +3202,11 @@ async function runEmitDemo(opts) {
       fetchImpl: opts.fetchImpl
     };
     const replacing = retiring === void 0 ? void 0 : planReplaces(retiring, manifest, wholeFits, frames.map((frame) => frame.kind === "bind"));
-    const total = manifest.chapters.length + (wholeFits ? 1 : 0) + 1 + frameIds.filter((id) => id !== void 0).length;
+    const total2 = manifest.chapters.length + (wholeFits ? 1 : 0) + 1 + frameIds.filter((id) => id !== void 0).length;
     const unit = "artifacts";
     let emitted = 0;
     const emitStep = async (params) => {
-      const result = await emitOrExplain(emit, { ...base, ...params }, emitted, total, unit);
+      const result = await emitOrExplain(emit, { ...base, ...params }, emitted, total2, unit);
       emitted += 1;
       return result;
     };
@@ -3017,7 +3214,7 @@ async function runEmitDemo(opts) {
       const wholeResult = await emitStep({
         file: wholePlan.output,
         artifactId: video.artifactId,
-        caption: `Demo: ${manifest.chapters.length} chapter${manifest.chapters.length === 1 ? "" : "s"}, ${(wholePlan.end - wholePlan.start).toFixed(1)} s`,
+        caption: `Demo: ${manifest.chapters.length} chapter${manifest.chapters.length === 1 ? "" : "s"}, ${whole.duration.toFixed(1)} s`,
         blobOptional: true,
         ...replaceOption(replacing?.video)
       });
@@ -3147,13 +3344,13 @@ function artifactIdOf(result) {
   if (typeof id !== "string") throw new EmitDemoError("the artifact was emitted but its id was not returned");
   return id;
 }
-async function emitOrExplain(emit, opts, emitted, total, unit) {
+async function emitOrExplain(emit, opts, emitted, total2, unit) {
   try {
     return await emit(opts);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     throw new EmitDemoError(
-      emitted > 0 ? `${message} \u2014 ${emitted} of ${total} ${unit} were already emitted; run the command again to emit the whole demo` : message
+      emitted > 0 ? `${message} \u2014 ${emitted} of ${total2} ${unit} were already emitted; run the command again to emit the whole demo` : message
     );
   }
 }
@@ -3299,5 +3496,180 @@ function decideFrames(params) {
     return { kind: "bind", index, frame: decision.bind, bytes };
   });
 }
+var BEAT_LEAD_IN = 0.15;
+function beatsOf(chapter) {
+  return "beats" in chapter ? chapter.beats : void 0;
+}
+function lazySpeaker(opts, params) {
+  let made;
+  return () => {
+    made ??= opts.speaker !== void 0 ? Promise.resolve(opts.speaker) : realSpeaker({ ...params, installedRoot: opts.installedVoiceRoot });
+    return made;
+  };
+}
+async function speak(speakerFor, label, line) {
+  const speaker = await speakerFor();
+  try {
+    return await speaker(line);
+  } catch (err) {
+    throw new EmitDemoError(`${label}: the narration could not be spoken: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function deadAirRefusal(problems) {
+  return `the demo holds dead air: ${problems.join("; ")} \u2014 tell each step as a beat with demo.say(), so the demo shows only narrated steps`;
+}
+var millis2 = (seconds) => Math.round(seconds * 1e3) / 1e3;
+async function renderWhole(params) {
+  const { manifest, manifestDir, videoPath, work, speakerFor, narrated, media } = params;
+  const output = join(work, "demo.webm");
+  const chapters = manifest.chapters;
+  const chapterLines = [];
+  const beatLines = [];
+  for (const [index, chapter] of chapters.entries()) {
+    const beats = beatsOf(chapter) ?? [];
+    if (beats.length === 0 && narrated && chapter.narration.trim() !== "") {
+      const speech2 = await speak(speakerFor, chapterLabel(index, chapter.title), chapter.narration);
+      const fit = fitSpeech(speech2.seconds, chapter.end - chapter.start);
+      if (!fit.ok) {
+        throw new EmitDemoError(
+          `${chapterLabel(index, chapter.title)}: the narration runs ${fit.overrunSeconds.toFixed(1)} s too long even at 1.3 times speed \u2014 shorten the line or lengthen the chapter`
+        );
+      }
+      chapterLines.push({ ...speech2, tempo: fit.tempo });
+    } else {
+      chapterLines.push(void 0);
+    }
+    const lines = [];
+    for (const [beatIndex, beat] of beats.entries()) {
+      if (!narrated || beat.narration.trim() === "") {
+        lines.push(void 0);
+        continue;
+      }
+      const label = `${chapterLabel(index, chapter.title)}, beat ${beatIndex + 1}`;
+      const recorded = beat.voice === void 0 ? void 0 : resolve(manifestDir, beat.voice.file);
+      const voice = recorded !== void 0 && existsSync(recorded) ? { wavPath: recorded, seconds: beat.voice.seconds } : await speak(speakerFor, label, beat.narration);
+      const budget = beat.end - beat.start - BEAT_LEAD_IN;
+      const tempo = voice.seconds <= budget ? 1 : voice.seconds / budget;
+      if (tempo > MAX_TEMPO) throw new EmitDemoError(`${label}: the line runs ${(voice.seconds / MAX_TEMPO - budget).toFixed(1)} s too long for its beat even at ${MAX_TEMPO} times speed`);
+      lines.push({ ...voice, tempo });
+    }
+    beatLines.push(lines);
+  }
+  const frame = (at) => Math.round(at * SEGMENT_FPS) / SEGMENT_FPS;
+  const snap = (span) => ({ start: frame(span.start), end: Math.max(frame(span.end), frame(span.start) + 1 / SEGMENT_FPS) });
+  const spoken = (start, line, lead) => line === void 0 ? void 0 : { start: start + lead, end: start + lead + line.seconds / line.tempo };
+  let motion;
+  try {
+    motion = await media.motion(videoPath);
+  } catch (err) {
+    throw new EmitDemoError(`cannot read the motion of ${videoPath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  let trimmed = 0;
+  const keep = (span, speech2) => {
+    const kept = keepParts(span, speech2, motion);
+    trimmed += span.end - span.start - kept.reduce((sum, part) => sum + (part.end - part.start), 0);
+    return kept.map(snap);
+  };
+  const shown = chapters.map((chapter, index) => {
+    const beats = beatsOf(chapter) ?? [];
+    const parts = beats.length === 0 ? keep(chapter, spoken(chapter.start, chapterLines[index], SPEECH_LEAD_IN)) : beats.flatMap((beat, beatIndex) => keep(beat, spoken(beat.start, beatLines[index][beatIndex], BEAT_LEAD_IN)));
+    return { ...snap(chapter), beats: parts };
+  });
+  const timeline = planTimeline(shown);
+  const speech = [];
+  for (const [index, chapter] of chapters.entries()) {
+    const line = chapterLines[index];
+    if (line !== void 0) speech.push({ wavPath: line.wavPath, tempo: line.tempo, delaySeconds: millis2(mapTime(timeline, frame(chapter.start)) + SPEECH_LEAD_IN) });
+    for (const [beatIndex, beat] of (beatsOf(chapter) ?? []).entries()) {
+      const beatLine = beatLines[index][beatIndex];
+      if (beatLine !== void 0) speech.push({ wavPath: beatLine.wavPath, tempo: beatLine.tempo, delaySeconds: millis2(mapTime(timeline, frame(beat.start)) + BEAT_LEAD_IN) });
+    }
+  }
+  const viewport = manifest.viewport;
+  try {
+    media.renderSegments({
+      video: videoPath,
+      spans: timeline.spans,
+      outStarts: timeline.outStarts,
+      duration: timeline.duration,
+      crossfade: CROSSFADE,
+      chapterStarts: timeline.chapters.map((range) => range.start),
+      output,
+      narrated,
+      speech,
+      ...viewport === void 0 ? {} : { crop: viewport }
+    });
+  } catch (err) {
+    throw new EmitDemoError(`ffmpeg could not cut the demo: ${String(err)}`);
+  }
+  let measure;
+  try {
+    measure = await media.measure(output, timeline.duration);
+  } catch (err) {
+    throw new EmitDemoError(`cannot measure the demo: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return {
+    output,
+    duration: timeline.duration,
+    ranges: timeline.chapters.map((range) => ({ start: Number(range.start.toFixed(3)), end: Number(range.end.toFixed(3)) })),
+    leftOut: timeline.leftOut,
+    trimmed,
+    measure
+  };
+}
+async function renderOnly(params) {
+  const { opts, manifest, manifestPath, videoPath, narrated, env, home, media, say, output } = params;
+  let videoSeconds;
+  try {
+    videoSeconds = media.probe(videoPath);
+  } catch (err) {
+    throw new EmitDemoError(`cannot read the video ${videoPath}: ${String(err)}`);
+  }
+  const problem = checkManifest({ manifest, videoSeconds });
+  if (problem !== void 0) throw new EmitDemoError(problem);
+  const work = mkdtempSync(join(tmpdir(), "outerlayer-demo-"));
+  try {
+    const speakerFor = lazySpeaker(opts, { env, home, work, say });
+    const whole = await renderWhole({ manifest, manifestDir: dirname(manifestPath), videoPath, work, speakerFor, narrated, media });
+    mkdirSync(dirname(output), { recursive: true });
+    copyFileSync(whole.output, output);
+    const deadAir = deadAirProblems(whole.measure);
+    const note = speechNote(whole.measure, narrated);
+    const failures = manifest.chapters.flatMap((chapter, index) => {
+      const failed = chapter.checks.filter((check) => !check.passed);
+      return failed.length === 0 ? [] : [`${chapterLabel(index, chapter.title)} failed: ${failed.map((check) => `"${check.text}"`).join(", ")}`];
+    });
+    const longest = whole.measure.deadAir[0];
+    const summary = {
+      output,
+      seconds: Number(whole.duration.toFixed(2)),
+      leftOutSeconds: Number(whole.leftOut.toFixed(2)),
+      deadAirCutSeconds: Number(whole.trimmed.toFixed(2)),
+      chapters: manifest.chapters.map((chapter, index) => ({ criterionId: chapter.criterionId, title: chapter.title, range: whole.ranges[index] })),
+      measure: {
+        frozenSeconds: Number(whole.measure.frozen.toFixed(2)),
+        spokenSeconds: Number(whole.measure.spoken.toFixed(2)),
+        longestDeadAir: longest === void 0 ? 0 : Number((longest.end - longest.start).toFixed(2))
+      },
+      deadAir,
+      ...note === void 0 ? {} : { note },
+      failures
+    };
+    writeFileSync(`${output}.json`, `${JSON.stringify(summary, null, 2)}
+`);
+    const share = (part) => `${whole.duration === 0 ? 0 : Math.round(part / whole.duration * 100)}%`;
+    const text = opts.json ? JSON.stringify(summary) : [
+      ...deadAir.map((line) => `${C.red}\u2717${C.reset} ${line}`),
+      ...note === void 0 ? [] : [`${C.yellow}!${C.reset} ${note}`],
+      `${deadAir.length === 0 ? `${C.green}\u2713${C.reset}` : `${C.red}\u2717${C.reset}`} demo rendered ${C.dim}\xB7${C.reset} ${output} ${C.dim}\xB7${C.reset} ${summary.seconds} s ${C.dim}\xB7${C.reset} speech ${share(whole.measure.spoken)} ${C.dim}\xB7${C.reset} ${summary.leftOutSeconds} s of setup and dead air left out`
+    ].join("\n");
+    if (!opts.quiet) process.stdout.write(`${text}
+`);
+    const exitCode = deadAir.length > 0 || failures.length > 0 ? 1 : 0;
+    return { exitCode, output: text, failures, recordArtifactId: "", video: { omitted: "size", bytes: 0 }, clips: [], screenshots: [], differences: [] };
+  } finally {
+    rmSync(work, { recursive: true });
+  }
+}
 
-export { EmitDemoError, runEmitDemo };
+export { EmitDemoError, realSpeaker, runEmitDemo };