explainer-video 0.0.0-stage → 0.4.0

package/skills/explainer-video-from-coursework/tools/frame-dedup.mjs

@@ -0,0 +1,131 @@
+/* =============================================================================
+   frame-dedup.mjs — capture each DISTINCT frame once; hardlink the repeats.
+
+   WHY THIS EXISTS
+   ---------------
+   renderAt(t) is a pure function of time, so consecutive output frames are very
+   often byte-identical (measured on this pipeline: 82.1% on a declarative diagram
+   scene, 90.3% on an svg scene, 99.7% on a held card). Chromium cannot know that,
+   so the old capture loop asked for a full 1920x1080 PNG screenshot — roughly 63 ms,
+   ~94% of render wall time — for every one of the 30 frames per second, and threw
+   away the ones that were mere re-photographs.
+
+   The loop here asks the PAGE instead: it hashes the serialized #stage SVG after each
+   renderAt(t) (~3.7 ms) and, when the markup is unchanged, hardlinks the previous
+   frame to this frame number — same inode, zero extra bytes — so the existing ffmpeg
+   encode path runs unchanged.
+
+   THE ONE WAY THIS CAN BE WRONG
+   -----------------------------
+   The probe compares MARKUP. Anything that moves pixels without changing the SVG
+   markup — a CSS @keyframes animation, a <canvas>, WebGL — would read as "unchanged"
+   and freeze. Two independent guards make that impossible to ship silently:
+
+     1. GATE   before frame 1, if `document.getAnimations().length > 0` the segment
+               takes the plain capture path (cheap, decisive, no sampling involved).
+     2. AUDIT  every AUDIT_EVERY frames, take a REAL screenshot and diff it against
+               the frame that was written. On disagreement: write the truthful frame,
+               REWIND and re-capture every frame since the last audit, then disable
+               dedup for the remainder of the segment.
+
+   So the fallback is the old behaviour, and it self-triggers. Worst case we pay the
+   original price and stay correct.
+
+   Measured: 2 real videos (72 scenes, ~54,000 frames) re-rendered to SSIM 1.000000
+   against renders that photographed every frame, at 3.28x and 4.32x the speed.
+   ========================================================================== */
+
+import { writeFileSync, linkSync, copyFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/* FNV-1a over the serialized stage + its length. Cheap, deterministic, and it covers
+   every attribute scene-core mutates (opacity, transform, stroke, fill, text, count). */
+const HASH_EXPR = `(() => {
+  const el = document.getElementById('stage') || document.body;
+  const s = el.outerHTML;
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619); }
+  return (h >>> 0).toString(16) + ':' + s.length;
+})()`;
+
+const ANIM_EXPR = '(document.getAnimations ? document.getAnimations().length : 0)';
+const AUDIT_EVERY = 30;   // ~1 s of video; 1 extra screenshot per 30 frames when active
+
+const framePath = (dir, i) => join(dir, `frame_${String(i).padStart(5, '0')}.png`);
+
+/**
+ * Render [tStart, tEnd) at `fps`, writing frame_%05d.png, capturing only distinct states.
+ * Returns stats; throws on a missing page (the caller already validated VIDEO_META).
+ */
+export async function runFrames({ dir, fps, tStart, tEnd, evaluate, screenshot, log = console.log }) {
+  const total = Math.max(1, Math.round((tEnd - tStart) * fps));
+  let screenshots = 0, reused = 0, audits = 0, mismatches = 0;
+  let prevHash = null, lastAudit = 0;
+  let off = false, offAt = null, offWhy = null;
+  const hashes = [];
+
+  const disable = (why, at) => {
+    if (off) return;
+    off = true; offAt = at; offWhy = why;
+    log(`[dedup] dedup off from frame ${at} (${why}) — plain capture for the rest of this segment`);
+  };
+
+  const t0 = Date.now();
+  for (let i = 0; i < total; i++) {
+    const t = tStart + i / fps;
+    await evaluate(`window.renderAt(${t})`);
+
+    /* GATE — after frame 0 draws, because a scene may inject its CSS on first render. */
+    if (i === 0) {
+      const anims = await evaluate(ANIM_EXPR);
+      if (anims > 0) disable(`scene declares ${anims} CSS/web animation(s)`, 0);
+    }
+
+    const hash = await evaluate(HASH_EXPR);
+    hashes.push(hash);
+
+    const canReuse = !off && prevHash !== null && hash === prevHash && existsSync(framePath(dir, i - 1));
+    if (canReuse) {
+      try { linkSync(framePath(dir, i - 1), framePath(dir, i)); }
+      catch { copyFileSync(framePath(dir, i - 1), framePath(dir, i)); }  // different filesystem
+      reused++;
+    } else {
+      writeFileSync(framePath(dir, i), await screenshot());
+      screenshots++;
+    }
+    prevHash = hash;
+
+    /* AUDIT — only meaningful while dedup is live. Once it is off every frame is a real
+       capture, so a disagreement could only mean the page animates on its own clock
+       between the capture and the audit; re-capturing then would burn time for nothing. */
+    if (!off && i > 0 && i % AUDIT_EVERY === 0) {
+      audits++;
+      const real = await screenshot();
+      const { readFileSync } = await import('node:fs');
+      if (!real.equals(readFileSync(framePath(dir, i)))) {
+        mismatches++;
+        log(`[dedup] audit mismatch at frame ${i} (t=${t.toFixed(2)}s): probe said unchanged, pixels differ`);
+        writeFileSync(framePath(dir, i), real);
+        const from = lastAudit + 1;
+        for (let j = from; j < i; j++) {
+          await evaluate(`window.renderAt(${tStart + j / fps})`);
+          writeFileSync(framePath(dir, j), await screenshot());
+          screenshots++; reused--;
+        }
+        if (i > from) log(`[dedup] re-captured frames ${from}..${i - 1} truthfully`);
+        disable('audit caught a change the markup probe missed', i);
+      }
+      lastAudit = i;
+    }
+
+    if (i % 120 === 0 || i === total - 1) {
+      const el = (Date.now() - t0) / 1000;
+      const rate = (i + 1) / Math.max(el, 0.001);
+      process.stdout.write(`\r[render] ${i + 1}/${total}  ${rate.toFixed(1)} fps  ` +
+        `shots=${screenshots} reused=${reused}  eta ${((total - i - 1) / Math.max(rate, 0.001)).toFixed(0)}s   `);
+    }
+  }
+  process.stdout.write('\n');
+  return { total, screenshots, reused, audits, mismatches, distinct: new Set(hashes).size,
+           disabledAt: offAt, disabledWhy: offWhy, captureSec: (Date.now() - t0) / 1000 };
+}

package/skills/explainer-video-from-coursework/tools/key-source.mjs

@@ -0,0 +1,151 @@
+// Resolve a Google API key from the OS's native secret store — never from a
+// plaintext file and never from the environment. The secret stays protected
+// from the shell, the harness, and anyone reading /proc, `ps`, or `env`.
+//
+// The store, per platform:
+//   macOS   Keychain           security find-generic-password -s gemini-tts -w
+//   Linux   Secret Service     secret-tool lookup service gemini-tts   (libsecret)
+//   Windows Credential Manager read via CredRead (advapi32) — the "generic credential"
+//                               whose Internet/network address is "gemini-tts"
+//
+// Resolution order (first hit wins):
+//   1. --key <value>          explicit CLI arg — transient; visible in the
+//                             process list, so one-off runs only
+//   2. the platform secret store
+//
+// Nothing here ever logs, echoes or returns the key to stdout.
+// Error text is scrubbed before it is printed.
+//
+// NOTE: the Linux and Windows branches are written from documented behaviour
+// and have not been run on those platforms (ROADMAP §2.1 — unverified off macOS).
+// Windows retrieval: https://learn.microsoft.com/en-us/windows/win32/api/wincred/nf-wincred-credreadw
+
+import { execFileSync } from 'node:child_process';
+
+const SERVICE = 'gemini-tts';
+
+// Windows CredMan read. CRED_TYPE_GENERIC = 1; the blob is UTF-16LE. The target
+// name is the "Internet or network address" typed in Credential Manager's GUI.
+const CRED_READ = `
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class Cred {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  private struct CREDENTIAL {
+    public int Flags; public int Type; public IntPtr TargetName; public IntPtr Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public int CredentialBlobSize; public IntPtr CredentialBlob; public int Persist;
+    public int AttributeCount; public IntPtr Attributes; public IntPtr TargetAlias; public IntPtr UserName;
+  }
+  [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+  private static extern bool CredRead(string target, int type, int flags, out IntPtr credential);
+  [DllImport("advapi32.dll", SetLastError = true)]
+  private static extern void CredFree(IntPtr credential);
+  public static string Get(string target) {
+    IntPtr p;
+    if (!CredRead(target, 1, 0, out p)) return null;   // 1 = CRED_TYPE_GENERIC
+    try {
+      var c = (CREDENTIAL)Marshal.PtrToStructure(p, typeof(CREDENTIAL));
+      if (c.CredentialBlobSize == 0) return "";
+      var b = new byte[c.CredentialBlobSize];
+      Marshal.Copy(c.CredentialBlob, b, 0, b.Length);
+      return System.Text.Encoding.Unicode.GetString(b);
+    } finally { CredFree(p); }
+  }
+}
+'@
+$key = [Cred]::Get('${SERVICE}')
+if ($null -eq $key) { exit 44 }
+[Console]::Write($key)
+`;
+
+function run(cmd, args) {
+  return execFileSync(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+}
+
+/** The secret-store backend for this platform, or null if there is none. */
+function backend() {
+  switch (process.platform) {
+    case 'darwin':
+      return {
+        name: 'Keychain',
+        retrieve: () => run('security', ['find-generic-password', '-s', SERVICE, '-w']),
+        storeHint: `security add-generic-password -U -s ${SERVICE} -a "$USER" -w   (prompts for the key)`,
+      };
+    case 'linux':
+      return {
+        name: 'Secret Service (secret-tool)',
+        retrieve: () => run('secret-tool', ['lookup', 'service', SERVICE]),
+        storeHint: `secret-tool store --label="Gemini TTS" service ${SERVICE}   (reads the key from stdin — paste it, then Ctrl-D)`,
+      };
+    case 'win32':
+      return {
+        name: 'Credential Manager',
+        retrieve: () => run('powershell.exe', ['-NoProfile', '-Command', CRED_READ]),
+        storeHint: `Control Panel → User Accounts → Credential Manager → Windows Credentials → "Add a generic credential" — Internet or network address: ${SERVICE}, Password: your API key`,
+      };
+    default:
+      return null;
+  }
+}
+
+/**
+ * @returns {{status:'ok'|'empty'|'missing'|'unsupported', key?:string}}
+ */
+export function fromSecretStore() {
+  const b = backend();
+  if (!b) return { status: 'unsupported' };
+  let out;
+  try {
+    out = b.retrieve();
+  } catch {
+    return { status: 'missing' };   // macOS exits 44 when the item is absent
+  }
+  const key = out.trim();
+  // An entry that exists but was stored empty has a zero-length password.
+  return key ? { status: 'ok', key } : { status: 'empty' };
+}
+
+/**
+ * @returns {{key: string|null, source: string, store: string}}
+ */
+export function loadKey(explicit) {
+  const st = fromSecretStore();
+
+  if (explicit && typeof explicit === 'string' && explicit !== 'true') {
+    return { key: explicit, source: 'cli --key', store: st.status };
+  }
+  if (st.status === 'ok') {
+    return { key: st.key, source: `secret store (${backend().name})`, store: st.status };
+  }
+  return { key: null, source: 'none', store: st.status };
+}
+
+/** Remove anything that looks like a key from a string before printing it. */
+export function scrub(text) {
+  if (!text) return text;
+  return String(text)
+    .replace(/AIza[0-9A-Za-z_\-]{10,}/g, 'AIza***REDACTED***')
+    .replace(/([?&]key=)[^&\s"']+/gi, '$1***REDACTED***')
+    .replace(/(x-goog-api-key["':\s]+)[0-9A-Za-z_\-]{10,}/gi, '$1***REDACTED***');
+}
+
+/** Human-readable description of where a key came from, with no secret in it. */
+export function describe(src, key) {
+  if (!key) return 'not found';
+  return `${src}, ${key.length} chars`;
+}
+
+/** User-facing "here is how to store your key", per platform and status. */
+export function storeHint(status) {
+  const b = backend();
+  if (!b) return '';
+  if (status === 'empty') {
+    return `\n  A ${b.name} credential exists but is empty — store it again:\n      ${b.storeHint}\n`;
+  }
+  if (status === 'missing') {
+    return `\n  Store the key in ${b.name}:\n      ${b.storeHint}\n`;
+  }
+  return '';
+}

package/skills/explainer-video-from-coursework/tools/model.mjs

@@ -0,0 +1,21 @@
+/* =============================================================================
+   model.mjs — the ONE place the duration/estimate constants live.
+
+   These feed ONLY the estimation layer: planner packing, script-check budget,
+   and pacing-check's fallback. The audio/video stages never read them — they
+   measure real durations with ffprobe (build-audio → timeline.json → render).
+
+   Both numbers are MEASURED, not guessed (video 6, the one fully-produced run):
+     WPM       = 153    Gemini Aoede narration pace: 508 words → 199.0s of audio
+     EXPANSION = 1.10   picture-over-narration overhead: 205.7s picture / 199.0s
+                        narration = 1.03, plus a small buffer for code-heavy
+                        videos we have not measured yet.
+
+   If a future run measures a different pace, change it HERE, not in the tools.
+
+   MAX_PAUSES = 3 pause prompts per code video (design §5.5): script-check and the
+   codebase skill's excerpt-check enforce the same cap; a fourth forces a split.
+   ========================================================================== */
+export const WPM = 153;
+export const EXPANSION = 1.10;
+export const MAX_PAUSES = 3;

package/skills/explainer-video-from-coursework/tools/naming.mjs

@@ -0,0 +1,38 @@
+/* =============================================================================
+   naming.mjs — one stable, order-preserving folder name per finished video.
+
+   The finished series lands as one folder per video:
+
+       <destination>/<NN>-<slug>/video.mp4
+       <destination>/<NN>-<slug>/description.md
+       <destination>/<NN>-<slug>/captions.srt
+
+   `NN` is the plan's `videoIndex` — the consumption order, stable and monotonic —
+   and `slug` is a filesystem-safe form of the video title. Because each video owns
+   its own folder, the fixed sidecar filenames (`description.md`, `captions.srt`)
+   can never collide across videos, and listing the destination sorts it into
+   watch order. `publish.mjs` and `assemble.mjs` both import this so the two agree
+   on the folder, regardless of the ad-hoc `--name` the agent may pick.
+   ========================================================================== */
+
+export function slugify(s) {
+  return String(s || '')
+    .toLowerCase()
+    .normalize('NFKD')                 // decompose, then strip combining accents
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')       // any run of non-alphanumerics → one dash
+    .replace(/^-+|-+$/g, '')           // no leading/trailing dashes
+    .slice(0, 64);                     // keep folders and paths short
+}
+
+/* Derive the per-video folder from the script. Falls back to `fallback` (the work
+   dir's `<NN>` basename) when the script is missing or carries no index/title. */
+export function videoDir(script, fallback) {
+  const hasIdx = script && script.videoIndex != null;
+  const idx = hasIdx ? String(script.videoIndex) : '';
+  const slug = slugify(script && script.title);
+  if (idx && slug) return `${idx}-${slug}`;
+  if (idx) return idx;
+  if (slug) return slug;
+  return fallback || 'video';
+}

package/skills/explainer-video-from-coursework/tools/onset-audit.mjs

@@ -0,0 +1,51 @@
+/* onset-audit.mjs — the earliest visual event in each scene, in seconds after the
+   narration starts. A scene whose first visual lands more than ~2.5s in opens on a
+   near-empty stage (header + badge only), which reads as a dead cut. */
+import { readdirSync, readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const off = v => {
+  if (typeof v === 'number') return v;
+  if (typeof v === 'string') {
+    const m = /^[a-z][a-z0-9-]*@(-?[0-9.]+)$/.exec(v);
+    if (m) return parseFloat(m[1]);
+  }
+  return null;
+};
+const push = (arr, v) => { const o = off(v); if (o != null) arr.push(o); };
+
+const roots = process.argv.slice(2);
+const rows = [];
+for (const root of roots) {
+  const dir = resolve(root, 'scenes');
+  let files;
+  try { files = readdirSync(dir).filter(f => f.endsWith('.js')); } catch { continue; }
+  for (const f of files) {
+    global.window = {};
+    await import(pathToFileURL(resolve(dir, f)).href);
+    const cfg = global.window.SCENE_CONFIG;
+    if (!cfg) { rows.push({ scene: f, onset: null, note: 'no SCENE_CONFIG' }); continue; }
+    const onsets = [];
+    Object.values(cfg.reveal || {}).forEach(a => push(onsets, a[0]));
+    Object.values(cfg.draw || {}).forEach(d => push(onsets, d.at && d.at[0]));
+    Object.values(cfg.hide || {}).forEach(a => push(onsets, a[0]));
+    (cfg.banners || []).forEach(b => push(onsets, b.from));
+    (cfg.flows || []).forEach(fl => push(onsets, fl.from));
+    const OV = cfg.overlays || {};
+    if (OV.cards) push(onsets, OV.cards.inAt);
+    if (OV.chips) push(onsets, OV.chips.at);
+    if (OV.title) push(onsets, OV.title.from);
+    if (OV.finalLine) push(onsets, OV.finalLine.at);
+    const finite = onsets.filter(n => Number.isFinite(n));
+    rows.push({ scene: f, onset: finite.length ? Math.min(...finite) : null });
+  }
+}
+rows.sort((a, b) => (b.onset ?? -1) - (a.onset ?? -1));
+const bad = rows.filter(r => (r.onset ?? 99) > 2.5);
+console.log('scene                            first visual (s after narration start)');
+console.log('─'.repeat(72));
+rows.forEach(r => console.log(`  ${r.scene.padEnd(30)} ${r.onset == null ? 'NONE' : r.onset.toFixed(1)}`));
+console.log('─'.repeat(72));
+console.log(`${rows.length} scenes · ${bad.length} open later than 2.5s`);
+bad.forEach(r => console.log(`  ✗ ${r.scene}  first visual at ${r.onset.toFixed(1)}s`));