videoclaw 3.0.0-alpha.1

package/dist/video/motion-overlay/avatar-host-transport.d.ts

@@ -0,0 +1,161 @@
+import type { MotionOverlayHostGenerator, MotionOverlayHostStep } from './avatar-host.js';
+/** Pure: snap a take duration to the nearest omni-flash duration (min 6s for speech). */
+export declare function snapOmniDuration(seconds: number): number;
+/** Map a motion-overlay aspect to the flow.ts `-r` ratio. Pure. */
+export declare function flowRatio(aspect: string): 'portrait' | 'landscape' | 'square';
+/**
+ * Pure: build the omni-flash R2V host prompt. The character image(s) are
+ * `ingredients:` references (comma-separated, space-free per flow.ts parsing); the
+ * line is delivered as benign on-camera address (avoids the "narrator says:"
+ * phrasing that trips the speech-edit filter).
+ *
+ * Consistency: omni-flash R2V treats the reference as a *loose* influence, so each
+ * take re-invents face/wardrobe/backdrop unless pinned. Two levers fight that drift:
+ * `appearance` (a stable visual+setting descriptor — e.g. the character's
+ * go-bananas base prompt — repeated on EVERY take so wardrobe/studio stop jumping)
+ * and `extraIngredients` (e.g. the previous take's last frame, chained in to carry
+ * identity forward). The prompt no longer hardcodes a Bunty-flavoured "friendly
+ * cartoon presenter in a sleek modern studio" — that generic text was itself a
+ * source of backdrop/wardrobe drift for any non-Bunty character.
+ */
+export declare function buildOmniHostPrompt(args: {
+    characterImage: string;
+    characterName: string;
+    text: string;
+    anatomy: MotionOverlayHostStep['anatomy'];
+    /** Stable visual + setting descriptor, pinned on every take. */
+    appearance?: string;
+    /** Additional ingredient refs (e.g. the prior take's chained last frame). */
+    extraIngredients?: string[];
+}): string;
+/** Pure: the `bun run flow.ts` argv for one omni-flash R2V+voice host generation. */
+export declare function buildOmniHostFlowArgs(args: {
+    prompt: string;
+    voice: string;
+    ratio: 'portrait' | 'landscape' | 'square';
+    durationSeconds: number;
+    outputDir: string;
+    tag: string;
+}): string[];
+/** Injectable flow.ts spawn. Resolves once the command exits. */
+export type FlowSpawn = (args: string[], opts: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export interface OmniHostConfig {
+    /** Absolute path to the locked character's reference image (R2V ingredient). */
+    characterImage: string;
+    /** Human label woven into the prompt (e.g. "Bunty"). */
+    characterName: string;
+    /** Flow voice preset (e.g. "Puck"). */
+    voice: string;
+    /** Flow `-r` ratio derived from the plan aspect. */
+    ratio: 'portrait' | 'landscape' | 'square';
+    /** vclaw-cli root holding flow.ts. */
+    cliRoot: string;
+    /** Env for the spawn (USEAPI creds, etc.). */
+    env: NodeJS.ProcessEnv;
+    /** The flow.ts spawn (injected; default shells `bun run flow.ts`). */
+    spawn: FlowSpawn;
+    /**
+     * Max generation attempts per take before giving up. The Flow safety filter
+     * rejects a benign generation probabilistically, so a plain retry of the SAME
+     * line usually clears — without a retry a single rejected take fail-fasts the
+     * whole multi-take reel. Default 3 (1 try + 2 retries). Min 1.
+     */
+    maxAttempts?: number;
+    /** Notified before each retry (attempt is 1-based, the one about to run). */
+    onRetry?: (info: {
+        takeIndex: number;
+        attempt: number;
+        maxAttempts: number;
+        detail: string;
+    }) => void;
+    /**
+     * Stable visual + setting descriptor pinned on every take's prompt (e.g. the
+     * character's go-bananas base prompt). Fights wardrobe/backdrop drift across the
+     * independently-generated takes. Omitted → a neutral default.
+     */
+    appearance?: string;
+    /**
+     * Chain identity forward: seed each take's R2V with the PREVIOUS take's last
+     * frame as an extra ingredient, so the face/wardrobe carry across takes. Requires
+     * `extractLastFrame`; a no-op without it. Default false.
+     */
+    chain?: boolean;
+    /**
+     * Injected last-frame extractor (CLI shells ffmpeg; tests inject a fake). Writes a
+     * still of `videoPath`'s final frame to `outPath`. Only used when `chain` is on.
+     */
+    extractLastFrame?: (videoPath: string, outPath: string) => Promise<void>;
+}
+/**
+ * Build the real omni-flash **R2V + native voice** host generator (the talking
+ * avatar: Omni produces audio + lip-synced video together; loose identity, mitigated
+ * by `appearance` pinning + cross-take frame chaining).
+ */
+export declare function createOmniHostGenerator(cfg: OmniHostConfig): MotionOverlayHostGenerator;
+/** Pure: snap a take duration to the nearest Veo I2V duration (min 6s). */
+export declare function snapVeoDuration(seconds: number): number;
+/**
+ * Pure: the Veo I2V host prompt. The character still is the literal first frame
+ * (`image:<still>`), so identity is pixel-locked at frame 0 of EVERY take — the
+ * tight-identity counterpart to R2V's loose influence. The clip is silent (Veo I2V
+ * has no native voice); the line drives only subtle mouth/expression motion, and
+ * the anatomy varies the delivery so stitched takes are not identical loops.
+ */
+export declare function buildVeoI2vHostPrompt(args: {
+    startImage: string;
+    characterName: string;
+    anatomy: MotionOverlayHostStep['anatomy'];
+    appearance?: string;
+}): string;
+/** Pure: the `bun run flow.ts` argv for one Veo I2V host generation (silent, no `--voice`). */
+export declare function buildVeoI2vHostFlowArgs(args: {
+    prompt: string;
+    ratio: 'portrait' | 'landscape' | 'square';
+    veoModel: string;
+    durationSeconds: number;
+    outputDir: string;
+    tag: string;
+}): string[];
+export interface VeoI2vHostConfig {
+    /** The fixed character still used as the literal first frame of EVERY take. */
+    startImage: string;
+    /** Human label woven into the prompt. */
+    characterName: string;
+    /** Stable appearance + setting descriptor (pinned on every take). */
+    appearance?: string;
+    /** flow.ts `-r` ratio (Veo I2V is landscape-only server-side, but passed through). */
+    ratio: 'portrait' | 'landscape' | 'square';
+    /** flow.ts `-m` model (e.g. `quality`); image mode resolves it to the I2V variant. */
+    veoModel: string;
+    /** vclaw-cli root holding flow.ts. */
+    cliRoot: string;
+    /** Env for the spawn (USEAPI creds, etc.). */
+    env: NodeJS.ProcessEnv;
+    /** The flow.ts spawn (injected; default shells `bun run flow.ts`). */
+    spawn: FlowSpawn;
+    /** Max generation attempts per take. Default 3, min 1. */
+    maxAttempts?: number;
+    /** Notified before each retry. */
+    onRetry?: (info: {
+        takeIndex: number;
+        attempt: number;
+        maxAttempts: number;
+        detail: string;
+    }) => void;
+}
+/**
+ * Build the **Veo I2V** host generator (the tight-identity, *silent* avatar). Every
+ * take starts from the SAME character still, so frame 0 of each take is pixel
+ * identical — far tighter identity than R2V — at the cost of no native voice (the
+ * reel is captioned, or a voiceover/soundtrack is added separately). No chaining is
+ * needed: the fixed first frame already locks identity.
+ */
+export declare function createVeoI2vHostGenerator(cfg: VeoI2vHostConfig): MotionOverlayHostGenerator;
+//# sourceMappingURL=avatar-host-transport.d.ts.map

package/dist/video/motion-overlay/avatar-host-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar-host-transport.d.ts","sourceRoot":"","sources":["../../../src/video/motion-overlay/avatar-host-transport.ts"],"names":[],"mappings":"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"}

package/dist/video/motion-overlay/avatar-host-transport.js

@@ -0,0 +1,325 @@
+/**
+ * Real avatar-host generator: Google Flow **omni-flash R2V + native voice**.
+ *
+ * Per take it drives omni-flash with the locked character's reference image as an
+ * R2V ingredient and a `--voice` preset, so the avatar SPEAKS the take's line —
+ * Omni generates the audio AND the lip-synced video together (no separate TTS, no
+ * muxing, no lip-sync model). This is the audio-native path the gemini-omni skill
+ * was built around, and (unlike the V2V "add-overlay" edit) it is NOT
+ * moderation-blocked.
+ *
+ * It shells the proven `flow.ts` sidecar (the same one `native-veo` uses) via an
+ * injectable `FlowSpawn`, so the orchestrator and the pure prompt/arg builders are
+ * unit-tested offline with no `bun`, no network, and no spend.
+ *
+ * Validated live 2026-06-05: go-bananas Bunty image → this transport → an 8s clip
+ * of Bunty speaking the line with native lip-sync, no moderation.
+ */
+import { rename, readdir, mkdir, access } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+/** omni-flash accepts these output durations (seconds). */
+const OMNI_DURATIONS = [4, 6, 8, 10];
+/** Pure: snap a take duration to the nearest omni-flash duration (min 6s for speech). */
+export function snapOmniDuration(seconds) {
+    const target = Math.max(6, seconds);
+    let best = OMNI_DURATIONS[0];
+    let bestDelta = Infinity;
+    for (const d of OMNI_DURATIONS) {
+        const delta = Math.abs(d - target);
+        if (delta < bestDelta || (delta === bestDelta && d > best)) {
+            best = d;
+            bestDelta = delta;
+        }
+    }
+    return best;
+}
+/** Map a motion-overlay aspect to the flow.ts `-r` ratio. Pure. */
+export function flowRatio(aspect) {
+    if (aspect === '9:16')
+        return 'portrait';
+    if (aspect === '1:1')
+        return 'square';
+    return 'landscape';
+}
+/** Per-anatomy delivery energy woven into the host prompt. Pure. */
+function energyForAnatomy(anatomy) {
+    switch (anatomy) {
+        case 'hook':
+            return 'bright, high-energy, grabbing attention';
+        case 'cta':
+            return 'warm and encouraging, inviting the viewer in';
+        case 'breath':
+            return 'calm, measured, letting the moment land';
+        default:
+            return 'confident and engaging';
+    }
+}
+/**
+ * Pure: build the omni-flash R2V host prompt. The character image(s) are
+ * `ingredients:` references (comma-separated, space-free per flow.ts parsing); the
+ * line is delivered as benign on-camera address (avoids the "narrator says:"
+ * phrasing that trips the speech-edit filter).
+ *
+ * Consistency: omni-flash R2V treats the reference as a *loose* influence, so each
+ * take re-invents face/wardrobe/backdrop unless pinned. Two levers fight that drift:
+ * `appearance` (a stable visual+setting descriptor — e.g. the character's
+ * go-bananas base prompt — repeated on EVERY take so wardrobe/studio stop jumping)
+ * and `extraIngredients` (e.g. the previous take's last frame, chained in to carry
+ * identity forward). The prompt no longer hardcodes a Bunty-flavoured "friendly
+ * cartoon presenter in a sleek modern studio" — that generic text was itself a
+ * source of backdrop/wardrobe drift for any non-Bunty character.
+ */
+export function buildOmniHostPrompt(args) {
+    const energy = energyForAnatomy(args.anatomy);
+    const line = args.text.replace(/"/g, "'").trim();
+    const refs = [args.characterImage, ...(args.extraIngredients ?? [])].filter(Boolean).join(',');
+    const look = args.appearance?.trim() || 'the same television presenter on a fixed studio set';
+    return (`ingredients:${refs} ${args.characterName} — ${look} — ` +
+        `stays visually identical to the reference image: same face, same hair, same wardrobe, ` +
+        `same studio setting and lighting from start to finish. ` +
+        `Looks directly at the camera and speaks to the audience, ${energy}, clearly saying: "${line}". ` +
+        `Natural mouth movement precisely synced to the words, locked head-and-shoulders camera.`);
+}
+/** Pure: the `bun run flow.ts` argv for one omni-flash R2V+voice host generation. */
+export function buildOmniHostFlowArgs(args) {
+    return [
+        'run',
+        'flow.ts',
+        '-p',
+        args.prompt,
+        '-m',
+        'omni-flash',
+        '-r',
+        args.ratio,
+        '--voice',
+        args.voice,
+        '--duration',
+        String(snapOmniDuration(args.durationSeconds)),
+        '--backend',
+        'useapi',
+        '--yes',
+        '-t',
+        args.tag,
+        '--output',
+        args.outputDir,
+    ];
+}
+/** Does a path already exist? (a complete host clip from a prior run → resume). */
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** List the `.mp4` files in a dir (absolute paths). */
+async function listMp4s(dir) {
+    try {
+        const names = await readdir(dir);
+        return new Set(names.filter((n) => n.endsWith('.mp4')).map((n) => join(dir, n)));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** A retryable single-attempt failure (non-zero exit or no fresh clip). */
+class HostAttemptError extends Error {
+}
+/**
+ * Shared host-clip scaffold for ALL flow.ts host engines (omni-flash R2V, Veo I2V).
+ * flow.ts writes a timestamp-named mp4 into a scratch dir; we diff the dir
+ * before/after to find the fresh clip and rename it to `step.outputPath`.
+ *
+ * - **Resume.** An existing `step.outputPath` (atomic rename → whole file) is reused;
+ *   `afterClip` still runs so a resumed run keeps any per-engine continuity.
+ * - **Bounded retry.** Flow rejects benign generations probabilistically; each take
+ *   is retried up to `maxAttempts` before throwing the actionable error.
+ *
+ * `buildArgs(scratchDir)` is the only engine-specific part. `afterClip` runs after a
+ * successful generation OR a resume (used by omni for chained-frame capture).
+ */
+async function runFlowHostClip(opts) {
+    const { ctx, step, maxAttempts } = opts;
+    if (await pathExists(step.outputPath)) {
+        await opts.afterClip?.();
+        return;
+    }
+    let lastDetail = '';
+    for (let n = 1; n <= maxAttempts; n++) {
+        try {
+            const scratchDir = join(ctx.cliRoot, 'output-videos');
+            const before = await listMp4s(scratchDir);
+            const result = await ctx.spawn(opts.buildArgs(scratchDir), { cwd: ctx.cliRoot, env: ctx.env });
+            if (result.code !== 0) {
+                throw new HostAttemptError(result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`);
+            }
+            const after = await listMp4s(scratchDir);
+            const fresh = [...after].filter((p) => !before.has(p));
+            if (fresh.length === 0) {
+                throw new HostAttemptError(result.stderr.trim() || result.stdout.trim() || 'no clip produced');
+            }
+            await mkdir(dirname(step.outputPath), { recursive: true });
+            await rename(fresh[0], step.outputPath);
+            await opts.afterClip?.();
+            return;
+        }
+        catch (err) {
+            if (!(err instanceof HostAttemptError))
+                throw err;
+            lastDetail = err.message;
+            if (n < maxAttempts) {
+                opts.onRetry?.({ takeIndex: step.index, attempt: n + 1, maxAttempts, detail: lastDetail });
+            }
+        }
+    }
+    throw new Error(`avatar-host ${opts.engineLabel} produced no clip for take ${step.index} after ${maxAttempts} attempt(s)` +
+        `${lastDetail ? ` (${lastDetail.slice(0, 200)})` : ''}. Likely a Flow safety-filter rejection or a slow/timed-out ` +
+        `provider queue — re-run to resume from this take (completed takes are reused), raise --host-retries, or adjust the line.`);
+}
+/**
+ * Build the real omni-flash **R2V + native voice** host generator (the talking
+ * avatar: Omni produces audio + lip-synced video together; loose identity, mitigated
+ * by `appearance` pinning + cross-take frame chaining).
+ */
+export function createOmniHostGenerator(cfg) {
+    const maxAttempts = Math.max(1, cfg.maxAttempts ?? 3);
+    const chaining = cfg.chain === true && typeof cfg.extractLastFrame === 'function';
+    // The previous take's chained last-frame (an extra ingredient for the next take).
+    let prevFrame;
+    /** Where this take's chained last frame is parked for the NEXT take to ingest. */
+    function chainFramePath(step) {
+        return join(dirname(step.outputPath), `.chain-${String(step.index).padStart(2, '0')}.png`);
+    }
+    /** Extract `step.outputPath`'s last frame to its chain path; becomes next take's seed. */
+    async function captureChainFrame(step) {
+        if (!chaining)
+            return;
+        try {
+            const fp = chainFramePath(step);
+            await cfg.extractLastFrame(step.outputPath, fp);
+            prevFrame = fp;
+        }
+        catch {
+            // Chaining is best-effort — a failed frame extract just drops the seed for the
+            // next take (it still generates from the character reference alone).
+            prevFrame = undefined;
+        }
+    }
+    return {
+        async generateHostClip(step) {
+            const extraIngredients = chaining && prevFrame ? [prevFrame] : [];
+            await runFlowHostClip({
+                ctx: cfg,
+                step,
+                maxAttempts,
+                engineLabel: 'omni-flash',
+                onRetry: cfg.onRetry,
+                buildArgs: (scratchDir) => buildOmniHostFlowArgs({
+                    prompt: buildOmniHostPrompt({
+                        characterImage: cfg.characterImage,
+                        characterName: cfg.characterName,
+                        text: step.text,
+                        anatomy: step.anatomy,
+                        appearance: cfg.appearance,
+                        extraIngredients,
+                    }),
+                    voice: cfg.voice,
+                    ratio: cfg.ratio,
+                    durationSeconds: step.durationSeconds,
+                    outputDir: scratchDir,
+                    tag: `host-${String(step.index).padStart(2, '0')}`,
+                }),
+                afterClip: () => captureChainFrame(step),
+            });
+        },
+    };
+}
+/** Veo 3.1 I2V accepts these output durations (seconds). */
+const VEO_I2V_DURATIONS = [4, 6, 8];
+/** Pure: snap a take duration to the nearest Veo I2V duration (min 6s). */
+export function snapVeoDuration(seconds) {
+    const target = Math.max(6, seconds);
+    let best = VEO_I2V_DURATIONS[0];
+    let bestDelta = Infinity;
+    for (const d of VEO_I2V_DURATIONS) {
+        const delta = Math.abs(d - target);
+        if (delta < bestDelta || (delta === bestDelta && d > best)) {
+            best = d;
+            bestDelta = delta;
+        }
+    }
+    return best;
+}
+/**
+ * Pure: the Veo I2V host prompt. The character still is the literal first frame
+ * (`image:<still>`), so identity is pixel-locked at frame 0 of EVERY take — the
+ * tight-identity counterpart to R2V's loose influence. The clip is silent (Veo I2V
+ * has no native voice); the line drives only subtle mouth/expression motion, and
+ * the anatomy varies the delivery so stitched takes are not identical loops.
+ */
+export function buildVeoI2vHostPrompt(args) {
+    const energy = energyForAnatomy(args.anatomy);
+    const look = args.appearance?.trim() || 'the same television presenter on a fixed studio set';
+    return (`image:${args.startImage} ${args.characterName} — ${look} — ` +
+        `appears to address the audience on camera, ${energy}, with subtle natural mouth and head movement; ` +
+        `identity, wardrobe, lighting and framing stay exactly as the first frame, locked head-and-shoulders camera.`);
+}
+/** Pure: the `bun run flow.ts` argv for one Veo I2V host generation (silent, no `--voice`). */
+export function buildVeoI2vHostFlowArgs(args) {
+    return [
+        'run',
+        'flow.ts',
+        '-p',
+        args.prompt,
+        '-m',
+        args.veoModel,
+        '-r',
+        args.ratio,
+        '--duration',
+        String(snapVeoDuration(args.durationSeconds)),
+        '--backend',
+        'useapi',
+        '--yes',
+        '-t',
+        args.tag,
+        '--output',
+        args.outputDir,
+    ];
+}
+/**
+ * Build the **Veo I2V** host generator (the tight-identity, *silent* avatar). Every
+ * take starts from the SAME character still, so frame 0 of each take is pixel
+ * identical — far tighter identity than R2V — at the cost of no native voice (the
+ * reel is captioned, or a voiceover/soundtrack is added separately). No chaining is
+ * needed: the fixed first frame already locks identity.
+ */
+export function createVeoI2vHostGenerator(cfg) {
+    const maxAttempts = Math.max(1, cfg.maxAttempts ?? 3);
+    return {
+        async generateHostClip(step) {
+            await runFlowHostClip({
+                ctx: cfg,
+                step,
+                maxAttempts,
+                engineLabel: 'veo-i2v',
+                onRetry: cfg.onRetry,
+                buildArgs: (scratchDir) => buildVeoI2vHostFlowArgs({
+                    prompt: buildVeoI2vHostPrompt({
+                        startImage: cfg.startImage,
+                        characterName: cfg.characterName,
+                        anatomy: step.anatomy,
+                        appearance: cfg.appearance,
+                    }),
+                    ratio: cfg.ratio,
+                    veoModel: cfg.veoModel,
+                    durationSeconds: step.durationSeconds,
+                    outputDir: scratchDir,
+                    tag: `host-${String(step.index).padStart(2, '0')}`,
+                }),
+            });
+        },
+    };
+}
+//# sourceMappingURL=avatar-host-transport.js.map

package/dist/video/motion-overlay/avatar-host-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar-host-transport.js","sourceRoot":"","sources":["../../../src/video/motion-overlay/avatar-host-transport.ts"],"names":[],"mappings":"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"}

package/dist/video/motion-overlay/avatar-host.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Avatar-host layout (Layout D) — per-take host base clip generation.
+ *
+ * The `avatar-host` layout replaces the original speaker with an identity-locked
+ * character host that SPEAKS each take's line. For each take we generate a fresh
+ * host clip with **omni-flash R2V + native voice**:
+ *
+ *   character reference image (R2V `ingredients:`) + the take's line + a voice
+ *      → omni-flash generates the audio AND the lip-synced video together
+ *
+ * Because Omni produces the speech and the mouth movement jointly, the avatar is
+ * genuinely lip-synced (no separate TTS / no muxing / no lip-sync model). The
+ * host clips are then stitched into the avatar reel and captioned via the local
+ * renderer. Unlike the V2V "add-overlay" edit, R2V generation is NOT
+ * moderation-blocked.
+ *
+ * Each step carries the take's spoken `text`; the voice + character reference are
+ * supplied by the generator (see `avatar-host-transport.ts`).
+ *
+ * Credit safety is structural: every side effect (the go-bananas character
+ * generation + the Veo I2V render) is delegated to an injectable
+ * {@link MotionOverlayHostGenerator}. The CLI supplies a generator that shells the
+ * real go-bananas + Veo I2V path; tests inject a fake, so the orchestrator runs
+ * offline with NO real generation and NO spend.
+ *
+ * Dry vs execute mirrors {@link runMotionOverlay}: default (`confirmSpend` falsey)
+ * enumerates the host clips that WOULD be generated without invoking the
+ * generator; only `confirmSpend: true` actually drives it.
+ */
+import type { MotionOverlayPlan, MotionTake } from './types.js';
+export declare class MotionOverlayAvatarError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** The subdir under the work folder where generated host base clips land. */
+export declare const HOST_DIRNAME = "host";
+/**
+ * A parsed `--gb-character` value: the locked go-bananas character that hosts the
+ * reel. The `id` is the go-bananas character id; `name` is the human label used in
+ * the generation prompt + manifest provenance.
+ */
+export interface GbCharacter {
+    name: string;
+    id: number;
+}
+/**
+ * Parse a `--gb-character` flag value of the form `Name:ID` (e.g. `Clawbot:291`).
+ * The name may contain spaces; only the FINAL `:` separates name from id so names
+ * like `Dr. Vox:97` parse correctly. Pure.
+ *
+ * @throws {@link MotionOverlayAvatarError} (`gb_character_malformed`) on a missing
+ * separator, an empty name, or a non-numeric / non-positive id.
+ */
+export declare function parseGbCharacter(raw: string): GbCharacter;
+/** Inputs for a single take's host clip generation. */
+export interface MotionOverlayHostStep {
+    index: number;
+    /** The locked host character (parsed from --gb-character). */
+    character: GbCharacter;
+    /** The line the host SPEAKS for this take (omni-flash generates the voice). */
+    text: string;
+    /** The take this host clip is for (for prompt/anatomy context). */
+    anatomy: MotionTake['anatomy'];
+    /** Target clip duration in seconds (matches the take). */
+    durationSeconds: number;
+    /** Absolute path the generated host clip should be written to. */
+    outputPath: string;
+}
+/**
+ * Injectable host generator — the single seam through which the go-bananas
+ * character generation + Veo I2V render flow. The CLI supplies a generator that
+ * shells the real path (go-bananas generate_with_character → Veo I2V startImage →
+ * download host clip to `step.outputPath`). Tests inject a fake so the
+ * orchestrator runs offline with no real generation.
+ */
+export interface MotionOverlayHostGenerator {
+    /**
+     * Generate one take's host base clip. Resolves once the host clip exists at
+     * `step.outputPath`.
+     */
+    generateHostClip(step: MotionOverlayHostStep): Promise<void>;
+}
+export interface RunAvatarHostOptions {
+    /** The injectable host generator (CLI shells real path; tests inject a fake). */
+    generator: MotionOverlayHostGenerator;
+    /** Per-take spoken line (take index → text) the host should say. Missing → ''. */
+    textByIndex?: Record<number, string>;
+    /**
+     * Permit the credit-spending go-bananas + Veo I2V generation to RUN. Default
+     * false → dry plan (the generator is never invoked); the result enumerates the
+     * host clips that WOULD be generated.
+     */
+    confirmSpend?: boolean;
+}
+/** What happened (or would happen) to one take's host base clip. */
+export interface MotionOverlayHostResult {
+    index: number;
+    anatomy: MotionTake['anatomy'];
+    /** Absolute path to the generated host base clip (the V2V base for this take). */
+    hostClip: string;
+    /** generated = the generator was invoked; planned = dry (not invoked). */
+    status: 'generated' | 'planned';
+}
+export interface RunAvatarHostReport {
+    schemaVersion: 1;
+    /** True only when the generator actually ran (confirmSpend). */
+    generated: boolean;
+    character: GbCharacter;
+    hosts: MotionOverlayHostResult[];
+    /**
+     * Per-take map: take index → absolute host clip path. This is what the V2V
+     * execute path consumes as the base footage override.
+     */
+    hostBaseByIndex: Record<number, string>;
+}
+/** Absolute path the host base clip for a take is written to. */
+export declare function hostClipPath(workdir: string, take: MotionTake): string;
+/**
+ * Generate (or dry-plan) the per-take host base clips for the avatar-host layout.
+ *
+ * Takes are processed strictly IN ORDER. Pure control flow — all generation I/O is
+ * delegated to `opts.generator`. Never mutates the input plan. The returned
+ * `hostBaseByIndex` map feeds {@link runMotionOverlay} so each take's V2V base is
+ * the generated host clip instead of the source take.
+ *
+ * @throws {@link MotionOverlayAvatarError} (`motion_overlay_avatar_layout`) if the
+ * plan's layout is not `avatar-host`, or (`motion_overlay_no_takes`) if there are
+ * no takes.
+ */
+export declare function runAvatarHostGeneration(plan: MotionOverlayPlan, character: GbCharacter, opts: RunAvatarHostOptions): Promise<RunAvatarHostReport>;
+//# sourceMappingURL=avatar-host.d.ts.map

package/dist/video/motion-overlay/avatar-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar-host.d.ts","sourceRoot":"","sources":["../../../src/video/motion-overlay/avatar-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AAE3E,qBAAa,wBAAyB,SAAQ,KAAK;aAE/B,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED,6EAA6E;AAC7E,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAyBzD;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,SAAS,EAAE,WAAW,CAAC;IACvB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC/B,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,SAAS,EAAE,0BAA0B,CAAC;IACtC,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC/B,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,CAAC,CAAC;IACjB,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,WAAW,CAAC;IACvB,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACjC;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAYD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,iBAAiB,EACvB,SAAS,EAAE,WAAW,EACtB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAgD9B"}