videodraft 0.4.1 → 0.6.0

package/README.md

@@ -37,6 +37,8 @@ Standalone images, clips and audio are complete deliverables. They do not need a
 ```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 audio "Read this in a calm documentary voice" --voice vivi_mixed_en_zh_ja_es_id --download narration.mp3
+videodraft generate audio "Extend @Audio1 with soft rain" --ref-audio ./opening.wav --download extended.wav --format wav
 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
@@ -50,6 +52,17 @@ videodraft edit motion ./character.png "Apply the reference dance" --motion-vide
 videodraft generate video "Match this performance" --model kling-o3-video-ref-edit --ref-video ./performance.mp4 --ref ./wardrobe.png --download ./guided.mp4
 ```
 
+`generate audio` automatically retries transient and lost responses with one
+stable operation key. To recover after stopping or losing the CLI process, set
+your own UUID up front and reuse it if needed:
+
+```bash
+videodraft generate audio "..." --idempotency-key "$(uuidgen)"
+```
+
+The server then returns the existing result or in-progress operation without
+generating or charging twice.
+
 Discover the full asset lane:
 
 ```bash
@@ -79,18 +92,18 @@ videodraft export <project> --download final.mp4
 
 ## Commands
 
-| Group           | Commands                                                                                                                                                                       |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Auth            | `login` `logout` `whoami`                                                                                                                                                      |
-| 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/sound-effect/dialogue/voice-changer/dub` `edit video/motion` `upscale image/video` `avatar script/create/render/get/list/fabric/lipsync` |
-| Jobs            | `status <job>` `wait <job>` `generations`                                                                                                                                      |
-| Media           | `upload <file>` `media list` `describe <url\|file>` `download <url>`                                                                                                           |
-| 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`                                                                                                                |
+| Group           | Commands                                                                                                                                                                             |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Auth            | `login` `logout` `whoami`                                                                                                                                                            |
+| 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/audio/voiceover/music/sound-effect/dialogue/voice-changer/dub` `edit video/motion` `upscale image/video` `avatar script/create/render/get/list/fabric/lipsync` |
+| Jobs            | `status <job>` `wait <job>` `generations`                                                                                                                                            |
+| Media           | `upload <file>` `media list` `describe <url\|file>` `download <url>`                                                                                                                 |
+| 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`                                                                                                                      |
 
 `call` reaches **every** VideoDraft API tool (the full MCP catalog), including ones without a curated command — new platform features work in the CLI the day they ship.
 

package/dist/client.d.ts

@@ -217,6 +217,12 @@ interface DownloadedFile {
     url: string;
     path: string;
     bytes: number;
+    /** Downscaled view copy in <dir>/previews/ (images over the size threshold
+     *  only). Agents should inspect this instead of the full-res original —
+     *  every full-res image an agent views is re-sent with each later message
+     *  of its chat. Best-effort: absent when preview generation failed or was
+     *  skipped. The original at `path` is always the deliverable. */
+    preview?: string;
 }
 declare function extFromUrl(url: string, fallback?: string): string;
 declare function renderTemplate(template: string, vars: {

package/dist/client.js

@@ -818,10 +818,136 @@ async function pollGenerations(client, jobIds, options = {}) {
 }
 
 // src/core/download.ts
+import { execFile } from "child_process";
 import fs2 from "fs";
 import path2 from "path";
 import { pipeline } from "stream/promises";
+import { promisify } from "util";
 import { Readable } from "stream";
+var execFileAsync = promisify(execFile);
+var PREVIEW_SOURCE_RE = /\.(png|jpe?g|webp|tiff?)$/i;
+var PREVIEW_SKIP_BYTES = 500 * 1024;
+var PREVIEW_MAX_DIM = 1536;
+var PREVIEW_JPEG_QUALITY = 85;
+var PREVIEW_CDN_WIDTH = 1080;
+var PREVIEW_EXTS = ["jpg", "webp", "png"];
+function previewPathFor(originalPath, ext = "jpg") {
+  return path2.join(
+    path2.dirname(originalPath),
+    "previews",
+    `${path2.basename(originalPath)}.${ext}`
+  );
+}
+function invalidatePreviews(originalPath) {
+  for (const ext of PREVIEW_EXTS) {
+    try {
+      fs2.rmSync(previewPathFor(originalPath, ext), { force: true });
+    } catch {
+    }
+  }
+}
+function shouldWritePreview(originalPath, bytes) {
+  return PREVIEW_SOURCE_RE.test(originalPath) && bytes >= PREVIEW_SKIP_BYTES;
+}
+function tempPreviewPath(previewPath) {
+  return `${previewPath}.tmp-${process.pid}`;
+}
+function commitPreview(tmpPath, previewPath) {
+  try {
+    if (fs2.existsSync(tmpPath) && fs2.statSync(tmpPath).size > 0) {
+      fs2.renameSync(tmpPath, previewPath);
+      return true;
+    }
+  } catch {
+  }
+  fs2.rmSync(tmpPath, { force: true });
+  return false;
+}
+async function writePreviewWithSips(originalPath, previewPath) {
+  if (process.platform !== "darwin") return false;
+  const tmp = tempPreviewPath(previewPath);
+  try {
+    await execFileAsync(
+      "sips",
+      [
+        "-Z",
+        String(PREVIEW_MAX_DIM),
+        "-s",
+        "format",
+        "jpeg",
+        "-s",
+        "formatOptions",
+        String(PREVIEW_JPEG_QUALITY),
+        originalPath,
+        "--out",
+        tmp
+      ],
+      { timeout: 1e4 }
+    );
+  } catch {
+    fs2.rmSync(tmp, { force: true });
+    return false;
+  }
+  return commitPreview(tmp, previewPath);
+}
+var cdnPreviewConsecutiveFailures = 0;
+var PREVIEW_CDN_MAX_CONSECUTIVE_FAILURES = 2;
+var PREVIEW_CDN_TIMEOUT_MS = 1e4;
+async function writePreviewFromCdn(sourceUrl, originalPath, fetchImpl) {
+  let host;
+  try {
+    host = new URL(sourceUrl).hostname;
+  } catch {
+    return void 0;
+  }
+  if (host !== "cdn.videodraft.ai") return void 0;
+  if (cdnPreviewConsecutiveFailures >= PREVIEW_CDN_MAX_CONSECUTIVE_FAILURES) return void 0;
+  const variant = `${DEFAULT_BASE_URL}/_next/image?url=${encodeURIComponent(sourceUrl)}&w=${PREVIEW_CDN_WIDTH}&q=75`;
+  let res;
+  try {
+    res = await fetchImpl(variant, {
+      headers: { Accept: "image/webp,image/jpeg,image/*" },
+      signal: AbortSignal.timeout(PREVIEW_CDN_TIMEOUT_MS)
+    });
+  } catch (err) {
+    cdnPreviewConsecutiveFailures++;
+    throw err;
+  }
+  if (!res.ok || !res.body) {
+    cdnPreviewConsecutiveFailures++;
+    return void 0;
+  }
+  cdnPreviewConsecutiveFailures = 0;
+  const contentType = res.headers.get("content-type") ?? "";
+  const ext = contentType.includes("webp") ? "webp" : contentType.includes("jpeg") || contentType.includes("jpg") ? "jpg" : contentType.includes("png") ? "png" : "webp";
+  const previewPath = previewPathFor(originalPath, ext);
+  const tmp = tempPreviewPath(previewPath);
+  try {
+    await pipeline(Readable.fromWeb(res.body), fs2.createWriteStream(tmp));
+  } catch {
+    fs2.rmSync(tmp, { force: true });
+    return void 0;
+  }
+  return commitPreview(tmp, previewPath) ? previewPath : void 0;
+}
+async function writePreview(originalPath, sourceUrl, bytes, fetchImpl = fetch) {
+  if (!PREVIEW_SOURCE_RE.test(originalPath)) return void 0;
+  invalidatePreviews(originalPath);
+  if (!shouldWritePreview(originalPath, bytes)) return void 0;
+  try {
+    const jpgPath = previewPathFor(originalPath, "jpg");
+    fs2.mkdirSync(path2.dirname(jpgPath), { recursive: true });
+    if (await writePreviewWithSips(originalPath, jpgPath).catch(() => false)) {
+      return jpgPath;
+    }
+    const cdnPath = await writePreviewFromCdn(sourceUrl, originalPath, fetchImpl).catch(
+      () => void 0
+    );
+    if (cdnPath) return cdnPath;
+  } catch {
+  }
+  return void 0;
+}
 function extFromUrl(url, fallback = "bin") {
   try {
     const pathname = new URL(url).pathname;
@@ -866,7 +992,10 @@ async function downloadOutputs(urls, template, vars, fetchImpl = fetch) {
       index: i,
       ext: extFromUrl(url)
     });
-    files.push(await downloadUrl(url, dest, fetchImpl));
+    const file = await downloadUrl(url, dest, fetchImpl);
+    const preview = await writePreview(file.path, url, file.bytes, fetchImpl);
+    if (preview) file.preview = preview;
+    files.push(file);
   }
   return files;
 }
@@ -888,6 +1017,8 @@ var MIME_BY_EXT = {
   m4v: "video/x-m4v",
   mp3: "audio/mpeg",
   wav: "audio/wav",
+  pcm: "audio/L16",
+  opus: "audio/opus",
   m4a: "audio/mp4",
   aac: "audio/aac",
   ogg: "audio/ogg",
@@ -917,19 +1048,25 @@ async function uploadFile(client, localPath, options = {}) {
   const uploadUrl = created?.upload_url;
   const filePath = created?.file_path;
   if (!uploadUrl || !filePath) {
-    throw new CliError("create_media_upload did not return upload_url/file_path.");
+    throw new CliError(
+      "create_media_upload did not return upload_url/file_path."
+    );
   }
   const { size } = fs3.statSync(resolved);
   const putRes = await fetchImpl(uploadUrl, {
     method: "PUT",
     headers: { "content-type": contentType, "content-length": String(size) },
-    body: Readable2.toWeb(fs3.createReadStream(resolved)),
+    body: Readable2.toWeb(
+      fs3.createReadStream(resolved)
+    ),
     // Node/undici requires duplex:"half" when the body is a stream.
     duplex: "half",
     signal: AbortSignal.timeout(6e5)
   });
   if (!putRes.ok) {
-    throw new CliError(`Upload PUT failed (HTTP ${putRes.status}). The presigned URL may have expired \u2014 retry.`);
+    throw new CliError(
+      `Upload PUT failed (HTTP ${putRes.status}). The presigned URL may have expired \u2014 retry.`
+    );
   }
   const finalized = await client.callTool("finalize_media_upload", {
     file_path: filePath,