videoclaw 3.0.0-alpha.1

package/dist/video/vocal-sync-plan.js

@@ -0,0 +1,166 @@
+/**
+ * vocal-sync-plan.ts — the planner that makes a music-video edit feel "in sync":
+ * it pins each PERFORMER to the moment their own vocal is heard, and keeps the
+ * baked lip-sync locked to the muxed song.
+ *
+ * Given a VOCAL MAP (the song segmented by timestamp into rap / hook /
+ * instrumental / outro, each vocal section carrying its lip-synced performer
+ * clip) plus the beat grid and B-roll pools, it emits a frame-aligned segment
+ * list (`clip | inSec | durationSec`) for {@link buildSegmentCutArgs}. PURE and
+ * deterministic given an injected `rng` and `clipDuration` — no I/O, no ffmpeg.
+ *
+ * The three lessons it encodes (each learned by getting it wrong first):
+ *  1. PERFORMER-ON-VOCAL: a music video needs the rapper on the rap and the
+ *     singer on the hook — assigning performers to GUESSED time blocks fights the
+ *     audio. Sections come from the transcribed vocal map, not a shot script.
+ *  2. TIME-ALIGNED SCRUB: a performer cut shows its clip at in-point
+ *     `(songTime - sectionStart)`, so the baked lips stay locked to the song even
+ *     across B-roll cutaways (cut away and back → correct lip position). The
+ *     performer holds ~2 of every 3 cuts and OPENS each vocal section.
+ *  3. FRAME-EXACT CONTINUOUS TIMELINE: walk one timeline from t=0 (no per-section
+ *     reset — that drops the intro and offsets every cue) and snap every cut to
+ *     the frame grid so the concatenated video-time == song-time. Paired with
+ *     `-frames:v` cutting, total drift is < 1 frame.
+ *  Plus DE-PATTERNING: B-roll draws from a shuffle-bag (never round-robin) with a
+ *  stepped in-point on reuse, so recurring footage doesn't read as a loop.
+ */
+const DEFAULT_CUTS = {
+    rap: 1.3, hook: 2.4, instrumental: 2.0, outro: 3.1,
+};
+const BROLL_ORDER = {
+    rap: ['action', 'trio'],
+    hook: ['atmo', 'trio'],
+    instrumental: ['atmo', 'trio', 'action'],
+    outro: ['vanish', 'atmo'],
+};
+function shuffle(arr, rng) {
+    const a = [...arr];
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a;
+}
+export function planVocalSync(input) {
+    const fps = input.fps ?? 24;
+    const rng = input.rng ?? Math.random;
+    const cuts = { ...DEFAULT_CUTS, ...input.cutLengths };
+    const beats = input.beats;
+    const nearestBeat = (t) => beats.length === 0 ? t : beats.reduce((p, b) => (Math.abs(b - t) < Math.abs(p - t) ? b : p), beats[0]);
+    // Boundaries and section lookup are FRAME-based, using the same rounding the
+    // walk uses. The previous float version (`find(b => b > t + 0.05)`) skipped a
+    // boundary whenever frame rounding put the walk within 0.05s before it, so
+    // the previous section's type/performer bled a full cut into the next
+    // section for roughly half of all boundaries.
+    const songEndF = Math.round(input.songEnd * fps);
+    const boundaryFrames = input.vocalMap.map((s) => Math.round(s.start * fps)).concat(songEndF);
+    const sectionAtFrame = (frame) => {
+        for (const s of input.vocalMap) {
+            if (frame >= Math.round(s.start * fps) && frame < Math.round(s.end * fps))
+                return s;
+        }
+        return { start: 0, end: input.songEnd, type: 'instrumental' };
+    };
+    const nextBoundaryFrame = (frame) => boundaryFrames.find((bf) => bf > frame) ?? songEndF;
+    const segs = [];
+    const useCount = {};
+    let lastClip = null;
+    const bags = {};
+    const draw = (poolKey) => {
+        const pool = input.pools[poolKey];
+        if (!pool || pool.length === 0)
+            return null;
+        let bag = bags[poolKey];
+        if (!bag || bag.length === 0)
+            bag = bags[poolKey] = shuffle(pool, rng);
+        let clip = bag.shift();
+        if (clip === lastClip && bag.length > 0) {
+            bag.push(clip);
+            clip = bag.shift();
+        }
+        return clip;
+    };
+    const emitBroll = (clip, durationSec) => {
+        const od = input.clipDuration(clip);
+        // Fail at PLAN time when the source can't supply the cut (plus the 0.05s
+        // min in-point and 0.15s tail margin the in-point stepper reserves).
+        // Previously the Math.max(0.05) floor masked this and it surfaced
+        // post-render as a misleading drift failure.
+        if (od < durationSec + 0.2) {
+            throw new Error(`planVocalSync: B-roll clip "${clip}" is ${od.toFixed(2)}s but a ${durationSec.toFixed(2)}s cut (+0.2s margin) is planned — use longer pool footage or shorter cutLengths.`);
+        }
+        lastClip = clip;
+        const n = (useCount[clip] = (useCount[clip] ?? 0) + 1);
+        const room = Math.max(0.05, od - durationSec - 0.15);
+        const inSec = +(((n - 1) * (durationSec + 0.5) + 0.2) % room).toFixed(4);
+        segs.push({ clip, inSec, durationSec, performer: false });
+    };
+    const emitPerformer = (clip, wantIn, durationSec) => {
+        const od = input.clipDuration(clip);
+        // An undersized lip-synced take cannot cover its section's cuts; the old
+        // clamp silently scrubbed to 0 and desynced the lips post-render.
+        if (od < durationSec) {
+            throw new Error(`planVocalSync: performer clip "${clip}" is ${od.toFixed(2)}s but a ${durationSec.toFixed(2)}s cut is planned — the lip-synced take must cover its section's cuts.`);
+        }
+        lastClip = clip;
+        const inSec = Math.max(0, Math.min(wantIn, od - durationSec));
+        segs.push({ clip, inSec: +inSec.toFixed(4), durationSec, performer: true });
+    };
+    // Walk an INTEGER-FRAME timeline so cumulative video-time == song-time exactly
+    // (float `t` accumulates rounding and would drift cuts off section boundaries).
+    const minFrames = Math.round(0.3 * fps); // skip sub-0.3s slivers
+    let tf = 0;
+    let lastType = null;
+    let cutIdx = 0;
+    let brollRot = 0;
+    while (tf < songEndF - Math.round(0.2 * fps)) {
+        const t = tf / fps;
+        const sec = sectionAtFrame(tf);
+        const spc = cuts[sec.type];
+        if (sec.type !== lastType) {
+            cutIdx = 0;
+            brollRot = 0;
+            lastType = sec.type;
+        }
+        let cutSec = nearestBeat(t + spc);
+        if (cutSec <= t + 0.25)
+            cutSec = t + spc;
+        let cf = Math.round(cutSec * fps);
+        const nbf = nextBoundaryFrame(tf);
+        if (cf > nbf)
+            cf = nbf;
+        if (cf > songEndF)
+            cf = songEndF;
+        if (cf <= tf) {
+            tf += 1; // guarantee forward progress at a degenerate boundary
+            continue;
+        }
+        const durFrames = cf - tf;
+        if (durFrames < minFrames) {
+            tf = cf;
+            continue;
+        }
+        const durationSec = durFrames / fps;
+        if (sec.performerClip && cutIdx % 3 !== 2) {
+            emitPerformer(sec.performerClip, (tf - Math.round(sec.start * fps)) / fps, durationSec);
+        }
+        else {
+            const order = BROLL_ORDER[sec.type];
+            const key = order[brollRot++ % order.length];
+            const clip = draw(key) ?? draw('trio') ?? draw('atmo');
+            if (!clip) {
+                tf = cf;
+                continue;
+            }
+            emitBroll(clip, durationSec);
+        }
+        tf = cf;
+        cutIdx += 1;
+    }
+    return segs;
+}
+/** Total planned duration (seconds) — feed to {@link assertNoDrift} against the built file. */
+export function plannedDuration(segs) {
+    return +segs.reduce((a, s) => a + s.durationSec, 0).toFixed(4);
+}
+//# sourceMappingURL=vocal-sync-plan.js.map

