explainer-video 0.0.0-stage → 0.4.0

package/skills/explainer-video-from-coursework/tools/tts-gemini.mjs

@@ -0,0 +1,394 @@
+// Google Gemini TTS backend — no npm dependencies (Node 22 global fetch).
+//
+//   node tools/tts-gemini.mjs --probe
+//   node tools/tts-gemini.mjs --text "Hello there" --voice Kore --style "warm, conversational" --out out.wav
+//   node tools/tts-gemini.mjs --voices
+//
+// Auth (first hit wins, no key is ever logged or echoed):
+//   1. --key <value>          explicit CLI arg — transient, visible in ps
+//   2. the OS secret store    macOS Keychain · Linux secret-tool · Windows Credential Manager
+//
+// Model: gemini-3.8-flash-tts  (Interactions API)
+//   POST https://generativelanguage.googleapis.com/v1beta/interactions
+//   Response: interaction.output_audio.data  -> base64 WAV
+//
+// TTS is "controllable": `speech_metadata.style` steers style, accent, pace, tone.
+
+import { writeFileSync, readFileSync } from 'node:fs';
+import { loadKey, scrub, describe, storeHint } from './key-source.mjs';
+
+export const API = 'https://generativelanguage.googleapis.com/v1beta';
+export const DEFAULT_MODEL = 'gemini-3.8-flash-tts';
+export const FALLBACK_MODEL = 'gemini-3.8-flash-lite-tts';
+
+// Prebuilt voice options (from the Gemini TTS docs).
+export const VOICES = [
+  'Kore', 'Puck', 'Charon', 'Fenrir', 'Aoede', 'Leda', 'Orus', 'Zephyr',
+  'Callirrhoe', 'Autonoe', 'Enceladus', 'Iapetus', 'Umbriel', 'Algieba',
+  'Despina', 'Erinome', 'Algenib', 'Rasalgethi', 'Laomedeia', 'Achernar',
+  'Alnilam', 'Schedar', 'Gacrux', 'Pulcherrima', 'Achird', 'Zubenelgenubi',
+  'Vindemiatrix', 'Sadachbia', 'Sadaltager', 'Sulafat',
+];
+
+let lastSource = 'none';
+
+function apiKey(explicit) {
+  const { key, source, store } = loadKey(explicit);
+  lastSource = source;
+  if (!key) {
+    throw new Error(
+      'No API key found. Store it in your OS secret store, then re-run.\n' +
+      storeHint(store) +
+      '  One-off override: pass --key <value> (visible in the process list).\n' +
+      '  Free key: https://aistudio.google.com/apikey'
+    );
+  }
+  return key;
+}
+
+/** Scrub anything key-shaped out of an error message before it is shown. */
+const safe = msg => scrub(msg);
+
+function errMessage(json, text) {
+  // Google returns either {error:{message}} or [{error:{message}}]
+  const j = Array.isArray(json) ? json[0] : json;
+  return scrub(j?.error?.message || text.slice(0, 400).replace(/\s+/g, ' '));
+}
+
+/**
+ * Locate the audio payload in an Interactions response.
+ *
+ * The SDK exposes a convenience field `output_audio`, but the raw REST body
+ * nests it as a model_output step:
+ *   steps[i].content[j] = { type:"audio", mime_type:"audio/wav", data:"<base64>" }
+ * Handle the SDK shape too, in case it is ever present.
+ */
+function extractAudio(json) {
+  const direct = json?.output_audio || json?.outputAudio;
+  if (direct?.data) return { data: direct.data, mime: direct.mime_type || 'audio/wav' };
+
+  for (const step of json?.steps || []) {
+    for (const c of step?.content || []) {
+      const isAudio = c?.type === 'audio' || String(c?.mime_type || '').startsWith('audio/');
+      if (c?.data && isAudio) return { data: c.data, mime: c.mime_type || 'audio/wav' };
+    }
+  }
+  return null;
+}
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/**
+ * POST/GET with automatic retry, but ONLY for limits that can plausibly clear.
+ *
+ * Free tier has BOTH:
+ *   • RPM  — "3 requests per minute"      -> retry after Ns, works
+ *   • RPD  — "10 requests per day"        -> retry after Nh, futile; fail fast
+ *
+ * Retrying an RPD exhaustion just burns wall-clock for nothing, so detect it
+ * from the message and abort immediately with an actionable error.
+ */
+async function call(path, body, key, method = 'POST', { retries = 4 } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    const res = await fetch(`${API}${path}`, {
+      method,
+      headers: { 'Content-Type': 'application/json', 'x-goog-api-key': key },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = JSON.parse(text); } catch {}
+
+    if (res.status === 429) {
+      const msg = errMessage(json, text);
+
+      // Daily quota: not worth waiting for.
+      if (/per day/i.test(msg) || /retry in\s*\d+\s*h/i.test(msg)) {
+        const eta = /retry in\s*([0-9hm\s.]+)/i.exec(msg)?.[1]?.trim() || 'unknown';
+        const err = new Error(
+          `Daily quota exhausted (${eta} until reset, ~midnight Pacific).\n` +
+          `  ${msg}\n` +
+          `  Options: wait for the reset, enable billing (Tier 1 raises limits; ` +
+          `this whole build costs ~2 cents), or use a different model which has its own quota:\n` +
+          `    --model gemini-3.8-flash-lite-tts\n` +
+          `    --model gemini-2.5-flash-preview-tts`
+        );
+        err.daily = true;
+        throw err;
+      }
+
+      // Per-minute throttle: waiting genuinely helps.
+      if (attempt < retries) {
+        const m = /retry in\s*(\d+(?:\.\d+)?)\s*s/i.exec(msg);
+        const wait = m ? Math.ceil(parseFloat(m[1])) + 3 : 25 * (attempt + 1);
+        process.stderr.write(`  [rate limit] per-minute 429 — waiting ${wait}s (retry ${attempt + 1}/${retries})\n`);
+        await sleep(wait * 1000);
+        continue;
+      }
+    }
+    return { status: res.status, ok: res.ok, json, text };
+  }
+}
+
+/** Synthesize one segment -> WAV buffer. */
+export async function synthesize({
+  text,
+  voice = 'Kore',
+  style = 'warm, natural, conversational — like explaining to a colleague',
+  model = DEFAULT_MODEL,
+  key,
+  speechConfig,
+} = {}) {
+  const k = apiKey(key);
+
+  // A voice id from voice replication / voice design is passed through as-is;
+  // a prebuilt voice is passed by name. Both go in speech_config[].voice.
+  const voiceEntry = speechConfig || { voice };
+
+  const body = {
+    model,
+    input: [{
+      type: 'user_input',
+      content: [{
+        type: 'text',
+        text,
+        annotations: style ? [{ type: 'speech_metadata', style }] : [],
+      }],
+    }],
+    response_format: { type: 'audio' },
+    generation_config: { speech_config: [voiceEntry] },
+  };
+
+  const r = await call('/interactions', body, k);
+  if (!r.ok) {
+    const msg = errMessage(r.json, r.text);
+    throw new Error(`Gemini TTS ${r.status}: ${msg}`);
+  }
+  const audio = extractAudio(r.json);
+  if (!audio) {
+    throw new Error('No audio in response. Top-level keys: ' +
+      Object.keys(r.json || {}).join(', '));
+  }
+  const wav = Buffer.from(audio.data, 'base64');
+  return { wav, mime: audio.mime, usage: r.json?.usage || null, raw: r.json };
+}
+
+/* ---- Batch TTS (generateContent + batchGenerateContent) ----
+   Batch is token-metered, not request-metered, so it sidesteps the per-day RPD
+   wall. It is generateContent-only and uses a DIFFERENT voice schema than the
+   Interactions API: speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName. */
+
+export function genTtsRequest(text, style, voice) {
+  const part = { text };
+  if (style) part.speech_metadata = { style };
+  return {
+    contents: [{ role: 'user', parts: [part] }],
+    generationConfig: {
+      responseModalities: ['AUDIO'],
+      speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: voice } } },
+    },
+  };
+}
+
+/**
+ * Synthesize many styled segments in one batch job. Returns the segments that
+ * produced audio, so a partial success still yields something.
+ *
+ * Fallback ladder: on a quota/transient failure the *remaining* segments spill
+ * onto `fallbackModel` — the "exhaust one model's daily budget, then the next"
+ * behaviour. The whole job is never silently downgraded; only the leftovers are.
+ *
+ * @returns {Promise<{segments: Array<{key, wav}>, jobs: number}>}
+ */
+export async function synthesizeBatch({
+  segments,                          // [{ key, text, style }]
+  voice = 'Kore',
+  model = DEFAULT_MODEL,
+  fallbackModel = FALLBACK_MODEL,
+  key,
+  pollMs = 15000,
+  timeoutMs = 30 * 60 * 1000,
+} = {}) {
+  const k = apiKey(key);
+  const done = new Map();            // key -> WAV Buffer
+
+  const submit = async (m, segs) => {
+    const body = {
+      batch: {
+        display_name: 'narration',
+        input_config: {
+          requests: {
+            requests: segs.map(s => ({ request: genTtsRequest(s.text, s.style, voice), metadata: { key: s.key } })),
+          },
+        },
+      },
+    };
+    const res = await fetch(`${API}/models/${m}:batchGenerateContent`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-goog-api-key': k },
+      body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let json = null; try { json = JSON.parse(text); } catch {}
+    if (!res.ok) {
+      const msg = scrub(json?.error?.message || text).slice(0, 300).replace(/\s+/g, ' ');
+      const err = new Error(`batch ${res.status}: ${msg}`);
+      err.quota = /quota|per day|RESOURCE_EXHAUSTED|exhausted/i.test(msg);
+      err.transient = err.quota || res.status === 429 || res.status === 503;
+      throw err;
+    }
+    const name = json?.name || json?.metadata?.name;
+    if (!name) throw new Error('batch submit returned no job name');
+    return name;
+  };
+
+  const poll = async (name) => {
+    const deadline = Date.now() + timeoutMs;
+    let last = null;
+    for (;;) {
+      if (Date.now() > deadline) {
+        const e = new Error(`batch job not finished after ${Math.round(timeoutMs / 60000)} min (${name})`);
+        e.timeout = true; throw e;
+      }
+      await sleep(pollMs);
+      const res = await fetch(`${API}/${name}`, { headers: { 'x-goog-api-key': k } });
+      const gj = await res.json();
+      const state = gj?.state || gj?.metadata?.state;
+      if (state !== last) { process.stderr.write(`  [batch] ${state}\n`); last = state; }
+      if (state === 'BATCH_STATE_SUCCEEDED') return gj;
+      if (state === 'BATCH_STATE_FAILED' || state === 'BATCH_STATE_CANCELLED') {
+        throw new Error(`batch job ${state}`);
+      }
+    }
+  };
+
+  /* Map each inlined response back to its segment (by echoed metadata key, else
+     by request order) and stash any audio. Returns the segments still missing. */
+  const harvest = (job, segs) => {
+    const list = job?.metadata?.output?.inlinedResponses?.inlinedResponses
+      || job?.output?.inlinedResponses?.inlinedResponses || [];
+    list.forEach((item, i) => {
+      const parts = item?.response?.candidates?.[0]?.content?.parts || [];
+      const audio = parts.find(p => (p?.inlineData?.mimeType || '').startsWith('audio'));
+      if (!audio) return;
+      const mk = item?.metadata?.key;
+      const seg = mk ? segs.find(s => s.key === mk) : segs[i];
+      if (seg) done.set(seg.key, Buffer.from(audio.inlineData.data, 'base64'));
+    });
+    return segs.filter(s => !done.has(s.key));
+  };
+
+  const rungs = [model];
+  if (fallbackModel && fallbackModel !== model) rungs.push(fallbackModel);
+
+  let pending = segments.slice();
+  let jobs = 0;
+  for (const m of rungs) {
+    if (!pending.length) break;
+    let failed = [];
+    try {
+      const name = await submit(m, pending);
+      jobs++;
+      failed = harvest(await poll(name), pending);
+    } catch (e) {
+      if (!e.transient && !e.timeout && !/BATCH_STATE_FAILED/.test(e.message)) throw e;
+      process.stderr.write(`  [batch] ${m} unavailable — ${e.message.split('\n')[0]}\n`);
+      failed = pending.slice();       // retry everything on the next rung
+    }
+    pending = failed;
+  }
+
+  if (pending.length) {
+    throw new Error(`[batch] ${pending.length} segment(s) still lack audio after all models: ${pending.map(s => s.key).join(', ')}`);
+  }
+  return {
+    segments: segments.filter(s => done.has(s.key)).map(s => ({ key: s.key, wav: done.get(s.key) })),
+    jobs,
+  };
+}
+
+/** List voices available to this project (prebuilt + extended library + custom). */
+export async function listVoices(key) {
+  const r = await call('/voices', null, apiKey(key), 'GET');
+  if (!r.ok) throw new Error(`voices ${r.status}: ${errMessage(r.json, r.text)}`);
+  return r.json;
+}
+
+/** Voice replication: reference audio + consent audio -> voice id. */
+export async function replicateVoice({ referenceWav, consentWav, displayName = 'Replicated Voice', model = DEFAULT_MODEL, store = true, key } = {}) {
+  const k = apiKey(key);
+  const b64 = p => (Buffer.isBuffer(p) ? p : readFileSync(p)).toString('base64');
+  const r = await call('/voices', {
+    store,
+    voice: {
+      model,
+      type: 'replicated',
+      display_name: displayName,
+      replicated: {
+        source_audio: { mime_type: 'audio/wav', data: b64(referenceWav) },
+        consent_audio: { mime_type: 'audio/wav', data: b64(consentWav) },
+      },
+    },
+  }, k);
+  if (!r.ok) throw new Error(`replicate ${r.status}: ${errMessage(r.json, r.text)}`);
+  return r.json;
+}
+
+/* ---------------- CLI ---------------- */
+const isMain = process.argv[1] && process.argv[1].endsWith('tts-gemini.mjs');
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const flag = (n, d = null) => {
+    const i = argv.indexOf('--' + n);
+    return i === -1 ? d : (argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true);
+  };
+
+  try {
+    if (flag('probe')) {
+      const k = apiKey(flag('key'));
+      console.log(`[auth] key source: ${describe(lastSource, k)}`);   // never the key itself
+      console.log('[probe] POST /v1beta/interactions  (expect 200 with a valid key)\n');
+      const r = await call('/interactions', {
+        model: DEFAULT_MODEL,
+        input: [{ type: 'user_input', content: [{ type: 'text', text: 'Testing one two three.',
+          annotations: [{ type: 'speech_metadata', style: 'neutral' }] }] }],
+        response_format: { type: 'audio' },
+        generation_config: { speech_config: [{ voice: 'Kore' }] },
+      }, k);
+      console.log('  status:', r.status);
+      if (r.ok) {
+        const a = extractAudio(r.json);
+        if (a) {
+          const n = Buffer.from(a.data, 'base64').length;
+          console.log(`  AUDIO OK — ${n} bytes, ${a.mime}`);
+          if (r.json.usage?.total_output_tokens != null) {
+            console.log(`  output tokens: ${r.json.usage.total_output_tokens}`);
+          }
+        } else {
+          console.log('  no audio found. keys:', Object.keys(r.json || {}).join(', '));
+        }
+      } else {
+        console.log('  body:', scrub(r.json?.error?.message || r.text).slice(0, 400));
+      }
+    } else if (flag('voices')) {
+      const v = await listVoices(flag('key'));
+      console.log(JSON.stringify(v, null, 2).slice(0, 2000));
+    } else if (flag('text')) {
+      const { wav } = await synthesize({
+        text: String(flag('text')),
+        voice: flag('voice', 'Kore'),
+        style: flag('style', undefined),
+        model: flag('model', DEFAULT_MODEL),
+        key: flag('key'),
+      });
+      const out = flag('out', 'tts-out.wav');
+      writeFileSync(out, wav);
+      console.log(`[ok] ${out}  ${(wav.length / 1024).toFixed(0)} KB`);
+    } else {
+      console.log('usage: --probe | --voices | --text "..." [--voice Kore] [--style "..."] [--out f.wav]');
+    }
+  } catch (e) {
+    console.error('[error]', scrub(e.message));
+    process.exit(1);
+  }
+}

