videoclaw 3.0.0-alpha.1

package/src/video/assemble/upscale.ts

@@ -0,0 +1,80 @@
+/**
+ * Gated, opt-in Topaz Video AI upscale planner for the assemble stage (WS9).
+ *
+ * This module is a PURE planner: `topazUpscalePlan` decides whether an upscale
+ * pass should run and, if so, builds the exact CLI command — but it NEVER spawns
+ * a process. The actual shell-out is a separate thin wrapper that runs only when
+ * `plan.run` is true, so the gate stays fully unit-testable and offline.
+ *
+ * The pass is opt-in via two knobs (both must be satisfied to run):
+ *  - enabled: the operator opted in (env flag VCLAW_TOPAZ_UPSCALE=1).
+ *  - cliPath: the Topaz CLI is installed / located (env path VCLAW_TOPAZ_CLI).
+ * When `enabled`/`cliPath` are omitted the planner falls back to those env vars,
+ * so a project without the flag set behaves as a no-op (run:false).
+ */
+
+/** Topaz CLI gate inputs. Explicit fields win over the env fallbacks. */
+export interface TopazUpscaleOptions {
+  /** Whether the operator opted in. Falls back to VCLAW_TOPAZ_UPSCALE === '1'. */
+  enabled?: boolean;
+  /** Path to the Topaz CLI binary. Falls back to VCLAW_TOPAZ_CLI. */
+  cliPath?: string;
+  /** Upscale factor (default 2). */
+  scale?: number;
+  /** Topaz model name (default 'prob-4'). */
+  model?: string;
+}
+
+/** The planner output. `run` gates the (separate) shell-out. */
+export interface TopazUpscalePlan {
+  /** True iff an upscale pass should actually run. */
+  run: boolean;
+  /** When run is false, why (so callers can log/skip clearly). */
+  reason?: string;
+  /** The CLI command to execute when run is true; `[]` when run is false. */
+  command: string[];
+}
+
+/**
+ * Plan a Topaz upscale pass for `input` -> `output`. PURE — never spawns.
+ *
+ * Resolution order for the two gate knobs: explicit option > env var. The pass
+ * runs only when it is BOTH enabled AND the CLI path is known; otherwise it
+ * returns `run:false` with a `reason` and an empty `command`.
+ */
+export function topazUpscalePlan(
+  input: string,
+  output: string,
+  opts: TopazUpscaleOptions = {},
+): TopazUpscalePlan {
+  const enabled = opts.enabled ?? process.env.VCLAW_TOPAZ_UPSCALE === '1';
+  const cliPath = opts.cliPath ?? process.env.VCLAW_TOPAZ_CLI;
+
+  if (!enabled) {
+    return { run: false, reason: 'Topaz upscale not enabled (VCLAW_TOPAZ_UPSCALE!=1)', command: [] };
+  }
+  if (!cliPath) {
+    return {
+      run: false,
+      reason: 'Topaz CLI not installed (VCLAW_TOPAZ_CLI absent)',
+      command: [],
+    };
+  }
+
+  const scale = opts.scale ?? 2;
+  const model = opts.model ?? 'prob-4';
+  return {
+    run: true,
+    command: [
+      cliPath,
+      '-i',
+      input,
+      '-o',
+      output,
+      '--scale',
+      String(scale),
+      '--model',
+      model,
+    ],
+  };
+}

package/src/video/asset-spec.ts