package/dist/video/vocal-sync-plan.js.map

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

package/dist/video/voice-clone.d.ts

@@ -0,0 +1,152 @@
+import type { AssetTagEntry } from './prompt-rules.js';
+/** One registered voice clone in `voice-clones.json`. */
+export interface VoiceCloneEntry {
+    /** Voice-asset name (what an @Name tag / character binding resolves to). */
+    name: string;
+    /** Optional character this voice belongs to (so the character always speaks it). */
+    character?: string;
+    /** The source audio sample this clone was built from. */
+    sourceAudio: string;
+    /** The built blank-video-with-audio clip (the reference the model consumes). */
+    clipPath: string;
+    /**
+     * Durable public URL for `clipPath`, hosted on Go Bananas. Required for the
+     * seedance-direct r2v voice-lock (the remote API needs a hosted URL, not a local
+     * path). Populated by `voice-clone --execute` when GB media hosting is available;
+     * absent when hosting is unavailable (the clip stays a local path).
+     */
+    hostedUrl?: string;
+    /** When sliced for drift control: the per-line clip paths (in order). */
+    slices?: string[];
+    /** Optional human description of the voice character/tone. */
+    description?: string;
+    /** Duration of the source audio in milliseconds (0 when not probed / dry-run). */
+    durationMs?: number;
+}
+export interface VoiceClonesArtifact {
+    schemaVersion: 1;
+    projectSlug: string;
+    generatedAt: string;
+    voices: VoiceCloneEntry[];
+}
+export interface VoiceClonesLookup {
+    voices: VoiceCloneEntry[];
+    /** name (lowercased) -> entry. */
+    voiceByName: Map<string, VoiceCloneEntry>;
+    /** character (lowercased) -> entry, for character→voice binding. */
+    voiceByCharacter: Map<string, VoiceCloneEntry>;
+    /**
+     * name (lowercased) -> AssetTagEntry, ready for buildAssetTagLookup's
+     * `voicesByName`. The referencePath is the blank-video clip so it classifies
+     * into Seedance `reference_videos`.
+     */
+    voiceEntryByName: Map<string, AssetTagEntry>;
+}
+export declare function voiceClonesPathFor(root: string, slug: string): string;
+/** Directory the built blank-video clips live in (under the project). */
+export declare function voiceCloneClipsDir(root: string, slug: string): string;
+export declare function writeVoiceClones(root: string, slug: string, artifact: VoiceClonesArtifact): Promise<void>;
+/**
+ * Read `artifacts/voice-clones.json`. Returns empty lookups when absent (graceful —
+ * the execution layer then injects no voice references, byte-identical to today). A
+ * present-but-malformed file is NOT swallowed (JSON.parse surfaces it).
+ */
+export declare function readVoiceClones(root: string, slug: string): Promise<VoiceClonesLookup>;
+export interface BlankVideoPlanOptions {
+    /** Source audio sample path. */
+    audioPath: string;
+    /** Output clip path (.mp4). */
+    outputPath: string;
+    /** Black-frame canvas width (default 1280). */
+    width?: number;
+    /** Black-frame canvas height (default 720). */
+    height?: number;
+    /** Optional fixed slice window for drift control (e.g. 2 seconds). */
+    startSeconds?: number;
+    durationSeconds?: number;
+    /**
+     * Clamp the OUTPUT to this many seconds (output-side `-t`). x264 keeps encoding
+     * frames after the audio ends, so `-shortest` alone lets the video stream overshoot
+     * the audio (e.g. 14s audio -> 16.2s video) and trip the r2v duration cap. Setting
+     * this to the audio length forces the whole clip to exactly that duration.
+     */
+    clampSeconds?: number;
+}
+/**
+ * Build the ffmpeg argv for one black-frame-plus-audio clip WITHOUT spawning.
+ *
+ * `-f lavfi -i color=c=black:s=WxH:r=24` synthesizes the black video; the audio
+ * sample is the second input. When a slice window is given, `-ss <start> -t <duration>`
+ * trims the AUDIO input. `clampSeconds` adds an output-side `-t` that forces the whole
+ * clip to that length — necessary because `-shortest` alone lets x264 overshoot the
+ * audio (trailing video frames), which would trip the r2v duration cap. PURE — splice
+ * the result straight into a runFfmpeg call. Throws on a non-audio source (code 1).
+ */
+export declare function planBlankVideoWithAudio(opts: BlankVideoPlanOptions): string[];
+export interface VoiceCloneInput {
+    /** Voice-asset name. */
+    name: string;
+    /** Source audio sample path. */
+    audioPath: string;
+    /** Optional character to bind the voice to. */
+    character?: string;
+    /** Optional voice description. */
+    description?: string;
+    /** Slice the recording into windows of this many seconds (drift fix; 0/undefined = single clip). */
+    sliceSeconds?: number;
+    /** Black-frame canvas. */
+    width?: number;
+    height?: number;
+}
+/**
+ * Max reference-video length the Seedance/Dreamina r2v voice-lock accepts
+ * (`dreamina-seedance-2-0` rejects refs over this with HTTP 500). A longer voice
+ * clip is warned about at clone time so the operator slices it before it hits the
+ * provider as an opaque 500.
+ */
+export declare const VOICE_REF_MAX_SECONDS = 15.2;
+export interface BuildVoiceCloneOptions {
+    workspaceRoot: string;
+    slug: string;
+    /** ISO timestamp (injected so the artifact stays deterministic/testable). */
+    generatedAt: string;
+    /** When true, plan only: return the entry + ffmpeg commands but spawn nothing. */
+    dryRun?: boolean;
+    /** Override the ffmpeg binary (tests / non-standard installs). */
+    ffmpegBin?: string;
+    /**
+     * Host the built clip and return its durable URL (or null when unavailable).
+     * Injected so it is testable and so dry-runs never touch the network; the handler
+     * wires the real Go Bananas uploader. Omitted/undefined -> no hosting attempted.
+     */
+    hostMedia?: (clipPath: string) => Promise<string | null>;
+}
+export interface BuildVoiceCloneResult {
+    entry: VoiceCloneEntry;
+    /** The ffmpeg command line(s) that were (or, on dryRun, would be) run. */
+    commands: string[];
+    /** Advisory warnings (duration over the r2v cap, hosting unavailable, …). */
+    warnings: string[];
+}
+/**
+ * Build a single voice clone: render its blank-video-with-audio clip(s) and return
+ * the artifact entry. On `dryRun`, no ffmpeg is spawned (commands are still
+ * returned for inspection) and durationMs is 0.
+ *
+ * Slicing: when `sliceSeconds > 0`, the source is probed for its length and one
+ * `<name>-NN.mp4` clip is emitted per window; `clipPath` points at the first slice
+ * (the primary reference) and `slices[]` lists them all. Without slicing, a single
+ * `<name>.mp4` clip is built.
+ */
+export declare function buildVoiceClone(input: VoiceCloneInput, opts: BuildVoiceCloneOptions): Promise<BuildVoiceCloneResult>;
+/**
+ * Build one voice clone and merge it into `voice-clones.json` (replacing any entry
+ * with the same name). Returns the persisted artifact + the build result. On
+ * `dryRun`, nothing is written and nothing is spawned — the would-be artifact is
+ * returned for inspection.
+ */
+export declare function registerVoiceClone(input: VoiceCloneInput, opts: BuildVoiceCloneOptions): Promise<{
+    artifact: VoiceClonesArtifact;
+    result: BuildVoiceCloneResult;
+}>;
+//# sourceMappingURL=voice-clone.d.ts.map