package/skills/explainer-video-from-coursework/tools/verify-audio.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/* =============================================================================
+   verify-audio.mjs — does the finished video's audio actually match the
+   narration track, sample for sample?
+
+   RMS was not good enough. Speech sits at a roughly constant level, so a part
+   playing the WRONG slice of narration can still have a similar RMS. The only
+   reliable question is: if you subtract one from the other, how much energy is
+   left?
+
+     residual = sqrt( sum((a-n)^2) / sum(a^2) )
+
+   Matching content -> residual is near zero (only codec noise).
+   Wrong slice     -> residual approaches ~1.4 (two unrelated signals).
+
+   Usage:
+     node tools/verify-audio.mjs --video out/<name>/<NN>/<output>.mp4 \
+                                 --narration out/<name>/<NN>/narration.wav [--max 0.25]
+   ========================================================================== */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, rmSync, existsSync, mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { requireCmd } from './env.mjs';
+
+requireCmd('ffmpeg');
+
+const argv = process.argv.slice(2);
+const flag = (n, d) => {
+  const i = argv.indexOf('--' + n);
+  return i === -1 ? d : argv[i + 1];
+};
+const VIDEO = flag('video');
+const NARR = flag('narration');
+const MAX = parseFloat(flag('max', '0.25'));
+const SR = 22050;
+
+if (!VIDEO || !NARR || !existsSync(VIDEO) || !existsSync(NARR)) {
+  console.error('usage: node tools/verify-audio.mjs --video <mp4> --narration <wav> [--max 0.25]');
+  process.exit(1);
+}
+
+const dir = mkdtempSync(join(tmpdir(), 'va-'));
+const raw = (src, out, extra = []) => {
+  execFileSync('ffmpeg', ['-y', '-v', 'error', '-i', src, ...extra,
+    '-f', 's16le', '-acodec', 'pcm_s16le', '-ar', String(SR), '-ac', '1', out]);
+};
+const aPath = join(dir, 'a.raw'), nPath = join(dir, 'n.raw');
+try {
+  raw(VIDEO, aPath, ['-vn']);
+  raw(NARR, nPath);
+  const A = readFileSync(aPath), N = readFileSync(nPath);
+
+  // compare only where the narration has any energy; lead-in silence would
+  // otherwise dominate and flatter the result
+  const samples = Math.floor(Math.min(A.length, N.length) / 2);
+  let num = 0, den = 0;
+  const win = Math.round(SR * 0.5);
+  const active = [];
+  for (let s = 0; s < samples; s += win) {
+    let e = 0;
+    for (let i = s; i < Math.min(s + win, samples); i++) {
+      const v = N.readInt16LE(i * 2);
+      e += v * v;
+    }
+    active.push(e);
+  }
+  const eMax = Math.max(...active) || 1;
+  for (let s = 0; s < samples; s++) {
+    if (active[Math.floor(s / win)] < eMax * 0.002) continue;   // skip near-silence
+    const av = A.readInt16LE(s * 2), nv = N.readInt16LE(s * 2);
+    num += (av - nv) * (av - nv);
+    den += nv * nv;
+  }
+  const residual = den > 0 ? Math.sqrt(num / den) : NaN;
+  const ok = residual <= MAX;
+  console.log(`  residual (difference energy / signal energy): ${residual.toFixed(4)}   (max ${MAX})`);
+  console.log(ok
+    ? '  ✓ finished audio matches the narration'
+    : '  ✗ finished audio does NOT match the narration — a part is playing the wrong slice');
+  rmSync(dir, { recursive: true, force: true });
+  process.exit(ok ? 0 : 2);
+} catch (e) {
+  rmSync(dir, { recursive: true, force: true });
+  console.error('[verify-audio] failed:', e.message.split('\n')[0]);
+  process.exit(1);
+}

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

