@hypersocial/decks-cli 0.9.2 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -144,6 +144,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | Ship | `hyperdecks release decks/<slug> --to "<name>" --email <e>` | `release_deck` |
 | Share-link poster | `hyperdecks poster <slug>` | `generate_deck_poster` |
 | PDF for a data room or attachment | `hyperdecks export <slug> --pdf [--notes] --out deck.pdf`, `hyperdecks export list` | `export_deck`, `list_exports` |
+| Video (MP4) for YouTube, LinkedIn or an attachment | `hyperdecks export <slug\|deck-dir> --video [--size 1080p\|720p\|4k] [--shape 16:9\|9:16\|1:1] [--title-card] [--end-card] [--no-captions] [--no-avatar] [--upload] --out deck.mp4`: records the narrated player in real time (a 4-minute deck takes about 5), avatar, voice and captions, no player chrome; a slug records the released copy, a deck folder its working copy; `--upload` lists it with the deck's exports | `export_deck { kind: "mp4" }` answers with this command (CLI only until the render worker ships) |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
 | One more link | `hyperdecks share new <slug> "<name>" [--no-forward]` | `create_share` (`allowForward`) |
 | Forwarding, one link | `hyperdecks share forward on\|off\|default <token>` | `set_share_forwarding` |

package/skills/hyperdecks/chat.md

@@ -103,6 +103,9 @@ makes the hello deck; continue from step 5 below.
    days; `notes: true` adds the slide's script after each slide.
    `list_exports` shows what was exported. Release first: it prints the live
    deck, not the draft.
+   A video (MP4) is recorded by the CLI for now: `export_deck { kind: "mp4" }`
+   answers with the `hyperdecks export <slug> --video` command; give it to the
+   user to run (it records in real time, so a 4-minute deck takes about 5).
 
 ## Rules that matter
 

package/src/commands.mjs

@@ -10,6 +10,7 @@ import {
   VERSION,
 } from "./runtime.mjs";
 import * as ops from "./ops.mjs";
+import { exportVideo } from "./export-video.mjs";
 import { presenterLine } from "./presenter.mjs";
 
 export const playbackLabel = (p) => p.narrationFinished ? "narration finished"
@@ -413,6 +414,13 @@ commands:
   export <slug|deck-dir> --pdf [--notes] [--out <file.pdf>] [--share <token>] [--json]
                    a PDF of the released deck: one 1600x900 page per slide (a script page after each
                    with --notes), a footer with the deck's tracked link; kept 30 days
+  export <slug|deck-dir> --video [--size 1080p|720p|4k] [--shape 16:9|9:16|1:1] [--no-captions]
+         [--no-avatar] [--title-card] [--end-card [--link <url>]] [--upload] [--out <file.mp4>] [--json]
+                   an MP4 of the narrated deck, recorded in real time (a 4-minute deck takes about
+                   5): the avatar, voice and captions, none of the player's chrome. A slug records
+                   the released copy, a deck folder its working copy. --title-card adds the title
+                   and presenter (2s), --end-card the deck's "Video viewers" link (3s); --upload
+                   keeps it with the deck's exports for 30 days
   export list [<slug>] [--json]    your exports and their download links
   export rm <exportId>             delete an export now
   poster <slug> [--force] [--json]
@@ -679,12 +687,18 @@ export function exportTarget(arg, opts = {}, cwd = process.cwd()) {
   return { slug: opts.slug || basename(dir), script: existsSync(scriptPath) ? readFileSync(scriptPath, "utf8") : undefined };
 }
 
