videoclaw 3.0.0-alpha.1

package/src/video/vocal-sync-plan.ts

@@ -0,0 +1,224 @@
+/**
+ * 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.
+ */
+
+export type VocalSectionType = 'rap' | 'hook' | 'instrumental' | 'outro';
+
+export interface VocalSection {
+  /** Section start in song seconds. */
+  start: number;
+  /** Section end in song seconds. */
+  end: number;
+  type: VocalSectionType;
+  /**
+   * The lip-synced performer clip id for this vocal section (rap → rapper clip,
+   * hook → singer clip). Omitted for instrumental/outro (B-roll only).
+   */
+  performerClip?: string;
+}
+
+/** B-roll clip ids grouped by role; performers come from the vocal map, not here. */
+export interface BrollPools {
+  action: string[];
+  atmo: string[];
+  trio: string[];
+  vanish: string[];
+}
+
+export interface PlanVocalSyncInput {
+  /** Contiguous, ordered vocal map covering [0, songEnd]. */
+  vocalMap: VocalSection[];
+  /** Beat timestamps (seconds), e.g. from aubiotrack. */
+  beats: number[];
+  /** Song length in seconds. */
+  songEnd: number;
+  pools: BrollPools;
+  /** Duration (seconds) of a clip id — injected so the planner stays pure. */
+  clipDuration: (clipId: string) => number;
+  /** Output frame rate (default 24). */
+  fps?: number;
+  /** Seconds-per-cut by section type. Verses cut fast; hooks hold longer. */
+  cutLengths?: Partial<Record<VocalSectionType, number>>;
+  /** Injected RNG (default Math.random) — seed it for deterministic tests. */
+  rng?: () => number;
+}
+
+export interface PlannedSegment {
+  clip: string;
+  /** Frame-aligned input-seek point. */
+  inSec: number;
+  /** Frame-aligned duration. */
+  durationSec: number;
+  /** True when this cut is a lip-synced performer (vs B-roll). */
+  performer: boolean;
+}
+
+const DEFAULT_CUTS: Record<VocalSectionType, number> = {
+  rap: 1.3, hook: 2.4, instrumental: 2.0, outro: 3.1,
+};
+const BROLL_ORDER: Record<VocalSectionType, Array<keyof BrollPools>> = {
+  rap: ['action', 'trio'],
+  hook: ['atmo', 'trio'],
+  instrumental: ['atmo', 'trio', 'action'],
+  outro: ['vanish', 'atmo'],
+};
+
+function shuffle<T>(arr: T[], rng: () => number): T[] {
+  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: PlanVocalSyncInput): PlannedSegment[] {
+  const fps = input.fps ?? 24;
+  const rng = input.rng ?? Math.random;
+  const cuts = { ...DEFAULT_CUTS, ...input.cutLengths };
+  const beats = input.beats;
+  const nearestBeat = (t: number): number =>
+    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: number): VocalSection => {
+    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: number): number =>
+    boundaryFrames.find((bf) => bf > frame) ?? songEndF;
+
+  const segs: PlannedSegment[] = [];
+  const useCount: Record<string, number> = {};
+  let lastClip: string | null = null;
+  const bags: Partial<Record<keyof BrollPools, string[]>> = {};
+
+  const draw = (poolKey: keyof BrollPools): string | null => {
+    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() as string;
+    if (clip === lastClip && bag.length > 0) {
+      bag.push(clip);
+      clip = bag.shift() as string;
+    }
+    return clip;
+  };
+
+  const emitBroll = (clip: string, durationSec: number): void => {
+    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: string, wantIn: number, durationSec: number): void => {
+    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: VocalSectionType | null = 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: PlannedSegment[]): number {
+  return +segs.reduce((a, s) => a + s.durationSec, 0).toFixed(4);
+}

package/src/video/voice-clone.ts

@@ -0,0 +1,410 @@
+/**
+ * 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';
+import type { AssetTagEntry } from './prompt-rules.js';
+
+// ── Artifact ──────────────────────────────────────────────────────────────────
+
+/** 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 function voiceClonesPathFor(root: string, slug: string): string {
+  return join(resolveProjectWorkspace(slug, root).artifactsDir, 'voice-clones.json');
+}
+
+/** Directory the built blank-video clips live in (under the project). */
+export function voiceCloneClipsDir(root: string, slug: string): string {
+  return join(resolveProjectWorkspace(slug, root).projectDir, 'voices');
+}
+
+export async function writeVoiceClones(
+  root: string,
+  slug: string,
+  artifact: VoiceClonesArtifact,
+): Promise<void> {
+  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: string, slug: string): Promise<VoiceClonesLookup> {
+  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')) as Partial<VoiceClonesArtifact>;
+  const voices: VoiceCloneEntry[] = Array.isArray(parsed.voices)
+    ? parsed.voices.filter((v): v is VoiceCloneEntry => !!v && !!v.name && !!v.clipPath)
+    : [];
+  const voiceByName = new Map<string, VoiceCloneEntry>();
+  const voiceByCharacter = new Map<string, VoiceCloneEntry>();
+  const voiceEntryByName = new Map<string, AssetTagEntry>();
+  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']);
+
+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 function planBlankVideoWithAudio(opts: BlankVideoPlanOptions): string[] {
+  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: string[] = [
+    '-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;
+}
+
+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 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 async function buildVoiceClone(
+  input: VoiceCloneInput,
+  opts: BuildVoiceCloneOptions,
+): Promise<BuildVoiceCloneResult> {
+  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: string[] = [];
+  const slices: string[] = [];
+  const warnings: string[] = [];
+  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: string | undefined;
+  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: VoiceCloneEntry = {
+    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: VoiceCloneInput,
+  opts: BuildVoiceCloneOptions,
+): Promise<{ artifact: VoiceClonesArtifact; result: BuildVoiceCloneResult }> {
+  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: VoiceClonesArtifact = {
+    schemaVersion: 1,
+    projectSlug: opts.slug,
+    generatedAt: opts.generatedAt,
+    voices: merged,
+  };
+  if (!opts.dryRun) {
+    await writeVoiceClones(opts.workspaceRoot, opts.slug, artifact);
+  }
+  return { artifact, result };
+}