@@ -0,0 +1,53 @@
+export interface ParsedAssetSpec {
+  id: string;
+  kind: 'image' | 'video' | 'audio' | 'subtitle' | 'other';
+  path: string;
+  sceneIndex?: number;
+  backend?: string;
+}
+
+const ALLOWED_KINDS = new Set(['image', 'video', 'audio', 'subtitle', 'other']);
+// A URI/URL scheme prefix (http://, https://, Asset://, gobananas://, gs://, s3://, …)
+// — its internal `://` and any `:port` would be shredded by a naive split(':').
+const SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.\-]*:\/\//;
+// For a scheme path, peel an optional trailing `:sceneIndex[:backend]` from the END
+// so the URL (which may itself contain colons) is preserved intact.
+const TRAILING_RE = /^(.*?)(?::(\d+)(?::([^:]+))?)?$/;
+
+/**
+ * Parse a `--asset kind:path[:sceneIndex][:backend]` spec. The path may be a
+ * local file path OR a URL / `Asset://` URI whose internal colons must survive.
+ * Local paths keep the original positional split (byte-identical behavior);
+ * scheme paths peel the trailing `:sceneIndex[:backend]` from the end instead.
+ */
+export function parseAssetSpec(raw: string): ParsedAssetSpec {
+  const firstColon = raw.indexOf(':');
+  const kindRaw = firstColon >= 0 ? raw.slice(0, firstColon) : '';
+  const remainder = firstColon >= 0 ? raw.slice(firstColon + 1) : '';
+  if (!kindRaw || !remainder) {
+    throw new Error(`Invalid --asset value: "${raw}". Expected kind:path[:sceneIndex][:backend]`);
+  }
+
+  let path: string;
+  let sceneIndexRaw: string | undefined;
+  let backend: string | undefined;
+
+  if (SCHEME_RE.test(remainder)) {
+    const match = TRAILING_RE.exec(remainder);
+    path = match?.[1] ?? remainder;
+    sceneIndexRaw = match?.[2];
+    backend = match?.[3];
+  } else {
+    [path, sceneIndexRaw, backend] = remainder.split(':');
+  }
+
+  const kind = (ALLOWED_KINDS.has(kindRaw) ? kindRaw : 'other') as ParsedAssetSpec['kind'];
+  const sceneIndex = sceneIndexRaw !== undefined && sceneIndexRaw !== '' ? Number(sceneIndexRaw) : undefined;
+  return {
+    id: `${kind}-${path}`,
+    kind,
+    path,
+    ...(Number.isFinite(sceneIndex) ? { sceneIndex } : {}),
+    ...(backend ? { backend } : {}),
+  };
+}

package/src/video/asset-tag-lookup.ts

@@ -0,0 +1,51 @@
+import type { AssetTagEntry, AssetTagLookup } from './prompt-rules.js';
+
+/**
+ * Build the name -> AssetTagEntry map for resolveAssetTags. Keys are lowercased.
+ * descriptor = description ?? name; referencePath = Asset:// URI (seedance) else
+ * the first referenceAssets image. environmentsByName (#3) is merged when present.
+ * Pure — the caller does the I/O (characters.json + seedance-assets.json).
+ *
+ * `assetUriOnly` (set on the seedance-direct route): a character's referencePath
+ * comes ONLY from its Asset:// URI — never the raw `referenceAssets[0]` portrait.
+ * A raw local portrait both fails seedance submit (the API needs a hosted URL /
+ * Asset:// URI) and trips the real-person content filter, so an @Name tag for an
+ * unregistered character contributes its descriptor text but no reference. The
+ * environment entries are unaffected (they carry already-hosted plate refs).
+ *
+ * `voicesByName` (#4): registered voice clones (the blank-video-with-audio trick).
+ * Merged LAST so an explicit @VoiceName tag resolves to the voice clip; a voice
+ * entry's referencePath is the blank-video clip, which the seedance transport
+ * classifies into `reference_videos` (the voice-locking reference). Absent → no-op.
+ */
+export function buildAssetTagLookup(input: {
+  characters: Array<{ name: string; description?: string; referenceAssets?: string[] }>;
+  assetUriByName: Map<string, string>;
+  assetUriOnly?: boolean;
+  environmentsByName?: AssetTagLookup;
+  voicesByName?: AssetTagLookup;
+}): AssetTagLookup {
+  const lookup: AssetTagLookup = new Map();
+  for (const character of input.characters) {
+    if (!character.name) continue;
+    const referencePath = input.assetUriOnly
+      ? input.assetUriByName.get(character.name)
+      : input.assetUriByName.get(character.name) ?? character.referenceAssets?.[0];
+    const entry: AssetTagEntry = {
+      descriptor: character.description ?? character.name,
+      ...(referencePath ? { referencePath } : {}),
+    };
+    lookup.set(character.name.toLowerCase(), entry);
+  }
+  if (input.environmentsByName) {
+    for (const [name, entry] of input.environmentsByName) {
+      lookup.set(name.toLowerCase(), entry);
+    }
+  }
+  if (input.voicesByName) {
+    for (const [name, entry] of input.voicesByName) {
+      lookup.set(name.toLowerCase(), entry);
+    }
+  }
+  return lookup;
+}