+export const EXPORT_USAGE = "usage: export <slug|deck-dir> --pdf [--notes] [--out <file.pdf>] [--share <token>]\n" +
+  "       export <slug|deck-dir> --video [--size 1080p|720p|4k] [--shape 16:9|9:16|1:1] [--no-captions] [--no-avatar] [--title-card] [--end-card [--link <url>]] [--upload] [--out <file.mp4>]";
+
 async function exportCmd(pos, opts) {
   const [arg] = pos;
-  const usage = "usage: export <slug|deck-dir> --pdf [--notes] [--out <file.pdf>] [--share <token>]";
+  const usage = EXPORT_USAGE;
   if (!arg) throw new Error(usage);
-  if (opts.mp4 || opts.gif) throw new Error("only --pdf exports are available so far (video comes later; the email GIF is `hyperdecks preview create`)");
-  if (!opts.pdf) throw new Error(`${usage}\n(--pdf is the only format so far)`);
+  if (opts.gif) throw new Error("the email GIF is `hyperdecks preview create`");
+  const video = opts.video || opts.mp4;
+  if (video && opts.pdf) throw new Error("pick one of --pdf and --video");
+  if (video) return void (await exportVideo(arg, opts));
+  if (!opts.pdf) throw new Error(`${usage}\n(pick --pdf or --video)`);
   const { slug, script } = exportTarget(arg, opts);
   if (slug !== arg) process.stderr.write(`deck folder ${arg} → slug ${slug} (pass --slug to change it)\n`);
   process.stderr.write(`rendering ${slug} as a PDF${opts.notes ? " with notes" : ""}…\n`);

package/src/export-video.mjs

@@ -0,0 +1,502 @@
+// hyperdecks export <slug|deck-dir> --video: a narrated deck as an MP4.
+//
+// Real time, as the email GIF preview records (preview-capture.mjs): Chromium
+// opens the deck in the player's export mode (?export=1: no chrome, autoplay,
+// no tracking; packages/player/export-mode.js) and the compositor's screencast
+// is written to disk at 30 fps until the tour ends. The screencast has no
+// sound, so the audio track is built from the clips themselves, each placed at
+// the moment the player really started it (window.__hdExport), so the voice
+// lands under the frames that show its captions and cues. An optional title
+// 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.
+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, routeCaptureRequest } from './preview-capture.mjs';
+
+const run = promisify(execFile);
+
+export const VIDEO_FPS = 30;
+export const VIDEO_SIZES = Object.freeze({ '720p': 720, '1080p': 1080, '4k': 2160 });
+export const VIDEO_SHAPES = Object.freeze(['16:9', '9:16', '1:1']);
+export const TITLE_CARD_SECONDS = 2;
+export const END_CARD_SECONDS = 3;
+// What the player's clock may run past the manifest's total before the export
+// is called stuck: slow clip loads and transitions add a little per slide.
+const STUCK_GRACE_SECONDS = 60;
+const MAX_CLIP_BYTES = 50 * 1024 * 1024;
+
+// Output pixels, and the viewport that draws them: 4K is the 1080p layout at
+// device scale 2, so a slide is laid out the same and drawn sharper. 9:16 and
+// 1:1 are viewports of that shape; the player's overlay layout letterboxes the
+// 16:9 stage on the deck's page colour.
+export function videoGeometry(size = '1080p', shape = '16:9') {
+  const short = VIDEO_SIZES[size];
+  if (!short) throw new Error(`--size must be one of ${Object.keys(VIDEO_SIZES).join(', ')} (got ${size})`);
+  if (!VIDEO_SHAPES.includes(shape)) throw new Error(`--shape must be one of ${VIDEO_SHAPES.join(', ')} (got ${shape})`);
+  const long = Math.round((short * 16) / 9);
+  const [width, height] = shape === '16:9' ? [long, short] : shape === '9:16' ? [short, long] : [short, short];
+  const scale = size === '4k' ? 2 : 1;
+  return { size, shape, width, height, scale, viewport: { width: width / scale, height: height / scale } };
+}
+
+// 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`);
+  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) {
+    let u;
+    try { u = new URL(opts.link); } catch { throw new Error(`--link must be a URL (got ${opts.link})`); }
+    if (!['http:', 'https:'].includes(u.protocol)) throw new Error('--link must be an http(s) URL');
+  }
+  if (opts.notes || opts.share) throw new Error('--notes and --share are PDF options; a video has neither');
+  return {
+    geometry,
+    captions: !opts['no-captions'],
+    avatar: !opts['no-avatar'],
+    titleCard: !!opts['title-card'],
+    endCard: !!opts['end-card'],
+    link: opts.link ?? null,
+    out: opts.out ?? null,
+    upload: !!opts.upload,
+  };
+}
+
+// The page the recorder opens: the deck in export mode.
+export function exportPageUrl(url, { captions = true, avatar = true } = {}) {
+  const u = new URL(url);
+  u.searchParams.set('export', '1');
+  if (!captions) u.searchParams.set('captions', '0');
+  if (!avatar) u.searchParams.set('avatar', '0');
+  return u.href;
+}
+
+// The player's own timeline (navigation.js deckTimeline): each slide runs its
+// clip then its hold, back to back. `plan` is what the player logged at ready:
+// [{ id, duration, hold }] in slide order.
+export function planTimeline(plan) {
+  const seconds = plan.map((s) => Math.max(0, (Number(s.duration) || 0) + (Number(s.hold) || 0)));
+  const starts = seconds.map((_, i) => seconds.slice(0, i).reduce((a, b) => a + b, 0));
+  return { ids: plan.map((s) => s.id), seconds, starts, total: seconds.reduce((a, b) => a + b, 0) };
+}
+
+// Each clip's audio and where it goes in the video, in seconds: when the
+// player started it, measured from the first recorded frame (`markMs`), after
+// a title card of `lead` seconds. A clip the player never started (the tour
+// stopped early) is left out; the caller warns.
+export function audioTimeline(log, markMs, lead = 0) {
+  const audioOf = new Map((log.plan ?? []).map((s) => [s.id, s.audio]));
+  return (log.clips ?? [])
+    .map((c) => ({ id: c.id, audio: c.audio ?? audioOf.get(c.id) ?? null, offset: lead + Math.max(0, (c.at - markMs) / 1000) }))
+    .filter((c) => c.audio);
+}
+
+// How far each clip started from where the manifest's timeline puts it, for a
+// warning: a slow clip load pushes everything after it later (the audio still
+// follows the player, so the video stays in sync).
+export function timelineDrift(log, markMs) {
+  const plan = planTimeline(log.plan ?? []);
+  const startOf = new Map(plan.ids.map((id, i) => [id, plan.starts[i]]));
+  return (log.clips ?? []).filter((c) => startOf.has(c.id)).map((c) => ({ id: c.id, drift: (c.at - markMs) / 1000 - startOf.get(c.id) }));
+}
+
+// ffmpeg args for the audio track, `seconds` long: silence up to the first
+// clip, then each clip padded with silence (or cut) to where the next one
+// starts, joined end to end. Clips never overlap (the player plays one at a
+// time), so nothing is mixed or normalised, and it needs no clip durations.
+// Only filters FFmpeg 4.1 has (the CLI's bundled build on Linux, Windows and
+// Intel Macs): aevalsrc, aresample, aformat, apad, atrim, asetpts, concat.
+export function audioMixArgs({ inputs, seconds, out }) {
+  const fmt = 'aresample=48000,aformat=sample_fmts=s16:channel_layouts=stereo';
+  const clips = [...inputs].filter((i) => i.offset < seconds).sort((a, b) => a.offset - b.offset);
+  const args = [];
+  for (const c of clips) args.push('-i', c.path);
+  const parts = [], labels = [];
+  const lead = clips.length ? clips[0].offset : seconds;
+  if (lead >= 0.001) {
+    parts.push(`aevalsrc=0|0:c=stereo:s=48000:d=${lead.toFixed(3)},${fmt}[lead]`);
+    labels.push('[lead]');
+  }
+  clips.forEach((c, n) => {
+    const end = n + 1 < clips.length ? clips[n + 1].offset : seconds;
+    parts.push(`[${n}:a]${fmt},apad,atrim=0:${Math.max(0.001, end - c.offset).toFixed(3)},asetpts=N/SR/TB[c${n}]`);
+    labels.push(`[c${n}]`);
+  });
+  parts.push(`${labels.join('')}concat=n=${labels.length}:v=0:a=1[mix]`);
+  return [...args, '-filter_complex', parts.join(';'), '-map', '[mix]', '-c:a', 'pcm_s16le', '-y', 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 }) {
+  return [
+    '-framerate', String(fps), '-i', frames,
+    '-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),
+    '-c:a', 'aac', '-b:a', '192k',
+    '-shortest', '-movflags', '+faststart', '-y', out,
+  ];
+}
+
+// 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, '');
+const escapeHtml = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+// A title or end card: the first slide's colour, ink and heading font, centred
+// text. `fonts` carries the deck's web fonts: its font stylesheet links and the
+// @font-face rules it could read, resolved against `base` (the deck's page).
+export function cardHtml({ lines, background = '#0b0b0f', color = '#ffffff', font = 'system-ui, sans-serif', width, height, fonts = { links: [], faces: '' }, base = null }) {
+  const [first, ...rest] = lines.filter(Boolean);
+  const unit = Math.min(width, height) / 1080;
+  const links = (fonts.links ?? []).filter((h) => /^https:\/\//.test(h)).map((h) => `<link rel="stylesheet" href="${escapeHtml(h)}">`).join('');
+  const faces = String(fonts.faces ?? '').replace(/<\/style/gi, '');
+  return `<!doctype html><html><head><meta charset="utf-8">${base ? `<base href="${escapeHtml(base)}">` : ''}${links}<style>${faces}
+html,body{margin:0;height:100%;background:${cssValue(background)};color:${cssValue(color)};font-family:${cssValue(font)}}
+body{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:${Math.round(28 * unit)}px;text-align:center;padding:0 8%;box-sizing:border-box}
+h1{font-size:${Math.round(84 * unit)}px;line-height:1.1;margin:0;font-weight:700;max-width:100%;overflow-wrap:anywhere}
+p{font-size:${Math.round(40 * unit)}px;margin:0;opacity:.8;max-width:100%;overflow-wrap:anywhere}
+</style></head><body><h1>${escapeHtml(first ?? '')}</h1>${rest.map((l) => `<p>${escapeHtml(l)}</p>`).join('')}</body></html>`;
+}
+
+const pad = (n) => String(n).padStart(6, '0');
+const frameName = (n) => `frame-${pad(n)}.jpg`;
+const clock = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`;
+
+async function ffmpegPath() {
+  try {
+    const path = (await import('@ffmpeg-installer/ffmpeg')).default.path;
+    await run(path, ['-version'], { timeout: 10000 });
+    return path;
+  } catch {
+    throw new Error('Portable FFmpeg missing. Reinstall the CLI with optional dependencies and install scripts enabled (`npm install -g hyperdecks --include=optional`); pnpm users must approve @ffmpeg-installer platform build scripts.');
+  }
+}
+
+async function ffmpeg(path, args, timeoutMs) {
+  try {
+    await run(path, ['-hide_banner', '-loglevel', 'error', '-nostdin', ...args], { timeout: Math.round(timeoutMs), maxBuffer: 4 * 1024 * 1024, env: { PATH: dirname(path), ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}) } });
+  } catch (e) {
+    throw new Error(`FFmpeg failed${e.killed ? ` (timed out after ${Math.round(timeoutMs / 1000)}s)` : ''}: ${String(e.stderr || e.message).trim().split('\n').slice(-3).join(' ')}`);
+  }
+}
+
+// Bounds a page.evaluate on the Node side (a busy main thread can hold it).
+async function within(promise, ms, fallback) {
+  promise.catch(() => {});
+  let timer;
+  try { return await Promise.race([promise, new Promise((ok) => { timer = setTimeout(() => ok(fallback), ms); })]); }
+  finally { clearTimeout(timer); }
+}
+
+// Screencast frames into numbered slots from `first`, one per 1/fps from
+// `mark` (epoch seconds): each slot holds the newest frame up to half a slot
+// past its time. `stop(seconds)` fills the slots up to that many seconds after `mark`
+// with the last frame and returns how many it wrote.
+function startFrameSlots(session, { dir, fps, first }) {
+  let mark = Infinity, last = null, next = 0, writes = Promise.resolve(), received = 0, stopped = false, failed = null;
+  // The first failed write (a full disk, say) is kept and thrown by check()/stop(), never left unhandled.
+  const write = (data) => {
+    const path = join(dir, frameName(first + next++));
+    writes = writes.then(() => (failed ? null : writeFile(path, data))).catch((e) => { failed ??= e; });
+  };
+  session.on('Page.screencastFrame', ({ data, metadata, sessionId }) => {
+    session.send('Page.screencastFrameAck', { sessionId }).catch(() => {});
+    const ts = metadata.timestamp ?? Date.now() / 1000;
+    if (stopped || ts < mark) return;
+    // A slot takes the frame nearest its time: one stamped up to half a slot after it beats the one before.
+    while (last && mark + (next + 0.5) / fps < ts) write(last);
+    last = Buffer.from(data, 'base64');
+    received++;
+  });
+  return {
+    get received() { return received; },
+    check() { if (failed) throw new Error(`could not write a frame: ${failed.message}`); },
+    get latest() { return mark + next / fps; },
+    begin(poster, at) { last = poster; mark = at; },
+    async stop(seconds) {
+      stopped = true;
+      const total = Math.max(1, Math.round(seconds * fps));
+      while (next < total) write(last);
+      await writes;
+      if (failed) throw new Error(`could not write a frame: ${failed.message}`);
+      return total;
+    },
+    settled: () => writes,
+  };
+}
+
+// The player's export log, read without trusting the page to answer quickly.
+const readLog = (page) => within(page.evaluate(() => {
+  const l = window.__hdExport;
+  return l ? JSON.parse(JSON.stringify(l)) : null;
+}), 5000, undefined);
+
+// 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 }.
+export async function recordVideo(config, { log = () => {}, chromium: injected } = {}) {
+  const { geometry, out } = config;
+  const ff = await ffmpegPath();
+  const chromium = injected ?? (await import('playwright')).chromium;
+  const warnings = [];
+  let browser, temp, phase = 'launch';
+  try {
+    temp = await mkdtemp(join(tmpdir(), 'hyperdecks-video-'));
+    try {
+      browser = await chromium.launch({
+        // config.sandbox: false only for CI runners whose AppArmor blocks Chromium's sandbox (the smoke suite).
+        headless: true, timeout: 30000, chromiumSandbox: config.sandbox ?? process.platform === 'linux',
+        args: ['--autoplay-policy=no-user-gesture-required', '--mute-audio', '--enable-unsafe-swiftshader'],
+        env: { ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}), PATH: process.env.PATH, TMPDIR: temp, HOME: temp },
+      });
+    } catch (e) {
+      throw new Error(`Could not launch isolated Chromium (${String(e?.message ?? e).split('\n')[0]}). Run \`hyperdecks preview setup\` to install it.`);
+    }
+    const pageUrl = exportPageUrl(config.url, config);
+    const context = await browser.newContext({ viewport: geometry.viewport, deviceScaleFactor: geometry.scale, serviceWorkers: 'block', acceptDownloads: false });
+    let blocked = 0;
+    await context.route('**/*', async (route) => { if (!await routeCaptureRequest(route, pageUrl, config.firstPartyOrigins)) blocked++; });
+    // A development checkout plays its own player/v1 (HYPERDECKS_PLAYER_DIR), not the released one.
+    if (config.playerDir) {
+      await context.route(/\/player\/v1\/[^?#]+/, async (route) => {
+        const name = new URL(route.request().url()).pathname.replace(/^.*\/player\/v1\//, '');
+        if (name.split('/').some((s) => s === '..' || s.startsWith('.'))) return route.abort();
+        const type = { '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.png': 'image/png' }[extname(name)] ?? 'application/octet-stream';
+        try { await route.fulfill({ body: await readFile(join(config.playerDir, name)), contentType: type }); }
+        catch { await route.abort(); }
+      });
+    }
+    await context.routeWebSocket('**/*', (ws) => ws.close());
+    await context.addInitScript(() => {
+      navigator.sendBeacon = () => false;
+      window.open = () => null;
+      // The player's export mode waits for this before it plays (export-mode.js).
+      window.__hdExportWait = new Promise((go) => { window.__hdExportGo = go; });
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(30000);
+    const pageErrors = [];
+    page.on('pageerror', (e) => pageErrors.push(String(e?.message ?? e)));
+    phase = 'page load';
+    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()}; is it on player/v1 (https://decks.hypersocial.ai/player/v1/player.js)?`);
+    });
+    let state = await readLog(page);
+    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.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');
+    const plan = planTimeline(state.plan ?? []);
+    // The cards wear the first slide's colours and its heading's font.
+    const look = await within(page.evaluate(() => {
+      const first = document.querySelector('section.slide');
+      const cs = (n) => n && getComputedStyle(n);
+      const solid = (c) => c && c !== 'rgba(0, 0, 0, 0)' && c !== 'transparent';
+      const slide = cs(first), body = cs(document.body), heading = cs(first?.querySelector('h1, h2, h3'));
+      const background = [slide?.backgroundColor, body?.backgroundColor].find(solid);
+      // Font stylesheets on another origin can't be read: link them; read the rest's @font-face rules.
+      const links = [...document.querySelectorAll('link[rel~="stylesheet"]')].map((l) => l.href).filter((h) => /^https:\/\/fonts\.(googleapis|bunny)\.net\//.test(h) || /^https:\/\/use\.typekit\.net\//.test(h));
+      const faces = [];
+      for (const sheet of document.styleSheets) {
+        try { for (const rule of sheet.cssRules) if (rule instanceof CSSFontFaceRule) faces.push(rule.cssText); } catch { /* cross-origin */ }
+      }
+      return { background: background ?? '#0b0b0f', color: heading?.color ?? slide?.color ?? '#ffffff', font: heading?.fontFamily ?? slide?.fontFamily ?? 'system-ui, sans-serif', fonts: { links, faces: faces.join('\n') } };
+    }), 5000, {});
+    // Every clip's audio is fetched before recording: a bad URL fails now, not after minutes of real time.
+    phase = 'clip audio';
+    const audioFiles = new Map();
+    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);
+      audioFiles.set(url, path);
+    }
+    log(`recording ${plan.ids.length} slides${plan.total ? `, about ${clock(plan.total)} in real time,` : ''} at ${geometry.width}×${geometry.height} (${geometry.shape})`);
+
+    // The title card's frames come first.
+    const lead = config.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`));
+      await within(p.evaluate(() => document.fonts.ready.then(() => true)), 5000, false);
+      const shot = await p.screenshot({ type: 'jpeg', quality: 92 });
+      await p.close();
+      return shot;
+    };
+    let frameCount = 0;
+    const repeat = async (image, seconds) => {
+      const first = join(temp, frameName(frameCount));
+      await writeFile(first, image);
+      const n = Math.round(seconds * VIDEO_FPS);
+      for (let i = 1; i < n; i++) await copyFile(first, join(temp, frameName(frameCount + i)));
+      frameCount += n;
+    };
+    if (config.titleCard) {
+      phase = 'title card';
+      await repeat(await card([config.title, config.presenter ? `Presented by ${config.presenter}` : null]), TITLE_CARD_SECONDS);
+    }
+
+    phase = 'recording';
+    const session = await context.newCDPSession(page);
+    const slots = startFrameSlots(session, { dir: temp, fps: VIDEO_FPS, first: frameCount });
+    await session.send('Page.startScreencast', { format: 'jpeg', quality: 90, maxWidth: geometry.width, maxHeight: geometry.height, everyNthFrame: 1 });
+    // A screenshot forces a fresh frame: it, and every compositor frame after it, show the deck as it starts.
+    const poster = await page.screenshot({ type: 'jpeg', quality: 90 });
+    const markMs = Date.now();
+    slots.begin(poster, markMs / 1000);
+    await page.evaluate(() => window.__hdExportGo());
+    // 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.
+    const secondsOf = new Map(plan.ids.map((id, i) => [id, plan.seconds[i]]));
+    let shown = 0, progress = 0, movedAt = Date.now();
+    for (;;) {
+      await new Promise((ok) => setTimeout(ok, 500));
+      slots.check();
+      const next = await readLog(page);
+      if (next) state = next;
+      const failedClip = state.errors?.[0];
+      if (failedClip) throw new Error(`narration failed on ${failedClip.id} (${failedClip.message}); the tour cannot go on`);
+      const moved = (state.slides?.length ?? 0) + (state.clips?.length ?? 0);
+      if (moved !== progress) { progress = moved; movedAt = Date.now(); }
+      for (; shown < (state.slides?.length ?? 0); shown++) {
+        const s = state.slides[shown];
+        const i = plan.ids.indexOf(s.id);
+        log(`  slide ${i + 1}/${plan.ids.length} ${s.id} · ${clock(Math.max(0, (s.at - markMs) / 1000))}${plan.total ? ` of ${clock(plan.total)}` : ''}`);
+      }
+      if (state.done) break;
+      const at = state.slides?.at(-1)?.id ?? plan.ids[0];
+      const allowed = ((secondsOf.get(at) || 0) * 1.5 + STUCK_GRACE_SECONDS) * 1000;
+      if (Date.now() - movedAt > allowed) throw new Error(`the tour stopped on slide ${at}: nothing moved for ${Math.round(allowed / 1000)}s${pageSaid()}`);
+    }
+    const seconds = Math.max(0.5, (state.doneAt - markMs) / 1000);
+    // Let the compositor deliver the frames up to the end before stopping.
+    const waitUntil = Date.now() + 1500;
+    while (slots.latest < markMs / 1000 + seconds && Date.now() < waitUntil) await new Promise((ok) => setTimeout(ok, 50));
+    await session.send('Page.stopScreencast').catch(() => {});
+    frameCount += await slots.stop(seconds);
+    if (!slots.received) throw new Error('the screencast delivered no frames after the first; the capture broke (nothing would move in the video)');
+    // Drift means something only when every clip's planned length is known (a data-clip deck's are not).
+    const drift = (state.plan ?? []).every((s) => !s.audio || s.duration > 0) ? timelineDrift(state, markMs) : [];
+    const worst = drift.reduce((a, d) => (Math.abs(d.drift) > Math.abs(a.drift) ? d : a), { drift: 0 });
+    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`);
+
+    if (config.endCard) {
+      phase = 'end card';
+      await repeat(await card([config.title, config.link]), END_CARD_SECONDS);
+    }
+    phase = 'browser close';
+    await context.close();
+    await browser.close();
+    browser = null;
+    if (blocked) warnings.push(`${blocked} request(s) blocked (tracking, navigation or unsafe destinations); nothing was recorded as a view.`);
+
+    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));
+    if (missing.length) warnings.push(`no audio started for ${missing.join(', ')}`);
+    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);
+
+    phase = 'encode';
+    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 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, 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 });
+  }
+}
+
+// ---- the command ------------------------------------------------------------
+
+const titleOf = (html) => (/<title[^>]*>([^<]*)<\/title>/i.exec(html)?.[1] ?? '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").trim();
+const mb = (n) => `${(n / 1e6).toFixed(1)} MB`;
+
+// hyperdecks export <slug|deck-dir> --video: a deck folder records its working
+// copy as `hyperdecks play` serves it (the owner's face added in memory, the
+// manifest index.html points at); a slug records the released copy. Progress
+// goes to stderr, the result to stdout.
+export async function exportVideo(arg, opts = {}, { log = (l) => process.stderr.write(`${l}\n`), print = (l) => console.log(l), cwd = process.cwd(), deps = {} } = {}) {
+  const o = videoOptions(opts);
+  const { existsSync, readFileSync } = await import('node:fs');
+  const { resolve, join: joinPath, basename } = await import('node:path');
+  const ops = deps.ops ?? await import('./ops.mjs');
+  const local = [resolve(cwd, arg), joinPath(cwd, 'decks', arg)].find((d) => existsSync(joinPath(d, 'index.html')));
+  // --upload files the MP4 under a deck you own: checked before minutes of recording.
+  if (o.upload) await ops.ownedDeck(opts, local ? (opts.slug || basename(local)) : arg);
+  let source;
+  if (local) {
+    const { startPlay } = deps.play ?? await import('./play.mjs');
+    const html = readFileSync(joinPath(local, 'index.html'), 'utf8');
+    const session = await startPlay([local], { ...opts, 'no-open': true }, { log: (l) => { if (!l.startsWith('▶')) log(l); }, cwd });
+    source = { slug: session.slug, title: titleOf(html) || session.slug, url: session.url, close: session.close, presenter: session.who?.face ?? null };
+  } else {
+    const deck = await ops.releasedDeck(opts, arg);
+    const { serveSource } = await import('./preview-capture.mjs');
+    const server = await serveSource({ html: deck.html });
+    source = { slug: arg, title: deck.title, url: server.url, close: server.close, presenter: null };
+  }
+  try {
+    let link = o.link;
+    if (o.endCard && !link) {
+      try { link = await ops.videoShareLink(opts, source.slug); }
+      catch (e) { throw new Error(`the end card needs the deck's link: ${ops.errorText?.(e) ?? e.message}. Pass --link <url> to name one`); }
+    }
+    const out = resolve(cwd, o.out ?? `${source.slug}.mp4`);
+    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,
+    }, { log });
+    let uploaded = null;
+    if (o.upload) {
+      log(`uploading ${mb(result.bytes)}…`);
+      try {
+        uploaded = await ops.uploadVideoExport(opts, { slug: source.slug, bytes: await readFile(out), seconds: result.seconds, width: result.width, height: result.height });
+      } catch (e) {
+        throw new Error(`${ops.errorText?.(e) ?? e.message}. The MP4 is saved at ${out}: share the file itself, or fix that and re-run with --upload (it records again)`);
+      }
+    }
+    const summary = { ...result, slug: source.slug, link: link ?? null, ...(uploaded ? { exportId: uploaded.exportId, url: uploaded.url, expiresAt: uploaded.expiresAt } : {}) };
+    if (opts.json) { print(JSON.stringify(summary, null, 2)); return summary; }
+    print(`✓ ${clock(result.seconds)} at ${result.width}×${result.height}, ${mb(result.bytes)} → ${out}`);
+    if (link && o.endCard) print(`  end card link: ${link}`);
+    for (const w of result.warnings) print(`  ⚠ ${w}`);
+    if (uploaded) print(`  on the deck page, and download (30 days): ${uploaded.url}`);
+    return summary;
+  } finally {
+    await source.close();
+  }
+}