package/dist/video/voice-clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-clone.d.ts","sourceRoot":"","sources":["../../src/video/voice-clone.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,CAAC,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,kCAAkC;IAClC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,oEAAoE;IACpE,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC/C;;;;OAIG;IACH,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC9C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4B5F;AAMD,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAmC7E;AAED,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,eAAe,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,qBAAqB,CAAC,CA6GhC;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC,CAiB3E"}

package/dist/video/voice-clone.js

@@ -0,0 +1,267 @@
+/**
+ * Voice clones — the "blank video with audio" voice-reference trick.
+ *
+ * Source of truth: the Jack-Vs-AI "cartoon show" workflow (VOICE DESIGN chapter).
+ * The production-learned insight is that supplying a target voice to a video model
+ * (Seedance 2 / Veo) as a raw MP3/WAV audio reference does NOT lock the voice — the
+ * generation drifts to a generic accent. Supplying the SAME audio as the track of a
+ * **black-frame video** ("blank video with the audio track there") DOES lock it: the
+ * model treats it as a video reference and clones the voice as a driving asset.
+ *
+ * This module is the deterministic CLI half: it BUILDS that black-frame-plus-audio
+ * MP4 from an audio sample (via the shared `runFfmpeg` helper) and persists each clip
+ * as a reusable **voice clone** asset (`artifacts/voice-clones.json`), mirroring the
+ * seedance-asset-library / environment-assets pattern. A voice clone can be bound to a
+ * character so that any scene featuring that character auto-injects the blank video
+ * into the Seedance `reference_videos` set at execution time — or reference a voice
+ * explicitly with an `@<voice-name>` tag (see `execution-runtime.ts` /
+ * `asset-tag-lookup.ts`). Absent artifact → byte-identical to today.
+ *
+ * Voice-drift fix from the workflow: `sliceSeconds` chops one long recording into N
+ * short clips (the creator recommends 2-second slices per dialogue line) so the model
+ * has cleaner per-line references.
+ *
+ * PURE / TESTABLE: `planBlankVideoWithAudio()` returns the ffmpeg argv WITHOUT
+ * spawning, so the whole planning surface is offline-testable. The executor only
+ * shells out when `dryRun` is false — and `runFfmpeg`/`ffprobeDuration` themselves
+ * short-circuit on dryRun, so tests never need ffmpeg installed.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { resolveProjectWorkspace } from './workspace.js';
+import { writeTextFileAtomic } from './atomic-write.js';
+import { runFfmpeg, ffprobeDuration, STANDARD_VIDEO_ARGS, STANDARD_AUDIO_ARGS } from './assemble/ffmpeg.js';
+export function voiceClonesPathFor(root, slug) {
+    return join(resolveProjectWorkspace(slug, root).artifactsDir, 'voice-clones.json');
+}
+/** Directory the built blank-video clips live in (under the project). */
+export function voiceCloneClipsDir(root, slug) {
+    return join(resolveProjectWorkspace(slug, root).projectDir, 'voices');
+}
+export async function writeVoiceClones(root, slug, artifact) {
+    const path = voiceClonesPathFor(root, slug);
+    await mkdir(dirname(path), { recursive: true });
+    await writeTextFileAtomic(path, `${JSON.stringify(artifact, null, 2)}\n`);
+}
+/**
+ * Read `artifacts/voice-clones.json`. Returns empty lookups when absent (graceful —
+ * the execution layer then injects no voice references, byte-identical to today). A
+ * present-but-malformed file is NOT swallowed (JSON.parse surfaces it).
+ */
+export async function readVoiceClones(root, slug) {
+    const path = voiceClonesPathFor(root, slug);
+    if (!existsSync(path)) {
+        return {
+            voices: [],
+            voiceByName: new Map(),
+            voiceByCharacter: new Map(),
+            voiceEntryByName: new Map(),
+        };
+    }
+    const parsed = JSON.parse(await readFile(path, 'utf-8'));
+    const voices = Array.isArray(parsed.voices)
+        ? parsed.voices.filter((v) => !!v && !!v.name && !!v.clipPath)
+        : [];
+    const voiceByName = new Map();
+    const voiceByCharacter = new Map();
+    const voiceEntryByName = new Map();
+    for (const v of voices) {
+        voiceByName.set(v.name.toLowerCase(), v);
+        if (v.character)
+            voiceByCharacter.set(v.character.toLowerCase(), v);
+        voiceEntryByName.set(v.name.toLowerCase(), {
+            descriptor: v.description ?? `the voice of ${v.character ?? v.name}`,
+            // Prefer the durable hosted URL (required by remote routes); fall back to the
+            // local clip when hosting was unavailable at clone time.
+            referencePath: v.hostedUrl ?? v.clipPath,
+        });
+    }
+    return { voices, voiceByName, voiceByCharacter, voiceEntryByName };
+}
+// ── Blank-video-with-audio builder ──────────────────────────────────────────────
+const AUDIO_EXTENSIONS = new Set(['.mp3', '.wav', '.m4a', '.aac', '.ogg', '.flac']);
+/**
+ * Build the ffmpeg argv for one black-frame-plus-audio clip WITHOUT spawning.
+ *
+ * `-f lavfi -i color=c=black:s=WxH:r=24` synthesizes the black video; the audio
+ * sample is the second input. When a slice window is given, `-ss <start> -t <duration>`
+ * trims the AUDIO input. `clampSeconds` adds an output-side `-t` that forces the whole
+ * clip to that length — necessary because `-shortest` alone lets x264 overshoot the
+ * audio (trailing video frames), which would trip the r2v duration cap. PURE — splice
+ * the result straight into a runFfmpeg call. Throws on a non-audio source (code 1).
+ */
+export function planBlankVideoWithAudio(opts) {
+    const ext = extname(opts.audioPath).toLowerCase();
+    if (!AUDIO_EXTENSIONS.has(ext)) {
+        throw new Error(`voice-clone source must be an audio file (${[...AUDIO_EXTENSIONS].join(', ')}); got "${opts.audioPath}".`);
+    }
+    const width = opts.width ?? 1280;
+    const height = opts.height ?? 720;
+    const args = [
+        '-f',
+        'lavfi',
+        '-i',
+        `color=c=black:s=${width}x${height}:r=24`,
+    ];
+    // Trim the AUDIO input window when slicing (apply -ss/-t to the audio input).
+    if (opts.startSeconds !== undefined)
+        args.push('-ss', String(opts.startSeconds));
+    if (opts.durationSeconds !== undefined)
+        args.push('-t', String(opts.durationSeconds));
+    args.push('-i', opts.audioPath, ...STANDARD_VIDEO_ARGS, ...STANDARD_AUDIO_ARGS, 
+    // Map the synthesized video + the real audio.
+    '-map', '0:v:0', '-map', '1:a:0');
+    // Output-side clamp: forces the whole clip (video + audio) to clampSeconds, so the
+    // video can't overshoot the audio. Falls back to -shortest when no clamp is known
+    // (e.g. dry-run, where the audio length isn't probed).
+    if (opts.clampSeconds !== undefined)
+        args.push('-t', String(opts.clampSeconds));
+    args.push('-shortest', opts.outputPath);
+    return args;
+}
+/**
+ * Max reference-video length the Seedance/Dreamina r2v voice-lock accepts
+ * (`dreamina-seedance-2-0` rejects refs over this with HTTP 500). A longer voice
+ * clip is warned about at clone time so the operator slices it before it hits the
+ * provider as an opaque 500.
+ */
+export const VOICE_REF_MAX_SECONDS = 15.2;
+/**
+ * Build a single voice clone: render its blank-video-with-audio clip(s) and return
+ * the artifact entry. On `dryRun`, no ffmpeg is spawned (commands are still
+ * returned for inspection) and durationMs is 0.
+ *
+ * Slicing: when `sliceSeconds > 0`, the source is probed for its length and one
+ * `<name>-NN.mp4` clip is emitted per window; `clipPath` points at the first slice
+ * (the primary reference) and `slices[]` lists them all. Without slicing, a single
+ * `<name>.mp4` clip is built.
+ */
+export async function buildVoiceClone(input, opts) {
+    if (!input.name?.trim())
+        throw new Error('voice-clone requires a --name.');
+    if (!input.audioPath?.trim())
+        throw new Error('voice-clone requires an --audio sample.');
+    if (!opts.dryRun && !existsSync(input.audioPath)) {
+        throw new Error(`voice-clone --audio not found: ${input.audioPath}`);
+    }
+    // Validate the source extension up front — before any ffprobe — so a non-audio
+    // sample fails fast with the input-error message (planBlankVideoWithAudio also
+    // checks, but now that we probe duration first, the early check keeps the error
+    // classification stable: input error / exit 1, not an ffprobe failure / exit 2).
+    const sourceExt = extname(input.audioPath).toLowerCase();
+    if (!AUDIO_EXTENSIONS.has(sourceExt)) {
+        throw new Error(`voice-clone source must be an audio file (${[...AUDIO_EXTENSIONS].join(', ')}); got "${input.audioPath}".`);
+    }
+    const clipsDir = voiceCloneClipsDir(opts.workspaceRoot, opts.slug);
+    if (!opts.dryRun)
+        await mkdir(clipsDir, { recursive: true });
+    const safeName = input.name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'voice';
+    const commands = [];
+    const slices = [];
+    const warnings = [];
+    let durationMs = 0;
+    const sliceSeconds = input.sliceSeconds && input.sliceSeconds > 0 ? input.sliceSeconds : 0;
+    if (sliceSeconds > 0) {
+        durationMs = await ffprobeDuration(input.audioPath, { dryRun: opts.dryRun });
+        // On dry-run we cannot probe, so plan a single representative slice; the real
+        // run probes and emits the full set. Either way the arg shapes are identical.
+        const totalSeconds = durationMs > 0 ? durationMs / 1000 : sliceSeconds;
+        const count = Math.max(1, Math.ceil(totalSeconds / sliceSeconds));
+        for (let i = 0; i < count; i += 1) {
+            const outputPath = join(clipsDir, `${safeName}-${String(i + 1).padStart(2, '0')}.mp4`);
+            const args = planBlankVideoWithAudio({
+                audioPath: input.audioPath,
+                outputPath,
+                ...(input.width !== undefined ? { width: input.width } : {}),
+                ...(input.height !== undefined ? { height: input.height } : {}),
+                startSeconds: i * sliceSeconds,
+                durationSeconds: sliceSeconds,
+                clampSeconds: sliceSeconds,
+            });
+            const { command } = await runFfmpeg(args, {
+                dryRun: opts.dryRun,
+                ...(opts.ffmpegBin ? { ffmpegBin: opts.ffmpegBin } : {}),
+            });
+            commands.push(command);
+            slices.push(outputPath);
+        }
+    }
+    else {
+        const outputPath = join(clipsDir, `${safeName}.mp4`);
+        // Probe the audio length BEFORE building so we can clamp the output to it (the
+        // video would otherwise overshoot — see planBlankVideoWithAudio). 0 on dry-run.
+        if (!opts.dryRun)
+            durationMs = await ffprobeDuration(input.audioPath, { dryRun: false });
+        const args = planBlankVideoWithAudio({
+            audioPath: input.audioPath,
+            outputPath,
+            ...(input.width !== undefined ? { width: input.width } : {}),
+            ...(input.height !== undefined ? { height: input.height } : {}),
+            ...(durationMs > 0 ? { clampSeconds: durationMs / 1000 } : {}),
+        });
+        const { command } = await runFfmpeg(args, {
+            dryRun: opts.dryRun,
+            ...(opts.ffmpegBin ? { ffmpegBin: opts.ffmpegBin } : {}),
+        });
+        commands.push(command);
+        slices.push(outputPath);
+    }
+    // Duration preflight (1B): a single voice reference longer than the r2v cap is
+    // rejected by Seedance with an opaque HTTP 500. Warn (without slicing) so the
+    // operator slices it; a sliced clone's primary slice is already short, so only
+    // warn for the un-sliced case.
+    if (sliceSeconds === 0 && durationMs > 0 && durationMs / 1000 > VOICE_REF_MAX_SECONDS) {
+        warnings.push(`voice clip is ${(durationMs / 1000).toFixed(1)}s; Seedance r2v requires the reference video ≤${VOICE_REF_MAX_SECONDS}s. ` +
+            `Re-run with --slice-seconds ${Math.floor(VOICE_REF_MAX_SECONDS)} (or a shorter sample) before using it on seedance-direct.`);
+    }
+    // Host the primary clip so remote routes get a durable public URL (seedance-direct
+    // r2v needs a hosted ref, not a local path). Injected + executor-only; on dry-run
+    // or when hosting is unavailable, hostedUrl stays unset and the clip stays local.
+    let hostedUrl;
+    if (!opts.dryRun && opts.hostMedia) {
+        const url = await opts.hostMedia(slices[0]);
+        if (url)
+            hostedUrl = url;
+        else
+            warnings.push('voice clip not hosted; remote routes (seedance-direct) need a hosted URL — host it before use.');
+    }
+    const entry = {
+        name: input.name.trim(),
+        ...(input.character ? { character: input.character.trim() } : {}),
+        sourceAudio: input.audioPath,
+        clipPath: slices[0],
+        ...(hostedUrl ? { hostedUrl } : {}),
+        ...(slices.length > 1 ? { slices } : {}),
+        ...(input.description ? { description: input.description.trim() } : {}),
+        durationMs,
+    };
+    return { entry, commands, warnings };
+}
+/**
+ * Build one voice clone and merge it into `voice-clones.json` (replacing any entry
+ * with the same name). Returns the persisted artifact + the build result. On
+ * `dryRun`, nothing is written and nothing is spawned — the would-be artifact is
+ * returned for inspection.
+ */
+export async function registerVoiceClone(input, opts) {
+    const result = await buildVoiceClone(input, opts);
+    const existing = await readVoiceClones(opts.workspaceRoot, opts.slug);
+    const merged = existing.voices.filter((v) => v.name.toLowerCase() !== result.entry.name.toLowerCase());
+    merged.push(result.entry);
+    const artifact = {
+        schemaVersion: 1,
+        projectSlug: opts.slug,
+        generatedAt: opts.generatedAt,
+        voices: merged,
+    };
+    if (!opts.dryRun) {
+        await writeVoiceClones(opts.workspaceRoot, opts.slug, artifact);
+    }
+    return { artifact, result };
+}
+//# sourceMappingURL=voice-clone.js.map

package/dist/video/voice-clone.js.map

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