@vibeframe/cli 0.27.0

package/src/commands/ai-audio.ts

@@ -0,0 +1,941 @@
+/**
+ * @module ai-audio
+ * @description Audio commands for the VibeFrame CLI.
+ *
+ * ## Commands: vibe ai transcribe, vibe ai tts, vibe ai voices, vibe ai sfx,
+ *             vibe ai isolate, vibe ai voice-clone, vibe ai music,
+ *             vibe ai music-status, vibe ai audio-restore, vibe ai dub, vibe ai duck
+ * ## Dependencies: Whisper, ElevenLabs, Replicate, FFmpeg
+ *
+ * Extracted from ai.ts as part of modularisation.
+ * ai.ts calls registerAudioCommands(aiCommand).
+ * @see MODELS.md for AI model configuration
+ */
+
+import { type Command } from 'commander';
+import { resolve, dirname, basename, extname } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import chalk from 'chalk';
+import ora from 'ora';
+import {
+  WhisperProvider,
+  ElevenLabsProvider,
+  ReplicateProvider,
+  ClaudeProvider,
+} from '@vibeframe/ai-providers';
+import { getApiKey } from '../utils/api-key.js';
+import { execSafe, execSafeSync, commandExists } from '../utils/exec-safe.js';
+import { detectFormat, formatTranscript } from '../utils/subtitle.js';
+import { formatTime } from './ai-helpers.js';
+
+function _registerAudioCommands(aiCommand: Command): void {
+
+aiCommand
+  .command("transcribe")
+  .description("Transcribe audio using Whisper")
+  .argument("<audio>", "Audio file path")
+  .option("-k, --api-key <key>", "OpenAI API key (or set OPENAI_API_KEY env)")
+  .option("-l, --language <lang>", "Language code (e.g., en, ko)")
+  .option("-o, --output <path>", "Output file path")
+  .option("-f, --format <format>", "Output format: json, srt, vtt (auto-detected from extension)")
+  .action(async (audioPath: string, options) => {
+    try {
+      const apiKey = await getApiKey("OPENAI_API_KEY", "OpenAI", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("OpenAI API key required. Set OPENAI_API_KEY in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      const spinner = ora("Initializing Whisper...").start();
+
+      const whisper = new WhisperProvider();
+      await whisper.initialize({ apiKey });
+
+      spinner.text = "Reading audio file...";
+      const absPath = resolve(process.cwd(), audioPath);
+      const audioBuffer = await readFile(absPath);
+      const audioBlob = new Blob([audioBuffer]);
+
+      spinner.text = "Transcribing...";
+      const result = await whisper.transcribe(audioBlob, options.language);
+
+      if (result.status === "failed") {
+        spinner.fail(chalk.red(`Transcription failed: ${result.error}`));
+        process.exit(1);
+      }
+
+      spinner.succeed(chalk.green("Transcription complete"));
+
+      console.log();
+      console.log(chalk.bold.cyan("Transcript"));
+      console.log(chalk.dim("─".repeat(60)));
+      console.log(result.fullText);
+      console.log();
+
+      if (result.segments && result.segments.length > 0) {
+        console.log(chalk.bold.cyan("Segments"));
+        console.log(chalk.dim("─".repeat(60)));
+        for (const seg of result.segments) {
+          const time = `[${formatTime(seg.startTime)} - ${formatTime(seg.endTime)}]`;
+          console.log(`${chalk.dim(time)} ${seg.text}`);
+        }
+        console.log();
+      }
+
+      if (options.output) {
+        const outputPath = resolve(process.cwd(), options.output);
+        const format = detectFormat(options.output, options.format);
+        const content = formatTranscript(result, format);
+        await writeFile(outputPath, content, "utf-8");
+        console.log(chalk.green(`Saved ${format.toUpperCase()} to: ${outputPath}`));
+      }
+    } catch (error) {
+      console.error(chalk.red("Transcription failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+aiCommand
+  .command("tts")
+  .description("Generate speech from text using ElevenLabs")
+  .argument("<text>", "Text to convert to speech")
+  .option("-k, --api-key <key>", "ElevenLabs API key (or set ELEVENLABS_API_KEY env)")
+  .option("-o, --output <path>", "Output audio file path", "output.mp3")
+  .option("-v, --voice <id>", "Voice ID (default: Rachel)", "21m00Tcm4TlvDq8ikWAM")
+  .option("--list-voices", "List available voices")
+  .action(async (text: string, options) => {
+    try {
+      const apiKey = await getApiKey("ELEVENLABS_API_KEY", "ElevenLabs", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("ElevenLabs API key required. Set ELEVENLABS_API_KEY in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      const elevenlabs = new ElevenLabsProvider();
+      await elevenlabs.initialize({ apiKey });
+
+      // List voices mode
+      if (options.listVoices) {
+        const spinner = ora("Fetching voices...").start();
+        const voices = await elevenlabs.getVoices();
+        spinner.succeed(chalk.green(`Found ${voices.length} voices`));
+
+        console.log();
+        console.log(chalk.bold.cyan("Available Voices"));
+        console.log(chalk.dim("─".repeat(60)));
+
+        for (const voice of voices) {
+          console.log();
+          console.log(`${chalk.bold(voice.name)} ${chalk.dim(`(${voice.voice_id})`)}`);
+          console.log(`  Category: ${voice.category}`);
+          if (voice.labels) {
+            const labels = Object.entries(voice.labels)
+              .map(([k, v]) => `${k}: ${v}`)
+              .join(", ");
+            console.log(`  ${chalk.dim(labels)}`);
+          }
+        }
+        console.log();
+        return;
+      }
+
+      const spinner = ora("Generating speech...").start();
+
+      const result = await elevenlabs.textToSpeech(text, {
+        voiceId: options.voice,
+      });
+
+      if (!result.success || !result.audioBuffer) {
+        spinner.fail(chalk.red(result.error || "TTS generation failed"));
+        process.exit(1);
+      }
+
+      const outputPath = resolve(process.cwd(), options.output);
+      await writeFile(outputPath, result.audioBuffer);
+
+      spinner.succeed(chalk.green("Speech generated"));
+      console.log();
+      console.log(chalk.dim(`Characters: ${result.characterCount}`));
+      console.log(chalk.green(`Saved to: ${outputPath}`));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red("TTS generation failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+aiCommand
+  .command("voices")
+  .description("List available ElevenLabs voices")
+  .option("-k, --api-key <key>", "ElevenLabs API key (or set ELEVENLABS_API_KEY env)")
+  .action(async (options) => {
+    try {
+      const apiKey = await getApiKey("ELEVENLABS_API_KEY", "ElevenLabs", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("ElevenLabs API key required. Set ELEVENLABS_API_KEY in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      const spinner = ora("Fetching voices...").start();
+      const elevenlabs = new ElevenLabsProvider();
+      await elevenlabs.initialize({ apiKey });
+
+      const voices = await elevenlabs.getVoices();
+      spinner.succeed(chalk.green(`Found ${voices.length} voices`));
+
+      console.log();
+      console.log(chalk.bold.cyan("Available Voices"));
+      console.log(chalk.dim("─".repeat(60)));
+
+      for (const voice of voices) {
+        console.log();
+        console.log(`${chalk.bold(voice.name)} ${chalk.dim(`(${voice.voice_id})`)}`);
+        console.log(`  Category: ${voice.category}`);
+      }
+      console.log();
+    } catch (error) {
+      console.error(chalk.red("Failed to fetch voices"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+aiCommand
+  .command("sfx")
+  .description("Generate sound effect using ElevenLabs")
+  .argument("<prompt>", "Description of the sound effect")
+  .option("-k, --api-key <key>", "ElevenLabs API key (or set ELEVENLABS_API_KEY env)")
+  .option("-o, --output <path>", "Output audio file path", "sound-effect.mp3")
+  .option("-d, --duration <seconds>", "Duration in seconds (0.5-22, default: auto)")
+  .option("--prompt-influence <value>", "Prompt influence (0-1, default: 0.3)")
+  .action(async (prompt: string, options) => {
+    try {
+      const apiKey = await getApiKey("ELEVENLABS_API_KEY", "ElevenLabs", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("ElevenLabs API key required. Set ELEVENLABS_API_KEY in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      const spinner = ora("Generating sound effect...").start();
+
+      const elevenlabs = new ElevenLabsProvider();
+      await elevenlabs.initialize({ apiKey });
+
+      const result = await elevenlabs.generateSoundEffect(prompt, {
+        duration: options.duration ? parseFloat(options.duration) : undefined,
+        promptInfluence: options.promptInfluence ? parseFloat(options.promptInfluence) : undefined,
+      });
+
+      if (!result.success || !result.audioBuffer) {
+        spinner.fail(chalk.red(result.error || "Sound effect generation failed"));
+        process.exit(1);
+      }
+
+      const outputPath = resolve(process.cwd(), options.output);
+      await writeFile(outputPath, result.audioBuffer);
+
+      spinner.succeed(chalk.green("Sound effect generated"));
+      console.log(chalk.green(`Saved to: ${outputPath}`));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red("Sound effect generation failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+aiCommand
+  .command("isolate")
+  .description("Isolate vocals from audio using ElevenLabs")
+  .argument("<audio>", "Input audio file path")
+  .option("-k, --api-key <key>", "ElevenLabs API key (or set ELEVENLABS_API_KEY env)")
+  .option("-o, --output <path>", "Output audio file path", "vocals.mp3")
+  .action(async (audioPath: string, options) => {
+    try {
+      const apiKey = await getApiKey("ELEVENLABS_API_KEY", "ElevenLabs", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("ElevenLabs API key required. Set ELEVENLABS_API_KEY in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      const spinner = ora("Reading audio file...").start();
+
+      const absPath = resolve(process.cwd(), audioPath);
+      const audioBuffer = await readFile(absPath);
+
+      spinner.text = "Isolating vocals...";
+
+      const elevenlabs = new ElevenLabsProvider();
+      await elevenlabs.initialize({ apiKey });
+
+      const result = await elevenlabs.isolateVocals(audioBuffer);
+
+      if (!result.success || !result.audioBuffer) {
+        spinner.fail(chalk.red(result.error || "Audio isolation failed"));
+        process.exit(1);
+      }
+
+      const outputPath = resolve(process.cwd(), options.output);
+      await writeFile(outputPath, result.audioBuffer);
+
+      spinner.succeed(chalk.green("Vocals isolated"));
+      console.log(chalk.green(`Saved to: ${outputPath}`));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red("Audio isolation failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+
+aiCommand
+  .command("voice-clone")
+  .description("Clone a voice from audio samples using ElevenLabs")
+  .argument("[samples...]", "Audio sample files (1-25 files)")
+  .option("-k, --api-key <key>", "ElevenLabs API key (or set ELEVENLABS_API_KEY env)")
+  .option("-n, --name <name>", "Voice name (required)")
+  .option("-d, --description <desc>", "Voice description")
+  .option("--labels <json>", "Labels as JSON (e.g., '{\"accent\": \"american\"}')")
+  .option("--remove-noise", "Remove background noise from samples")
+  .option("--list", "List all available voices")
+  .action(async (samples: string[], options) => {
+    try {
+      const apiKey = await getApiKey("ELEVENLABS_API_KEY", "ElevenLabs", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("ElevenLabs API key required. Set ELEVENLABS_API_KEY in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      const elevenlabs = new ElevenLabsProvider();
+      await elevenlabs.initialize({ apiKey });
+
+      // List voices mode
+      if (options.list) {
+        const spinner = ora("Fetching voices...").start();
+        const voices = await elevenlabs.getVoices();
+        spinner.succeed(chalk.green(`Found ${voices.length} voices`));
+
+        console.log();
+        console.log(chalk.bold.cyan("Available Voices"));
+        console.log(chalk.dim("─".repeat(60)));
+
+        for (const voice of voices) {
+          const category = chalk.dim(`(${voice.category})`);
+          console.log(`${chalk.bold(voice.name)} ${category}`);
+          console.log(`  ${chalk.dim("ID:")} ${voice.voice_id}`);
+          if (voice.labels && Object.keys(voice.labels).length > 0) {
+            console.log(`  ${chalk.dim("Labels:")} ${JSON.stringify(voice.labels)}`);
+          }
+          console.log();
+        }
+        return;
+      }
+
+      // Clone voice mode
+      if (!options.name) {
+        console.error(chalk.red("Voice name is required. Use --name <name>"));
+        process.exit(1);
+      }
+
+      if (!samples || samples.length === 0) {
+        console.error(chalk.red("At least one audio sample is required"));
+        process.exit(1);
+      }
+
+      const spinner = ora("Reading audio samples...").start();
+
+      const audioBuffers: Buffer[] = [];
+      for (const samplePath of samples) {
+        const absPath = resolve(process.cwd(), samplePath);
+        if (!existsSync(absPath)) {
+          spinner.fail(chalk.red(`File not found: ${samplePath}`));
+          process.exit(1);
+        }
+        const buffer = await readFile(absPath);
+        audioBuffers.push(buffer);
+      }
+
+      spinner.text = `Cloning voice from ${audioBuffers.length} sample(s)...`;
+
+      const labels = options.labels ? JSON.parse(options.labels) : undefined;
+
+      const result = await elevenlabs.cloneVoice(audioBuffers, {
+        name: options.name,
+        description: options.description,
+        labels,
+        removeBackgroundNoise: options.removeNoise,
+      });
+
+      if (!result.success) {
+        spinner.fail(chalk.red(result.error || "Voice cloning failed"));
+        process.exit(1);
+      }
+
+      spinner.succeed(chalk.green("Voice cloned successfully"));
+      console.log();
+      console.log(chalk.bold.cyan("Voice Details"));
+      console.log(chalk.dim("─".repeat(60)));
+      console.log(`Name: ${chalk.bold(options.name)}`);
+      console.log(`Voice ID: ${chalk.bold(result.voiceId)}`);
+      console.log();
+      console.log(chalk.dim("Use this voice ID with:"));
+      console.log(chalk.dim(`  pnpm vibe ai tts "Hello world" -v ${result.voiceId}`));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red("Voice cloning failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+aiCommand
+  .command("music")
+  .description("Generate background music from a text prompt using MusicGen")
+  .argument("<prompt>", "Description of the music to generate")
+  .option("-k, --api-key <key>", "Replicate API token (or set REPLICATE_API_TOKEN env)")
+  .option("-d, --duration <seconds>", "Duration in seconds (1-30)", "8")
+  .option("-m, --melody <file>", "Reference melody audio file for conditioning")
+  .option("--model <model>", "Model variant: large, stereo-large, melody-large, stereo-melody-large", "stereo-large")
+  .option("-o, --output <path>", "Output audio file path", "music.mp3")
+  .option("--no-wait", "Don't wait for generation to complete (async mode)")
+  .action(async (prompt: string, options) => {
+    try {
+      const apiKey = await getApiKey("REPLICATE_API_TOKEN", "Replicate", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("Replicate API token required. Set REPLICATE_API_TOKEN in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      const replicate = new ReplicateProvider();
+      await replicate.initialize({ apiKey });
+
+      const spinner = ora("Starting music generation...").start();
+
+      const duration = Math.max(1, Math.min(30, parseFloat(options.duration)));
+
+      // If melody file provided, upload it first
+      let melodyUrl: string | undefined;
+      if (options.melody) {
+        spinner.text = "Uploading melody reference...";
+        const absPath = resolve(process.cwd(), options.melody);
+        if (!existsSync(absPath)) {
+          spinner.fail(chalk.red(`Melody file not found: ${options.melody}`));
+          process.exit(1);
+        }
+        // For Replicate, we need a publicly accessible URL
+        // In practice, users would need to host the file or use a data URL
+        console.log(chalk.yellow("Note: Melody conditioning requires a publicly accessible URL"));
+        console.log(chalk.yellow("Please upload your melody file and provide the URL"));
+        process.exit(1);
+      }
+
+      const result = await replicate.generateMusic(prompt, {
+        duration,
+        model: options.model as "large" | "stereo-large" | "melody-large" | "stereo-melody-large",
+        melodyUrl,
+      });
+
+      if (!result.success || !result.taskId) {
+        spinner.fail(chalk.red(result.error || "Music generation failed"));
+        process.exit(1);
+      }
+
+      if (!options.wait) {
+        spinner.succeed(chalk.green("Music generation started"));
+        console.log();
+        console.log(`Task ID: ${chalk.bold(result.taskId)}`);
+        console.log(chalk.dim("Check status with: pnpm vibe ai music-status " + result.taskId));
+        return;
+      }
+
+      spinner.text = "Generating music (this may take a few minutes)...";
+
+      const finalResult = await replicate.waitForMusic(result.taskId);
+
+      if (!finalResult.success || !finalResult.audioUrl) {
+        spinner.fail(chalk.red(finalResult.error || "Music generation failed"));
+        process.exit(1);
+      }
+
+      spinner.text = "Downloading generated audio...";
+
+      const response = await fetch(finalResult.audioUrl);
+      if (!response.ok) {
+        spinner.fail(chalk.red("Failed to download generated audio"));
+        process.exit(1);
+      }
+
+      const audioBuffer = Buffer.from(await response.arrayBuffer());
+      const outputPath = resolve(process.cwd(), options.output);
+      await writeFile(outputPath, audioBuffer);
+
+      spinner.succeed(chalk.green("Music generated successfully"));
+      console.log();
+      console.log(`Saved to: ${chalk.bold(outputPath)}`);
+      console.log(`Duration: ${duration}s`);
+      console.log(`Model: ${options.model}`);
+      console.log();
+    } catch (error) {
+      console.error(chalk.red("Music generation failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+aiCommand
+  .command("music-status")
+  .description("Check music generation status")
+  .argument("<task-id>", "Task ID from music generation")
+  .option("-k, --api-key <key>", "Replicate API token (or set REPLICATE_API_TOKEN env)")
+  .action(async (taskId: string, options) => {
+    try {
+      const apiKey = await getApiKey("REPLICATE_API_TOKEN", "Replicate", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("Replicate API token required. Set REPLICATE_API_TOKEN in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      const replicate = new ReplicateProvider();
+      await replicate.initialize({ apiKey });
+
+      const result = await replicate.getMusicStatus(taskId);
+
+      console.log();
+      console.log(chalk.bold.cyan("Music Generation Status"));
+      console.log(chalk.dim("─".repeat(60)));
+      console.log(`Task ID: ${taskId}`);
+
+      if (result.audioUrl) {
+        console.log(`Status: ${chalk.green("completed")}`);
+        console.log(`Audio URL: ${result.audioUrl}`);
+      } else if (result.error) {
+        console.log(`Status: ${chalk.red("failed")}`);
+        console.log(`Error: ${result.error}`);
+      } else {
+        console.log(`Status: ${chalk.yellow("processing")}`);
+      }
+      console.log();
+    } catch (error) {
+      console.error(chalk.red("Failed to get music status"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+aiCommand
+  .command("audio-restore")
+  .description("Restore audio quality (denoise, enhance)")
+  .argument("<audio>", "Input audio file path")
+  .option("-k, --api-key <key>", "Replicate API token (or set REPLICATE_API_TOKEN env)")
+  .option("-o, --output <path>", "Output audio file path")
+  .option("--ffmpeg", "Use FFmpeg for restoration (free, no API needed)")
+  .option("--denoise", "Enable noise reduction (default: true)", true)
+  .option("--no-denoise", "Disable noise reduction")
+  .option("--enhance", "Enable audio enhancement")
+  .option("--noise-floor <dB>", "FFmpeg noise floor threshold", "-30")
+  .action(async (audioPath: string, options) => {
+    try {
+      const absPath = resolve(process.cwd(), audioPath);
+      if (!existsSync(absPath)) {
+        console.error(chalk.red(`File not found: ${audioPath}`));
+        process.exit(1);
+      }
+
+      // Default output path
+      const ext = extname(audioPath);
+      const baseName = basename(audioPath, ext);
+      const defaultOutput = `${baseName}-restored${ext || ".mp3"}`;
+      const outputPath = resolve(process.cwd(), options.output || defaultOutput);
+
+      // FFmpeg mode (free)
+      if (options.ffmpeg) {
+        const spinner = ora("Restoring audio with FFmpeg...").start();
+
+        try {
+          const noiseFloor = options.noiseFloor || "-30";
+
+          // Build filter chain
+          const filters: string[] = [];
+
+          if (options.denoise !== false) {
+            filters.push(`afftdn=nf=${noiseFloor}`);
+          }
+
+          if (options.enhance) {
+            filters.push("highpass=f=80");
+            filters.push("lowpass=f=12000");
+            filters.push("loudnorm=I=-16:TP=-1.5:LRA=11");
+          }
+
+          const ffmpegArgs = ["-i", absPath];
+          if (filters.length > 0) {
+            ffmpegArgs.push("-af", filters.join(","));
+          }
+          ffmpegArgs.push("-y", outputPath);
+
+          execSafeSync("ffmpeg", ffmpegArgs);
+
+          spinner.succeed(chalk.green("Audio restored with FFmpeg"));
+          console.log(`Saved to: ${chalk.bold(outputPath)}`);
+          console.log();
+        } catch (error) {
+          spinner.fail(chalk.red("FFmpeg restoration failed"));
+          if (error instanceof Error && "message" in error) {
+            console.error(chalk.dim(error.message));
+          }
+          process.exit(1);
+        }
+        return;
+      }
+
+      // Replicate AI mode
+      const apiKey = await getApiKey("REPLICATE_API_TOKEN", "Replicate", options.apiKey);
+      if (!apiKey) {
+        console.error(chalk.red("Replicate API token required. Set REPLICATE_API_TOKEN in .env or run: vibe setup"));
+        console.error(chalk.dim("Or use --ffmpeg for free FFmpeg-based restoration"));
+        process.exit(1);
+      }
+
+      const replicate = new ReplicateProvider();
+      await replicate.initialize({ apiKey });
+
+      // For Replicate, we need a publicly accessible URL
+      // This is a limitation - users need to upload their file first
+      console.log(chalk.yellow("Note: Replicate requires a publicly accessible audio URL"));
+      console.log(chalk.yellow("For local files, use --ffmpeg for free local processing"));
+      console.log();
+      console.log(chalk.dim("Example with FFmpeg:"));
+      console.log(chalk.dim(`  pnpm vibe ai audio-restore ${audioPath} --ffmpeg`));
+      process.exit(1);
+    } catch (error) {
+      console.error(chalk.red("Audio restoration failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+aiCommand
+  .command("dub")
+  .description("Dub audio/video to another language (transcribe, translate, TTS)")
+  .argument("<media>", "Input media file (video or audio)")
+  .option("-l, --language <lang>", "Target language code (e.g., es, ko, ja) (required)")
+  .option("--source <lang>", "Source language code (default: auto-detect)")
+  .option("-v, --voice <id>", "ElevenLabs voice ID for output")
+  .option("--analyze-only", "Only analyze and show timing, don't generate audio")
+  .option("-o, --output <path>", "Output file path")
+  .action(async (mediaPath: string, options) => {
+    try {
+      if (!options.language) {
+        console.error(chalk.red("Target language is required. Use -l or --language"));
+        process.exit(1);
+      }
+
+      const absPath = resolve(process.cwd(), mediaPath);
+      if (!existsSync(absPath)) {
+        console.error(chalk.red(`File not found: ${mediaPath}`));
+        process.exit(1);
+      }
+
+      // Check required API keys
+      const openaiKey = await getApiKey("OPENAI_API_KEY", "OpenAI", undefined);
+      const anthropicKey = await getApiKey("ANTHROPIC_API_KEY", "Anthropic", undefined);
+      const elevenlabsKey = await getApiKey("ELEVENLABS_API_KEY", "ElevenLabs", undefined);
+
+      if (!openaiKey) {
+        console.error(chalk.red("OpenAI API key required for transcription. Set OPENAI_API_KEY in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      if (!anthropicKey) {
+        console.error(chalk.red("Anthropic API key required for translation. Set ANTHROPIC_API_KEY in .env or run: vibe setup"));
+        process.exit(1);
+      }
+
+      if (!options.analyzeOnly && !elevenlabsKey) {
+        console.error(chalk.red("ElevenLabs API key required for TTS. Set ELEVENLABS_API_KEY in .env or run: vibe setup"));
+        console.error(chalk.dim("Or use --analyze-only to preview timing without generating audio"));
+        process.exit(1);
+      }
+
+      const spinner = ora("Extracting audio...").start();
+
+      // Check if input is video
+      const ext = extname(absPath).toLowerCase();
+      const isVideo = [".mp4", ".mov", ".avi", ".mkv", ".webm"].includes(ext);
+
+      // Step 1: Extract audio if video
+      let audioPath = absPath;
+      if (isVideo) {
+        const tempAudioPath = resolve(dirname(absPath), `temp-audio-${Date.now()}.mp3`);
+        try {
+          execSafeSync("ffmpeg", ["-i", absPath, "-vn", "-acodec", "mp3", "-y", tempAudioPath]);
+          audioPath = tempAudioPath;
+        } catch (error) {
+          spinner.fail(chalk.red("Failed to extract audio from video"));
+          process.exit(1);
+        }
+      }
+
+      // Step 2: Transcribe with Whisper
+      spinner.text = "Transcribing audio...";
+      const whisper = new WhisperProvider();
+      await whisper.initialize({ apiKey: openaiKey });
+
+      const audioBuffer = await readFile(audioPath);
+      const audioBlob = new Blob([audioBuffer]);
+
+      const transcriptResult = await whisper.transcribe(audioBlob, options.source);
+
+      if (transcriptResult.status === "failed" || !transcriptResult.segments) {
+        spinner.fail(chalk.red(`Transcription failed: ${transcriptResult.error}`));
+        process.exit(1);
+      }
+
+      // Step 3: Translate with Claude
+      spinner.text = "Translating...";
+      const claude = new ClaudeProvider();
+      await claude.initialize({ apiKey: anthropicKey });
+
+      // Build translation prompt
+      const segments = transcriptResult.segments;
+      const segmentTexts = segments.map((s, i) => `[${i}] ${s.text}`).join("\n");
+
+      // Language names for better translation context
+      const languageNames: Record<string, string> = {
+        en: "English", es: "Spanish", fr: "French", de: "German",
+        it: "Italian", pt: "Portuguese", ja: "Japanese", ko: "Korean",
+        zh: "Chinese", ar: "Arabic", ru: "Russian", hi: "Hindi",
+      };
+      const targetLangName = languageNames[options.language] || options.language;
+
+      // Use Claude's analyzeContent method to translate the segments
+      // The segments maintain their timing, we just need translated text
+      let translatedSegments: Array<{ index: number; text: string; startTime: number; endTime: number }> = [];
+
+      try {
+        // For translation, we use analyzeContent with a custom prompt
+        // This returns storyboard segments which we can adapt for translation
+        const storyboard = await claude.analyzeContent(
+          `TRANSLATE to ${targetLangName}. Return the translated text only, preserving segment numbers:\n\n${segmentTexts}`,
+          segments[segments.length - 1]?.endTime || 60
+        );
+
+        // Map storyboard results to translated segments
+        // If storyboard returned results, use descriptions as translations
+        if (storyboard && storyboard.length > 0) {
+          translatedSegments = segments.map((s, i) => ({
+            index: i,
+            text: storyboard[i]?.description || s.text,
+            startTime: s.startTime,
+            endTime: s.endTime,
+          }));
+        } else {
+          // Fallback: use original text
+          translatedSegments = segments.map((s, i) => ({
+            index: i,
+            text: s.text,
+            startTime: s.startTime,
+            endTime: s.endTime,
+          }));
+        }
+      } catch {
+        // Fallback: just show original text
+        translatedSegments = segments.map((s, i) => ({
+          index: i,
+          text: s.text,
+          startTime: s.startTime,
+          endTime: s.endTime,
+        }));
+      }
+
+      spinner.succeed(chalk.green("Transcription and translation complete"));
+
+      // Display timing analysis
+      console.log();
+      console.log(chalk.bold.cyan("Dubbing Analysis"));
+      console.log(chalk.dim("─".repeat(60)));
+      console.log(`Source language: ${transcriptResult.detectedLanguage || options.source || "auto"}`);
+      console.log(`Target language: ${targetLangName}`);
+      console.log(`Segments: ${segments.length}`);
+      console.log();
+
+      console.log(chalk.bold("Segment Timing:"));
+      for (let i = 0; i < Math.min(5, segments.length); i++) {
+        const seg = segments[i];
+        const time = `[${formatTime(seg.startTime)} - ${formatTime(seg.endTime)}]`;
+        console.log(`${chalk.dim(time)} ${seg.text}`);
+        console.log(`${chalk.dim("           →")} ${chalk.green(translatedSegments[i]?.text || seg.text)}`);
+        console.log();
+      }
+
+      if (segments.length > 5) {
+        console.log(chalk.dim(`... and ${segments.length - 5} more segments`));
+      }
+
+      if (options.analyzeOnly) {
+        console.log();
+        console.log(chalk.dim("Use without --analyze-only to generate dubbed audio"));
+
+        // Save timing to JSON if output specified
+        if (options.output) {
+          const timingPath = resolve(process.cwd(), options.output);
+          const timingData = {
+            sourcePath: absPath,
+            sourceLanguage: transcriptResult.detectedLanguage || options.source || "auto",
+            targetLanguage: options.language,
+            segments: segments.map((s, i) => ({
+              index: i,
+              startTime: s.startTime,
+              endTime: s.endTime,
+              original: s.text,
+              translated: translatedSegments[i]?.text || s.text,
+            })),
+          };
+          await writeFile(timingPath, JSON.stringify(timingData, null, 2));
+          console.log(`Timing saved to: ${chalk.bold(timingPath)}`);
+        }
+        return;
+      }
+
+      // Step 4: Generate TTS for each segment
+      spinner.start("Generating dubbed audio...");
+      const elevenlabs = new ElevenLabsProvider();
+      await elevenlabs.initialize({ apiKey: elevenlabsKey! });
+
+      const dubbedAudioBuffers: Array<{ buffer: Buffer; startTime: number }> = [];
+
+      for (let i = 0; i < translatedSegments.length; i++) {
+        spinner.text = `Generating audio segment ${i + 1}/${translatedSegments.length}...`;
+        const seg = translatedSegments[i];
+
+        const ttsResult = await elevenlabs.textToSpeech(seg.text, {
+          voiceId: options.voice,
+        });
+
+        if (ttsResult.success && ttsResult.audioBuffer) {
+          dubbedAudioBuffers.push({
+            buffer: ttsResult.audioBuffer,
+            startTime: seg.startTime,
+          });
+        }
+      }
+
+      // Step 5: Combine and save
+      spinner.text = "Combining audio...";
+
+      // For simplicity, just concatenate the audio buffers
+      // In production, you'd use FFmpeg to properly place them at timestamps
+      const combinedBuffer = Buffer.concat(dubbedAudioBuffers.map((a) => a.buffer));
+
+      const outputExt = isVideo ? ".mp3" : extname(absPath);
+      const defaultOutputPath = resolve(
+        dirname(absPath),
+        `${basename(absPath, extname(absPath))}-${options.language}${outputExt}`
+      );
+      const finalOutputPath = resolve(process.cwd(), options.output || defaultOutputPath);
+
+      await writeFile(finalOutputPath, combinedBuffer);
+
+      spinner.succeed(chalk.green("Dubbing complete"));
+      console.log();
+      console.log(`Saved to: ${chalk.bold(finalOutputPath)}`);
+      console.log();
+
+      // Clean up temp audio if we extracted from video
+      if (isVideo && audioPath !== absPath) {
+        try {
+          const { unlink } = await import("node:fs/promises");
+          await unlink(audioPath);
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red("Dubbing failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// Smart Editing Commands
+// ============================================
+
+// Audio Ducking (FFmpeg only)
+aiCommand
+  .command("duck")
+  .description("Auto-duck background music when voice is present (FFmpeg)")
+  .argument("<music>", "Background music file path")
+  .option("-v, --voice <path>", "Voice/narration track (required)")
+  .option("-o, --output <path>", "Output audio file path")
+  .option("-t, --threshold <dB>", "Sidechain threshold in dB", "-30")
+  .option("-r, --ratio <ratio>", "Compression ratio", "3")
+  .option("-a, --attack <ms>", "Attack time in ms", "20")
+  .option("-l, --release <ms>", "Release time in ms", "200")
+  .action(async (musicPath: string, options) => {
+    try {
+      if (!options.voice) {
+        console.error(chalk.red("Voice track required. Use --voice <path>"));
+        process.exit(1);
+      }
+
+      // Check FFmpeg availability
+      if (!commandExists("ffmpeg")) {
+        console.error(chalk.red("FFmpeg not found. Please install FFmpeg."));
+        process.exit(1);
+      }
+
+      const spinner = ora("Processing audio ducking...").start();
+
+      const absMusic = resolve(process.cwd(), musicPath);
+      const absVoice = resolve(process.cwd(), options.voice);
+      const outputPath = options.output
+        ? resolve(process.cwd(), options.output)
+        : absMusic.replace(/(\.[^.]+)$/, "-ducked$1");
+
+      // Convert threshold from dB to linear (0-1 scale)
+      const thresholdDb = parseFloat(options.threshold);
+      const thresholdLinear = Math.pow(10, thresholdDb / 20);
+
+      const ratio = parseFloat(options.ratio);
+      const attack = parseFloat(options.attack);
+      const release = parseFloat(options.release);
+
+      // FFmpeg sidechain compress filter
+      const filterComplex = `[0:a][1:a]sidechaincompress=threshold=${thresholdLinear}:ratio=${ratio}:attack=${attack}:release=${release}[out]`;
+
+      await execSafe("ffmpeg", ["-i", absMusic, "-i", absVoice, "-filter_complex", filterComplex, "-map", "[out]", outputPath, "-y"]);
+
+      spinner.succeed(chalk.green("Audio ducking complete"));
+      console.log();
+      console.log(chalk.dim("─".repeat(60)));
+      console.log(`Music: ${musicPath}`);
+      console.log(`Voice: ${options.voice}`);
+      console.log(`Threshold: ${thresholdDb}dB`);
+      console.log(`Ratio: ${ratio}:1`);
+      console.log(`Attack/Release: ${attack}ms / ${release}ms`);
+      console.log();
+      console.log(chalk.green(`Output: ${outputPath}`));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red("Audio ducking failed"));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+// AI Color Grading
+
+}
+
+/**
+ * Register all audio sub-commands on the given parent command.
+ * Called from ai.ts: registerAudioCommands(aiCommand)
+ */
+export function registerAudioCommands(aiCommand: Command): void {
+  _registerAudioCommands(aiCommand);
+}