videoclaw 3.0.0-alpha.1

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

@@ -0,0 +1,244 @@
+/**
+ * Music generation via Google Lyria 3 on the **Gemini Developer API** (NOT
+ * Vertex). This is an API-KEY product, so it resolves a key from the existing
+ * Gemini key pool (GEMINI_API_KEYS / GOOGLE_API_KEYS / GOOGLE_API_KEY) via
+ * `fetchGeminiWithPool` — no Vertex project, no billing, just a Gemini key.
+ *
+ * VERIFIED LIVE (2026-06-01) against the Gemini Developer API:
+ *
+ *   POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL}:generateContent?key={KEY}
+ *   Content-Type: application/json
+ *   Body: { contents: [{ parts: [ { text: "<prompt>" } , <optional image part> ] }] }
+ *
+ *   Optional image-to-music conditioning attaches a second part in the SAME
+ *   parts array:
+ *     { inlineData: { mimeType: "image/png", data: "<base64>" } }
+ *
+ *   Response: candidates[0].content.parts[] — find the part whose
+ *   inlineData.mimeType starts with "audio/" (observed "audio/mpeg"); its
+ *   inlineData.data is base64 MP3. (There is also a { text: "<instrumental>" }
+ *   part which we ignore.)
+ *
+ * MODEL (via LYRIA3_MODEL env, default lyria-3-clip-preview):
+ *   - lyria-3-clip-preview  Lyria 3, 30s clip, text + image  (default)
+ *   - lyria-3-pro-preview   Lyria 3 Pro, full song up to ~184s, text + image
+ *
+ * Output is MP3 (audio/mpeg) — the file is always written with a `.mp3`
+ * extension regardless of the requested outputPath suffix. durationMs is a
+ * deterministic estimate from input.durationSec (or a model-default: 180s for
+ * a 'pro' model, 30s otherwise) — true MP3 duration parsing is out of scope.
+ *
+ * Availability: a Gemini key is resolvable (pool size > 0 or one of the env
+ * vars set); gated via the descriptor's requiresGeminiKey flag in the registry.
+ */
+
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+import { fetchGeminiWithPool } from '../gemini-key-pool.js';
+import { VclawError } from '../errors.js';
+import type { MusicBackend, MusicGenInput, MusicGenResult } from './types.js';
+
+const DEFAULT_LYRIA3_MODEL = 'lyria-3-clip-preview';
+
+/** Default clip lengths (seconds) when the caller omits durationSec. */
+const PRO_DEFAULT_SEC = 180;
+const CLIP_DEFAULT_SEC = 30;
+
+/**
+ * Gemini API key sources, in the same precedence as the global key pool
+ * (gemini-key-pool.ts). Used to resolve an explicit key from a caller-supplied
+ * `input.env` so the pool (which only reads process.env) can be bypassed.
+ */
+const GEMINI_KEY_VARS = ['GEMINI_API_KEYS', 'GOOGLE_API_KEYS', 'GOOGLE_API_KEY'] as const;
+
+/**
+ * Resolve the first key from a caller-supplied env that process.env does not
+ * already expose. Returns undefined when no env was passed, or when the passed
+ * env adds no key beyond process.env (in which case the global pool selects).
+ * Mirrors native-gemini-tts.ts's resolver.
+ */
+function resolveKeyOverrideFromEnv(env: NodeJS.ProcessEnv | undefined): string | undefined {
+  if (!env || env === process.env) return undefined;
+  for (const varName of GEMINI_KEY_VARS) {
+    const raw = env[varName];
+    if (typeof raw !== 'string' || raw.trim() === '') continue;
+    if (process.env[varName] === raw) continue;
+    const first = raw.split(/[,;\n\s]+/).map((t) => t.trim()).find((t) => t.length > 0);
+    if (first) return first;
+  }
+  return undefined;
+}
+
+/** Force a `.mp3` extension on the output path (Lyria 3 returns MP3). */
+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`;
+}
+
+/** Map a file extension to an image MIME type for the inlineData part. */
+function imageMimeForPath(p: string): string {
+  switch (extname(p).toLowerCase()) {
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.webp':
+      return 'image/webp';
+    case '.gif':
+      return 'image/gif';
+    case '.png':
+    default:
+      return 'image/png';
+  }
+}
+
+/**
+ * Defensive extraction of the first base64 inlineData payload whose mimeType
+ * starts with "audio/". The Gemini response also carries a { text } part (the
+ * instrumental description) which must be ignored.
+ */
+function extractAudioBase64(parsed: unknown): string | undefined {
+  if (typeof parsed !== 'object' || parsed === null) return undefined;
+  const candidates = (parsed as { candidates?: unknown }).candidates;
+  if (!Array.isArray(candidates) || candidates.length === 0) return undefined;
+  const parts = (candidates[0] as { content?: { parts?: unknown } })?.content?.parts;
+  if (!Array.isArray(parts)) return undefined;
+  for (const part of parts) {
+    const inlineData = (part as { inlineData?: { mimeType?: unknown; data?: unknown } })?.inlineData;
+    const mime = inlineData?.mimeType;
+    const data = inlineData?.data;
+    if (
+      typeof mime === 'string' &&
+      mime.startsWith('audio/') &&
+      typeof data === 'string' &&
+      data.length > 0
+    ) {
+      return data;
+    }
+  }
+  return undefined;
+}
+
+export const lyria3Backend: MusicBackend = {
+  id: 'lyria3',
+  kind: 'music',
+  displayName: 'Lyria 3 (Gemini API)',
+  // API-key product, not Vertex. Availability is resolved from the Gemini key
+  // pool (see isMusicBackendAvailable), so requiredEnv stays empty and the
+  // registry gates on requiresGeminiKey instead of this backend's id.
+  requiredEnv: [],
+  requiresVertex: false,
+  requiresGeminiKey: true,
+  summary:
+    'Music generation via Google Lyria 3 on the Gemini Developer API (key-based, NOT Vertex). Default lyria-3-clip-preview (30s); LYRIA3_MODEL=lyria-3-pro-preview for a full song (~184s). Optional image-to-music conditioning via imagePath. Returns MP3. Requires a Gemini API key (GEMINI_API_KEYS / GOOGLE_API_KEYS / GOOGLE_API_KEY).',
+
+  async generate(input: MusicGenInput): Promise<MusicGenResult> {
+    const env = input.env ?? process.env;
+    const model = env['LYRIA3_MODEL'] ?? DEFAULT_LYRIA3_MODEL;
+    const isPro = model.includes('pro');
+    const durationSec = input.durationSec ?? (isPro ? PRO_DEFAULT_SEC : CLIP_DEFAULT_SEC);
+    const durationMs = durationSec * 1000;
+    const outputPath = forceMp3Path(input.outputPath);
+
+    if (!input.prompt.trim()) {
+      throw new VclawError('music_gen_failed', 'Cannot generate music with an empty prompt.', {
+        backend: 'lyria3',
+      });
+    }
+
+    // Dry-run: estimate duration from the model/request; do NOT touch network.
+    // Write a placeholder MP3 (empty) so downstream existsSync() stays consistent.
+    if (input.dryRun) {
+      await mkdir(dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, Buffer.alloc(0));
+      return { path: outputPath, durationMs, backendId: 'lyria3' };
+    }
+
+    // Build the contents body: text prompt + optional image-to-music part.
+    const parts: Array<
+      { text: string } | { inlineData: { mimeType: string; data: string } }
+    > = [{ text: input.prompt }];
+
+    if (input.imagePath) {
+      let imgBytes: Buffer;
+      try {
+        imgBytes = await readFile(input.imagePath);
+      } catch (err) {
+        throw new VclawError(
+          'music_gen_failed',
+          `Could not read image for image-to-music conditioning: ${input.imagePath}`,
+          { backend: 'lyria3', error: err instanceof Error ? err.message : String(err) },
+        );
+      }
+      parts.push({
+        inlineData: {
+          mimeType: imageMimeForPath(input.imagePath),
+          data: imgBytes.toString('base64'),
+        },
+      });
+    }
+
+    const requestBody = JSON.stringify({ contents: [{ parts }] });
+
+    // Resolve a key from input.env when it carries one the global pool (which
+    // only reads process.env) cannot see; otherwise the pool selects.
+    const keyOverride = resolveKeyOverrideFromEnv(input.env);
+
+    const poolOptions: { fetcher?: typeof fetch; keyOverride?: string } = {};
+    if (input.fetcher) poolOptions.fetcher = input.fetcher;
+    if (keyOverride) poolOptions.keyOverride = keyOverride;
+
+    const response = await fetchGeminiWithPool(
+      (key) =>
+        `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${encodeURIComponent(key)}`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: requestBody,
+      },
+      poolOptions,
+    );
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new VclawError(
+        'music_gen_failed',
+        `Lyria 3 (Gemini API) request failed with HTTP ${response.status}.`,
+        { backend: 'lyria3', status: response.status, body: body.slice(0, 500) },
+      );
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = await response.json();
+    } catch (err) {
+      throw new VclawError('music_gen_failed', 'Lyria 3 returned a non-JSON response.', {
+        backend: 'lyria3',
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    const b64 = extractAudioBase64(parsed);
+    if (!b64) {
+      throw new VclawError(
+        'music_gen_failed',
+        'Lyria 3 response contained no audio/* inlineData part.',
+        { backend: 'lyria3' },
+      );
+    }
+
+    const bytes = Buffer.from(b64, 'base64');
+    if (bytes.length === 0) {
+      throw new VclawError('music_gen_failed', 'Lyria 3 returned an empty audio payload.', {
+        backend: 'lyria3',
+      });
+    }
+
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, bytes);
+
+    // durationMs is an estimate from the request/model (MP3 duration parsing is
+    // out of scope — Lyria 3 returns audio/mpeg without a trivial header read).
+    return { path: outputPath, durationMs, backendId: 'lyria3' };
+  },
+};

package/src/video/audio-platform/registry.ts

@@ -0,0 +1,220 @@
+/**
+ * Audio-platform registry — enumerates all known MusicBackend implementations
+ * and provides availability helpers.
+ *
+ * A backend is available iff:
+ *   - every var in requiredEnv is set (non-empty) in env, AND
+ *   - (!requiresVertex || at least one of GOOGLE_CLOUD_PROJECT / VERTEX_PROJECT
+ *     / GCLOUD_PROJECT is set in env), AND
+ *   - (!requiresGeminiKey || at least one of GEMINI_API_KEYS / GOOGLE_API_KEYS
+ *     / GOOGLE_API_KEY is set in env)
+ *
+ * The Gemini-key gate (requiresGeminiKey) covers API-key Gemini products such
+ * as the Lyria 3 music backend: they declare an empty requiredEnv (no single
+ * fixed var) and resolve a key from the pool sources. Gating on the flag — not
+ * the backend id — keeps the rule decoupled from backend identity.
+ *
+ * Vertex credential liveness (ADC token validity) is NOT checked here — that
+ * would require a network call. The check is intentionally env-only so it is
+ * synchronous, pure, and testable.
+ */
+
+import { sunoBackend } from './suno-backend.js';
+import { lyriaBackend } from './native-lyria.js';
+import { lyria3Backend } from './native-lyria3.js';
+import { flowMusicBackend } from './native-flowmusic.js';
+import { geminiTts } from './native-gemini-tts.js';
+import { elevenLabsTts } from './native-elevenlabs-tts.js';
+import { elevenLabsSfx } from './native-elevenlabs-sfx.js';
+import type { MusicBackend, SfxBackend, TtsBackend } from './types.js';
+
+/** All registered music backends, in priority order. */
+export const MUSIC_BACKENDS: MusicBackend[] = [sunoBackend, lyriaBackend, lyria3Backend, flowMusicBackend];
+
+/**
+ * All registered TTS backends, in priority order. `gemini-tts` stays first (the
+ * documented default), with `elevenlabs-tts` as the Gemini-free alternative —
+ * selected explicitly via `--backend elevenlabs-tts` (or auto-picked when it is
+ * the only available backend).
+ */
+export const TTS_BACKENDS: TtsBackend[] = [geminiTts, elevenLabsTts];
+
+/**
+ * Gemini API key sources (same precedence as src/video/gemini-key-pool.ts).
+ * The gemini-tts backend is an API-key product; availability is satisfied iff
+ * at least one of these env vars is set (non-empty) in `env`.
+ */
+const GEMINI_KEY_VARS = ['GEMINI_API_KEYS', 'GOOGLE_API_KEYS', 'GOOGLE_API_KEY'] as const;
+
+const VERTEX_PROJECT_VARS = [
+  'GOOGLE_CLOUD_PROJECT',
+  'VERTEX_PROJECT',
+  'GCLOUD_PROJECT',
+] as const;
+
+/** Shared useapi.net bearer token (same var the dreamina/runway routes use). */
+const USEAPI_TOKEN_VAR = 'USEAPI_API_TOKEN';
+
+/**
+ * Returns true if the backend's runtime prerequisites are satisfied in `env`.
+ * Pure and synchronous — no network calls.
+ */
+export function isMusicBackendAvailable(
+  b: MusicBackend,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  // All declared env vars must be set and non-empty.
+  for (const varName of b.requiredEnv) {
+    const val = env[varName];
+    if (!val || val.trim() === '') return false;
+  }
+
+  // Vertex backends additionally require a project env var.
+  if (b.requiresVertex) {
+    const hasProject = VERTEX_PROJECT_VARS.some((v) => {
+      const val = env[v];
+      return val && val.trim() !== '';
+    });
+    if (!hasProject) return false;
+  }
+
+  // API-key Gemini backends (e.g. lyria3) additionally require a Gemini key
+  // from any of the pool sources. Gated on the flag, not the backend id.
+  if (b.requiresGeminiKey) {
+    const hasKey = GEMINI_KEY_VARS.some((v) => {
+      const val = env[v];
+      return val && val.trim() !== '';
+    });
+    if (!hasKey) return false;
+  }
+
+  // useapi-transport backends (e.g. flowmusic) require the shared useapi.net
+  // bearer token. Gated on the flag, not the backend id.
+  if (b.requiresUseApi) {
+    const token = env[USEAPI_TOKEN_VAR];
+    if (!token || token.trim() === '') return false;
+  }
+
+  return true;
+}
+
+/**
+ * Returns all music backends that are currently available in `env`.
+ */
+export function listAvailableMusicBackends(
+  env: NodeJS.ProcessEnv = process.env,
+): MusicBackend[] {
+  return MUSIC_BACKENDS.filter((b) => isMusicBackendAvailable(b, env));
+}
+
+/**
+ * Returns the MusicBackend with the given `id`, or throws if not found.
+ * Does NOT check availability — the caller decides whether to gate on it.
+ */
+export function getMusicBackend(id: string): MusicBackend {
+  const backend = MUSIC_BACKENDS.find((b) => b.id === id);
+  if (!backend) {
+    const known = MUSIC_BACKENDS.map((b) => b.id).join(', ');
+    throw new Error(`Unknown music backend '${id}'. Known backends: ${known}`);
+  }
+  return backend;
+}
+
+/**
+ * Returns true if the TTS backend's runtime prerequisites are satisfied in
+ * `env`. Pure and synchronous — no network calls.
+ *
+ * Backends that set `requiresGeminiKey` (e.g. gemini-tts) declare an empty
+ * requiredEnv (an API-key product, not a fixed env-var product), so
+ * availability additionally requires a Gemini key from the pool sources: at
+ * least one of GEMINI_API_KEYS / GOOGLE_API_KEYS / GOOGLE_API_KEY must be set
+ * and non-empty. Gating on the flag (not the backend id) keeps this rule
+ * decoupled from backend identity and extensible to future TTS backends.
+ */
+export function isTtsBackendAvailable(
+  b: TtsBackend,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  // All declared env vars must be set and non-empty.
+  for (const varName of b.requiredEnv) {
+    const val = env[varName];
+    if (!val || val.trim() === '') return false;
+  }
+
+  // Backends requiring a Gemini API key need one from any of the pool sources.
+  if (b.requiresGeminiKey) {
+    const hasKey = GEMINI_KEY_VARS.some((v) => {
+      const val = env[v];
+      return val && val.trim() !== '';
+    });
+    if (!hasKey) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Returns all TTS backends that are currently available in `env`.
+ */
+export function listAvailableTtsBackends(
+  env: NodeJS.ProcessEnv = process.env,
+): TtsBackend[] {
+  return TTS_BACKENDS.filter((b) => isTtsBackendAvailable(b, env));
+}
+
+/**
+ * Returns the TtsBackend with the given `id`, or throws if not found.
+ * Does NOT check availability — the caller decides whether to gate on it.
+ */
+export function getTtsBackend(id: string): TtsBackend {
+  const backend = TTS_BACKENDS.find((b) => b.id === id);
+  if (!backend) {
+    const known = TTS_BACKENDS.map((b) => b.id).join(', ');
+    throw new Error(`Unknown TTS backend '${id}'. Known backends: ${known}`);
+  }
+  return backend;
+}
+
+// ---------------------------------------------------------------------------
+// SFX registry
+// ---------------------------------------------------------------------------
+
+/** All registered SFX backends, in priority order. */
+export const SFX_BACKENDS: SfxBackend[] = [elevenLabsSfx];
+
+/**
+ * Returns true if the SFX backend's runtime prerequisites are satisfied in
+ * `env`. Pure and synchronous — no network calls.
+ */
+export function isSfxBackendAvailable(
+  b: SfxBackend,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  for (const varName of b.requiredEnv) {
+    const val = env[varName];
+    if (!val || val.trim() === '') return false;
+  }
+  return true;
+}
+
+/**
+ * Returns all SFX backends that are currently available in `env`.
+ */
+export function listAvailableSfxBackends(
+  env: NodeJS.ProcessEnv = process.env,
+): SfxBackend[] {
+  return SFX_BACKENDS.filter((b) => isSfxBackendAvailable(b, env));
+}
+
+/**
+ * Returns the SfxBackend with the given `id`, or throws if not found.
+ * Does NOT check availability — the caller decides whether to gate on it.
+ */
+export function getSfxBackend(id: string): SfxBackend {
+  const backend = SFX_BACKENDS.find((b) => b.id === id);
+  if (!backend) {
+    const known = SFX_BACKENDS.map((b) => b.id).join(', ');
+    throw new Error(`Unknown SFX backend '${id}'. Known backends: ${known}`);
+  }
+  return backend;
+}

package/src/video/audio-platform/suno-backend.ts

@@ -0,0 +1,36 @@
+/**
+ * Suno music backend — wraps the existing generateMusic() from
+ * src/video/assemble/music.ts (Kie.ai Suno provider).
+ *
+ * This backend delegates entirely to the proven assemble-layer
+ * implementation; it does NOT re-implement any transport logic.
+ * Availability: requires KIE_API_KEY in env.
+ */
+
+import { generateMusic } from '../assemble/music.js';
+import type { MusicBackend, MusicGenInput, MusicGenResult } from './types.js';
+
+export const sunoBackend: MusicBackend = {
+  id: 'suno',
+  kind: 'music',
+  displayName: 'Suno (Kie.ai)',
+  requiredEnv: ['KIE_API_KEY'],
+  summary: 'Background-music generation via Kie.ai Suno V5 (submit → poll → download). Requires KIE_API_KEY.',
+
+  async generate(input: MusicGenInput): Promise<MusicGenResult> {
+    const env = input.env ?? process.env;
+    const result = await generateMusic({
+      prompt: input.prompt,
+      durationSec: input.durationSec,
+      outputPath: input.outputPath,
+      dryRun: input.dryRun,
+      apiKey: env['KIE_API_KEY'],
+      ...(input.fetcher ? { fetcher: input.fetcher } : {}),
+    });
+    return {
+      path: result.path,
+      durationMs: result.durationMs,
+      backendId: 'suno',
+    };
+  },
+};

package/src/video/audio-platform/types.ts

@@ -0,0 +1,138 @@
+/**
+ * Audio-platform — shared types for music and TTS backends.
+ *
+ * This interface is the canonical contract for all MusicBackend
+ * implementations in videoclaw. Every backend must conform to these
+ * exact shapes; the registry enforces availability before dispatch.
+ */
+
+export type AudioBackendKind = 'music' | 'tts' | 'sfx';
+
+export interface AudioBackendDescriptor {
+  id: string;
+  kind: AudioBackendKind;
+  displayName: string;
+  requiredEnv: string[];
+  requiresVertex?: boolean;
+  /**
+   * When true, availability additionally requires a Gemini API key resolvable
+   * from the key-pool sources (GEMINI_API_KEYS / GOOGLE_API_KEYS /
+   * GOOGLE_API_KEY). This is for API-key Gemini products that declare an empty
+   * `requiredEnv` (no single fixed var). The registry gates on this flag rather
+   * than the backend id, so the availability rule stays decoupled from
+   * backend identity.
+   */
+  requiresGeminiKey?: boolean;
+  /**
+   * When true, availability additionally requires the shared useapi.net bearer
+   * token (USEAPI_API_TOKEN — the same token used by the dreamina/runway video
+   * routes). This is for useapi-transport backends (e.g. FlowMusic) that declare
+   * an empty `requiredEnv` and reuse the existing token rather than introducing a
+   * new one. The registry gates on this flag, not the backend id.
+   */
+  requiresUseApi?: boolean;
+  summary: string;
+}
+
+export interface MusicGenInput {
+  prompt: string;
+  durationSec?: number;
+  outputPath: string;
+  dryRun?: boolean;
+  fetcher?: typeof fetch;
+  env?: NodeJS.ProcessEnv;
+  /**
+   * Optional path to a reference image for image-to-music conditioning.
+   * Additive and backend-specific: the Lyria 3 (Gemini API) backend attaches it
+   * as an inlineData part; backends that don't support it (suno, Vertex lyria)
+   * ignore the field.
+   */
+  imagePath?: string;
+  /**
+   * User-supplied lyrics ([Verse]/[Chorus]-tagged). Backend-specific: the
+   * FlowMusic backend renders these as a vocal song; backends that don't support
+   * lyrics (suno, lyria, lyria3) ignore the field.
+   */
+  lyrics?: string;
+  /**
+   * Force an instrumental render. Backend-specific to FlowMusic (which otherwise
+   * decides whether to sing based on the prompt); ignored by other backends.
+   */
+  instrumental?: boolean;
+  /**
+   * Lyrics-writer version used when the MODEL writes the lyrics (FlowMusic only;
+   * ignored when explicit lyrics are supplied, and by other backends).
+   */
+  ghostwriter?: 'standard' | 'pro';
+}
+
+export interface MusicGenResult {
+  path: string;
+  durationMs: number;
+  backendId: string;
+}
+
+export interface MusicBackend extends AudioBackendDescriptor {
+  kind: 'music';
+  generate(input: MusicGenInput): Promise<MusicGenResult>;
+}
+
+export interface TtsGenInput {
+  text: string;
+  voice?: string;
+  outputPath: string;
+  dryRun?: boolean;
+  fetcher?: typeof fetch;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface TtsGenResult {
+  path: string;
+  durationMs: number;
+  backendId: string;
+}
+
+export interface TtsBackend extends AudioBackendDescriptor {
+  kind: 'tts';
+  /**
+   * File extension (no dot) the backend writes — e.g. `'wav'` for gemini-tts
+   * (PCM wrapped as WAV) or `'mp3'` for elevenlabs-tts. Callers that choose the
+   * output path (e.g. `generateNarration`) use this so the extension matches the
+   * actual bytes. Defaults to `'wav'` when absent.
+   */
+  outputExtension?: string;
+  generate(input: TtsGenInput): Promise<TtsGenResult>;
+}
+
+export interface SfxGenInput {
+  /** Natural-language description of the sound effect to generate. */
+  text: string;
+  /** Desired duration in seconds (0.5–22). Defaults to 2s when omitted. */
+  durationSec?: number;
+  /** Prompt influence (0–1, default 0.3). Controls how closely the output
+   *  follows the text vs. spontaneous model variation. */
+  promptInfluence?: number;
+  /** Absolute path the downloaded mp3 is written to. */
+  outputPath: string;
+  /** Skip all network + file I/O; return a synthetic result for dry runs. */
+  dryRun?: boolean;
+  /** Injectable fetch for offline tests; defaults to the global `fetch`. */
+  fetcher?: typeof fetch;
+  /** Override env (e.g. { ELEVENLABS_API_KEY: '...' }) for library callers
+   *  that cannot mutate process.env. */
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface SfxGenResult {
+  /** Path the audio was written to (== input.outputPath). */
+  path: string;
+  /** Duration in milliseconds. */
+  durationMs: number;
+  /** Backend id that produced the result. */
+  backendId: string;
+}
+
+export interface SfxBackend extends AudioBackendDescriptor {
+  kind: 'sfx';
+  generate(input: SfxGenInput): Promise<SfxGenResult>;
+}