videodraft 0.1.2 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # videodraft
 
-The official [VideoDraft](https://videodraft.ai) CLI — create AI videos, images, voiceovers and music from your terminal. Built for humans **and** coding agents: every command supports `--json`, exit codes are stable, async jobs are first-class.
+The official [VideoDraft](https://videodraft.ai) CLI — create AI videos, images and audio from your terminal. Built for humans **and** coding agents: every command supports `--json`, exit codes are stable, async jobs are first-class.
 
 ```bash
 npx videodraft login
@@ -30,40 +30,61 @@ export VIDEODRAFT_API_KEY=vd_mcp_…  # headless / CI — no login command neede
 
 Credentials are stored in `~/.config/videodraft/config.json` (0600). `videodraft logout` revokes and clears them.
 
-## The pipeline
+## Asset generation first
 
-```bash
-videodraft credits                              # know your budget
-videodraft create "<idea>" --ar 9:16            # idea → script → visual assets → storyboard
-videodraft shots <project> --grid --estimate    # preview the cost…
-videodraft shots <project> --grid               # …then batch-generate every shot image
-videodraft produce <project>                    # voiceovers + captions + production timeline
-videodraft export <project> --download final.mp4
-```
-
-Single assets don't need a project:
+Standalone images, clips and audio are complete deliverables. They do not need a VideoDraft project unless you want to attach them to an existing project or turn them into a multi-scene production.
 
 ```bash
 videodraft generate image "isometric workspace, warm light" --num 4 --download "./out/{job_id}_{index}.{ext}"
 videodraft generate video "slow dolly over a misty lake" --model google-veo3.1 --duration 6 --estimate
 videodraft generate voiceover "Welcome to VideoDraft" --download welcome.mp3
 videodraft generate music "minimal ambient, 60 BPM" --download bgm.mp3
+videodraft generate sound-effect "cinematic whoosh, sub hit" --duration 3 --download sfx.mp3
+videodraft generate dialogue --line "elevenlabs-kPzsL2i3teMYv0FxEYQ6:Ready?" --line "elevenlabs-s3TPKV1kjDlVtZbl4Ksh:Let's go." --download dialogue.mp3
+videodraft generate voice-changer ./speech.wav --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --duration 12 --download changed.mp3
+videodraft generate dub ./clip.mp4 --to es --duration 30 --download dubbed.mp4
 videodraft upscale image ./photo.png --scale 4x --download ./photo-4x.png
 videodraft avatar create ./founder.jpg --script "$(videodraft avatar script 'our launch' --json | jq -r .script)"
 ```
 
+Discover the full asset lane:
+
+```bash
+videodraft tools list
+videodraft tools list --lane assets
+videodraft tools list --lane asset_io
+videodraft models image
+videodraft models video
+videodraft models audio
+```
+
+Asset I/O is part of the asset workflow: `videodraft upload`, `videodraft download`, generation `--download`, and local refs like `--ref ./image.png` make files usable by agents and visible in local workspaces.
+
+## The project pipeline
+
+Use projects when the user asks for a story, storyboard, editable web project, timeline, production flow, or exported MP4.
+
+```bash
+videodraft credits                              # know your budget
+videodraft create "<idea>" --ar 9:16            # idea → script → visual assets → storyboard
+videodraft shots <project> --grid --estimate    # preview the cost…
+videodraft shots <project> --grid               # …then batch-generate every shot image
+videodraft produce <project>                    # voiceovers + captions + production timeline
+videodraft export <project> --download final.mp4
+```
+
 ## Commands
 
 | Group | Commands |
 |---|---|
 | Auth | `login` `logout` `whoami` |
-| Account | `credits` `costs [model]` `models [image\|video\|voices\|styles]` `workspaces` `sessions list/create` |
+| Account | `credits` `costs [model]` `models [image\|video\|audio\|voices\|styles]` `workspaces` `sessions list/create` |
 | Projects | `projects list/get/delete/favorite/open` `checkpoint create/list/restore` |
 | Pipeline | `create` `shots` `produce` (`--mode full_video`) `attach` `finalize` `export` `export-status` `video-prompts` |
-| Generate | `generate image/video/voiceover/music` `upscale image/video` `avatar script/create/render/get/list` |
+| Generate | `generate image/video/voiceover/music/sound-effect/dialogue/voice-changer/dub` `upscale image/video` `avatar script/create/render/get/list` |
 | Jobs | `status <job>` `wait <job>` `generations` |
 | Media | `upload <file>` `media list` `describe <url\|file>` `download <url>` |
-| Everything else | `tools list` `tools schema <name>` `call <tool> --args '<json>'` |
+| Everything else | `tools list [--lane assets\|asset_io\|project_data\|production]` `tools schema <name>` `call <tool> --args '<json>'` |
 | Agents | `skills install [--agent claude\|codex\|cursor]` `skills path` |
 | Utility | `config get/set/path` `completion bash\|zsh` `docs` `--version` |
 

package/dist/index.js

@@ -15,7 +15,7 @@ __export(version_exports, {
   VERSION: () => VERSION
 });
 import fs from "fs";
-function readVersion() {
+function readVersionFromDisk() {
   try {
     const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
     return typeof pkg.version === "string" ? pkg.version : "0.0.0";
@@ -23,11 +23,17 @@ function readVersion() {
     return "0.0.0";
   }
 }
+function resolveVersion() {
+  if ("0.2.1") {
+    return "0.2.1";
+  }
+  return readVersionFromDisk();
+}
 var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = readVersion();
+    VERSION = resolveVersion();
   }
 });
 
@@ -1068,7 +1074,12 @@ function registerAccountCommands(program) {
       ]);
     });
   });
-  program.command("costs [model]").description("Show credit costs \u2014 pass a model id plus video settings for an exact estimate").option("--type <type>", "image | video").option("--duration <seconds>", "video duration in seconds").option("--resolution <res>", 'e.g. "720p", "1080p", "1K", "2K"').option("--quality <tier>", 'e.g. "standard", "pro", "fast"').option("--rendering-speed <tier>", 'image speed/cost tier, e.g. Ideogram V4 "Turbo"/"Balanced"/"Quality"').option("--audio", "include native model audio in the estimate").option("--no-audio", "exclude native model audio").option("--num <n>", "image batch size").action(async function(model) {
+  program.command("costs [model]").description(
+    "Show credit costs \u2014 pass a model id plus settings for an exact estimate"
+  ).option("--type <type>", "image | video | audio").option("--duration <seconds>", "video/audio duration in seconds").option("--length <seconds>", "ElevenLabs Music output length in seconds").option("--chars <n>", "ElevenLabs Dialogue character count").option("--resolution <res>", 'e.g. "720p", "1080p", "1K", "2K"').option("--quality <tier>", 'e.g. "standard", "pro", "fast"').option(
+    "--rendering-speed <tier>",
+    'image speed/cost tier, e.g. Ideogram V4 "Turbo"/"Balanced"/"Quality"'
+  ).option("--audio", "include native model audio in the estimate").option("--no-audio", "exclude native model audio").option("--num <n>", "image batch size").action(async function(model) {
     const ctx = buildContext(this);
     const opts = this.opts();
     const result = await ctx.client.callTool(
@@ -1077,6 +1088,8 @@ function registerAccountCommands(program) {
         model_id: model,
         type: opts.type,
         duration_seconds: opts.duration ? Number(opts.duration) : void 0,
+        length_seconds: opts.length ? Number(opts.length) : void 0,
+        characters: opts.chars ? Number(opts.chars) : void 0,
         resolution: opts.resolution,
         quality: opts.quality,
         rendering_speed: opts.renderingSpeed,
@@ -1086,7 +1099,9 @@ function registerAccountCommands(program) {
     );
     emit(ctx.out, result);
   });
-  program.command("models [kind]").description("List available models: image | video | voices | styles (default: image + video)").action(async function(kind) {
+  program.command("models [kind]").description(
+    "List available models: image | video | audio | voices | styles (default: image + video + audio)"
+  ).action(async function(kind) {
     const ctx = buildContext(this);
     const wanted = kind ?? "all";
     const result = {};
@@ -1096,8 +1111,15 @@ function registerAccountCommands(program) {
     if (wanted === "video" || wanted === "all") {
       result.video = await ctx.client.callTool("list_available_video_models");
     }
-    if (wanted === "voices") result.voices = await ctx.client.callTool("list_available_voices");
-    if (wanted === "styles") result.styles = await ctx.client.callTool("list_available_styles");
+    if (wanted === "audio" || wanted === "all") {
+      result.audio = await ctx.client.callTool("list_available_audio_models");
+    }
+    if (wanted === "voices") {
+      result.voices = await ctx.client.callTool("list_available_voices");
+    }
+    if (wanted === "styles") {
+      result.styles = await ctx.client.callTool("list_available_styles");
+    }
     emit(ctx.out, result, (o) => {
       for (const [section, payload] of Object.entries(result)) {
         const models = Array.isArray(payload) ? payload : payload?.models ?? payload?.voices ?? payload?.styles ?? [];
@@ -1577,6 +1599,14 @@ async function uploadFile(client, localPath, options = {}) {
 
 // src/commands/generate.ts
 var URI_SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+var VIDEO_SOURCE_RE = /\.(mp4|mov|webm|m4v|gif)(?:[?#].*)?$/i;
+function inferDubMediaType(source, explicit) {
+  if (explicit) {
+    if (explicit === "audio" || explicit === "video") return explicit;
+    throw new Error('--type must be "audio" or "video"');
+  }
+  return VIDEO_SOURCE_RE.test(source) ? "video" : "audio";
+}
 async function resolveRefs(ctx, refs) {
   const resolved = [];
   for (const ref of refs) {
@@ -1669,7 +1699,7 @@ async function handleAsyncJob(ctx, submitted, options) {
   }
 }
 function registerGenerateCommands(program) {
-  const generate = program.command("generate").description("Generate images, video, voiceovers and music");
+  const generate = program.command("generate").description("Generate images, video and audio");
   generate.command("image <prompt...>").description("Generate an image (async; waits by default)").option("--model <id>", "image model id (default nano-banana-2)").option("--ar <ratio>", 'aspect ratio, e.g. "16:9"').option("--resolution <res>", 'e.g. "1K", "2K", "4K"').option("--quality <tier>", "model-specific quality tier").option("--rendering-speed <tier>", 'Ideogram speed/cost tier, e.g. V4 "Turbo"/"Balanced"/"Quality"').option("--num <n>", "variations of this prompt in one call (1-4)").option("--seed <n>", "seed (supported models only, e.g. Flux, Ideogram V4)").option("--ref <url|file>", "reference image (repeatable; local files are uploaded)", collect, []).option("--video-ref <url|file>", "video reference \u2014 nano-banana-2 only (http(s)/gs:///YouTube, or local file)").option("--style <id>", "style preset id").option("--project <id>", "attach to a project").option("--session <id>", "AI Studio session id").option("--scene <n>", "0-based scene index (with --project: writes onto that shot)").option("--shot <n>", "0-based shot index").option("--download <path>", "download outputs (template: {job_id} {index} {ext})").option("--no-wait", "submit and return the job id immediately").option("--estimate", "print the cost estimate and exit (spends nothing)").action(async function(promptWords) {
     const ctx = buildContext(this);
     const opts = this.opts();
@@ -1716,7 +1746,10 @@ function registerGenerateCommands(program) {
       label: "Generating image"
     });
   });
-  generate.command("video [prompt...]").description("Generate a video clip (async; per-second pricing \u2014 see --estimate)").option("--model <id>", "video model id (default google-veo3.1 fast)").option("--ar <ratio>", 'aspect ratio, e.g. "16:9", "9:16"').option("--duration <seconds>", "clip duration in seconds").option("--resolution <res>", 'e.g. "720p", "1080p"').option("--quality <tier>", 'e.g. "fast", "quality", "standard", "pro"').option("--audio", "generate native model audio").option("--no-audio", "disable native model audio").option("--start-image <url|file>", "start frame (image-to-video)").option("--end-image <url|file>", "end frame (supported models only)").option("--ref <url|file>", "reference image (repeatable)", collect, []).option("--ref-video <url|file>", "reference video (repeatable; Seedance 2, Wan 2.7; local files uploaded)", collect, []).option("--ref-audio <url|file>", "reference audio (repeatable; Seedance 2; local files uploaded)", collect, []).option("--segment <prompt:seconds>", "multi-prompt segment (repeatable; Kling 3.0 / 3.0 Turbo / O3)", collect, []).option("--negative <text>", "negative prompt (Kling/Wan/Luma)").option("--seed <n>", "seed").option("--project <id>", "attach to a project").option("--session <id>", "AI Studio session id").option("--scene <n>", "0-based scene index").option("--shot <n>", "0-based shot index").option("--download <path>", "download outputs (template: {job_id} {index} {ext})").option("--no-wait", "submit and return the job id immediately").option("--estimate", "print the cost estimate and exit (spends nothing)").action(async function(promptWords = []) {
+  generate.command("video [prompt...]").description("Generate a video clip (async; per-second pricing \u2014 see --estimate)").option("--model <id>", "video model id (default google-veo3.1 fast)").option("--ar <ratio>", 'aspect ratio, e.g. "16:9", "9:16"').option("--duration <seconds>", "clip duration in seconds").option("--resolution <res>", 'e.g. "480p", "720p", "1080p", "4k"').option(
+    "--quality <tier>",
+    'e.g. "mini", "fast", "standard", "quality", "pro"'
+  ).option("--audio", "generate native model audio").option("--no-audio", "disable native model audio").option("--start-image <url|file>", "start frame (image-to-video)").option("--end-image <url|file>", "end frame (supported models only)").option("--ref <url|file>", "reference image (repeatable)", collect, []).option("--ref-video <url|file>", "reference video (repeatable; Seedance 2, Wan 2.7; local files uploaded)", collect, []).option("--ref-audio <url|file>", "reference audio (repeatable; Seedance 2; local files uploaded)", collect, []).option("--segment <prompt:seconds>", "multi-prompt segment (repeatable; Kling 3.0 / 3.0 Turbo / O3)", collect, []).option("--negative <text>", "negative prompt (Kling/Wan/Luma)").option("--seed <n>", "seed").option("--project <id>", "attach to a project").option("--session <id>", "AI Studio session id").option("--scene <n>", "0-based scene index").option("--shot <n>", "0-based shot index").option("--download <path>", "download outputs (template: {job_id} {index} {ext})").option("--no-wait", "submit and return the job id immediately").option("--estimate", "print the cost estimate and exit (spends nothing)").action(async function(promptWords = []) {
     const ctx = buildContext(this);
     const opts = this.opts();
     const prompt = promptWords.join(" ").trim();
@@ -1804,16 +1837,19 @@ function registerGenerateCommands(program) {
       for (const f of downloaded ?? []) note(o, fmt.dim(o, `saved ${f.path}`));
     });
   });
-  generate.command("music <prompt...>").description("Generate background music (Lyria 3)").option("--model <id>", "lyria-3-clip-preview (30s, default) | lyria-3-pro-preview (180s)").option("--ref <url|file>", "reference image to inspire the music (repeatable)", collect, []).option("--project <id>", "link the generation to a project's AI Studio session").option("--attach <project_id>", "also set the track as that project's background music").option("--volume <n>", "0-100 BGM volume when attaching (default 30)").option("--bgm-disabled", "when attaching, store the BGM as disabled (enabled:false)").option("--session <id>", "AI Studio session id").option("--download <path>", "download the audio file").action(async function(promptWords) {
+  generate.command("music <prompt...>").description("Generate background music").option("--model <id>", "lyria-3-clip-preview (default) | lyria-3-pro-preview | elevenlabs-music").option("--length <seconds>", "for --model elevenlabs-music: length 10\u2013120s (default 30)").option("--instrumental", "for --model elevenlabs-music: force instrumental (no vocals)").option("--ref <url|file>", "reference image to inspire the music (Lyria only, repeatable)", collect, []).option("--project <id>", "link the generation to a project's AI Studio session").option("--attach <project_id>", "also set the track as that project's background music").option("--volume <n>", "0-100 BGM volume when attaching (default 30)").option("--bgm-disabled", "when attaching, store the BGM as disabled (enabled:false)").option("--session <id>", "AI Studio session id").option("--download <path>", "download the audio file").action(async function(promptWords) {
     const ctx = buildContext(this);
     const opts = this.opts();
-    const refs = await resolveRefs(ctx, opts.ref ?? []);
-    capture("cli_generate", { kind: "music", model: opts.model ?? "default" });
+    const musicModel = opts.model ?? "lyria-3-clip-preview";
+    const refs = musicModel === "elevenlabs-music" ? [] : await resolveRefs(ctx, opts.ref ?? []);
+    capture("cli_generate", { kind: "music", model: musicModel });
     const result = await ctx.client.callTool(
       "generate_music",
       compact({
         prompt: promptWords.join(" "),
-        model: opts.model,
+        model: musicModel,
+        length_seconds: opts.length ? Number(opts.length) : void 0,
+        force_instrumental: opts.instrumental ? true : void 0,
         image_urls: refs.length > 0 ? refs : void 0,
         project_id: opts.project,
         attach_to_project_id: opts.attach,
@@ -1834,6 +1870,173 @@ function registerGenerateCommands(program) {
       for (const f of downloaded ?? []) note(o, fmt.dim(o, `saved ${f.path}`));
     });
   });
+  generate.command("sound-effect <prompt...>").description("Generate a sound effect (ElevenLabs Sound Effects)").option("--duration <seconds>", "length 0.5\u201322s (default 5)").option("--influence <0-1>", "prompt influence (default 0.3)").option("--project <id>", "link to a project's AI Studio session").option("--session <id>", "AI Studio session id").option("--download <path>", "download the audio file").action(async function(promptWords) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    capture("cli_generate", { kind: "sound_effect" });
+    const result = await ctx.client.callTool(
+      "generate_sound_effect",
+      compact({
+        prompt: promptWords.join(" "),
+        duration_seconds: opts.duration ? Number(opts.duration) : void 0,
+        prompt_influence: opts.influence ? Number(opts.influence) : void 0,
+        project_id: opts.project,
+        session_id: opts.session
+      })
+    );
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "sound-effect"
+      });
+    }
+    const media = buildMediaDescriptors(urls, "audio");
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, `saved ${f.path}`));
+      }
+    );
+  });
+  generate.command("dialogue").description(
+    "Generate multi-speaker dialogue (ElevenLabs Text-to-Dialogue). Repeat --line."
+  ).option(
+    "--line <voiceId:text>",
+    'a dialogue line as "voiceId:text" (repeatable)',
+    collect,
+    []
+  ).option("--stability <0|0.5|1>", "voice stability").option("--language <iso>", "ISO 639-1 language code").option("--project <id>", "link to a project's AI Studio session").option("--session <id>", "AI Studio session id").option("--download <path>", "download the audio file").action(async function() {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    const lines = opts.line.map((raw) => {
+      const i = raw.indexOf(":");
+      if (i < 0) {
+        throw new Error(`--line must be "voiceId:text" (got "${raw}")`);
+      }
+      return { voice_id: raw.slice(0, i).trim(), text: raw.slice(i + 1).trim() };
+    });
+    if (lines.length === 0) throw new Error("at least one --line is required");
+    capture("cli_generate", { kind: "dialogue" });
+    const result = await ctx.client.callTool(
+      "generate_dialogue",
+      compact({
+        lines,
+        stability: opts.stability !== void 0 ? Number(opts.stability) : void 0,
+        language_code: opts.language,
+        project_id: opts.project,
+        session_id: opts.session
+      })
+    );
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "dialogue"
+      });
+    }
+    const media = buildMediaDescriptors(urls, "audio");
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, `saved ${f.path}`));
+      }
+    );
+  });
+  generate.command("voice-changer <audio>").description("Restyle speech into another ElevenLabs voice (Voice Changer)").option("--voice <id>", "target ElevenLabs voice id (default Brittney)").option(
+    "--duration <seconds>",
+    "length of the source audio in seconds (required, max 300)"
+  ).option("--remove-noise", "remove background noise from the input").option("--project <id>", "link to a project's AI Studio session").option("--session <id>", "AI Studio session id").option("--download <path>", "download the audio file").action(async function(source) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    if (!opts.duration) {
+      throw new Error(
+        "--duration <seconds> is required (length of the source audio)"
+      );
+    }
+    const [audioUrl] = await resolveRefs(ctx, [source]);
+    capture("cli_generate", { kind: "voice_changer" });
+    const result = await ctx.client.callTool(
+      "change_voice",
+      compact({
+        audio_url: audioUrl,
+        voice_id: opts.voice,
+        duration_seconds: Number(opts.duration),
+        remove_background_noise: opts.removeNoise ? true : void 0,
+        project_id: opts.project,
+        session_id: opts.session
+      })
+    );
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "voice-changed"
+      });
+    }
+    const media = buildMediaDescriptors(urls, "audio");
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, `saved ${f.path}`));
+      }
+    );
+  });
+  generate.command("dub <media>").description("Dub a video/audio file into another language (ElevenLabs Dubbing)").option("--to <iso>", "target language ISO 639-1 code, e.g. es or te (required)").option("--from <iso>", "source language ISO 639-1 code (auto-detected if omitted)").option("--type <audio|video>", "source media type override").option(
+    "--duration <seconds>",
+    "length of the source media in seconds (required, max 300)"
+  ).option("--speakers <n>", "number of speakers (auto-detected if omitted)").option("--project <id>", "link to a project's AI Studio session").option("--session <id>", "AI Studio session id").option("--download <path>", "download the dubbed file").action(async function(source) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    if (!opts.to) throw new Error("--to <iso> (target language) is required");
+    if (!opts.duration) {
+      throw new Error(
+        "--duration <seconds> is required (length of the source media)"
+      );
+    }
+    const mediaType = inferDubMediaType(source, opts.type);
+    const [mediaUrl] = await resolveRefs(ctx, [source]);
+    capture("cli_generate", { kind: "dub" });
+    const result = await ctx.client.callTool(
+      "dub_media",
+      compact({
+        video_url: mediaType === "video" ? mediaUrl : void 0,
+        audio_url: mediaType === "audio" ? mediaUrl : void 0,
+        target_lang: opts.to,
+        source_lang: opts.from,
+        num_speakers: opts.speakers ? Number(opts.speakers) : void 0,
+        duration_seconds: Number(opts.duration),
+        project_id: opts.project,
+        session_id: opts.session
+      })
+    );
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "dubbed"
+      });
+    }
+    const media = buildMediaDescriptors(urls, mediaType);
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, `saved ${f.path}`));
+      }
+    );
+  });
   const upscale = program.command("upscale").description("Upscale images and videos (Topaz)");
   upscale.command("image <url|file>").description("Upscale an image (synchronous)").option("--scale <factor>", '"1x" | "2x" | "4x" (default 2x)').option("--session <id>", "AI Studio session id").option("--download <path>", "download the result").action(async function(source) {
     const ctx = buildContext(this);
@@ -2257,7 +2460,7 @@ function registerJobCommands(program) {
       throw err;
     }
   });
-  program.command("generations").description("List recent + in-flight generations").option("--type <type>", "image | video").option("--status <status>", "pending | processing | completed | failed").option("--limit <n>", "max rows (default 30)").action(async function() {
+  program.command("generations").description("List recent + in-flight generations").option("--type <type>", "image | video | sounds").option("--status <status>", "pending | processing | completed | failed").option("--limit <n>", "max rows (default 30)").action(async function() {
     const ctx = buildContext(this);
     const opts = this.opts();
     const result = await ctx.client.callTool(
@@ -2373,19 +2576,97 @@ function parseKeyValueArgs(pairs) {
   }
   return args;
 }
+var CATEGORY_ORDER = [
+  "asset_generation",
+  "asset_io",
+  "asset_library",
+  "project_creation",
+  "project_data",
+  "production",
+  "account_models_costs",
+  "jobs",
+  "danger_zone",
+  "raw"
+];
+var LANE_ORDER = [
+  "assets",
+  "asset_io",
+  "projects",
+  "project_data",
+  "production",
+  "library",
+  "account",
+  "danger",
+  "raw"
+];
+function firstSentence(description) {
+  return description.split(/[.!]\s/)[0].slice(0, 90);
+}
 function registerToolCommands(program) {
   const tools = program.command("tools").description("Inspect the full MCP tool catalog");
-  tools.command("list", { isDefault: true }).description("List every available tool").action(async function() {
+  tools.command("list", { isDefault: true }).description("List the grouped VideoDraft tool catalog").option(
+    "--lane <lane>",
+    "filter by lane: assets | asset_io | projects | project_data | production | library | account | danger | raw"
+  ).option(
+    "--category <category>",
+    "filter by category, e.g. asset_generation, asset_io, project_data, or production"
+  ).action(async function() {
     const ctx = buildContext(this);
-    const list = await ctx.client.listTools();
-    emit(ctx.out, list.map((t) => ({ name: t.name, description: t.description })), (o) => {
-      table(
+    const opts = this.opts();
+    if (opts.lane && !LANE_ORDER.includes(opts.lane)) {
+      throw new CliError(
+        `Unknown lane "${opts.lane}". Expected one of: ${LANE_ORDER.join(", ")}`,
+        EXIT.USAGE
+      );
+    }
+    if (opts.category && !CATEGORY_ORDER.includes(opts.category)) {
+      throw new CliError(
+        `Unknown category "${opts.category}". Expected one of: ${CATEGORY_ORDER.join(", ")}`,
+        EXIT.USAGE
+      );
+    }
+    let summary;
+    const catalog = await ctx.client.callTool(
+      "get_tool_catalog",
+      compact({ lane: opts.lane, category: opts.category })
+    );
+    summary = catalog?.tools ?? [];
+    emit(ctx.out, summary, (o) => {
+      const categories = Array.from(
+        new Set(summary.map((tool) => tool.category))
+      ).sort((a, b) => {
+        const ai = CATEGORY_ORDER.indexOf(a);
+        const bi = CATEGORY_ORDER.indexOf(b);
+        return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi) || a.localeCompare(b);
+      });
+      if (categories.length === 0) {
+        table(o, ["name", "type", "risk", "description"], []);
+      }
+      for (const category of categories) {
+        const rows = summary.filter((tool) => tool.category === category);
+        process.stdout.write(`
+${fmt.bold(o, category)}
+`);
+        table(
+          o,
+          ["name", "type", "risk", "description"],
+          rows.map((tool) => [
+            tool.name,
+            tool.subcategory ?? "",
+            tool.risks.join(","),
+            firstSentence(tool.description)
+          ])
+        );
+      }
+      const suffix = opts.lane ? ` in lane "${opts.lane}"` : opts.category ? ` in category "${opts.category}"` : "";
+      note(
         o,
-        ["name", "description"],
-        list.map((t) => [t.name, t.description.split(/[.!]\s/)[0].slice(0, 90)])
+        fmt.dim(
+          o,
+          `
+${summary.length} tools${suffix}. Inspect one: videodraft tools schema <name>`
+        )
       );
-      note(o, fmt.dim(o, `
-${list.length} tools. Inspect one: videodraft tools schema <name>`));
     });
   });
   tools.command("schema <name>").description("Show a tool's description and JSON input schema").action(async function(name) {
@@ -2787,7 +3068,7 @@ async function configureProxy() {
 function buildProgram() {
   const program = new Command();
   program.name("videodraft").description(
-    "Create AI videos, images, voiceovers and music from your terminal.\nAgent-friendly: every command supports --json; exit codes are stable\n(0 ok, 1 error, 2 usage, 3 auth, 4 insufficient credits)."
+    "Create AI videos, images and audio from your terminal.\nAgent-friendly: every command supports --json; exit codes are stable\n(0 ok, 1 error, 2 usage, 3 auth, 4 insufficient credits)."
   ).version(VERSION, "-v, --version", "print the CLI version").option("--json", "machine-readable JSON output").option("--no-color", "disable colored output (NO_COLOR is also respected)").option("--base-url <url>", "VideoDraft server (default https://app.videodraft.ai; env VIDEODRAFT_BASE_URL)").option("--token <vd_mcp_token>", "bearer token for this invocation (env VIDEODRAFT_API_KEY)").option("--profile <name>", "config profile (default: default)").option("--wait-interval <duration>", "poll interval for --wait, e.g. 3s (default)").option("--wait-timeout <duration>", "max wait for --wait, e.g. 10m (default)").showSuggestionAfterError(true).exitOverride();
   registerAuthCommands(program);
   registerAccountCommands(program);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "videodraft",
-  "version": "0.1.2",
-  "description": "Official VideoDraft CLI — create AI videos, images, voiceovers and music from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
+  "version": "0.2.1",
+  "description": "Official VideoDraft CLI — create AI videos, images and audio from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
   "license": "MIT",
   "type": "module",
   "homepage": "https://videodraft.ai/cli",

package/skills/videodraft/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: videodraft
-description: Create AI videos, images, voiceovers, music, storyboards, avatar videos and product/ad videos with VideoDraft. Use when the user mentions VideoDraft, or asks to generate/make a video, video ad, explainer, storyboard, talking-head/avatar video, AI image, voiceover/TTS, or background music — including batch/programmatic video generation in scripts or CI. Works via the `videodraft` CLI (preferred in terminals) or the VideoDraft MCP connector.
-license: MIT
-metadata:
-  author: VideoDraft (videodraft.ai)
-  homepage: https://videodraft.ai/cli
+description: Create AI videos, images, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos and product/ad videos with VideoDraft. Use when the user mentions VideoDraft, or asks to generate/make a video, video ad, explainer, storyboard, talking-head/avatar video, AI image, voiceover/TTS, background music, sound effects, dialogue audio, voice changing, or dubbing — including batch/programmatic video generation in scripts or CI. Works via the `videodraft` CLI (preferred in terminals) or the VideoDraft MCP connector.
 ---
 
 # VideoDraft
 
-VideoDraft is an AI video creation platform: idea → script → storyboard (scenes + shot images) → production (voiceover, captions, motion clips, music) → exported MP4. You can drive all of it from this environment.
+VideoDraft is an AI video creation platform where asset generation is the priority lane:
+
+- **Asset generation**: standalone images, video clips, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.
+- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.
+- **Project production**: idea → script → storyboard (scenes + shot images) → project data → production timeline → exported MP4. Use this only when the user asks for a story, storyboard, editable project, timeline, or final video.
 
 ## How to connect
 
@@ -21,15 +21,18 @@ Two equivalent surfaces (same backend, same credits, same projects):
      • HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).
      • SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat — use browser `login` or the env var so the token never lands in the transcript.
    - Every command accepts `--json` (parse this, don't scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (→ tell the user, don't retry).
-   - Full API access: `videodraft tools list`, `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
+   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.
+   - Asset lane: `videodraft generate image|video|voiceover|music|sound-effect|dialogue|voice-changer|dub`, `videodraft upload`, and `videodraft download`.
+   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
 2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly — the CLI's curated commands map 1:1 onto these tools.
 
-## First decision: asset or video?
+## First decision: asset or project?
 
-- **One standalone asset** (a single image, clip, voiceover, or music track, no story): generate it directly. Do NOT create a project.
+- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.
   - `videodraft generate image "a red fox in snow, cinematic" --ar 16:9 --download ./out/`
   - `videodraft generate video "slow dolly over a misty lake" --model google-veo3.1 --duration 6 --download ./out/`
-- **A video / ad / explainer / anything multi-scene**: create a project so the work stays organized, editable in the web app, and exportable.
+- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations, but do not make a storyboard/project unless the user asks for one.
+- **A multi-scene video / ad / explainer, storyboard, timeline, or final exported video**: create a project so the work stays organized, editable in the web app, and exportable.
   - `videodraft create "30s launch video for our espresso machine" --ar 9:16`
 - **Just a script** (no video asked for): `videodraft create "..." --script-only`. Stop at the script — do not build a storyboard the user didn't ask for.
 - **Iterating on existing work**: find it first (`videodraft projects list`) and reuse that project. Never create a new project to change an existing one.
@@ -39,10 +42,10 @@ Two equivalent surfaces (same backend, same credits, same projects):
 Generation costs credits (video is per-second; shot-image batches are the largest single spend). Before anything expensive:
 
 1. `videodraft credits` — check the balance.
-2. `videodraft generate video "..." --estimate` or `videodraft costs <model> --duration 8 --resolution 1080p` — get the quote.
+2. `videodraft generate video "..." --estimate` or `videodraft costs <model> --duration 8 --resolution 1080p` — get the quote. For ElevenLabs audio, use `--type audio` plus `--duration`, `--length`, or `--chars`.
 3. Tell the user the model + settings + rough cost and get a go-ahead. Ask rather than assume aspect ratio, duration, and model when they matter.
 
-`videodraft models image|video` lists every model with its supported inputs (aspect ratios, resolutions, reference limits) — consult it instead of guessing capabilities.
+`videodraft models image|video|audio` lists every model with its supported inputs (aspect ratios, resolutions, reference limits, audio billing inputs) — consult it instead of guessing capabilities.
 
 ## Async jobs
 
@@ -80,7 +83,7 @@ videodraft produce <project_id>                 # voiceovers + captions + produc
 videodraft export <project_id> --download final.mp4
 ```
 
-Optional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), and music (`videodraft generate music "..." --attach <project_id>`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).
+Optional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music "..." --attach <project_id>`), and standalone audio assets (`generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).
 
 Avatar/talking-head videos are their own short flow: `videodraft avatar script` → `avatar create` → `avatar render` (paid step).
 

package/skills/videodraft/references/models.md

@@ -5,6 +5,7 @@ Always consult the live catalog instead of memorizing this page — models chang
 ```bash
 videodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)
 videodraft models video --json     # every video model + inputs + per-second pricing metadata
+videodraft models audio --json     # standalone audio/media models + pricing inputs
 videodraft models voices --json    # TTS voices
 videodraft models styles --json    # visual style presets
 ```
@@ -14,7 +15,8 @@ videodraft models styles --json    # visual style presets
 - **Image**: `nano-banana-2` (the platform default, 1K). Use `--num 1..4` for variations of one prompt in a single call — never loop for variations.
 - **Video**: `google-veo3.1` at fast quality (6s / 720p) — the platform default.
 - **Voiceover**: ElevenLabs Brittney (default voice).
-- **Music**: `lyria-3-clip-preview` (30s, cheap); `lyria-3-pro-preview` for 180s/quality.
+- **Music**: `lyria-3-clip-preview` (30s, cheap); `lyria-3-pro-preview` for 180s/quality; `elevenlabs-music` for music that can include vocals/lyrics.
+- **ElevenLabs audio**: `generate sound-effect`, `generate dialogue`, `generate voice-changer`, and `generate dub` are synchronous audio/media calls. Voice changer and dubbing require the source media duration in seconds for billing and currently accept source media up to 300s.
 
 ## Capability gotchas
 
@@ -32,12 +34,15 @@ videodraft models styles --json    # visual style presets
 - Video: usually credits/second × duration; rate depends on model + resolution + quality + native audio on/off.
 - Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) — the largest single spend in the pipeline.
 - Avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p.
+- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. Voice changer and dubbing reject source media above 300s in the current synchronous flow.
 - Upscales: priced by scale and source size.
 
 Quote before spending:
 
 ```bash
 videodraft costs google-veo3.1 --type video --duration 8 --resolution 1080p --audio
+videodraft costs elevenlabs-dubbing --type audio --duration 60
+videodraft costs elevenlabs-dialogue --type audio --chars 350
 videodraft generate video "..." --estimate        # same quote, inline
 videodraft credits                                 # current balance
 ```

package/skills/videodraft/references/pipeline.md

@@ -16,6 +16,10 @@ Everything here works through the CLI (`videodraft <command>` / `videodraft call
 | Motion clip for a shot | `videodraft generate video --project <id>` | `generate_video` |
 | Attach a finished clip to the timeline | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot` |
 | Background music | `videodraft generate music --attach <project>` | `generate_music` / `set_background_music` |
+| Sound effect | `videodraft generate sound-effect "..."` | `generate_sound_effect` |
+| Dialogue audio | `videodraft generate dialogue --line "voice:text"` | `generate_dialogue` |
+| Voice changer | `videodraft generate voice-changer <audio>` | `change_voice` |
+| Dubbing | `videodraft generate dub <audio_or_video>` | `dub_media` |
 | Scene voiceover | `videodraft generate voiceover --project <id> --scene N` | `generate_voiceover` |
 | Final MP4 | `videodraft export <project>` | `export_video` + `check_export_status` |