@@ -0,0 +1,124 @@
+/* =============================================================================
+   workdir.mjs — one work dir per video, enforced rather than assumed.
+
+   Why this exists
+   ---------------
+   The per-video work dir (`out/<name>/<NN>/`) holds artefacts named the SAME for
+   every video: `narration.wav`, `timeline.json`, `timeline.js`, `lines.json`,
+   `manifest.json`, the rendered MP4. Nothing in those names carries the video's
+   identity, so pointing two videos at one directory does not fail — the second
+   run silently overwrites the first's timeline, and every later stage then reads
+   a timeline that describes a different video. Stage 4 is where that first
+   becomes possible, which is why this check runs there.
+
+   The fix is an identity marker, not a filename heuristic. A directory may hold
+   whatever it likes — plan files, a `scripts/` dir, a single-video plan whose
+   work dir genuinely IS the plan dir — and that is all fine. The only thing that
+   is refused is a directory already claimed by a DIFFERENT video.
+
+   Identity is the plan's `videoIndex`: it is the stable, monotonic key the whole
+   pipeline is indexed by (see `naming.mjs`). The title is recorded too, but a
+   title change is NOT a conflict — re-running `apply-enrichment` legitimately
+   retitles a video, so a same-index/different-title run updates the marker and
+   carries on.
+
+   Cross-stage behaviour belongs in a tool, not in either SKILL.md — `build-audio`,
+   `align` and `assemble` all import this so they cannot disagree.
+   ========================================================================== */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MARKER = '.video-identity';
+
+function readMarker(dir) {
+  const p = join(dir, MARKER);
+  if (!existsSync(p)) return null;
+  try {
+    const j = JSON.parse(readFileSync(p, 'utf8'));
+    return j && typeof j === 'object' ? j : { corrupt: true };
+  } catch {
+    return { corrupt: true };
+  }
+}
+
+/* Atomic: a half-written marker would read as corrupt and block a legitimate run. */
+function writeMarker(dir, identity) {
+  mkdirSync(dir, { recursive: true });
+  const p = join(dir, MARKER);
+  const tmp = p + '.' + process.pid + '.tmp';
+  writeFileSync(tmp, JSON.stringify(identity, null, 2) + '\n');
+  renameSync(tmp, p);
+}
+
+/**
+ * Claim (or verify) a work dir for one video.
+ *
+ * Exits non-zero when the dir belongs to a different `videoIndex`, naming both
+ * videos and the path it was asked to write. Otherwise returns the identity now
+ * recorded, writing or refreshing the marker as needed.
+ *
+ * @param {string} workDir  the per-video work dir the caller was given
+ * @param {object} script   the parsed script.json
+ * @param {string} tool     short stage label for messages, e.g. 'build-audio'
+ */
+export function claimWorkDir(workDir, script, tool = 'stage') {
+  const idxRaw = script && script.videoIndex != null ? Number(script.videoIndex) : null;
+  const idx = Number.isFinite(idxRaw) ? idxRaw : null;
+  const title = String((script && script.title) || '').trim();
+
+  const label = i => (i && i.title ? `video ${i.videoIndex} — "${i.title}"` : `video ${i.videoIndex}`);
+  const mine = idx != null ? `video ${idx}${title ? ` — "${title}"` : ''}` : `an unnamed video${title ? ` ("${title}")` : ''}`;
+
+  const prev = readMarker(workDir);
+
+  if (prev && prev.corrupt) {
+    console.error(`\n[workdir] ${workDir}/${MARKER} is unreadable — rewriting it for ${mine}.`);
+    console.error(`[workdir] If that dir was already in use by another video, its artefacts may be mixed.`);
+  } else if (prev && prev.videoIndex != null && idx != null && Number(prev.videoIndex) !== idx) {
+    console.error(`
+[workdir] Refusing to write: this work dir already belongs to ${label(prev)}.
+
+            dir      ${workDir}
+            ${tool.padEnd(8)} asked for ${mine}
+
+          Every video's work dir holds the same file names — narration.wav,
+          timeline.json, timeline.js, lines.json, manifest.json — so writing a
+          second video here silently overwrites the first's timeline and every
+          later stage then reads the wrong video's timings.
+
+          Give each video its own dir:
+
+              --out out/<name>/<videoIndex>          e.g.  --out out/<name>/${idx}
+
+          If ${label(prev)} is finished with this dir, move or delete it first.
+`);
+    process.exit(3);
+  } else if (prev && prev.videoIndex == null && idx == null && prev.title && title && prev.title !== title) {
+    console.error(`\n[workdir] warning: ${workDir} holds "${prev.title}" but was given "${title}",`);
+    console.error(`[workdir] and neither script declares a videoIndex — assuming one video. Set videoIndex in the`);
+    console.error(`[workdir] script to get a hard guarantee.`);
+  }
+
+  const identity = {
+    videoIndex: idx,
+    title: title || null,
+    claimed_by: tool,
+    claimed_at: new Date().toISOString(),
+    ...(prev && prev.claimed_at && idx != null && Number(prev.videoIndex) === idx ? { first_claimed_at: prev.first_claimed_at || prev.claimed_at } : {}),
+  };
+
+  /* A same-index title change is legitimate (re-enrichment retitles videos). */
+  const titleChanged = !!(prev && !prev.corrupt && prev.title && title && prev.title !== title);
+  writeMarker(workDir, identity);
+  if (titleChanged) {
+    console.log(`[workdir] retitled in place: "${prev.title}" → "${title}" (same videoIndex ${idx})`);
+  }
+
+  return identity;
+}
+
+/** Read a work dir's identity without claiming it (for reporting/diagnostics). */
+export function readWorkDirIdentity(workDir) {
+  return readMarker(workDir);
+}