videoclaw 3.0.0-alpha.1

package/dist/cli/handlers/motion-overlay.js

@@ -0,0 +1,651 @@
+/**
+ * Motion-overlay command handler for `vclaw` — `vclaw video motion-overlay`.
+ *
+ * Extracted verbatim from the monolithic `vclaw.ts`. Turns an existing
+ * talking-head video into a reel with speech-synced motion-graphics overlays:
+ * ingest -> transcribe -> slice into takes -> compose overlay prompts -> render
+ * via one of four layouts (split | overlay | motion-only | avatar-host). Plan/dry
+ * by default; spend (omni-flash V2V or avatar-host R2V generation) requires
+ * `--execute --confirm-spend`. Only `handleVideoMotionOverlay` is exported (it is
+ * the dispatch entry); every other symbol here is an internal helper for it.
+ * Dispatch stays in `vclaw.ts`. See docs/MOTION_OVERLAY.md.
+ */
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { parseFlagValue, parseProjectSlugFlag, requireSpendConfirmation } from '../args.js';
+import { VclawError } from '../../video/errors.js';
+import { writeOutput } from '../../video/cli-output.js';
+import { runFfmpeg } from '../../video/assemble/index.js';
+import { isProjectSlug } from '../../video/projects.js';
+import { resolveProjectWorkspace } from '../../video/workspace.js';
+import { planMotionOverlay } from '../../video/motion-overlay/run.js';
+import { createDefaultMotionOverlayRunner, runMotionOverlay, } from '../../video/motion-overlay/execute.js';
+import { validateTranscript, transcribeAudio } from '../../video/motion-overlay/transcribe.js';
+import { parseGbCharacter, runAvatarHostGeneration, } from '../../video/motion-overlay/avatar-host.js';
+import { createFlowV2VTransport, flowV2VConfigFromEnv } from '../../video/motion-overlay/v2v-transport.js';
+import { renderLocalOverlay } from '../../video/motion-overlay/render-local.js';
+import { detectMotifs } from '../../video/motion-overlay/motifs.js';
+import { emitFlowPack, restitchFlowOutputs } from '../../video/motion-overlay/flow-pack.js';
+import { renderAnimatedOverlay } from '../../video/motion-overlay/animate-render.js';
+import { analyzeTake } from '../../video/motion-overlay/analyze-reel.js';
+import { createOmniHostGenerator, createVeoI2vHostGenerator, snapVeoDuration, flowRatio } from '../../video/motion-overlay/avatar-host-transport.js';
+import { extractAudio, probeVideo } from '../../video/motion-overlay/ingest.js';
+import { stitch } from '../../video/assemble/stitch.js';
+const MOTION_OVERLAY_LAYOUTS = ['split', 'overlay', 'motion-only', 'avatar-host'];
+const MOTION_OVERLAY_STYLES = ['apple-clean', 'editorial-dark', 'knowledge-tool'];
+/**
+ * Build offline injection deps for `planMotionOverlay` from opt-in env stubs.
+ * These exist ONLY so the e2e CLI test can run with no ffmpeg + no network STT;
+ * production runs leave every var unset and get an empty deps object (real
+ * ffmpeg/Gemini path). Never document these as a public surface.
+ *
+ *  - VCLAW_MOTION_OVERLAY_FAKE_FFMPEG=1 → all ffmpeg cuts/extracts become no-ops.
+ *  - VCLAW_MOTION_OVERLAY_PROBE_STUB=<json> → probe returns this {durationSeconds,width,height}.
+ *  - VCLAW_MOTION_OVERLAY_TRANSCRIPT_STUB=<path> → STT returns this transcript JSON.
+ */
+function buildMotionOverlayTestDeps() {
+    const deps = {};
+    if (process.env.VCLAW_MOTION_OVERLAY_FAKE_FFMPEG === '1') {
+        // No-op ffmpeg, but still touch the output path (last arg) so cuts/extracts
+        // leave placeholder take/frame files — the flow-pack copy step needs them.
+        deps.runFfmpeg = async (a) => {
+            const out = a[a.length - 1];
+            await mkdir(dirname(out), { recursive: true }).catch(() => { });
+            await writeFile(out, '').catch(() => { });
+            return { command: `ffmpeg ${a.join(' ')}` };
+        };
+    }
+    const probeStub = process.env.VCLAW_MOTION_OVERLAY_PROBE_STUB;
+    if (probeStub) {
+        const parsed = JSON.parse(probeStub);
+        deps.probe = async () => ({
+            durationSeconds: parsed.durationSeconds,
+            width: parsed.width,
+            height: parsed.height,
+        });
+    }
+    const transcriptStub = process.env.VCLAW_MOTION_OVERLAY_TRANSCRIPT_STUB;
+    if (transcriptStub) {
+        deps.transcriber = async () => {
+            const raw = readFileSync(transcriptStub, 'utf-8');
+            const value = JSON.parse(raw);
+            return validateTranscript(value, transcriptStub);
+        };
+    }
+    return deps;
+}
+/**
+ * `vclaw video music-video` — the vocal-synced, beat-exact music-video assembler.
+ *
+ * Phase 2 implements the plan/dry path: ingest → STT → slice → compose → write
+ * work folder + manifest + per-take prompts. `--execute` is reserved for Phase 4
+ * (V2V render); until then it requires `--confirm-spend` (exit-3 otherwise) and
+ * reports that execution is not yet wired so no spend is silently attempted.
+ */
+export async function handleVideoMotionOverlay(args) {
+    const input = parseFlagValue(args, '--input');
+    if (!input) {
+        throw new VclawError('missing_required_flag', 'video motion-overlay requires --input <video-path>', {
+            missing: ['--input'],
+        });
+    }
+    if (!existsSync(input)) {
+        throw new VclawError('asset_not_found', `--input not found: ${input}`, { path: input });
+    }
+    const layoutRaw = parseFlagValue(args, '--layout') ?? 'split';
+    if (!MOTION_OVERLAY_LAYOUTS.includes(layoutRaw)) {
+        throw new VclawError('invalid_flag_value', `video motion-overlay: --layout must be one of ${MOTION_OVERLAY_LAYOUTS.join(', ')}, got: ${layoutRaw}`, { flag: '--layout' });
+    }
+    const layout = layoutRaw;
+    const styleRaw = parseFlagValue(args, '--style') ?? 'apple-clean';
+    if (!MOTION_OVERLAY_STYLES.includes(styleRaw)) {
+        throw new VclawError('invalid_flag_value', `video motion-overlay: --style must be one of ${MOTION_OVERLAY_STYLES.join(', ')}, got: ${styleRaw}`, { flag: '--style' });
+    }
+    const style = styleRaw;
+    const headlinesFlag = args.includes('--headlines');
+    const iconsFlag = args.includes('--icons');
+    const animateFlag = args.includes('--animate');
+    let emitFlowPackFlag = args.includes('--emit-flow-pack');
+    const restitchDir = parseFlagValue(args, '--restitch');
+    const accent = parseFlagValue(args, '--accent');
+    const lang = parseFlagValue(args, '--lang') ?? 'auto';
+    let renderMode = parseFlagValue(args, '--render') ?? 'v2v';
+    if (renderMode !== 'v2v' && renderMode !== 'local') {
+        throw new VclawError('invalid_flag_value', `video motion-overlay: --render must be 'v2v' or 'local', got: ${renderMode}`, { flag: '--render' });
+    }
+    // `--delivery` — the high-level "where the animation comes from" knob. It sets the
+    // render mode + flow-pack defaults; --render/--emit-flow-pack remain the low-level
+    // controls (used when --delivery is absent).
+    //   local    → render the reel locally (reliable, free).            [default product]
+    //   flow-web → render local AND emit the Flow hand-off pack (paste into Flow web).
+    //   flow-api → omni-flash V2V via the API (gated; needs --execute --confirm-spend).
+    const delivery = parseFlagValue(args, '--delivery');
+    if (delivery !== undefined) {
+        if (delivery !== 'local' && delivery !== 'flow-web' && delivery !== 'flow-api') {
+            throw new VclawError('invalid_flag_value', `video motion-overlay: --delivery must be local|flow-web|flow-api, got: ${delivery}`, { flag: '--delivery' });
+        }
+        renderMode = delivery === 'flow-api' ? 'v2v' : 'local';
+        if (delivery === 'flow-web')
+            emitFlowPackFlag = true;
+    }
+    const kicker = parseFlagValue(args, '--kicker') ?? '';
+    const transcriptPath = parseFlagValue(args, '--transcript');
+    if (transcriptPath && !existsSync(transcriptPath)) {
+        throw new VclawError('asset_not_found', `--transcript not found: ${transcriptPath}`, { path: transcriptPath });
+    }
+    let gbCharacter;
+    if (layout === 'avatar-host') {
+        const gbRaw = parseFlagValue(args, '--gb-character');
+        if (!gbRaw) {
+            throw new VclawError('missing_required_flag', 'video motion-overlay --layout avatar-host requires --gb-character <Name:ID>', { missing: ['--gb-character'] });
+        }
+        try {
+            gbCharacter = parseGbCharacter(gbRaw);
+        }
+        catch (err) {
+            throw new VclawError('invalid_flag_value', err instanceof Error ? err.message : String(err), { flag: '--gb-character' });
+        }
+    }
+    // Avatar-host: the R2V reference still for the host, and the Flow voice preset
+    // Omni uses to speak each line. The image is required only at --execute time.
+    const gbCharacterImage = parseFlagValue(args, '--gb-character-image');
+    if (gbCharacterImage && !existsSync(gbCharacterImage)) {
+        throw new VclawError('asset_not_found', `--gb-character-image not found: ${gbCharacterImage}`, {
+            path: gbCharacterImage,
+        });
+    }
+    const gbVoice = parseFlagValue(args, '--gb-voice') ?? 'Puck';
+    const hostRetriesRaw = parseFlagValue(args, '--host-retries');
+    let hostAttempts = 3;
+    if (hostRetriesRaw !== undefined) {
+        const n = Number(hostRetriesRaw);
+        if (!Number.isInteger(n) || n < 1) {
+            throw new VclawError('invalid_flag_value', '--host-retries must be a positive integer (attempts per take, default 3)');
+        }
+        hostAttempts = n;
+    }
+    const hostLook = parseFlagValue(args, '--host-look');
+    const hostChain = !args.includes('--no-host-chain');
+    const hostEngine = parseFlagValue(args, '--host-engine') ?? 'omni-r2v';
+    if (hostEngine !== 'omni-r2v' && hostEngine !== 'veo-i2v') {
+        throw new VclawError('invalid_flag_value', `--host-engine must be omni-r2v or veo-i2v, got: ${hostEngine}`);
+    }
+    const maxRaw = parseFlagValue(args, '--max-take-seconds');
+    let maxTakeSeconds = 10;
+    if (maxRaw !== undefined) {
+        maxTakeSeconds = Number(maxRaw);
+        if (!Number.isFinite(maxTakeSeconds) || maxTakeSeconds <= 0) {
+            throw new VclawError('invalid_flag_value', `--max-take-seconds must be a positive number, got: ${maxRaw}`, {
+                flag: '--max-take-seconds',
+            });
+        }
+    }
+    const root = parseFlagValue(args, '--root') ?? process.cwd();
+    const projectSlug = parseProjectSlugFlag(args);
+    const outputDir = parseFlagValue(args, '--output-dir');
+    let workdir;
+    if (outputDir) {
+        workdir = resolve(outputDir);
+    }
+    else if (projectSlug) {
+        if (!isProjectSlug(projectSlug)) {
+            throw new VclawError('invalid_slug', `Invalid --project slug: ${JSON.stringify(projectSlug)}`, {
+                slug: projectSlug,
+            });
+        }
+        workdir = join(resolveProjectWorkspace(projectSlug, root).artifactsDir, 'motion-overlay');
+    }
+    else {
+        throw new VclawError('missing_required_flag', 'video motion-overlay requires --project <slug> or --output-dir <path>', { missing: ['--project', '--output-dir'] });
+    }
+    const execute = args.includes('--execute');
+    const dryRun = args.includes('--dry-run') || !execute;
+    const preview = args.includes('--preview');
+    // The spend gate fires the moment --execute is requested without --confirm-spend
+    // (exit-3), so no provider is ever silently called. The V2V render mode and the
+    // avatar-host layout (omni-flash R2V generation) spend; `--render local` is free
+    // (sharp + ffmpeg only) and needs no gate.
+    if (execute && (renderMode === 'v2v' || layout === 'avatar-host')) {
+        requireSpendConfirmation(args, args.includes('--dry-run'), 'motion-overlay', 'Omni Flash');
+    }
+    // Offline test seams (never used in production): a probe/transcript stub +
+    // a fake-ffmpeg switch let the e2e CLI test run without ffmpeg or a network
+    // STT call. Real runs leave these unset and use the live ffmpeg/Gemini path.
+    const deps = buildMotionOverlayTestDeps();
+    const result = await planMotionOverlay({
+        input: resolve(input),
+        workdir,
+        layout,
+        style,
+        lang,
+        maxTakeSeconds,
+        ...(accent ? { accent } : {}),
+        ...(transcriptPath ? { transcriptPath } : {}),
+        ...(preview ? { preview: true } : {}),
+    }, deps);
+    // Phase 4 — render. With --execute --confirm-spend, run each take through the
+    // omni-flash V2V transport, restore the original take audio, and clip-stitch
+    // the reel. The runner is the single side-effect seam (default = the real Flow
+    // V2V path + ffmpeg + assemble stitch); the offline e2e test injects a fake.
+    // Avatar-host (Layout D): before V2V, generate a per-take host base clip
+    // (go-bananas locked character -> Veo I2V keyframe -> short clip). Each host
+    // clip becomes the V2V base footage for its take (the original take audio is
+    // still restored on top). The generator is the single side-effect seam
+    // (default = the real go-bananas + Veo I2V path); the offline e2e test injects
+    // a fake. Only runs under --execute --confirm-spend (no spend in plan mode).
+    // `--render local`: produce the finished reel locally (native sharp lower-thirds
+    // + ffmpeg overlay) from the source + transcript — no provider, no spend. This is
+    // the reliable overlay path (omni-flash V2V edits are moderation-blocked for most
+    // inputs). Runs regardless of --execute since it costs nothing.
+    // `--restitch <dir>`: the operator pasted each take into Flow and downloaded the
+    // animated clips into <dir>. Re-mux each with its ORIGINAL audio and concat the
+    // finished reel. Terminal — skips all rendering/generation/spend.
+    const fakeFfmpeg = process.env.VCLAW_MOTION_OVERLAY_FAKE_FFMPEG === '1';
+    const ffmpegRun = fakeFfmpeg
+        ? async (a) => { await writeFile(a[a.length - 1], ''); }
+        : async (a) => { await runFfmpeg(a); };
+    let restitchResult;
+    if (restitchDir) {
+        const reel = join(result.plan.workdir, 'motion-overlay-reel.mp4');
+        restitchResult = await restitchFlowOutputs(result.plan, resolve(restitchDir), reel, {
+            ffmpeg: ffmpegRun,
+            ...(fakeFfmpeg ? { listDir: async () => result.plan.takes.map((t) => join(resolve(restitchDir), basename(t.file))) } : {}),
+        });
+    }
+    let localReelPath;
+    if (!restitchDir && renderMode === 'local') {
+        localReelPath = await renderMotionOverlayLocalReel(result.plan, kicker, style, headlinesFlag, iconsFlag, animateFlag);
+    }
+    let executeReport;
+    let avatarResult;
+    if (!restitchDir && execute && layout === 'avatar-host') {
+        if (!gbCharacterImage) {
+            throw new VclawError('missing_required_flag', 'motion-overlay --layout avatar-host --execute requires --gb-character-image <path> (the R2V reference still the host is generated from)', { missing: ['--gb-character-image'] });
+        }
+        avatarResult = await executeAvatarHostReel({
+            plan: result.plan,
+            character: gbCharacter,
+            characterImage: resolve(gbCharacterImage),
+            voice: gbVoice,
+            kicker,
+            hostAttempts,
+            hostLook,
+            hostChain,
+            hostEngine,
+            variant: style,
+            headlines: headlinesFlag,
+            icons: iconsFlag,
+        });
+    }
+    else if (!restitchDir && execute && renderMode === 'v2v') {
+        const runner = buildMotionOverlayRunner();
+        executeReport = await runMotionOverlay(result.plan, { runner, confirmSpend: true });
+    }
+    // `--emit-flow-pack`: write the drop-in Flow hand-off bundle (take clips + clean
+    // prompt .txt + README) so the operator can paste each take into Flow's web editor.
+    let flowPackResult;
+    if (emitFlowPackFlag && !restitchDir) {
+        const r = await emitFlowPack(result.plan, join(result.plan.workdir, 'flow-pack'));
+        flowPackResult = { packDir: r.packDir, entries: r.entries };
+    }
+    writeOutput({
+        action: 'motion-overlay',
+        mode: execute ? 'execute' : 'plan',
+        dryRun,
+        layout,
+        style,
+        accent: result.plan.accent,
+        language: result.plan.language,
+        input: result.plan.input.path,
+        workdir: result.plan.workdir,
+        takeCount: result.plan.takes.length,
+        manifestPath: result.manifestPath,
+        readmePath: result.readmePath,
+        promptPaths: result.promptPaths,
+        renderMode,
+        ...(delivery ? { delivery } : {}),
+        ...(result.reviewPath ? { reviewPath: result.reviewPath } : {}),
+        ...(restitchResult ? { restitched: true, reelPath: restitchResult.outputPath, restitchedTakes: restitchResult.takeCount } : {}),
+        ...(flowPackResult ? { flowPackDir: flowPackResult.packDir, flowPackTakes: flowPackResult.entries.length } : {}),
+        ...(localReelPath ? { localReelPath } : {}),
+        ...(gbCharacter ? { gbCharacter: `${gbCharacter.name}:${gbCharacter.id}` } : {}),
+        ...(executeReport
+            ? {
+                executed: executeReport.executed,
+                reelPath: executeReport.reelPath,
+                renderedTakes: executeReport.takes.map((t) => ({ index: t.index, restoredTake: t.restoredTake })),
+            }
+            : {}),
+        ...(avatarResult
+            ? {
+                executed: true,
+                hostEngine,
+                reelPath: avatarResult.reelPath,
+                avatarReelPath: avatarResult.rawReelPath,
+                captioned: avatarResult.captioned,
+                hostClips: avatarResult.hostClips,
+                ...(hostEngine === 'omni-r2v' ? { voice: gbVoice } : {}),
+            }
+            : {}),
+    });
+}
+/** The real flow.ts spawn: `bun run flow.ts ...` in the vclaw-cli dir. */
+const realFlowSpawn = (flowArgs, opts) => new Promise((resolveSpawn, rejectSpawn) => {
+    const bin = opts.env.VCLAW_VEO_BUN_BIN || 'bun';
+    const child = spawn(bin, flowArgs, { cwd: opts.cwd, env: opts.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => child.kill('SIGTERM'), 300_000);
+    child.stdout?.on('data', (d) => {
+        stdout += String(d);
+    });
+    child.stderr?.on('data', (d) => {
+        stderr += String(d);
+    });
+    child.on('error', rejectSpawn);
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        resolveSpawn({ code: code ?? 1, stdout, stderr });
+    });
+});
+/**
+ * Avatar-host `--execute`: generate a per-take host clip with omni-flash R2V +
+ * native voice (the avatar SPEAKS each line, lip-synced — Omni makes the audio and
+ * video together), stitch the clips into the avatar reel, then caption it by
+ * re-transcribing the avatar's own speech (its timing differs from the source) and
+ * running the local lower-third renderer. Captioning is best-effort; the
+ * lip-synced reel stands on its own if it fails. `VCLAW_MOTION_OVERLAY_FAKE_RUNNER`
+ * no-ops every side effect so the CLI e2e runs offline with no spend.
+ */
+async function executeAvatarHostReel(args) {
+    const { plan, character, characterImage, voice, kicker } = args;
+    const hostAttempts = args.hostAttempts ?? 3;
+    const hostChain = args.hostChain !== false;
+    const hostEngine = args.hostEngine ?? 'omni-r2v';
+    const variant = args.variant ?? 'apple-clean';
+    const wantHeadlines = args.headlines === true;
+    const wantIcons = args.icons === true;
+    const fake = process.env.VCLAW_MOTION_OVERLAY_FAKE_RUNNER === '1';
+    // 1. Per-take spoken line from the saved transcript (segments within the take window).
+    const txRaw = await readFile(join(plan.workdir, 'source', 'transcript.json'), 'utf-8');
+    const segments = JSON.parse(txRaw).segments ?? [];
+    const textByIndex = {};
+    for (const take of plan.takes) {
+        textByIndex[take.index] = segments
+            .filter((s) => s.start >= take.start - 0.01 && s.start < take.end + 0.01)
+            .map((s) => s.text)
+            .join(' ')
+            .trim();
+    }
+    // 2. Generate the per-take host clips. Two engines:
+    //    - omni-r2v (default): omni-flash R2V + NATIVE VOICE (talking, lip-synced),
+    //      loose identity mitigated by --host-look pinning + cross-take frame chaining.
+    //    - veo-i2v: Veo I2V from the SAME character still each take → pixel-tight
+    //      identity, SILENT (captioned). The consistency-first engine.
+    // Adapted post-extraction from vclaw.ts: import.meta.url now resolves to
+    // dist/cli/handlers/motion-overlay.js (one directory deeper), so the bundled
+    // Bun vclaw-cli package at the repo root needs three '..' hops, not two.
+    const cliRoot = process.env.VCLAW_VEO_CLI_ROOT ?? join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'vclaw-cli');
+    const onRetry = ({ takeIndex, attempt, maxAttempts, detail }) => process.stderr.write(`[motion-overlay] take ${takeIndex} rejected — retry ${attempt}/${maxAttempts}` +
+        `${detail ? ` (${detail.slice(0, 120)})` : ''}\n`);
+    let generator;
+    if (fake) {
+        generator = {
+            async generateHostClip(step) {
+                await mkdir(dirname(step.outputPath), { recursive: true });
+                await writeFile(step.outputPath, '');
+            },
+        };
+    }
+    else if (hostEngine === 'veo-i2v') {
+        generator = createVeoI2vHostGenerator({
+            startImage: characterImage,
+            characterName: character.name,
+            appearance: args.hostLook,
+            // Veo I2V is landscape-only server-side; flow.ts forces it regardless.
+            ratio: 'landscape',
+            veoModel: 'quality',
+            cliRoot,
+            env: process.env,
+            spawn: realFlowSpawn,
+            maxAttempts: hostAttempts,
+            onRetry,
+        });
+    }
+    else {
+        generator = createOmniHostGenerator({
+            characterImage,
+            characterName: character.name,
+            voice,
+            ratio: flowRatio(plan.input.aspect),
+            cliRoot,
+            env: process.env,
+            spawn: realFlowSpawn,
+            maxAttempts: hostAttempts,
+            // Consistency: pin the character's look on every take + chain each take from
+            // the previous take's last frame so identity/wardrobe carry across the reel.
+            appearance: args.hostLook,
+            chain: hostChain,
+            extractLastFrame: async (videoPath, outPath) => {
+                // Grab the final frame: seek to the last second, let -update overwrite each
+                // decoded frame so the file ends on the very last one.
+                await runFfmpeg(['-sseof', '-1', '-i', videoPath, '-update', '1', '-q:v', '2', outPath]);
+            },
+            onRetry,
+        });
+    }
+    const hostReport = await runAvatarHostGeneration(plan, character, { generator, textByIndex, confirmSpend: true });
+    // 3. Stitch the host clips (in take order) into the avatar reel.
+    const orderedHostClips = [...plan.takes]
+        .sort((a, b) => a.index - b.index)
+        .map((t) => hostReport.hostBaseByIndex[t.index]);
+    const rawReelPath = join(plan.workdir, 'avatar-reel.mp4');
+    if (fake) {
+        await writeFile(rawReelPath, '');
+    }
+    else {
+        await stitch({ segments: orderedHostClips, outputPath: rawReelPath });
+    }
+    // 4. Caption → local lower-thirds. omni-r2v re-transcribes the avatar's OWN speech
+    //    (Omni's pacing differs from the source). veo-i2v is SILENT, so captions come
+    //    from the planned script timed to each take's snapped Veo duration.
+    let reelPath = rawReelPath;
+    let captioned = false;
+    if (!fake) {
+        try {
+            let captions;
+            if (hostEngine === 'veo-i2v') {
+                const ordered = [...plan.takes].sort((a, b) => a.index - b.index);
+                captions = [];
+                let offset = 0;
+                for (const take of ordered) {
+                    const dur = snapVeoDuration(take.durationSeconds);
+                    const text = textByIndex[take.index];
+                    if (text)
+                        captions.push({ text, start: offset, end: offset + dur });
+                    offset += dur;
+                }
+            }
+            else {
+                const audioPath = join(plan.workdir, 'avatar-audio.m4a');
+                await extractAudio(rawReelPath, audioPath);
+                const tx = await transcribeAudio(audioPath, plan.language);
+                captions = tx.segments.map((s) => ({ text: s.text, start: s.start, end: s.end }));
+            }
+            if (captions.length > 0) {
+                const probe = await probeVideo(rawReelPath);
+                const capSegments = captions.map((c) => ({ start: c.start, end: c.end, text: c.text }));
+                const split = {
+                    index: 0,
+                    start: captions[0].start,
+                    end: captions[captions.length - 1].end,
+                    segmentIndices: captions.map((_, i) => i),
+                };
+                const accentWords = analyzeTake(split, capSegments, 1).anchorWords.map((a) => a.word);
+                const headlineMoments = wantHeadlines ? deriveHeadlineMoments(capSegments, accentWords) : [];
+                const motifMoments = wantIcons ? detectMotifs(capSegments) : [];
+                reelPath = join(plan.workdir, 'motion-overlay-avatar.mp4');
+                await renderLocalOverlay({
+                    sourceVideo: rawReelPath,
+                    captions,
+                    dims: { width: probe.width, height: probe.height },
+                    style: { accent: plan.accent, ...(kicker ? { kicker } : {}), accentWords, variant },
+                    ...(headlineMoments.length ? { headlines: headlineMoments } : {}),
+                    ...(motifMoments.length ? { motifs: motifMoments } : {}),
+                    cardDir: join(plan.workdir, 'cards'),
+                    outputPath: reelPath,
+                }, { ffmpeg: async (a) => { await runFfmpeg(a); } });
+                captioned = true;
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[motion-overlay/avatar] caption pass skipped: ${err.message}\n`);
+        }
+    }
+    return { reelPath, rawReelPath, hostClips: hostReport.hostBaseByIndex, captioned };
+}
+/**
+ * `--headlines`: turn anchor words into giant centred kinetic-typography pulses at
+ * the moment each is spoken (the source skill's signature beat). At most one per
+ * caption, capped (default 6) so the reel doesn't strobe. Shared by `--render local`
+ * and the avatar-host caption pass.
+ */
+function deriveHeadlineMoments(segments, accentWords, max = 6) {
+    const moments = [];
+    const used = new Set();
+    for (const seg of segments) {
+        const hit = accentWords.find((w) => {
+            const key = w.toLowerCase();
+            return !used.has(key) && new RegExp(`\\b${w.replace(/[^A-Za-z0-9]/g, '')}\\b`, 'i').test(seg.text);
+        });
+        if (hit) {
+            used.add(hit.toLowerCase());
+            const start = seg.start + 0.15;
+            moments.push({ word: hit, start, end: Math.min(seg.end, start + 1.6) });
+        }
+        if (moments.length >= max)
+            break;
+    }
+    return moments;
+}
+/**
+ * `--render local`: render the finished overlay reel from the planned source +
+ * transcript using the native sharp lower-third renderer + an ffmpeg overlay
+ * composite. Free (no provider). Captions come from the saved transcript; accent
+ * words reuse the same anchor-word detector the prompt composer uses. Returns the
+ * reel path.
+ */
+async function renderMotionOverlayLocalReel(plan, kicker, variant, headlines, icons, animate) {
+    const txRaw = await readFile(join(plan.workdir, 'source', 'transcript.json'), 'utf-8');
+    const tx = JSON.parse(txRaw);
+    const segments = tx.segments ?? [];
+    if (segments.length === 0) {
+        throw new VclawError('unexpected_internal_error', 'motion-overlay --render local: the transcript has no segments to caption.');
+    }
+    const captions = segments.map((s) => ({ text: s.text, start: s.start, end: s.end }));
+    // Reuse the anchor-word detector over one split spanning the whole transcript.
+    const split = {
+        index: 0,
+        start: segments[0].start,
+        end: segments[segments.length - 1].end,
+        segmentIndices: segments.map((_, i) => i),
+    };
+    const accentWords = analyzeTake(split, segments, 1).anchorWords.map((a) => a.word);
+    const headlineMoments = headlines ? deriveHeadlineMoments(segments, accentWords) : [];
+    const motifMoments = icons ? detectMotifs(segments) : [];
+    const reelPath = join(plan.workdir, 'motion-overlay-local.mp4');
+    // Offline test seam: VCLAW_MOTION_OVERLAY_FAKE_FFMPEG no-ops sharp + ffmpeg so the
+    // CLI e2e exercises the --render local path without rasterising or invoking ffmpeg.
+    const fake = process.env.VCLAW_MOTION_OVERLAY_FAKE_FFMPEG === '1';
+    const renderDeps = fake
+        ? { ffmpeg: async () => { await writeFile(reelPath, ''); }, rasterise: async () => Buffer.from('') }
+        : { ffmpeg: async (ffArgs) => { await runFfmpeg(ffArgs); } };
+    if (animate) {
+        // --animate: render a real motion-graphics layer — per-frame composite with
+        // entrance + word-by-word reveal + stat count-up/gauge-fill — overlaid on source.
+        const style = { accent: plan.accent, ...(kicker ? { kicker } : {}), accentWords, variant };
+        const elements = [
+            ...captions.map((c) => ({ kind: 'lower-third', start: c.start, end: c.end, text: c.text })),
+            ...headlineMoments.map((h) => ({ kind: 'headline', start: h.start, end: h.end, word: h.word })),
+            ...motifMoments.map((m) => m.kind === 'stat'
+                ? { kind: 'stat', start: m.start, end: m.end, value: Number(m.value ?? 0), ...(m.unit ? { unit: m.unit } : {}), ...(m.gauge !== undefined ? { gauge: m.gauge } : {}) }
+                : { kind: 'icon', start: m.start, end: m.end, motif: m }),
+        ];
+        await renderAnimatedOverlay({
+            sourceVideo: plan.input.path,
+            dims: { width: plan.input.width, height: plan.input.height },
+            durationSeconds: plan.input.durationSeconds,
+            style,
+            elements,
+            frameDir: join(plan.workdir, 'frames-anim'),
+            outputPath: reelPath,
+        }, renderDeps);
+        return reelPath;
+    }
+    await renderLocalOverlay({
+        sourceVideo: plan.input.path,
+        captions,
+        dims: { width: plan.input.width, height: plan.input.height },
+        style: { accent: plan.accent, ...(kicker ? { kicker } : {}), accentWords, variant },
+        ...(headlineMoments.length ? { headlines: headlineMoments } : {}),
+        ...(motifMoments.length ? { motifs: motifMoments } : {}),
+        cardDir: join(plan.workdir, 'cards'),
+        outputPath: reelPath,
+    }, renderDeps);
+    return reelPath;
+}
+/**
+ * Build the motion-overlay execute runner. In production this is the default
+ * runner (real Flow V2V + ffmpeg audio-restore + assemble clip-stitch). The
+ * offline e2e test sets `VCLAW_MOTION_OVERLAY_FAKE_RUNNER=1` to swap in a runner
+ * that touches no provider/ffmpeg — it just writes empty placeholder outputs — so
+ * the --execute path is exercised end-to-end without any spend.
+ */
+function buildMotionOverlayRunner() {
+    if (process.env.VCLAW_MOTION_OVERLAY_FAKE_RUNNER === '1') {
+        const touch = async (p) => {
+            await mkdir(dirname(p), { recursive: true });
+            await writeFile(p, '', 'utf-8');
+        };
+        return {
+            async runV2V(step) {
+                await touch(step.outputPath);
+            },
+            async restoreAudio(step) {
+                await touch(step.outputPath);
+            },
+            async stitch(step) {
+                await touch(step.outputPath);
+            },
+        };
+    }
+    return createDefaultMotionOverlayRunner({ v2v: motionOverlayV2VTransport });
+}
+/**
+ * The real per-take omni-flash V2V transport for the default runner: upload the
+ * take as the Flow V2V reference media, submit omni-flash with the composed
+ * prompt, poll, and download the annotated take to `outputPath` (see
+ * `motion-overlay/v2v-transport.ts`). Credentials (USEAPI_API_TOKEN +
+ * USEAPI_ACCOUNT_EMAIL) are read lazily from the environment so a missing-creds
+ * failure surfaces at execute time with a clear message, not at import.
+ *
+ * Note: the Google Flow safety filter rejects some source clips for editing
+ * (FINISH_REASON_INPUT_VIDEO_EDIT) regardless of prompt; the transport retries a
+ * few times, then fails with an actionable message suggesting a different clip.
+ */
+const motionOverlayV2VTransport = async (step) => {
+    let config;
+    try {
+        config = flowV2VConfigFromEnv();
+    }
+    catch (err) {
+        throw new VclawError('provider_unreachable', err.message, {
+            hint: 'export USEAPI_API_TOKEN and USEAPI_ACCOUNT_EMAIL (e.g. from .env) before --execute',
+        });
+    }
+    return createFlowV2VTransport(config)(step);
+};
+//# sourceMappingURL=motion-overlay.js.map