@hypersocial/decks-cli 0.9.5 → 0.9.7

package/src/export-video.mjs

@@ -14,12 +14,18 @@
 // card (2 s) and end card (3 s) are plain pages rendered the same size.
 // ffmpeg (the CLI's portable @ffmpeg-installer build) mixes and encodes:
 // H.264, AAC, +faststart.
+//
+// A range of slides (config.range, `--slides a-b`) records just those slides;
+// the render worker splits a long deck that way across machines: each records
+// a video-only segment (config.segment) and says where each clip started in
+// it, and joinVideo concatenates the segments and lays the whole deck's audio
+// under them once, so the voice has no seam.
 import { copyFile, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, extname, join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { allowCaptureDestination, installChromium, isMissingBrowser, noteSoftwareWebgl, recorderArgs, routeCaptureRequest } from './preview-capture.mjs';
+import { allowCaptureDestination, allowCaptureRequest, installChromium, isMissingBrowser, noteSoftwareWebgl, recorderArgs, routeCaptureRequest } from './preview-capture.mjs';
 import { installFrameClock } from './frame-clock.mjs';
 
 const run = promisify(execFile);
@@ -53,6 +59,7 @@ export function videoGeometry(size = '1080p', shape = '16:9') {
 // The command's options, checked before anything launches.
 export function videoOptions(opts = {}) {
   for (const k of ['size', 'shape', 'out', 'link', 'slug']) if (k in opts && typeof opts[k] !== 'string') throw new Error(`--${k} requires a value`);
+  if ('slides' in opts && typeof opts.slides !== 'string') throw new Error('--slides requires a value (a-b, counting from 1)');
   const geometry = videoGeometry(opts.size ?? '1080p', opts.shape ?? '16:9');
   if (opts.out && extname(opts.out).toLowerCase() !== '.mp4') throw new Error(`--out must name an .mp4 file (got ${opts.out})`);
   if (opts.link !== undefined) {
@@ -70,9 +77,19 @@ export function videoOptions(opts = {}) {
     link: opts.link ?? null,
     out: opts.out ?? null,
     upload: !!opts.upload,
+    range: opts.slides ? parseSlides(opts.slides) : null,
   };
 }
 
+// --slides 3-5 (or 4): the slides to record, counting from 1, as 0-based
+// indexes { from, to } (inclusive). The deck's own length is checked once it loads.
+export function parseSlides(text) {
+  const m = /^\s*(\d+)\s*(?:-\s*(\d+)\s*)?$/.exec(String(text ?? ''));
+  const from = m ? Number(m[1]) : NaN, to = m ? Number(m[2] ?? m[1]) : NaN;
+  if (!m || from < 1 || to < from) throw new Error(`--slides must be a range like 3-5 or one slide like 4, counting from 1 (got ${text})`);
+  return { from: from - 1, to: to - 1 };
+}
+
 // The page the recorder opens: the deck in export mode.
 export function exportPageUrl(url, { captions = true, avatar = true } = {}) {
   const u = new URL(url);
@@ -138,18 +155,83 @@ export function audioMixArgs({ inputs, seconds, out }) {
 }
 
 // ffmpeg args for the MP4: the numbered frames at `fps` and the mixed audio.
-export function encodeArgs({ frames, fps = VIDEO_FPS, audio, width, height, out }) {
+// Without `audio`, a video-only segment with the same picture settings, so
+// segments join without a re-encode (joinArgs).
+const PICTURE = (fps) => ['-c:v', 'libx264', '-preset', 'fast', '-crf', '20', '-r', String(fps)];
+export function encodeArgs({ frames, fps = VIDEO_FPS, audio, width, height, out, startNumber = 0 }) {
+  return [
+    '-framerate', String(fps), ...(startNumber ? ['-start_number', String(startNumber)] : []), '-i', frames,
+    ...(audio ? ['-i', audio, '-map', '0:v', '-map', '1:a'] : ['-map', '0:v']),
+    '-vf', `scale=${width}:${height}:flags=lanczos,format=yuv420p`,
+    ...PICTURE(fps),
+    ...(audio ? ['-c:a', 'aac', '-b:a', '192k', '-shortest'] : ['-an']),
+    '-movflags', '+faststart', '-y', out,
+  ];
+}
+
+// ffmpeg args that join the segments (a concat list file) under the whole
+// audio track: the picture copied as is, or re-encoded when `reencode`.
+// Only a deck whose clips are plain http(s) URLs of bounded length is split:
+// the join fetches each clip again from its URL on another machine, and Convex
+// keeps the list on a row (a data: or blob: clip, or a huge one, renders whole).
+export const MAX_SPLIT_AUDIO_URL = 1000;
+// The seam: a segment that is not the last records this much past its last
+// slide, through the next slide's real transition (the glide, the bubble's
+// exit, the parts rising), as a single render draws it; the next segment
+// renders the same time from a fresh start but keeps none of it. Its frames
+// after that match a single render's. Longer than any transition (~0.7 s,
+// transitions.js) plus its staggered parts.
+export const SEAM_SECONDS = 2;
+export const SEAM_FRAMES = SEAM_SECONDS * VIDEO_FPS;
+export const MAX_SPLIT_CLIPS = 200;
+export function splittableAudio(plan) {
+  const audio = plan.map((s) => s.audio).filter(Boolean);
+  return audio.length <= MAX_SPLIT_CLIPS && audio.every((a) => typeof a === 'string' && a.length <= MAX_SPLIT_AUDIO_URL && /^https?:\/\//i.test(a));
+}
+
+// What ffmpeg says about a file it opens: its duration and frame size, from
+// the stream header it prints (the portable build has no ffprobe).
+export function probeText(text) {
+  const d = /Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/.exec(text);
+  const v = /Video:.*?\b(\d{2,5})x(\d{2,5})\b/.exec(text);
+  return {
+    seconds: d ? Number(d[1]) * 3600 + Number(d[2]) * 60 + Number(d[3]) : null,
+    width: v ? Number(v[1]) : null,
+    height: v ? Number(v[2]) : null,
+  };
+}
+async function probe(path, file) {
+  // Without an output ffmpeg exits 1 after printing the input's header: that is the answer.
+  const text = await new Promise((ok) => execFile(path, ['-hide_banner', '-nostdin', '-i', file], { timeout: 60000, env: { PATH: dirname(path), ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}) } }, (_e, _out, err) => ok(String(err ?? ''))));
+  return probeText(text);
+}
+
+export function joinArgs({ list, audio, out, fps = VIDEO_FPS, reencode = false }) {
   return [
-    '-framerate', String(fps), '-i', frames,
+    '-f', 'concat', '-safe', '0', '-i', list,
     '-i', audio,
     '-map', '0:v', '-map', '1:a',
-    '-vf', `scale=${width}:${height}:flags=lanczos,format=yuv420p`,
-    '-c:v', 'libx264', '-preset', 'fast', '-crf', '20', '-r', String(fps),
+    ...(reencode ? ['-vf', 'format=yuv420p', ...PICTURE(fps)] : ['-c:v', 'copy']),
     '-c:a', 'aac', '-b:a', '192k',
     '-shortest', '-movflags', '+faststart', '-y', out,
   ];
 }
 
+// Each segment's clips placed on the joined video's timeline: a segment starts
+// where the frames before it end, so the audio follows the real frame counts.
+export function joinTimeline(segments, fps = VIDEO_FPS) {
+  let frames = 0;
+  const clips = [];
+  for (const s of segments) {
+    for (const c of s.clips ?? []) clips.push({ id: c.id, audio: c.audio, offset: Math.max(0, frames / fps + (Number(c.offset) || 0)) });
+    frames += s.frames;
+  }
+  return { clips, frames, seconds: frames / fps };
+}
+
+// The concat demuxer's list: one quoted path a line.
+export const concatList = (files) => files.map((f) => `file '${String(f).replace(/'/g, "'\\''")}'`).join('\n') + '\n';
+
 // A computed style value inside <style>: entities are not decoded there, so it
 // is not HTML-escaped; anything that could end the rule or the element goes.
 const cssValue = (s) => String(s ?? '').replace(/[<>{};\\]/g, '');
@@ -206,6 +288,20 @@ export async function clipSeconds(path, file) {
   return seconds;
 }
 
+// One clip's audio into `path`: only from a public address (or the deck's own
+// origin, `entryUrl`), no redirects, at most MAX_CLIP_BYTES.
+async function downloadClip(url, path, { id, entryUrl }) {
+  if (!await allowCaptureDestination(url, entryUrl)) throw new Error(`clip ${id}'s audio is not on a public address: ${url}`);
+  let res;
+  try { res = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(30000) }); }
+  catch (e) { throw new Error(`could not download clip ${id}'s audio (${url}): ${e.cause?.message ?? e.message}`); }
+  if (!res.ok) throw new Error(`could not download clip ${id}'s audio (${res.status} from ${url})`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (bytes.length > MAX_CLIP_BYTES) throw new Error(`clip ${id}'s audio is over ${MAX_CLIP_BYTES / 1024 / 1024} MB`);
+  await writeFile(path, bytes);
+}
+const clipPath = (dir, n, url) => join(dir, `clip-${n}${extname(new URL(url).pathname).slice(0, 6) || '.audio'}`);
+
 // Bounds a page.evaluate on the Node side (a busy main thread can hold it).
 async function within(promise, ms, fallback) {
   promise.catch(() => {});
@@ -224,15 +320,40 @@ const readLog = (page, ms = 5000) => within(page.evaluate(() => {
 // What the page's network did before a ready timeout, for the error message.
 // `blocked` holds the URLs the capture rules refused; `failed` is the last
 // request that failed for another reason ({ url, error }).
-export function readySaw({ blocked = [], failed = null } = {}) {
+export function readySaw({ refused = 0, unreachable = [], failed = null } = {}) {
   const cut = (u) => (u.length > 160 ? `${u.slice(0, 157)}…` : u);
   const parts = [];
-  if (blocked.length) parts.push(`${blocked.length} request${blocked.length === 1 ? '' : 's'} blocked, last ${cut(blocked.at(-1))}`);
+  // Passed the recorder's rules but could not be fetched (DNS, timeout, a redirect): these can stop a deck.
+  if (unreachable.length) parts.push(`${unreachable.length} request${unreachable.length === 1 ? '' : 's'} could not be fetched, last ${cut(unreachable.at(-1))}`);
   // requestfailed can fire before the route handler records the block.
-  if (failed && !blocked.includes(failed.url)) parts.push(`last failed request ${cut(failed.url)} (${failed.error})`);
+  if (failed && !unreachable.includes(failed.url)) parts.push(`last failed request ${cut(failed.url)} (${failed.error})`);
+  // Tracking, view counts, links and navigation are refused on every recording; only a count, not a cause.
+  if (refused) parts.push(`${refused} tracking or navigation request${refused === 1 ? '' : 's'} refused, as on every recording`);
   return parts.length ? ` (${parts.join('; ')})` : '';
 }
 
+// How slow a slide draws, for the render worker's split (lib/videoSegments.ts
+// slideCosts): 1 for a plain slide, plus 0.3 for each video or embedded page it
+// shows (up to 3). Measured on Fly at 1080p in software: plain slides 0.67–0.75 s
+// a frame, slides with video 0.94–1.36.
+export const MEDIA_WEIGHT = 0.3;
+export function slideWeight(media) {
+  const n = Number.isFinite(media) && media > 0 ? Math.min(3, Math.floor(media)) : 0;
+  return Math.round((1 + MEDIA_WEIGHT * n) * 100) / 100;
+}
+
+// How long a deck may take to become ready: config.readyTimeoutMs, else
+// HYPERDECKS_READY_TIMEOUT_MS, else 120 s. A small cloud machine draws the deck
+// in software and can need a minute or more (the render worker passes 300 s).
+export const READY_TIMEOUT_MS = 120000;
+export function readyTimeoutMs(config = {}, env = process.env) {
+  for (const v of [config.readyTimeoutMs, env.HYPERDECKS_READY_TIMEOUT_MS]) {
+    const n = Number(v);
+    if (v != null && v !== '' && Number.isFinite(n) && n > 0) return Math.floor(n);
+  }
+  return READY_TIMEOUT_MS;
+}
+
 // Why a child process failed: the last line it printed, or its timeout.
 const reasonOf = (e) => (e?.killed ? 'timed out' : String(e?.stderr || '').trim().split('\n').filter(Boolean).at(-1) || String(e?.message ?? e).split('\n')[0]);
 
@@ -259,8 +380,15 @@ export async function launchRecorder(chromium, options, { log = () => {}, instal
 
 // Records `config.url` (a page that loads player/v1) and writes the MP4.
 // config: { url, geometry, captions, avatar, titleCard, endCard, title,
-// presenter, link, out, firstPartyOrigins, playerDir }. `log` gets progress
-// lines. Returns { file, seconds, width, height, bytes, slides, clips, warnings }.
+// presenter, link, out, firstPartyOrigins, playerDir, range, plan, segment }.
+// range { from, to }: only those slides (0-based, inclusive); the title card
+// only when it starts at the first slide, the end card only when it ends at the
+// last. plan({ seconds, ranges }) → { to, segment }: asked once the player's
+// plan is read (the render worker's lead job asks Convex how to split);
+// segment: true then records slides 0..to as a segment. segment: the file is
+// video only, and the result's `segment` { from, to, frames, clips } says where
+// each clip started in it (joinVideo). `log` gets progress lines. Returns
+// { file, seconds, width, height, bytes, slides, clips, warnings, segment? }.
 export async function recordVideo(config, { log = () => {}, chromium: injected, install } = {}) {
   const { geometry, out } = config;
   const ff = await ffmpegPath();
@@ -279,10 +407,15 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     await noteSoftwareWebgl(browser, log);
     const pageUrl = exportPageUrl(config.url, config);
     const context = await browser.newContext({ viewport: geometry.viewport, deviceScaleFactor: geometry.scale, serviceWorkers: 'block', acceptDownloads: false });
-    const blockedUrls = [];
-    let failed = null;
+    const blockedUrls = [], unreachable = [];
+    let refused = 0, failed = null;
     await context.route('**/*', async (route) => {
-      if (!await routeCaptureRequest(route, pageUrl, config.firstPartyOrigins)) blockedUrls.push(route.request().url());
+      if (await routeCaptureRequest(route, pageUrl, config.firstPartyOrigins)) return;
+      const r = route.request();
+      blockedUrls.push(r.url());
+      // Refused by rule (expected) or allowed but unreachable (worth naming).
+      if (allowCaptureRequest(r.url(), r.method(), r.resourceType(), pageUrl, config.firstPartyOrigins)) unreachable.push(r.url());
+      else refused++;
     });
     // A development checkout plays its own player/v1 (HYPERDECKS_PLAYER_DIR), not the released one.
     if (config.playerDir) {
@@ -297,6 +430,8 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     await context.routeWebSocket('**/*', (ws) => ws.close());
     // The page clock goes in before any of the deck's scripts (frame-clock.mjs).
     await context.addInitScript({ content: `(${installFrameClock.toString()})(window);` });
+    // A range opens on its first slide (export-mode.js exportRangeStart).
+    if (config.range?.from > 0) await context.addInitScript((from) => { window.__hdExportFrom = from; }, config.range.from);
     await context.addInitScript(() => {
       navigator.sendBeacon = () => false;
       window.open = () => null;
@@ -313,17 +448,39 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     await page.goto(pageUrl, { waitUntil: 'domcontentloaded', timeout: 60000 });
     phase = 'player ready';
     const pageSaid = () => (pageErrors.length ? ` (page errors: ${pageErrors.slice(0, 3).join('; ').slice(0, 400)})` : '');
-    await page.waitForSelector('body[data-hd-ready="true"]', { timeout: 60000 }).catch((e) => {
-      throw new Error(`the deck never became ready (${e.message.split('\n')[0]})${pageSaid()}${readySaw({ blocked: blockedUrls, failed })}; is it on player/v1 (https://decks.hypersocial.ai/player/v1/player.js)?`);
+    const readyWait = readyTimeoutMs(config);
+    await page.waitForSelector('body[data-hd-ready="true"]', { timeout: readyWait }).catch(() => {
+      const saw = readySaw({ refused, unreachable, failed });
+      // Nothing failed and no page error: the deck was still loading (a slow machine), not broken.
+      const hint = unreachable.length || failed || pageErrors.length
+        ? 'is it on player/v1 (https://hyperdecks.ai/player/v1/player.js)?'
+        : 'nothing failed, so it was probably still loading on a slow machine: raise HYPERDECKS_READY_TIMEOUT_MS (ms) to wait longer';
+      throw new Error(`the deck was not ready after ${Math.round(readyWait / 1000)}s${pageSaid()}${saw}; ${hint}`);
     });
     let state = await readLog(page, 30000);
     if (state === undefined) throw new Error(`the deck's player did not return its export log within 30s${pageSaid()}`);
-    if (!state) throw new Error(`the deck's player has no export mode: it must load https://decks.hypersocial.ai/player/v1/player.js (an older copy, or its own runtime, cannot be recorded)${pageSaid()}`);
+    if (!state) throw new Error(`the deck's player has no export mode: it must load https://hyperdecks.ai/player/v1/player.js (an older copy, or its own runtime, cannot be recorded)${pageSaid()}`);
     if (state.manifestError) throw new Error(`the deck's narration manifest could not load (${state.manifestError.url}: ${state.manifestError.message}); nothing was recorded`);
     if (state.silent) throw new Error('the deck has no narration to record: run `hyperdecks narrate` first');
     // An older player plays its narration on wall time, which a frame-by-frame recording cannot follow.
-    if (!(state.version >= 2 && state.clock === 'page')) throw new Error('the deck\'s player is older than this CLI (its narration cannot follow a frame-by-frame recording); reload https://decks.hypersocial.ai/player/v1/player.js, or update the deck\'s copy');
+    if (!(state.version >= 2 && state.clock === 'page')) throw new Error('the deck\'s player is older than this CLI (its narration cannot follow a frame-by-frame recording); reload https://hyperdecks.ai/player/v1/player.js, or update the deck\'s copy');
     const plan = planTimeline(state.plan ?? []);
+    const last = plan.ids.length - 1;
+    let range = config.range ?? null, segment = !!config.segment;
+    if (config.plan) {
+      // Videos and embedded pages per slide, read from the page: the split balances by time to render.
+      const media = await within(page.evaluate((ids) => ids.map((id) => document.getElementById(id)?.querySelectorAll('video, iframe').length ?? 0), plan.ids), 10000, null).catch(() => null);
+      const weights = Array.isArray(media) && media.length === plan.ids.length ? media.map(slideWeight) : undefined;
+      const answer = await config.plan({ seconds: plan.seconds, ranges: state.range === true && splittableAudio(state.plan ?? []), ...(weights ? { weights } : {}) });
+      if (answer?.segment) { range = { from: 0, to: answer.to }; segment = true; }
+    }
+    if (range) {
+      const { from, to } = range;
+      if (!(Number.isInteger(from) && Number.isInteger(to) && from >= 0 && from <= to && to <= last)) throw new Error(`slides ${from + 1}-${to + 1} are not in this deck (it has ${plan.ids.length})`);
+      if ((from > 0 || to < last) && state.range !== true) throw new Error('the deck\'s player is older than this CLI (it cannot record a range of slides); reload https://hyperdecks.ai/player/v1/player.js, or update the deck\'s copy');
+    }
+    const from = range?.from ?? 0, to = range?.to ?? last;
+    const inRange = (id) => { const i = plan.ids.indexOf(id); return i >= from && i <= to; };
     const face = state.presenter;
     if (config.avatar !== false && face?.wanted === 'head' && face.shown !== 'head') warnings.push(`the deck's live head did not load${face.why ? ` (${face.why})` : ''}; the video shows ${face.shown === 'static' ? 'its still image' : 'captions only'}`);
     // The cards wear the first slide's colours and its heading's font.
@@ -343,25 +500,22 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     }), 5000, {});
     // Every clip's audio is fetched before recording: a bad URL fails now, not after minutes of real time.
     phase = 'clip audio';
+    // A range needs only its own slides' clips.
     const audioFiles = new Map(), clipLengths = {};
-    for (const [n, url] of [...new Set((state.plan ?? []).map((s) => s.audio).filter(Boolean))].entries()) {
-      const id = state.plan.find((s) => s.audio === url).id;
-      if (!await allowCaptureDestination(url, pageUrl)) throw new Error(`clip ${id}'s audio is not on a public address: ${url}`);
-      let res;
-      try { res = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(30000) }); }
-      catch (e) { throw new Error(`could not download clip ${id}'s audio (${url}): ${e.cause?.message ?? e.message}`); }
-      if (!res.ok) throw new Error(`could not download clip ${id}'s audio (${res.status} from ${url})`);
-      const bytes = Buffer.from(await res.arrayBuffer());
-      if (bytes.length > MAX_CLIP_BYTES) throw new Error(`clip ${id}'s audio is over ${MAX_CLIP_BYTES / 1024 / 1024} MB`);
-      const path = join(temp, `clip-${n}${extname(new URL(url).pathname).slice(0, 6) || '.audio'}`);
-      await writeFile(path, bytes);
+    const wanted = (state.plan ?? []).filter((s) => inRange(s.id));
+    for (const [n, url] of [...new Set(wanted.map((s) => s.audio).filter(Boolean))].entries()) {
+      const id = wanted.find((s) => s.audio === url).id;
+      const path = clipPath(temp, n, url);
+      await downloadClip(url, path, { id, entryUrl: pageUrl });
       audioFiles.set(url, path);
       clipLengths[url] = await clipSeconds(ff, path).catch((e) => { throw new Error(`clip ${id}'s audio: ${e.message}`); });
     }
-    log(`recording ${plan.ids.length} slides${plan.total ? `, about ${clock(plan.total)} of video,` : ''} at ${geometry.width}×${geometry.height} (${geometry.shape}), frame by frame`);
+    const part = from > 0 || to < last ? ` (slides ${from + 1}-${to + 1}${segment ? ', a segment' : ''})` : '';
+    log(`recording ${plan.ids.length} slides${part}${plan.total ? `, about ${clock(plan.total)} of video,` : ''} at ${geometry.width}×${geometry.height} (${geometry.shape}), frame by frame`);
 
     // The title card's frames come first.
-    const lead = config.titleCard ? TITLE_CARD_SECONDS : 0;
+    const titleCard = config.titleCard && from === 0, endCard = config.endCard && to === last;
+    const lead = titleCard ? TITLE_CARD_SECONDS : 0;
     const card = async (lines) => {
       const p = await context.newPage();
       await p.setContent(cardHtml({ lines, ...look, base: pageUrl, width: geometry.viewport.width, height: geometry.viewport.height }), { waitUntil: 'load', timeout: 15000 }).catch((e) => warnings.push(`a card's fonts did not finish loading (${e.message.split('\n')[0]}); it may show a fallback font`));
@@ -378,7 +532,7 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
       for (let i = 1; i < n; i++) await copyFile(first, join(temp, frameName(frameCount + i)));
       frameCount += n;
     };
-    if (config.titleCard) {
+    if (titleCard) {
       phase = 'title card';
       await repeat(await card([config.title, config.presenter ? `Presented by ${config.presenter}` : null]), TITLE_CARD_SECONDS);
     }
@@ -400,11 +554,14 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     // Frame 0 is the deck as it starts; frame n shows it n/fps seconds later on the page clock.
     const markMs = await page.evaluate(() => performance.timeOrigin + window.__hdFrameClock.freeze());
     // Each clip ends where its real audio does (the manifest's length can be off), as <audio> would end it.
-    await page.evaluate((lengths) => { window.__hdExportClipLengths = lengths; window.__hdExportGo(); return window.__hdFrameClock.settle(); }, clipLengths);
+    // A range's tour ends after its last slide (export-mode.js exportRangeEnd).
+    await page.evaluate(({ lengths, to }) => { window.__hdExportClipLengths = lengths; if (to != null) window.__hdExportTo = to; window.__hdExportGo(); return window.__hdFrameClock.settle(); }, { lengths: clipLengths, to: range ? to : null });
     const firstFrame = frameCount;
     await capture();
     const secondsOf = new Map(plan.ids.map((id, i) => [id, plan.seconds[i]]));
     let shown = 0, progress = 0, movedAt = 0, end = Infinity;
+    // A segment's seam frames (SEAM_FRAMES): recorded past its end, dropped from its start.
+    const tail = segment && to < last ? SEAM_FRAMES : 0, skip = segment && from > 0 ? SEAM_FRAMES : 0;
     // Stuck: no slide landed and no clip started for longer than the current
     // slide's planned clip and hold (unknown for a data-clip deck) plus a grace, on the page clock.
     for (let n = 1; n < end; n++) {
@@ -430,9 +587,9 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
           log(`  slide ${i + 1}/${plan.ids.length} ${s.id} · ${clock(Math.max(0, (s.at - markMs) / 1000))}${plan.total ? ` of ${clock(plan.total)}` : ''}`);
         }
         // The video ends on the frame where the tour ended.
-        if (state.done) end = Math.max(n + 1, Math.round(((state.doneAt - markMs) / 1000) * fps));
+        if (state.done) end = Math.max(n + 1, Math.round(((state.doneAt - markMs) / 1000) * fps) + tail);
       }
-      const on = state.slides?.at(-1)?.id ?? plan.ids[0];
+      const on = state.slides?.at(-1)?.id ?? plan.ids[from];
       const allowed = (secondsOf.get(on) || 0) * 1.5 + STUCK_GRACE_SECONDS;
       if (end === Infinity && at - movedAt > allowed) throw new Error(`the tour stopped on slide ${on}: nothing moved for ${Math.round(allowed)}s of the deck${pageSaid()}`);
     }
@@ -447,7 +604,7 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     if (Math.abs(worst.drift) > 2) warnings.push(`the player ran up to ${worst.drift.toFixed(1)}s off the manifest's timeline (by ${worst.id}: clip loads, transitions); each clip's audio is placed where it really started, so the voice stays in sync`);
     const render = { frames, seconds: wall };
 
-    if (config.endCard) {
+    if (endCard) {
       phase = 'end card';
       await repeat(await card([config.title, config.link]), END_CARD_SECONDS);
     }
@@ -459,14 +616,41 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
 
     phase = 'audio';
     const clips = audioTimeline(state, markMs, lead);
-    const missing = plan.ids.filter((id) => !clips.some((c) => c.id === id) && (state.plan.find((s) => s.id === id)?.audio));
+    // A seam's tail plays the next slide's clip too: that one is the next segment's.
+    const own = clips.filter((c) => inRange(c.id));
+    const missing = plan.ids.filter((id) => inRange(id) && !clips.some((c) => c.id === id) && (state.plan.find((s) => s.id === id)?.audio));
     if (missing.length) warnings.push(`no audio started for ${missing.join(', ')}`);
+    const total = frameCount / VIDEO_FPS;
+    const place = async (encoded) => {
+      await rename(encoded, out).catch(async (e) => {
+        if (e.code !== 'EXDEV') throw e;
+        await copyFile(encoded, out);
+      });
+      return (await stat(out)).size;
+    };
+    const encodeMs = Math.round(Math.max(300000, total * 20000) * geometry.scale);
+    if (segment) {
+      // The picture only: the join lays the whole deck's audio under all the segments at once.
+      phase = 'encode';
+      if (frameCount - skip < 1) throw new Error(`slides ${from + 1}-${to + 1} are shorter than the ${SEAM_SECONDS}s seam`);
+      const kept = frameCount - skip;
+      log(`encoding ${clock(kept / VIDEO_FPS)} of video…`);
+      const encoded = join(temp, 'video.mp4');
+      await ffmpeg(ff, encodeArgs({ frames: join(temp, 'frame-%06d.jpg'), audio: null, width: geometry.width, height: geometry.height, out: encoded, startNumber: skip }), encodeMs);
+      const bytes = await place(encoded);
+      if (pageErrors.length) warnings.push(`${pageErrors.length} page error(s) while recording: ${pageErrors.slice(0, 2).join('; ').slice(0, 300)}`);
+      return {
+        file: out, seconds: kept / VIDEO_FPS, width: geometry.width, height: geometry.height, bytes, slides: to - from + 1, clips: own.length, render, warnings,
+        // frames: in the file. A clip's offset is from the file's first frame:
+        // after a dropped seam, a slide's clip may start (just) before it.
+        segment: { from, to, frames: kept, tail, clips: own.map((c) => ({ id: c.id, audio: c.audio, offset: c.offset - skip / VIDEO_FPS })) },
+      };
+    }
     const inputs = clips.map((c) => {
       const path = audioFiles.get(c.audio);
       if (!path) throw new Error(`clip ${c.id} played audio the plan did not list (${c.audio})`);
       return { path, offset: c.offset };
     });
-    const total = frameCount / VIDEO_FPS;
     const audio = join(temp, 'audio.wav');
     await ffmpeg(ff, audioMixArgs({ inputs, seconds: total, out: audio }), 300000);
 
@@ -474,18 +658,81 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     log(`encoding ${clock(total)} of video…`);
     // Encoded beside the temp frames, then moved into place: a failed encode never leaves a broken file at `out`.
     const encoded = join(temp, 'video.mp4');
-    await ffmpeg(ff, encodeArgs({ frames: join(temp, 'frame-%06d.jpg'), audio, width: geometry.width, height: geometry.height, out: encoded }), Math.round(Math.max(300000, total * 20000) * geometry.scale));
+    await ffmpeg(ff, encodeArgs({ frames: join(temp, 'frame-%06d.jpg'), audio, width: geometry.width, height: geometry.height, out: encoded }), encodeMs);
+    const bytes = await place(encoded);
+    if (pageErrors.length) warnings.push(`${pageErrors.length} page error(s) while recording: ${pageErrors.slice(0, 2).join('; ').slice(0, 300)}`);
+    return { file: out, seconds: total, width: geometry.width, height: geometry.height, bytes, slides: to - from + 1, clips: clips.length, render, warnings };
+  } catch (e) {
+    throw new Error(`Video export failed during ${phase}: ${e.message}`);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    if (temp) await rm(temp, { recursive: true, force: true });
+  }
+}
+
+// Joins segments recorded by recordVideo({ segment: true }), in order, into
+// one MP4: the whole deck's audio mixed once over the joined timeline (each
+// clip where its segment says it started, after the frames before it), the
+// picture copied as is (the segments share their encode settings), or
+// re-encoded once if the copy fails. segments: [{ file, frames, clips }].
+// Clip audio comes only from public addresses, or from `origin` (the deck's
+// page, for a local deck). Returns { file, seconds, bytes, frames, reencoded, warnings }.
+export async function joinVideo({ segments, out, origin = null }, { log = () => {} } = {}) {
+  if (!Array.isArray(segments) || !segments.length) throw new Error('joinVideo needs at least one segment');
+  const ff = await ffmpegPath();
+  const warnings = [];
+  let temp, phase = 'clip audio';
+  try {
+    temp = await mkdtemp(join(tmpdir(), 'hyperdecks-join-'));
+    log(`joining ${segments.length} segments…`);
+    const timeline = joinTimeline(segments);
+    const files = new Map();
+    for (const c of timeline.clips) {
+      if (files.has(c.audio)) continue;
+      const path = clipPath(temp, files.size, c.audio);
+      await downloadClip(c.audio, path, { id: c.id, entryUrl: origin ?? 'https://origin.invalid/' });
+      files.set(c.audio, path);
+    }
+    phase = 'audio';
+    const audio = join(temp, 'audio.wav');
+    await ffmpeg(ff, audioMixArgs({ inputs: timeline.clips.map((c) => ({ path: files.get(c.audio), offset: c.offset })), seconds: timeline.seconds, out: audio }), 300000);
+    phase = 'join';
+    const list = join(temp, 'segments.txt');
+    await writeFile(list, concatList(segments.map((s) => s.file)));
+    log(`encoding ${clock(timeline.seconds)} of video…`);
+    const encoded = join(temp, 'video.mp4');
+    let reencoded = false;
+    // A joined file must be as long as its segments' frames say: a short or
+    // damaged piece would otherwise cut the picture and (-shortest) the voice.
+    const checked = async () => {
+      const got = await probe(ff, encoded);
+      if (got.seconds == null) throw new Error('ffmpeg could not read the joined file back');
+      if (Math.abs(got.seconds - timeline.seconds) > 0.25) throw new Error(`the joined video is ${got.seconds.toFixed(2)}s, not the ${timeline.seconds.toFixed(2)}s its segments hold (a segment is short or damaged)`);
+      return got;
+    };
+    let got;
+    try {
+      await ffmpeg(ff, joinArgs({ list, audio, out: encoded }), Math.max(300000, timeline.seconds * 2000));
+      got = await checked();
+    } catch (e) {
+      reencoded = true;
+      warnings.push(`the segments were re-encoded at the join (copying them failed: ${e.message.slice(0, 200)})`);
+      try {
+        await ffmpeg(ff, joinArgs({ list, audio, out: encoded, reencode: true }), Math.max(300000, timeline.seconds * 20000));
+        got = await checked();
+      } catch (again) {
+        throw new Error(`${again.message} (copying had failed first: ${e.message.slice(0, 200)})`);
+      }
+    }
     await rename(encoded, out).catch(async (e) => {
       if (e.code !== 'EXDEV') throw e;
       await copyFile(encoded, out);
     });
     const bytes = (await stat(out)).size;
-    if (pageErrors.length) warnings.push(`${pageErrors.length} page error(s) while recording: ${pageErrors.slice(0, 2).join('; ').slice(0, 300)}`);
-    return { file: out, seconds: total, width: geometry.width, height: geometry.height, bytes, slides: plan.ids.length, clips: clips.length, render, warnings };
+    return { file: out, seconds: timeline.seconds, width: got.width, height: got.height, bytes, frames: timeline.frames, reencoded, warnings };
   } catch (e) {
-    throw new Error(`Video export failed during ${phase}: ${e.message}`);
+    throw new Error(`Video join failed during ${phase}: ${e.message}`);
   } finally {
-    if (browser) await browser.close().catch(() => {});
     if (temp) await rm(temp, { recursive: true, force: true });
   }
 }
@@ -529,7 +776,7 @@ export async function exportVideo(arg, opts = {}, { log = (l) => process.stderr.
     log(`recording ${source.slug}${local ? ' (working copy)' : ' (released copy)'} → ${out}`);
     const result = await recordVideo({
       url: source.url, geometry: o.geometry, captions: o.captions, avatar: o.avatar, titleCard: o.titleCard, endCard: o.endCard,
-      title: source.title, presenter: source.presenter, link, out, playerDir: process.env.HYPERDECKS_PLAYER_DIR || null,
+      title: source.title, presenter: source.presenter, link, out, playerDir: process.env.HYPERDECKS_PLAYER_DIR || null, range: o.range,
     }, { log });
     let uploaded = null;
     if (o.upload) {

package/src/exportHelp.mjs

@@ -3,7 +3,7 @@
 
 export const VIDEO_EXPORT_HELP =
   "kind \"mp4\" records the narrated deck as a video on our render worker (drawn frame by frame, " +
-  "so it takes several times the deck's length: a 4-minute deck about half an hour), with the options size (720p, 1080p, 4k), shape (16:9, 9:16, 1:1), captions, avatar, " +
+  "split across several machines: a 4-minute deck takes about 12 minutes), with the options size (720p, 1080p, 4k), shape (16:9, 9:16, 1:1), captions, avatar, " +
   "titleCard and endCard (the deck's tracked link). It returns { exportId, status: \"queued\" } at once: poll " +
   "check_export(exportId) every 20-30 seconds until status is ready (url is the MP4, kept 30 days; title and description " +
   "are ready for YouTube) or failed (error says why). The owner is also emailed the link. One video per deck at a time, " +

package/src/files.mjs

@@ -17,6 +17,7 @@ const FILES = {
   "templates/layouts/number.html": () => new URL("../templates/layouts/number.html", import.meta.url),
   "templates/layouts/product.html": () => new URL("../templates/layouts/product.html", import.meta.url),
   "templates/layouts/phones.html": () => new URL("../templates/layouts/phones.html", import.meta.url),
+  "templates/layouts/split.html": () => new URL("../templates/layouts/split.html", import.meta.url),
   "templates/layouts/quote.html": () => new URL("../templates/layouts/quote.html", import.meta.url),
   "templates/layouts/team.html": () => new URL("../templates/layouts/team.html", import.meta.url),
   "templates/layouts/timeline.html": () => new URL("../templates/layouts/timeline.html", import.meta.url),

package/src/firstDeck.mjs

@@ -78,7 +78,7 @@ export function fillFirstDeck({ html, title, answers, presenter, voice }) {
   // A character's live head presents its own deck; a person's voice ships with
   // captions only (data-presenter="none"), never on a character's face.
   if (presenter === "dash") {
-    out = swap(out, /(<script type="module" src="https:\/\/decks\.hypersocial\.ai\/player\/v1\/player\.js"[^>]*?)\sdata-presenter="none"/, (_, tag) => `${tag} data-presenter="head" data-avatar="${DASH_AVATAR}"`, "player tag");
+    out = swap(out, /(<script type="module" src="https:\/\/(?:decks\.hypersocial\.ai|hyperdecks\.ai)\/player\/v1\/player\.js"[^>]*?)\sdata-presenter="none"/, (_, tag) => `${tag} data-presenter="head" data-avatar="${DASH_AVATAR}"`, "player tag");
   }
   const s = (t) => slots(t, answers, false);
   const script = `---

package/src/guide.mjs

@@ -8,7 +8,7 @@ import { packageText } from "./files.mjs";
 import { LAYOUTS, readLayout } from "./layouts.mjs";
 import { fontPairingsMarkdown } from "./brand.mjs";
 
-export const GUIDE_TOPICS = ["workflow", "format", "script", "scripts", "design", "layouts", "presenter", "transitions", "check"];
+export const GUIDE_TOPICS = ["workflow", "format", "script", "scripts", "design", "look", "layouts", "presenter", "transitions", "check"];
 const CLI_NOTE = "_Written for the CLI. On the hosted MCP there is no folder: use the tool names in `deck_guide` (workflow), hosted URLs for every file, and write_deck_source for edits._\n\n";
 
 // One <!-- topic: name --> section of SKILL.md: its heading and body, up to the

package/src/layouts.mjs

@@ -5,8 +5,8 @@ import { packageText } from "./files.mjs";
 
 export const NARRATED_FILES = { "index.html": "narrated-deck.html", "script.md": "script.md", "evidence.md": "evidence.md" };
 // The library, in a sensible deck order; `--layouts` takes any order and repeats.
-export const LAYOUTS = ["hero", "number", "product", "phones", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
-const LAYOUT_ALIASES = { "big-number": "number", "product-shot": "product", "phone-row": "phones", comparison: "compare", "three-up": "features" };
+export const LAYOUTS = ["hero", "number", "product", "split", "phones", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
+const LAYOUT_ALIASES = { "big-number": "number", "product-shot": "product", "phone-row": "phones", comparison: "compare", "three-up": "features", "image-copy": "split", "image-text": "split" };
 
 const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");