videoclaw 3.0.0-alpha.1

package/dist/cli/handlers/media-production.js

@@ -0,0 +1,673 @@
+/**
+ * Media-production command handlers for `vclaw`.
+ *
+ * Extracted verbatim from the monolithic `vclaw.ts`: `assemble` (FFmpeg
+ * stitch incl. --from-clips), `gen-image` (diegetic prop/screen/overlay
+ * stills), `overlay` (graphic/alert/lower-third motion graphics with the
+ * drawtext preflight), `music-video` (vocal-synced beat-exact assembler,
+ * plan/dry by default), `title-card` (Pillow+RAQM title overlays),
+ * `finish` (Topaz upscale; hosted backends spend-gated), and `lipsync`
+ * (OmniHuman, spend-gated). Dispatch stays in `vclaw.ts`.
+ */
+import { dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { parseFlagValue, parseProjectSlugFlag, parseRepeatableFlag } from '../args.js';
+import { VclawError } from '../../video/errors.js';
+import { writeOutput } from '../../video/cli-output.js';
+import { ensureProjectWorkspace } from '../../video/workspace.js';
+import { assembleProject, writeAssembleReport } from '../../video/assemble/assemble.js';
+import { generateGenImage, buildGenImageRequest, GEN_IMAGE_KINDS, GEN_IMAGE_BACKENDS, DEFAULT_GEN_IMAGE_BACKEND, } from '../../video/gen-image.js';
+import { buildFlowImageParams, FLOW_IMAGE_MODELS, FLOW_IMAGE_ASPECTS, FLOW_IMAGE_MAX_REFERENCES, FLOW_IMAGE_MAX_CHARACTERS, looksLikeFlowCharacterRef, looksLikeFlowMediaRef, } from '../../video/gen-image-flow.js';
+import { readFlowCharacters } from '../../video/flow-character-library.js';
+import { buildOverlayArgs, buildAlertTextArgs, buildLowerThirdArgs, runFfmpeg, OVERLAY_POSITION_IDS } from '../../video/assemble/index.js';
+import { ffmpegSupportsFilter } from '../../video/post-production.js';
+import { buildMusicVideoPlan, runMusicVideo } from '../../video/music-video.js';
+import { runTitleOverlay } from '../../video/title-overlay.js';
+import { runStitchAd } from '../../video/assemble/stitch-ad.js';
+import { runFinish, isHostedBackend, FINISH_BACKEND_IDS, TOPAZ_GRAIN_MAX } from '../../video/finish.js';
+import { runLipsync } from '../../video/lipsync.js';
+import { ANIMATION_STYLES, ANIMATION_STYLE_IDS, DEFAULT_ANIMATION_STYLE, getAnimationStyle } from '../../video/assemble/animation-styles.js';
+/**
+ * `video animation-styles [--style <id>]` — list the slide-animation styles from
+ * the shared registry (animation-styles.json), or show one style's full Veo
+ * motion prompt. Read-only, free. The styles drive `bunty_animate_slides.py`
+ * (the Veo F2V generator); this surfaces them as a first-class, discoverable
+ * CLI feature so operators can pick a style for animated slide decks.
+ */
+export async function handleVideoAnimationStyles(args) {
+    const styleId = parseFlagValue(args, '--style');
+    if (styleId) {
+        const style = getAnimationStyle(styleId);
+        if (!style) {
+            throw new VclawError('invalid_flag_value', `video animation-styles: unknown --style "${styleId}". Valid: ${ANIMATION_STYLE_IDS.join(', ')}`, { flag: '--style' });
+        }
+        writeOutput({ command: 'video animation-styles', style });
+        return;
+    }
+    writeOutput({
+        command: 'video animation-styles',
+        defaultStyle: DEFAULT_ANIMATION_STYLE,
+        count: ANIMATION_STYLES.length,
+        styles: ANIMATION_STYLES.map(({ id, label, description }) => ({ id, label, description })),
+    });
+}
+export async function handleVideoAssemble(args) {
+    const slug = parseProjectSlugFlag(args);
+    if (!slug) {
+        throw new VclawError('missing_required_flag', 'video assemble requires --project <slug>', { missing: ['--project'] });
+    }
+    const root = parseFlagValue(args, '--root') ?? process.cwd();
+    const dryRun = args.includes('--dry-run');
+    const brandProfilePath = parseFlagValue(args, '--brand-profile') ?? undefined;
+    // Clip-stitch mode: concatenate the per-scene rendered clips from
+    // `vclaw video execute` (outputs/scene-<i>.mp4) instead of animating slides.
+    const fromRenderedClips = args.includes('--from-clips');
+    const workspace = await ensureProjectWorkspace(slug, root);
+    const result = await assembleProject({
+        workspace,
+        dryRun,
+        ...(fromRenderedClips ? { fromRenderedClips } : {}),
+        ...(brandProfilePath ? { brandProfilePath } : {}),
+    });
+    const { artifactPath } = await writeAssembleReport(workspace, result, brandProfilePath);
+    writeOutput({ slug, artifactPath, ...result });
+}
+export async function handleVideoGenImage(args) {
+    const slug = parseProjectSlugFlag(args);
+    const prompt = parseFlagValue(args, '--prompt');
+    const kind = parseFlagValue(args, '--kind');
+    const missing = [];
+    if (!slug)
+        missing.push('--project');
+    if (!prompt)
+        missing.push('--prompt');
+    if (!kind)
+        missing.push('--kind');
+    if (missing.length > 0) {
+        throw new VclawError('missing_required_flag', 'video gen-image requires --project <slug>, --prompt "<text>", and --kind prop|screen|overlay', { missing });
+    }
+    if (!GEN_IMAGE_KINDS.includes(kind)) {
+        throw new VclawError('missing_required_flag', `video gen-image: --kind must be one of ${GEN_IMAGE_KINDS.join(', ')}, got: ${kind}`, { flag: '--kind' });
+    }
+    const root = parseFlagValue(args, '--root') ?? process.cwd();
+    const sceneRaw = parseFlagValue(args, '--scene');
+    let scene;
+    if (sceneRaw !== undefined) {
+        scene = Number(sceneRaw);
+        if (!Number.isInteger(scene) || scene < 0) {
+            throw new VclawError('missing_required_flag', '--scene must be a non-negative integer', { flag: '--scene' });
+        }
+    }
+    const aspectRatio = parseFlagValue(args, '--aspect');
+    const model = parseFlagValue(args, '--model');
+    const dryRun = args.includes('--dry-run');
+    // --backend (additive): gobananas (default, byte-identical legacy), openai, flow.
+    const backendRaw = parseFlagValue(args, '--backend');
+    const backend = (backendRaw ?? DEFAULT_GEN_IMAGE_BACKEND);
+    if (backendRaw !== undefined && !GEN_IMAGE_BACKENDS.includes(backend)) {
+        throw new VclawError('invalid_flag_value', `video gen-image: --backend must be one of ${GEN_IMAGE_BACKENDS.join(', ')}, got: ${backendRaw}`, { flag: '--backend' });
+    }
+    // Flow-only flags — rejected loudly on other backends (no silent ignore).
+    const refs = parseRepeatableFlag(args, '--ref');
+    const characterValues = parseRepeatableFlag(args, '--character');
+    const countRaw = parseFlagValue(args, '--count');
+    const seedRaw = parseFlagValue(args, '--seed');
+    if (backend !== 'flow') {
+        const flowOnly = [];
+        if (refs.length > 0)
+            flowOnly.push('--ref');
+        if (characterValues.length > 0)
+            flowOnly.push('--character');
+        if (countRaw !== undefined)
+            flowOnly.push('--count');
+        if (seedRaw !== undefined)
+            flowOnly.push('--seed');
+        if (flowOnly.length > 0) {
+            throw new VclawError('invalid_flag_value', `video gen-image: ${flowOnly.join(', ')} require${flowOnly.length === 1 ? 's' : ''} --backend flow (current backend: ${backend})`, { flags: flowOnly, backend });
+        }
+    }
+    if (backend === 'flow' && model !== undefined && !FLOW_IMAGE_MODELS.includes(model)) {
+        throw new VclawError('invalid_flag_value', `video gen-image: --model must be one of ${FLOW_IMAGE_MODELS.join(', ')} with --backend flow, got: ${model}`, { flag: '--model' });
+    }
+    if (refs.length > FLOW_IMAGE_MAX_REFERENCES) {
+        throw new VclawError('invalid_flag_value', `video gen-image: at most ${FLOW_IMAGE_MAX_REFERENCES} --ref values are supported (reference_1..${FLOW_IMAGE_MAX_REFERENCES}), got ${refs.length}`, { flag: '--ref' });
+    }
+    if (characterValues.length > FLOW_IMAGE_MAX_CHARACTERS) {
+        throw new VclawError('invalid_flag_value', `video gen-image: at most ${FLOW_IMAGE_MAX_CHARACTERS} --character values are supported (character_1..${FLOW_IMAGE_MAX_CHARACTERS}), got ${characterValues.length}`, { flag: '--character' });
+    }
+    let count;
+    if (countRaw !== undefined) {
+        count = Number(countRaw);
+        if (!Number.isInteger(count) || count < 1 || count > 4) {
+            throw new VclawError('invalid_flag_value', `video gen-image: --count must be an integer between 1 and 4, got: ${countRaw}`, { flag: '--count' });
+        }
+    }
+    let seed;
+    if (seedRaw !== undefined) {
+        seed = Number(seedRaw);
+        if (!Number.isInteger(seed) || seed < 0) {
+            throw new VclawError('invalid_flag_value', `video gen-image: --seed must be a non-negative integer, got: ${seedRaw}`, { flag: '--seed' });
+        }
+    }
+    // --aspect with --backend flow: validate at the handler so misuse surfaces
+    // as invalid_flag_value like every other flow flag (not as an internal error
+    // escaping buildFlowImageParams). Mirrors the gen-image-flow guard: "auto"
+    // derives the aspect from the references, so it needs a nano-banana model
+    // AND at least one reference image (--ref / --character).
+    if (backend === 'flow' && aspectRatio !== undefined) {
+        if (!FLOW_IMAGE_ASPECTS.includes(aspectRatio)) {
+            throw new VclawError('invalid_flag_value', `video gen-image: --aspect must be one of ${FLOW_IMAGE_ASPECTS.join(', ')} with --backend flow, got: ${aspectRatio}`, { flag: '--aspect' });
+        }
+        if (aspectRatio === 'auto' && (model === 'imagen-4' || (refs.length === 0 && characterValues.length === 0))) {
+            throw new VclawError('invalid_flag_value', 'video gen-image: --aspect auto requires a nano-banana model and at least one reference image (--ref or --character) with --backend flow', { flag: '--aspect' });
+        }
+    }
+    // Go Bananas-only: lock the still to a managed character (--character-id) and/or
+    // render via a style preset (--style-preset-id, e.g. the reference-sheet preset).
+    // Rejected loudly on other backends — they have their own reference mechanisms.
+    const characterIdRaw = parseFlagValue(args, '--character-id');
+    const stylePresetIdRaw = parseFlagValue(args, '--style-preset-id');
+    if (backend !== 'gobananas') {
+        const gbOnly = [];
+        if (characterIdRaw !== undefined)
+            gbOnly.push('--character-id');
+        if (stylePresetIdRaw !== undefined)
+            gbOnly.push('--style-preset-id');
+        if (gbOnly.length > 0) {
+            throw new VclawError('invalid_flag_value', `video gen-image: ${gbOnly.join(', ')} require${gbOnly.length === 1 ? 's' : ''} --backend gobananas (current backend: ${backend})`, { flags: gbOnly, backend });
+        }
+    }
+    let characterId;
+    if (characterIdRaw !== undefined) {
+        characterId = Number(characterIdRaw);
+        if (!Number.isInteger(characterId) || characterId < 1) {
+            throw new VclawError('invalid_flag_value', `video gen-image: --character-id must be a positive integer, got: ${characterIdRaw}`, { flag: '--character-id' });
+        }
+    }
+    let stylePresetId;
+    if (stylePresetIdRaw !== undefined) {
+        stylePresetId = Number(stylePresetIdRaw);
+        if (!Number.isInteger(stylePresetId) || stylePresetId < 1) {
+            throw new VclawError('invalid_flag_value', `video gen-image: --style-preset-id must be a positive integer, got: ${stylePresetIdRaw}`, { flag: '--style-preset-id' });
+        }
+    }
+    const workspace = await ensureProjectWorkspace(slug, root);
+    const fileName = `${kind}${scene !== undefined ? `-scene${String(scene).padStart(3, '0')}` : ''}.png`;
+    const outputPath = parseFlagValue(args, '--out') ?? join(workspace.projectDir, 'assets', 'props', fileName);
+    const reqOpts = {
+        prompt: prompt, kind: kind,
+        ...(aspectRatio ? { aspectRatio } : {}),
+        ...(model ? { model } : {}),
+        ...(characterId !== undefined ? { characterId } : {}),
+        ...(stylePresetId !== undefined ? { stylePresetId } : {}),
+    };
+    if (backend === 'flow') {
+        // Resolve --character values: a registered name (case-insensitive, via
+        // flow-characters.json) wins; otherwise the value must already look like a
+        // saved Flow character ref — anything else fails fast.
+        const lookup = characterValues.length > 0
+            ? await readFlowCharacters(root, slug)
+            : { characters: [], characterRefByName: new Map() };
+        const refByLowerName = new Map();
+        for (const [name, ref] of lookup.characterRefByName)
+            refByLowerName.set(name.toLowerCase(), ref);
+        const characterRefs = characterValues.map((value) => {
+            const resolved = refByLowerName.get(value.toLowerCase());
+            if (resolved !== undefined)
+                return resolved;
+            if (looksLikeFlowCharacterRef(value))
+                return value;
+            throw new VclawError('character_not_found', `video gen-image: --character ${JSON.stringify(value)} is not a registered Flow character for project ${slug} ` +
+                'and does not look like a Flow character ref (user:...-character:...). ' +
+                'Register it first with vclaw video flow-register-characters.', { flag: '--character', value });
+        });
+        // Classify --ref values by SHAPE (same polarity as generateViaFlow /
+        // flow-character-library): media-ref-shaped values pass through; anything
+        // else is a local path and must exist. A typo'd path fails fast here —
+        // including under --dry-run, where it would otherwise silently drop out
+        // of plannedUploads and ship verbatim as a bogus mediaGenerationId.
+        const plannedUploads = refs.filter((ref) => !looksLikeFlowMediaRef(ref));
+        const missingRefPaths = plannedUploads.filter((ref) => !existsSync(ref));
+        if (missingRefPaths.length > 0) {
+            throw new VclawError('invalid_flag_value', `video gen-image: --ref local path${missingRefPaths.length === 1 ? '' : 's'} not found: ${missingRefPaths.join(', ')} ` +
+                '(values not shaped like an uploaded Flow media ref (user:...) are treated as local image paths and must exist)', { flag: '--ref', missing: missingRefPaths });
+        }
+        if (dryRun) {
+            // Composed params with markers + the model x reference matrix STILL
+            // validated; uploads are NOT performed — local --ref paths appear
+            // verbatim in reference_N and are listed as planned uploads.
+            const accountEmail = process.env.USEAPI_ACCOUNT_EMAIL ?? '<USEAPI_ACCOUNT_EMAIL>';
+            const request = buildFlowImageParams({
+                prompt: prompt,
+                kind: kind,
+                email: accountEmail,
+                ...(model ? { model } : {}),
+                ...(aspectRatio ? { aspectRatio } : {}),
+                ...(count !== undefined ? { count } : {}),
+                ...(seed !== undefined ? { seed } : {}),
+                references: refs,
+                characterRefs,
+            });
+            writeOutput({
+                slug,
+                action: 'gen-image',
+                dryRun: true,
+                backend: 'flow',
+                kind,
+                ...(scene !== undefined ? { scene } : {}),
+                outputPath,
+                plannedUploads,
+                requestNote: 'local --ref paths shown verbatim in reference_N; a real run uploads them and substitutes their mediaGenerationIds',
+                request,
+            });
+            return;
+        }
+        const result = await generateGenImage({
+            ...reqOpts, backend, outputPath, refs, characterRefs,
+            ...(count !== undefined ? { count } : {}),
+            ...(seed !== undefined ? { seed } : {}),
+        });
+        writeOutput({
+            slug,
+            action: 'gen-image',
+            dryRun: false,
+            ...(scene !== undefined ? { scene } : {}),
+            ...result,
+            registerHint: `vclaw video assets --project ${slug} --asset image:${result.path}${scene !== undefined ? `:${scene}` : ''}`,
+        });
+        return;
+    }
+    if (dryRun) {
+        writeOutput({
+            slug,
+            action: 'gen-image',
+            dryRun: true,
+            ...(backendRaw !== undefined ? { backend } : {}),
+            kind,
+            ...(scene !== undefined ? { scene } : {}),
+            outputPath,
+            // The .png here is a placeholder; the real run rewrites the extension to the
+            // format the API actually serves (commonly .jpg) via withImageExtension.
+            outputPathNote: 'extension resolved at download time; the real file may be .jpg',
+            request: buildGenImageRequest({ ...reqOpts, backend }),
+        });
+        return;
+    }
+    const result = await generateGenImage({ ...reqOpts, backend, outputPath });
+    writeOutput({
+        slug,
+        action: 'gen-image',
+        dryRun: false,
+        ...(scene !== undefined ? { scene } : {}),
+        ...result,
+        registerHint: `vclaw video assets --project ${slug} --asset image:${result.path}${scene !== undefined ? `:${scene}` : ''}`,
+    });
+}
+export async function handleVideoOverlay(args) {
+    const input = parseFlagValue(args, '--input');
+    const output = parseFlagValue(args, '--output');
+    const missing = [];
+    if (!input)
+        missing.push('--input');
+    if (!output)
+        missing.push('--output');
+    if (missing.length > 0) {
+        throw new VclawError('missing_required_flag', 'video overlay requires --input <video> and --output <path>', { missing });
+    }
+    const graphic = parseFlagValue(args, '--graphic');
+    const alert = parseFlagValue(args, '--alert');
+    const lowerThird = parseFlagValue(args, '--lower-third');
+    const chosen = [graphic, alert, lowerThird].filter((v) => v !== undefined).length;
+    if (chosen !== 1) {
+        throw new VclawError('missing_required_flag', 'video overlay requires exactly one of --graphic <png>, --alert "<text>", or --lower-third "<text>"', { flags: ['--graphic', '--alert', '--lower-third'] });
+    }
+    const position = parseFlagValue(args, '--position');
+    if (position !== undefined && !OVERLAY_POSITION_IDS.includes(position)) {
+        throw new VclawError('invalid_flag_value', `video overlay: --position must be one of ${OVERLAY_POSITION_IDS.join(', ')}, got: ${position}`, { flag: '--position' });
+    }
+    const numFlag = (name, bounds = {}) => {
+        const raw = parseFlagValue(args, name);
+        if (raw === undefined)
+            return undefined;
+        // `Number('')` is 0, so an empty value would silently become 0 — reject it.
+        if (raw.trim() === '') {
+            throw new VclawError('invalid_flag_value', `${name} must be a number, got an empty value`, { flag: name });
+        }
+        const n = Number(raw);
+        if (!Number.isFinite(n)) {
+            throw new VclawError('invalid_flag_value', `${name} must be a number, got: ${raw}`, { flag: name });
+        }
+        if (bounds.exclusiveMin !== undefined && n <= bounds.exclusiveMin) {
+            throw new VclawError('invalid_flag_value', `${name} must be greater than ${bounds.exclusiveMin}, got: ${raw}`, { flag: name });
+        }
+        if (bounds.min !== undefined && n < bounds.min) {
+            throw new VclawError('invalid_flag_value', `${name} must be >= ${bounds.min}, got: ${raw}`, { flag: name });
+        }
+        if (bounds.max !== undefined && n > bounds.max) {
+            throw new VclawError('invalid_flag_value', `${name} must be <= ${bounds.max}, got: ${raw}`, { flag: name });
+        }
+        return n;
+    };
+    // Times/fades are non-negative seconds; opacity is a 0..1 alpha; pulse-hz and
+    // font-size must be strictly positive.
+    const startSec = numFlag('--start', { min: 0 });
+    const endSec = numFlag('--end', { min: 0 });
+    const fadeInSec = numFlag('--fade-in', { min: 0 });
+    const fadeOutSec = numFlag('--fade-out', { min: 0 });
+    const opacity = numFlag('--opacity', { min: 0, max: 1 });
+    const pulseHz = numFlag('--pulse-hz', { exclusiveMin: 0 });
+    const fontSize = numFlag('--font-size', { exclusiveMin: 0 });
+    const color = parseFlagValue(args, '--color');
+    // The color flows unsanitized into the ffmpeg drawtext filter (fontcolor=<c>), so
+    // an empty or filter-special value would be silently dropped or inject filter
+    // segments. Accept only color names / #hex / name@opacity.
+    if (color !== undefined && !/^[A-Za-z]+(@[0-9.]+)?$|^#[0-9A-Fa-f]{6,8}(@[0-9.]+)?$/.test(color)) {
+        throw new VclawError('invalid_flag_value', `video overlay: --color must be a color name or #hex (optionally @opacity), got: ${color}`, { flag: '--color' });
+    }
+    const dryRun = args.includes('--dry-run');
+    let mode;
+    let ffargs;
+    if (graphic !== undefined) {
+        mode = 'graphic';
+        ffargs = buildOverlayArgs(input, graphic, output, {
+            ...(position ? { position } : {}),
+            ...(startSec !== undefined ? { startSec } : {}),
+            ...(endSec !== undefined ? { endSec } : {}),
+            ...(fadeInSec !== undefined ? { fadeInSec } : {}),
+            ...(fadeOutSec !== undefined ? { fadeOutSec } : {}),
+            ...(opacity !== undefined ? { opacity } : {}),
+        });
+    }
+    else if (alert !== undefined) {
+        mode = 'alert';
+        ffargs = buildAlertTextArgs(input, alert, output, {
+            ...(startSec !== undefined ? { startSec } : {}),
+            ...(endSec !== undefined ? { endSec } : {}),
+            ...(pulseHz !== undefined ? { pulseHz } : {}),
+            ...(color ? { color } : {}),
+            ...(fontSize !== undefined ? { fontSize } : {}),
+        });
+    }
+    else {
+        mode = 'lower-third';
+        ffargs = buildLowerThirdArgs(input, lowerThird, output, {
+            ...(startSec !== undefined ? { startSec } : {}),
+            ...(endSec !== undefined ? { endSec } : {}),
+            ...(fadeInSec !== undefined ? { fadeInSec } : {}),
+            ...(fadeOutSec !== undefined ? { fadeOutSec } : {}),
+            ...(color ? { color } : {}),
+            ...(fontSize !== undefined ? { fontSize } : {}),
+        });
+    }
+    // The --alert / --lower-third paths use ffmpeg's drawtext filter, which is
+    // only present in an ffmpeg built with libfreetype. Preflight on a real run
+    // so the operator gets an actionable message instead of a cryptic mid-render
+    // "No such filter: 'drawtext'". (--graphic uses overlay, no drawtext needed.)
+    if (!dryRun && (mode === 'alert' || mode === 'lower-third')) {
+        const hasDrawtext = await ffmpegSupportsFilter('drawtext');
+        if (!hasDrawtext) {
+            throw new VclawError('ffmpeg_failed', `video overlay --${mode} needs an ffmpeg built with libfreetype (the 'drawtext' filter), which this ffmpeg lacks. Install a freetype-enabled ffmpeg (e.g. \`brew tap homebrew-ffmpeg/ffmpeg && brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-freetype --with-fontconfig\`), or use --graphic to composite a pre-rendered text PNG instead.`, { mode, missingFilter: 'drawtext' });
+        }
+    }
+    const result = await runFfmpeg(ffargs, { dryRun });
+    process.stdout.write(`${JSON.stringify({ action: 'overlay', mode, dryRun, input, output, command: result.command }, null, 2)}\n`);
+}
+/**
+ * `vclaw video music-video` — the vocal-synced, beat-exact music-video assembler.
+ *
+ * Reads an operator-authored config (song + clip registry + B-roll pools + either
+ * an explicit vocal map or a transcript to auto-classify), compiles a frame-exact
+ * ffmpeg plan via {@link buildMusicVideoPlan}, and renders it with
+ * {@link runMusicVideo}. PLAN/DRY by default (prints the plan + per-cut summary,
+ * no ffmpeg); `--execute` renders and asserts zero drift. Fully local — no
+ * provider, no spend — so no spend gate is needed.
+ */
+export async function handleVideoMusicVideo(args) {
+    const configPath = parseFlagValue(args, '--config');
+    if (!configPath) {
+        throw new VclawError('missing_required_flag', 'video music-video requires --config <music-video-config.json>', {
+            missing: ['--config'],
+        });
+    }
+    const workDir = parseFlagValue(args, '--work-dir') ?? dirname(resolve(configPath));
+    const execute = args.includes('--execute');
+    const dryRun = args.includes('--dry-run') || !execute;
+    let config;
+    try {
+        config = JSON.parse(await readFile(configPath, 'utf8'));
+    }
+    catch (err) {
+        throw new VclawError('invalid_flag_value', `video music-video: could not read/parse --config ${configPath}: ${err.message}`, {
+            flag: '--config',
+            configPath,
+        });
+    }
+    const outputOverride = parseFlagValue(args, '--output');
+    if (outputOverride)
+        config = { ...config, output: outputOverride };
+    const plan = buildMusicVideoPlan(config, resolve(workDir));
+    const result = await runMusicVideo(plan, {
+        dryRun,
+        ...(parseFlagValue(args, '--ffmpeg-bin') ? { ffmpegBin: parseFlagValue(args, '--ffmpeg-bin') } : {}),
+        ...(parseFlagValue(args, '--ffprobe-bin') ? { ffprobeBin: parseFlagValue(args, '--ffprobe-bin') } : {}),
+    });
+    process.stdout.write(`${JSON.stringify({
+        command: 'video music-video',
+        dryRun: result.dryRun,
+        output: result.output,
+        plannedDurationSec: result.plannedDurationSec,
+        builtDurationSec: result.builtDurationSec,
+        segmentCount: result.segmentCount,
+        performerCuts: result.performerCuts,
+        brollCuts: result.brollCuts,
+        grade: result.grade || null,
+        vocalSections: plan.vocalMap.map((s) => ({ start: s.start, end: s.end, type: s.type, performerClip: s.performerClip ?? null })),
+        ...(result.dryRun ? { steps: plan.steps.map((st) => ({ kind: st.kind, label: st.label })) } : {}),
+    }, null, 2)}\n`);
+}
+/**
+ * `vclaw video title-card` — burn music-video TITLE overlays (a faded lower-third
+ * and/or a centred end card that holds to EOF) onto a finished cut. Rasterized via
+ * Pillow + RAQM, so it works on any ffmpeg build and any script (Devanagari/Arabic).
+ * Plan/dry by default; without --dry-run it renders. Fully local, no spend.
+ */
+export async function handleVideoTitleCard(args) {
+    const input = parseFlagValue(args, '--input');
+    const output = parseFlagValue(args, '--output');
+    const missing = [];
+    if (!input)
+        missing.push('--input');
+    if (!output)
+        missing.push('--output');
+    if (missing.length > 0) {
+        throw new VclawError('missing_required_flag', 'video title-card requires --input <video> and --output <path>', { missing });
+    }
+    const lowerThird = parseFlagValue(args, '--lower-third');
+    const endCard = parseFlagValue(args, '--end-card');
+    if (!lowerThird && !endCard) {
+        throw new VclawError('missing_required_flag', 'video title-card requires at least one of --lower-third "<a||b>" or --end-card "<a||b>"', {
+            flags: ['--lower-third', '--end-card'],
+        });
+    }
+    const splitLines = (v) => v === undefined ? undefined : v.split('||').map((s) => s.trim()).filter(Boolean);
+    const numFlag = (name) => {
+        const raw = parseFlagValue(args, name);
+        if (raw === undefined)
+            return undefined;
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n < 0) {
+            throw new VclawError('invalid_flag_value', `${name} must be a non-negative number, got: ${raw}`, { flag: name });
+        }
+        return n;
+    };
+    const result = await runTitleOverlay({
+        input: input,
+        output: output,
+        ...(splitLines(lowerThird) ? { lowerThird: splitLines(lowerThird) } : {}),
+        ...(splitLines(endCard) ? { endCard: splitLines(endCard) } : {}),
+        ...(numFlag('--lt-start') !== undefined ? { lowerThirdStartSec: numFlag('--lt-start') } : {}),
+        ...(numFlag('--lt-end') !== undefined ? { lowerThirdEndSec: numFlag('--lt-end') } : {}),
+        ...(numFlag('--end-hold') !== undefined ? { endCardSec: numFlag('--end-hold') } : {}),
+        ...(parseFlagValue(args, '--title-font') ? { titleFont: parseFlagValue(args, '--title-font') } : {}),
+        ...(parseFlagValue(args, '--body-font') ? { bodyFont: parseFlagValue(args, '--body-font') } : {}),
+        ...(parseFlagValue(args, '--title-color') ? { titleColor: parseFlagValue(args, '--title-color') } : {}),
+        ...(parseFlagValue(args, '--sub-color') ? { subColor: parseFlagValue(args, '--sub-color') } : {}),
+        ...(parseFlagValue(args, '--accent-color') ? { accentColor: parseFlagValue(args, '--accent-color') } : {}),
+        ...(args.includes('--no-accent') ? { noAccent: true } : {}),
+        ...(args.includes('--dry-run') ? { dryRun: true } : {}),
+        ...(parseFlagValue(args, '--python') ? { python: parseFlagValue(args, '--python') } : {}),
+    });
+    process.stdout.write(`${JSON.stringify({ command: 'video title-card', ...result }, null, 2)}\n`);
+}
+/**
+ * `vclaw video stitch-ad` — assemble ordered scene clips into a short ad with
+ * cross-dissolves and an optional music bed laid UNDER the native voice (+ a
+ * one-shot SFX). The native character-ad finishing recipe: pair it after
+ * `flow-r2v` scenes and before `title-card` / `make-vertical`.
+ */
+export async function handleVideoStitchAd(args) {
+    const clips = parseRepeatableFlag(args, '--clip');
+    const output = parseFlagValue(args, '--out');
+    const missing = [];
+    if (clips.length === 0)
+        missing.push('--clip');
+    if (!output)
+        missing.push('--out');
+    if (missing.length > 0) {
+        throw new VclawError('missing_required_flag', 'video stitch-ad requires at least one --clip <path> and --out <path>', { missing });
+    }
+    const num = (name) => {
+        const raw = parseFlagValue(args, name);
+        if (raw === undefined)
+            return undefined;
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n < 0) {
+            throw new VclawError('invalid_flag_value', `${name} must be a non-negative number, got: ${raw}`, { flag: name });
+        }
+        return n;
+    };
+    const result = await runStitchAd({
+        clips,
+        output: output,
+        ...(num('--dissolve') !== undefined ? { dissolveSec: num('--dissolve') } : {}),
+        ...(num('--width') !== undefined ? { width: num('--width') } : {}),
+        ...(num('--height') !== undefined ? { height: num('--height') } : {}),
+        ...(num('--fps') !== undefined ? { fps: num('--fps') } : {}),
+        ...(parseFlagValue(args, '--bed') ? { bedPath: parseFlagValue(args, '--bed') } : {}),
+        ...(num('--bed-level') !== undefined ? { bedLevel: num('--bed-level') } : {}),
+        ...(parseFlagValue(args, '--sfx') ? { sfxPath: parseFlagValue(args, '--sfx') } : {}),
+        ...(num('--sfx-at') !== undefined ? { sfxAtSec: num('--sfx-at') } : {}),
+        ...(num('--sfx-level') !== undefined ? { sfxLevel: num('--sfx-level') } : {}),
+        ...(args.includes('--dry-run') ? { dryRun: true } : {}),
+    });
+    process.stdout.write(`${JSON.stringify({ command: 'video stitch-ad', ...result }, null, 2)}\n`);
+}
+/**
+ * `vclaw video finish` — upscale/finish a rendered video to a clean HD master.
+ *
+ * Hosted Topaz (Proteus default / Gaia / Starlight) runs via the apiz/xskill
+ * client (upload → submit → await → download); `topaz-local` shells the local
+ * Topaz CLI. The anti-plastic "detail-not-sharp" recipe is on by default. Hosted
+ * backends are PAID → spend-gated (exit-3 `spend_confirmation_required` unless
+ * --confirm-spend or --dry-run); topaz-local is free. `--dry-run` plans only.
+ */
+export async function handleVideoFinish(args) {
+    const input = parseFlagValue(args, '--input');
+    const output = parseFlagValue(args, '--output');
+    const missing = [];
+    if (!input)
+        missing.push('--input');
+    if (!output)
+        missing.push('--output');
+    if (missing.length > 0) {
+        throw new VclawError('missing_required_flag', 'video finish requires --input <video> and --output <path>', { missing });
+    }
+    const backend = (parseFlagValue(args, '--backend') ?? 'topaz-proteus');
+    if (!FINISH_BACKEND_IDS.includes(backend)) {
+        throw new VclawError('invalid_flag_value', `video finish: --backend must be one of ${FINISH_BACKEND_IDS.join(', ')}, got: ${backend}`, { flag: '--backend' });
+    }
+    const numFlagF = (name, min, max) => {
+        const raw = parseFlagValue(args, name);
+        if (raw === undefined)
+            return undefined;
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n < min || n > max) {
+            throw new VclawError('invalid_flag_value', `${name} must be a number in [${min}, ${max}], got: ${raw}`, { flag: name });
+        }
+        return n;
+    };
+    const dryRun = args.includes('--dry-run');
+    const hosted = isHostedBackend(backend);
+    // Hosted Topaz is paid → require --confirm-spend (unless planning).
+    if (hosted && !dryRun && !args.includes('--confirm-spend')) {
+        throw new VclawError('spend_confirmation_required', `video finish: backend "${backend}" runs a paid hosted Topaz job. Re-run with --confirm-spend (or --dry-run to plan).`, { backend });
+    }
+    const result = await runFinish({
+        backend,
+        input: input,
+        output: output,
+        dryRun,
+        ...(args.includes('--sharpen') ? { detailNotSharp: false } : {}),
+        ...(numFlagF('--scale', 1, 4) !== undefined ? { scale: numFlagF('--scale', 1, 4) } : {}),
+        // Topaz's real grain ceiling is 0.1 (the published 0..1 schema lies) —
+        // reject out-of-range values here instead of silently clamping them later.
+        ...(numFlagF('--grain', 0, TOPAZ_GRAIN_MAX) !== undefined ? { grain: numFlagF('--grain', 0, TOPAZ_GRAIN_MAX) } : {}),
+        ...(numFlagF('--noise', 0, 1) !== undefined ? { noise: numFlagF('--noise', 0, 1) } : {}),
+        ...(numFlagF('--recover-detail', 0, 1) !== undefined ? { recoverDetail: numFlagF('--recover-detail', 0, 1) } : {}),
+        ...(parseFlagValue(args, '--topaz-cli') ? { topazCliPath: parseFlagValue(args, '--topaz-cli') } : {}),
+    });
+    process.stdout.write(`${JSON.stringify({ command: 'video finish', ...result }, null, 2)}\n`);
+}
+/**
+ * `vclaw video lipsync` — audio-driven lip-sync: a still/keyframe + a vocal track
+ * → a lip-synced talking-head clip via OmniHuman v1.5 (apiz/xskill). Uploads
+ * image+audio → submits → awaits → downloads → normalizes to CFR fps + even dims
+ * (so the clip seeks frame-accurately in the assembler). PAID → spend-gated
+ * (exit-3 unless --confirm-spend; --dry-run plans). Audio length is checked
+ * against the model cap (1080p≤30s, 720p≤60s) up front.
+ */
+export async function handleVideoLipsync(args) {
+    const image = parseFlagValue(args, '--image');
+    const audio = parseFlagValue(args, '--audio');
+    const output = parseFlagValue(args, '--output');
+    const missing = [];
+    if (!image)
+        missing.push('--image');
+    if (!audio)
+        missing.push('--audio');
+    if (!output)
+        missing.push('--output');
+    if (missing.length > 0) {
+        throw new VclawError('missing_required_flag', 'video lipsync requires --image <path>, --audio <path>, and --output <path>', { missing });
+    }
+    const resolution = (parseFlagValue(args, '--resolution') ?? '1080p');
+    if (resolution !== '720p' && resolution !== '1080p') {
+        throw new VclawError('invalid_flag_value', `video lipsync: --resolution must be 720p or 1080p, got: ${resolution}`, { flag: '--resolution' });
+    }
+    const fpsRaw = parseFlagValue(args, '--fps');
+    let normalizeFps;
+    if (fpsRaw !== undefined) {
+        normalizeFps = Number(fpsRaw);
+        if (!Number.isFinite(normalizeFps) || normalizeFps <= 0) {
+            throw new VclawError('invalid_flag_value', `video lipsync: --fps must be a positive number, got: ${fpsRaw}`, { flag: '--fps' });
+        }
+    }
+    const dryRun = args.includes('--dry-run');
+    if (!dryRun && !args.includes('--confirm-spend')) {
+        throw new VclawError('spend_confirmation_required', 'video lipsync runs a paid hosted OmniHuman job. Re-run with --confirm-spend (or --dry-run to plan).', {});
+    }
+    const result = await runLipsync({
+        image: image,
+        audio: audio,
+        output: output,
+        resolution,
+        dryRun,
+        ...(parseFlagValue(args, '--prompt') ? { prompt: parseFlagValue(args, '--prompt') } : {}),
+        ...(args.includes('--turbo') ? { turbo: true } : {}),
+        ...(args.includes('--no-normalize') ? { skipNormalize: true } : {}),
+        ...(normalizeFps !== undefined ? { normalizeFps } : {}),
+    });
+    process.stdout.write(`${JSON.stringify({ command: 'video lipsync', ...result }, null, 2)}\n`);
+}
+//# sourceMappingURL=media-production.js.map