package/src/ops.mjs

@@ -209,7 +209,8 @@ export async function generatePoster(opts, fields = {}) {
 export async function exportDeck(opts, fields = {}) {
   if (!fields.slug) throw new Error("slug is required");
   const kind = fields.kind ?? "pdf";
-  if (kind !== "pdf") throw new Error(`kind "${kind}" is not supported yet: only "pdf" (video export comes from \`hyperdecks export --mp4\` later)`);
+  if (kind === "mp4") throw new Error(videoFromCli(String(fields.slug)));
+  if (kind !== "pdf") throw new Error(`kind "${kind}" is not supported: "pdf", or "mp4" from the CLI`);
   const args = { slug: String(fields.slug), kind: "pdf" };
   if (fields.notes) args.notes = true;
   if (fields.script) args.script = String(fields.script);
@@ -217,6 +218,71 @@ export async function exportDeck(opts, fields = {}) {
   return (await client(opts)).action(api.exports.create, args);
 }
 
+// What export_deck { kind: "mp4" } answers (the same words as convex/exports.ts videoFromCli).
+export const videoFromCli = (slug) =>
+  `video exports run from the CLI until the render worker ships: \`hyperdecks export ${slug} --video --out ${slug}.mp4\` ` +
+  "records the narrated deck in real time (add --upload to keep the MP4 with the deck's exports, --shape 9:16 or 1:1, --size 720p or 4k).";
+
+// The released copy of a deck you own, for `export --video <slug>`: { slug, title, html }.
+// Owner only, as export_deck is: a video is the owner's to make.
+export async function ownedDeck(opts, slug) {
+  const c = await client(opts);
+  const [deck, me] = await Promise.all([c.query(api.decks.get, { slug }), c.query(api.decks.whoami, {})]);
+  if (!me) throw new Error("not logged in: run `hyperdecks login` first");
+  if (!deck) throw new Error(`deck not found: ${slug} (register it first, or pass --slug)`);
+  if (!me.isAdmin && deck.ownerId !== me.subject) throw new Error(`forbidden: ${slug} is not your deck`);
+  return deck;
+}
+export async function releasedDeck(opts, slug) {
+  const deck = await ownedDeck(opts, slug);
+  if (deck.status === "archived") throw new Error(`${slug} is archived; restore it before exporting`);
+  let html = deck.html ?? null;
+  if (!html && deck.htmlUrl) {
+    const res = await fetch(deck.htmlUrl, { signal: AbortSignal.timeout(30000) });
+    if (!res.ok) throw new Error(`could not read ${slug}'s released HTML (${res.status})`);
+    html = await res.text();
+  }
+  if (!html) throw new Error(`${slug} has no released HTML yet; release it first`);
+  return { slug, title: deck.title ?? slug, html };
+}
+
+// The link a video's end card shows: the deck's own "Video viewers" link, made
+// on first use, so a viewer who types it in counts as a view of that link and
+// never as a recipient's (their views and view limit).
+export const VIDEO_RECIPIENT = "Video viewers";
+export async function videoShareLink(opts, slug) {
+  const live = (await listShares(opts, slug)).find((s) => s.recipient === VIDEO_RECIPIENT && s.enabled && !s.qa && !s.archived && !s.requireEmail && (s.expiresAt == null || s.expiresAt > Date.now()) && (s.viewLimit == null || s.opens < s.viewLimit));
+  const token = live?.token ?? (await createShare(opts, { slug, recipient: VIDEO_RECIPIENT })).token;
+  return `${target(opts).shareBase}/v/${token}`;
+}
+
+// `export --video --upload`: file the MP4 with the deck's exports (30 days).
+// Returns { exportId, url, expiresAt }.
+export async function uploadVideoExport(opts, { slug, bytes, seconds, width, height }, { fetchImpl = fetch, timeoutMs = 30 * 60_000 } = {}) {
+  const c = await client(opts);
+  const { exportId, uploadUrl } = await c.mutation(api.exports.startVideoUpload, { slug, bytes: bytes.length, seconds, width, height });
+  try {
+    let res;
+    try {
+      res = await fetchImpl(uploadUrl, { method: "POST", headers: { "Content-Type": "video/mp4" }, body: bytes, signal: AbortSignal.timeout(timeoutMs) });
+    } catch (e) {
+      throw new Error(`upload failed: ${e?.name === "TimeoutError" ? `no answer in ${Math.round(timeoutMs / 60000)} min` : e?.message || String(e)}`);
+    }
+    if (!res.ok) throw new Error(`upload failed: ${res.status} ${await res.text()}`);
+    const body = await res.text();
+    let storageId;
+    try { ({ storageId } = JSON.parse(body)); } catch { /* checked below */ }
+    if (!storageId) throw new Error(`upload failed: the storage answered without a file id (${body.slice(0, 200)})`);
+    const done = await c.mutation(api.exports.finishVideoUpload, { exportId, storageId });
+    if (!done.ok) throw new Error(`upload refused: ${done.error}`);
+    return { exportId, url: done.url, expiresAt: done.expiresAt };
+  } catch (e) {
+    // The row says so at once, rather than "uploading…" until the sweep.
+    await c.mutation(api.exports.failVideoUpload, { exportId, error: errorText(e) }).catch((err) => console.error(`[export] could not mark export ${exportId} failed: ${errorText(err)}`));
+    throw e;
+  }
+}
+
 // Your exports (newest first, 30 days), optionally for one deck.
 export async function listExports(opts, fields = {}) {
   return (await client(opts)).query(api.exports.list, fields.slug ? { slug: String(fields.slug) } : {});

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.9.2";
+export const VERSION = "0.9.3";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -132,6 +132,9 @@ export const api = {
     create: makeFunctionReference("exports:create"),
     list: makeFunctionReference("exports:list"),
     remove: makeFunctionReference("exports:remove"),
+    startVideoUpload: makeFunctionReference("exports:startVideoUpload"),
+    finishVideoUpload: makeFunctionReference("exports:finishVideoUpload"),
+    failVideoUpload: makeFunctionReference("exports:failVideoUpload"),
   },
   review: {
     reviewDeck: makeFunctionReference("review:reviewDeck"),
@@ -161,7 +164,7 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "strict", "fix", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "no-logo", "pdf", "notes", "mp4", "gif"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "strict", "fix", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "no-logo", "pdf", "notes", "mp4", "gif", "video", "no-captions", "no-avatar", "title-card", "end-card"]);
 // release's recipients, in order: each --to starts one, and an --email right
 // after it belongs to it (`--to A --email a --to B`). Collected as opts.recipients;
 // opts.email stays the last --email for the other commands (share new).