package/src/video/atomic-write.ts

@@ -0,0 +1,7 @@
+import { rename, writeFile } from 'node:fs/promises';
+
+export async function writeTextFileAtomic(path: string, content: string): Promise<void> {
+  const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(tempPath, content);
+  await rename(tempPath, path);
+}

package/src/video/audio-platform/native-elevenlabs-sfx.ts

@@ -0,0 +1,128 @@
+/**
+ * SCAFFOLD: ElevenLabs Sound Effects request/response per docs at
+ * https://elevenlabs.io/docs/api-reference/sound-generation; verify against a
+ * real ELEVENLABS_API_KEY before treating this as production-ready.
+ *
+ * ElevenLabs SFX backend — wraps the ElevenLabs Sound Generation endpoint:
+ *   POST https://api.elevenlabs.io/v1/sound-generation
+ *   Header: xi-api-key: <ELEVENLABS_API_KEY>
+ *   Body (JSON): { text, duration_seconds?, prompt_influence? }
+ *   Response: audio/mpeg bytes (mp3)
+ *
+ * The API honors a requested `duration_seconds` (0.5–22 s) and a
+ * `prompt_influence` scalar (0–1, default 0.3). This backend:
+ *   - Resolves the API key from `input.env?.ELEVENLABS_API_KEY ?? process.env.ELEVENLABS_API_KEY`.
+ *   - Writes the returned mp3 bytes to `outputPath`.
+ *   - Returns `durationMs` derived from the requested `durationSec * 1000`
+ *     (default 2 000 ms). The API honors the requested duration so this is
+ *     a reliable estimate without requiring an ffprobe call.
+ *   - On dry-run: creates the output directory and writes a zero-byte
+ *     placeholder mp3; does NOT touch the network.
+ *   - On non-2xx or empty response body: throws VclawError('music_gen_failed')
+ *     (reusing the existing error code avoids touching the errors catalog).
+ *
+ * Availability: `ELEVENLABS_API_KEY` must be set and non-empty (in env or
+ * process.env). The backend is inert without the key.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { VclawError } from '../errors.js';
+import type { SfxBackend, SfxGenInput, SfxGenResult } from './types.js';
+
+const ELEVENLABS_SFX_URL = 'https://api.elevenlabs.io/v1/sound-generation';
+
+/** Default duration when neither the caller nor the API provides one. */
+const DEFAULT_DURATION_SEC = 2;
+
+/**
+ * Resolve the ElevenLabs API key from a caller-supplied env object or
+ * process.env, preferring the caller-supplied env so library callers that
+ * cannot mutate process.env can still authenticate.
+ */
+function resolveApiKey(env: NodeJS.ProcessEnv | undefined): string | undefined {
+  const key = env?.ELEVENLABS_API_KEY ?? process.env.ELEVENLABS_API_KEY;
+  return key && key.trim() !== '' ? key.trim() : undefined;
+}
+
+export const elevenLabsSfx: SfxBackend = {
+  id: 'elevenlabs-sfx',
+  kind: 'sfx',
+  displayName: 'ElevenLabs Sound Effects',
+  requiredEnv: ['ELEVENLABS_API_KEY'],
+  requiresVertex: false,
+  summary:
+    'Sound-effect generation via the ElevenLabs Sound Generation API. Returns an mp3 of the requested duration (0.5–22 s). Requires ELEVENLABS_API_KEY.',
+
+  async generate(input: SfxGenInput): Promise<SfxGenResult> {
+    if (!input.text || !input.text.trim()) {
+      throw new VclawError(
+        'music_gen_failed',
+        'ElevenLabs SFX: cannot generate a sound effect from empty text.',
+        { backendId: 'elevenlabs-sfx' },
+      );
+    }
+
+    const durationSec = input.durationSec ?? DEFAULT_DURATION_SEC;
+    const durationMs = Math.round(durationSec * 1000);
+
+    // Dry-run: create directory + write zero-byte placeholder; no network.
+    if (input.dryRun) {
+      await mkdir(dirname(input.outputPath), { recursive: true });
+      await writeFile(input.outputPath, new Uint8Array(0));
+      return { path: input.outputPath, durationMs, backendId: 'elevenlabs-sfx' };
+    }
+
+    const apiKey = resolveApiKey(input.env);
+    if (!apiKey) {
+      throw new VclawError(
+        'music_gen_failed',
+        'ElevenLabs SFX: ELEVENLABS_API_KEY is not set. Export it before generating sound effects.',
+        { backendId: 'elevenlabs-sfx', envVar: 'ELEVENLABS_API_KEY' },
+      );
+    }
+
+    const doFetch = input.fetcher ?? fetch;
+
+    const requestBody: Record<string, unknown> = {
+      text: input.text.trim(),
+      duration_seconds: durationSec,
+    };
+    if (input.promptInfluence !== undefined) {
+      requestBody.prompt_influence = input.promptInfluence;
+    }
+
+    const response = await doFetch(ELEVENLABS_SFX_URL, {
+      method: 'POST',
+      headers: {
+        'xi-api-key': apiKey,
+        'Content-Type': 'application/json',
+        Accept: 'audio/mpeg',
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new VclawError(
+        'music_gen_failed',
+        `ElevenLabs SFX request failed with HTTP ${response.status}.`,
+        { backendId: 'elevenlabs-sfx', status: response.status, body: body.slice(0, 500) },
+      );
+    }
+
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.length === 0) {
+      throw new VclawError(
+        'music_gen_failed',
+        'ElevenLabs SFX returned an empty audio payload.',
+        { backendId: 'elevenlabs-sfx' },
+      );
+    }
+
+    await mkdir(dirname(input.outputPath), { recursive: true });
+    await writeFile(input.outputPath, bytes);
+
+    return { path: input.outputPath, durationMs, backendId: 'elevenlabs-sfx' };
+  },
+};

package/src/video/audio-platform/native-elevenlabs-tts.ts

@@ -0,0 +1,119 @@
+/**
+ * ElevenLabs TTS narration backend — wraps the ElevenLabs Text-to-Speech endpoint:
+ *   POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}
+ *   Header: xi-api-key: <ELEVENLABS_API_KEY>
+ *   Body (JSON): { text, model_id }
+ *   Response: audio/mpeg bytes (mp3)
+ *
+ * This exists so `vclaw video narrate` has a working backend that does NOT
+ * depend on the Gemini `generativelanguage` API being enabled on the key's GCP
+ * project (the gemini-tts backend 403s when it isn't). It is the fallback /
+ * alternative TTS path, selected explicitly via `--backend elevenlabs-tts`.
+ *
+ * This backend:
+ *   - Resolves the API key from `input.env?.ELEVENLABS_API_KEY ?? process.env.ELEVENLABS_API_KEY`.
+ *   - Treats `input.voice` as an ElevenLabs **voice_id** (defaults to "Rachel"),
+ *     and uses the `eleven_multilingual_v2` model.
+ *   - Writes the returned mp3 bytes to `outputPath`.
+ *   - Returns `durationMs` ESTIMATED from text length (~14 chars/sec). ElevenLabs
+ *     returns compressed mp3 with no duration field, and we avoid a spawn
+ *     (ffprobe) to keep this backend pure + offline-testable. Callers that need
+ *     exact timing (e.g. narration-fit) probe the written file themselves.
+ *   - On dry-run: creates the output directory and writes a zero-byte
+ *     placeholder mp3; does NOT touch the network.
+ *   - On missing key / non-2xx / empty body: throws VclawError('tts_failed').
+ *
+ * Availability (registry): `ELEVENLABS_API_KEY` set and non-empty.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { VclawError } from '../errors.js';
+import type { TtsBackend, TtsGenInput, TtsGenResult } from './types.js';
+
+const ELEVENLABS_TTS_BASE_URL = 'https://api.elevenlabs.io/v1/text-to-speech';
+const TTS_MODEL = 'eleven_multilingual_v2';
+/** Stable default ElevenLabs voice ("Rachel") when the caller passes no voice. */
+const DEFAULT_VOICE_ID = '21m00Tcm4TlvDq8ikWAM';
+/** Chars-per-second heuristic for duration estimation (~14 cps speech). */
+const CHARS_PER_SEC = 14;
+
+function resolveApiKey(env: NodeJS.ProcessEnv | undefined): string | undefined {
+  const key = env?.ELEVENLABS_API_KEY ?? process.env.ELEVENLABS_API_KEY;
+  return key && key.trim() !== '' ? key.trim() : undefined;
+}
+
+function estimateDurationMs(text: string): number {
+  return Math.round((Math.max(1, text.trim().length / CHARS_PER_SEC)) * 1000);
+}
+
+export const elevenLabsTts: TtsBackend = {
+  id: 'elevenlabs-tts',
+  kind: 'tts',
+  outputExtension: 'mp3',
+  displayName: 'ElevenLabs TTS (eleven_multilingual_v2)',
+  requiredEnv: ['ELEVENLABS_API_KEY'],
+  requiresVertex: false,
+  summary:
+    'Single-speaker text-to-speech via the ElevenLabs API (eleven_multilingual_v2). Returns mp3. `--voice` is an ElevenLabs voice_id (default "Rachel"). Requires ELEVENLABS_API_KEY. A Gemini-free alternative to gemini-tts.',
+
+  async generate(input: TtsGenInput): Promise<TtsGenResult> {
+    if (!input.text || !input.text.trim()) {
+      throw new VclawError('tts_failed', 'Cannot synthesize narration from empty text.', {
+        backendId: 'elevenlabs-tts',
+      });
+    }
+
+    const durationMs = estimateDurationMs(input.text);
+
+    // Dry-run: create directory + write zero-byte placeholder; no network.
+    if (input.dryRun) {
+      await mkdir(dirname(input.outputPath), { recursive: true });
+      await writeFile(input.outputPath, new Uint8Array(0));
+      return { path: input.outputPath, durationMs, backendId: 'elevenlabs-tts' };
+    }
+
+    const apiKey = resolveApiKey(input.env);
+    if (!apiKey) {
+      throw new VclawError(
+        'tts_failed',
+        'ElevenLabs TTS: ELEVENLABS_API_KEY is not set. Export it before generating narration.',
+        { backendId: 'elevenlabs-tts', envVar: 'ELEVENLABS_API_KEY' },
+      );
+    }
+
+    const voiceId = input.voice && input.voice.trim() ? input.voice.trim() : DEFAULT_VOICE_ID;
+    const doFetch = input.fetcher ?? fetch;
+
+    const response = await doFetch(`${ELEVENLABS_TTS_BASE_URL}/${encodeURIComponent(voiceId)}`, {
+      method: 'POST',
+      headers: {
+        'xi-api-key': apiKey,
+        'Content-Type': 'application/json',
+        Accept: 'audio/mpeg',
+      },
+      body: JSON.stringify({ text: input.text.trim(), model_id: TTS_MODEL }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new VclawError(
+        'tts_failed',
+        `ElevenLabs TTS request failed with HTTP ${response.status}.`,
+        { backendId: 'elevenlabs-tts', status: response.status, body: body.slice(0, 500) },
+      );
+    }
+
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.length === 0) {
+      throw new VclawError('tts_failed', 'ElevenLabs TTS returned an empty audio payload.', {
+        backendId: 'elevenlabs-tts',
+      });
+    }
+
+    await mkdir(dirname(input.outputPath), { recursive: true });
+    await writeFile(input.outputPath, bytes);
+
+    return { path: input.outputPath, durationMs, backendId: 'elevenlabs-tts' };
+  },
+};

package/src/video/audio-platform/native-flowmusic.ts

@@ -0,0 +1,167 @@
+/**
+ * FlowMusic music backend — Google Lyria 3 Pro vocal songs via useapi.net.
+ *
+ * Unlike the instrumental-only Lyria backends (native-lyria / native-lyria3),
+ * FlowMusic generates FULL VOCAL SONGS (and instrumentals): it honors
+ * user-supplied `lyrics` and an `instrumental` toggle. It is an async, job-polled
+ * provider, so this backend wraps the providers/flowmusic-useapi.ts transport:
+ *   submit (mode:async) → poll GET /jobs/{jobid} until terminal → download the
+ *   first clip's mp3 via the auth'd /music/download endpoint → write `.mp3`.
+ *
+ * Availability reuses the shared USEAPI_API_TOKEN (the same token as the
+ * dreamina/runway routes) — gated in the registry via `requiresUseApi`, not a
+ * backend-specific requiredEnv. Optional: VCLAW_FLOWMUSIC_ACCOUNT pins the
+ * flowmusic.app account; VCLAW_FLOWMUSIC_GHOSTWRITER ('standard'|'pro') picks the
+ * lyrics-writer when the model writes lyrics. The poll cadence is configurable
+ * via VCLAW_FLOWMUSIC_POLL_INTERVAL_MS / VCLAW_FLOWMUSIC_POLL_MAX_ATTEMPTS
+ * (tests set the interval to 0 to stay fast + offline).
+ */
+
+import { mkdir, writeFile, rename } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+import { VclawError } from '../errors.js';
+import {
+  submitFlowMusicJob,
+  pollFlowMusicJob,
+  downloadFlowMusicClipMp3,
+  type FlowMusicFetchLike,
+  type FlowMusicGhostwriter,
+} from '../providers/flowmusic-useapi.js';
+import type { MusicBackend, MusicGenInput, MusicGenResult } from './types.js';
+
+/** Lyria 3 Pro full songs land ~40–150s; used only as a fallback duration estimate. */
+const DEFAULT_DURATION_SEC = 150;
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_POLL_MAX_ATTEMPTS = 90; // ~7.5 min ceiling at 5s
+
+/** Force a `.mp3` extension on the output path (we download mp3 bytes). */
+function forceMp3Path(p: string): string {
+  const ext = extname(p);
+  if (ext.toLowerCase() === '.mp3') return p;
+  return ext ? `${p.slice(0, p.length - ext.length)}.mp3` : `${p}.mp3`;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isGhostwriter(v: string | undefined): v is FlowMusicGhostwriter {
+  return v === 'standard' || v === 'pro';
+}
+
+function positiveIntFromEnv(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+export const flowMusicBackend: MusicBackend = {
+  id: 'flowmusic',
+  kind: 'music',
+  displayName: 'FlowMusic (Lyria 3 Pro, useapi.net)',
+  // Reuses the shared USEAPI_API_TOKEN; gated in the registry via requiresUseApi
+  // rather than a backend-specific requiredEnv (no new token is introduced).
+  requiredEnv: [],
+  requiresUseApi: true,
+  summary:
+    'Full vocal songs (and instrumentals) via Google Lyria 3 Pro on useapi.net FlowMusic. ' +
+    'Honors --lyrics and --instrumental. Async submit → poll → mp3 download. Reuses USEAPI_API_TOKEN; ' +
+    'optional VCLAW_FLOWMUSIC_ACCOUNT / VCLAW_FLOWMUSIC_GHOSTWRITER.',
+
+  async generate(input: MusicGenInput): Promise<MusicGenResult> {
+    const env = input.env ?? process.env;
+    const outputPath = forceMp3Path(input.outputPath);
+    const fallbackDurationMs = (input.durationSec ?? DEFAULT_DURATION_SEC) * 1000;
+
+    if (!input.prompt.trim()) {
+      throw new VclawError('music_gen_failed', 'Cannot generate music with an empty prompt.', {
+        backend: 'flowmusic',
+      });
+    }
+
+    // Dry-run: estimate duration, write a placeholder mp3, touch no network.
+    if (input.dryRun) {
+      await mkdir(dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, Buffer.alloc(0));
+      return { path: outputPath, durationMs: fallbackDurationMs, backendId: 'flowmusic' };
+    }
+
+    const apiToken = (env['USEAPI_API_TOKEN'] ?? '').trim();
+    if (!apiToken) {
+      throw new VclawError('music_gen_failed', 'FlowMusic requires USEAPI_API_TOKEN.', {
+        backend: 'flowmusic',
+      });
+    }
+    const account = env['VCLAW_FLOWMUSIC_ACCOUNT']?.trim() || undefined;
+    const ghostwriterRaw = env['VCLAW_FLOWMUSIC_GHOSTWRITER']?.trim();
+    const ghostwriter = isGhostwriter(ghostwriterRaw) ? ghostwriterRaw : undefined;
+    const fetchImpl = input.fetcher as unknown as FlowMusicFetchLike | undefined;
+
+    const pollIntervalMs = positiveIntFromEnv(env['VCLAW_FLOWMUSIC_POLL_INTERVAL_MS'], DEFAULT_POLL_INTERVAL_MS);
+    const maxAttempts = positiveIntFromEnv(env['VCLAW_FLOWMUSIC_POLL_MAX_ATTEMPTS'], DEFAULT_POLL_MAX_ATTEMPTS);
+
+    const submit = await submitFlowMusicJob({
+      apiToken,
+      prompt: input.prompt,
+      ...(account ? { account } : {}),
+      ...(input.instrumental !== undefined ? { instrumental: input.instrumental } : {}),
+      ...(input.lyrics ? { lyrics: input.lyrics } : {}),
+      ...(ghostwriter ? { ghostwriter } : {}),
+      ...(fetchImpl ? { fetchImpl } : {}),
+    });
+
+    // Poll to a terminal state (bounded). The submit may already be terminal in
+    // some responses; the loop body re-polls on 'pending'.
+    let poll = await pollFlowMusicJob({
+      apiToken,
+      jobid: submit.jobid,
+      ...(fetchImpl ? { fetchImpl } : {}),
+    });
+    for (let attempt = 0; poll.status === 'pending' && attempt < maxAttempts; attempt += 1) {
+      if (pollIntervalMs > 0) await sleep(pollIntervalMs);
+      poll = await pollFlowMusicJob({
+        apiToken,
+        jobid: submit.jobid,
+        ...(fetchImpl ? { fetchImpl } : {}),
+      });
+    }
+
+    if (poll.status === 'failed') {
+      throw new VclawError(
+        'music_gen_failed',
+        `FlowMusic generation failed: ${poll.error ?? 'unknown error'}`,
+        { backend: 'flowmusic', jobid: submit.jobid, error: poll.error },
+      );
+    }
+    if (poll.status !== 'completed' || poll.clips.length === 0) {
+      throw new VclawError(
+        'music_gen_failed',
+        'FlowMusic job did not complete in time (no clips returned).',
+        { backend: 'flowmusic', jobid: submit.jobid, status: poll.status },
+      );
+    }
+
+    const clip = poll.clips[0]; // A/B pair → MVP takes the first clip.
+    const bytes = await downloadFlowMusicClipMp3({
+      apiToken,
+      clip: clip.clip,
+      ...(fetchImpl ? { fetchImpl } : {}),
+    });
+    if (bytes.length === 0) {
+      throw new VclawError('music_gen_failed', 'FlowMusic returned an empty audio payload.', {
+        backend: 'flowmusic',
+        jobid: submit.jobid,
+      });
+    }
+
+    await mkdir(dirname(outputPath), { recursive: true });
+    // Atomic write: tmp → rename (mirrors native-dreamina's downloadToFile).
+    const tmp = `${outputPath}.tmp`;
+    await writeFile(tmp, bytes);
+    await rename(tmp, outputPath);
+
+    // Prefer the clip's real duration; fall back to the request estimate.
+    const durationMs = clip.durationS != null ? Math.round(clip.durationS * 1000) : fallbackDurationMs;
+    return { path: outputPath, durationMs, backendId: 'flowmusic' };
+  },
+};