@mevdragon/vidfarm-devcli 0.16.0 → 0.18.0

package/dist/src/cli.js

@@ -168,22 +168,22 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             original vs decomposed (caption-free),
                             non-billing (alias: ghostcut)
 
-Clip hunting (the third library — mine long-form video into a reusable clip store):
-  clips scan <video-path>   Hunt short clips out of a long video.        LOCAL-FIRST: local ffmpeg +
+Raws (the third library — mine long-form video into a reusable raws store):
+  raws scan <video-path>    Hunt short clips out of a long video.        LOCAL-FIRST: local ffmpeg +
                             Detect → tag/transcribe → embed → persist    your local claude/codex CLI
                             to ~/.vidfarm/clips.db.                      (keys are fallback)
     --range "MM:SS-MM:SS"     Only hunt these source windows (repeatable; big cost saver)
     --duration <sec>          Target clip length as a SOFT band (10→5-20s, 30→20-40s)
     --aspect 9:16|16:9|4:3|1:1  Crop clips (also: vertical/horizontal/square) [--crop-focus <f>]
     --no-text                 Prefer scenes WITHOUT captions/on-screen text (selection only)
-    --cloud [--url <url>]     BACKUP: run on the deployed pipeline       → POST /clips/scan (+ poll)
+    --cloud [--url <url>]     BACKUP: run on the deployed pipeline       → POST /raws/scan (+ poll)
                               (uploads to your temp folder — 30-day TTL — bills AWS compute only)
     --dry-run                 Show the estimated cost and stop (over $1 needs --yes/confirm)
-  clips list                List the local clip library                  → GET  /clips
-  clips search "<text>"     Hybrid structured + semantic search          → POST /clips/search
-  clips preset list|run <name>|save <name> --from-query '<...>'          → /clips/presets
-  clips export <ids...> --to <dir>   Copy clip mp4s + metadata out
-                            (run 'vidfarm clips' for the full clips help)
+  raws list                 List the local raws library                  → GET  /raws
+  raws search "<text>"      Hybrid structured + semantic search          → POST /raws/search
+  raws preset list|run <name>|save <name> --from-query '<...>'          → /raws/presets
+  raws export <ids...> --to <dir>   Copy raw mp4s + metadata out
+                            (run 'vidfarm raws' for the full raws help)
 
 Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit backup:
   tts "<text>"              Text → narration audio file.                 LOCAL: your OPENAI/GEMINI/
@@ -528,6 +528,7 @@ async function main() {
         case "annotate-file":
             await runAnnotateFileCommand(rest);
             return;
+        case "raws":
         case "clips":
             await runClipsCommand(rest);
             return;
@@ -722,7 +723,7 @@ async function runServeCommand(argv) {
     // render_target="cloud" upstream handoff (the editor's "Render in Cloud").
     process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
     // Same trap for clip hunts: a dev-shell .env carrying the staging clip-scan
-    // ARN would route this box's /clips/scan to the cloud Step Functions. serve
+    // ARN would route this box's /raws/scan to the cloud Step Functions. serve
     // hunts are LOCAL-FIRST (local agent CLI / BYOK keys); the upstream cloud is
     // the explicit backup inside the scan route itself.
     process.env.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN = "";
@@ -2256,7 +2257,7 @@ async function runGenerateCommand(argv) {
     }
 }
 // ── Speech: tts / stt ────────────────────────────────────────────────────────
-// LOCAL-FIRST like `clips scan`: both commands default to running on the
+// LOCAL-FIRST like `raws scan`: both commands default to running on the
 // user's OWN AI key (GEMINI_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY or
 // the --*-key flags) via src/services/speech.ts — local ffmpeg demux, direct
 // provider call, no cloud job, no wallet. The REST primitive routes

package/dist/src/devcli/clips.js

@@ -14,9 +14,9 @@ import { createInterface } from "node:readline/promises";
 import { createIdV7 } from "../lib/ids.js";
 import { buildEffectiveGuidance, ClipModelClient, detectLocalAgent, detectScenes, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, scanVideo, searchClips } from "../services/clip-curation/index.js";
 import { ClipStore } from "./clip-store.js";
-export const CLIPS_HELP = `vidfarm clips — build & search a local clip library (local ffmpeg + local agent by default)
+export const CLIPS_HELP = `vidfarm raws — build & search a local raws library (local ffmpeg + local agent by default)
 
-  clips scan <video-path>          Mine a long-form video into tagged, searchable clips
+  raws scan <video-path>           Mine a long-form video into tagged, searchable raws
     --provider <p>                 agent | gemini | openai | openrouter
                                    Default: agent when a local claude/codex CLI is installed
                                    (your subscription, no API key), else gemini.
@@ -27,8 +27,8 @@ export const CLIPS_HELP = `vidfarm clips — build & search a local clip library
                                    Inline hints are honored too: "between 12:30 and 15:45",
                                    "30 sec clips", "vertical", "no captions".
     --range "MM:SS-MM:SS"          Only hunt inside this source range (repeatable / comma-separated)
-    --duration <sec>               Target clip length as a SOFT band (10→5-20s, 30→20-40s, …)
-    --aspect <a>                   Crop clips to 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square)
+    --duration <sec>               Target raw length as a SOFT band (10→5-20s, 30→20-40s, …)
+    --aspect <a>                   Crop raws to 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square)
     --crop-focus <f>               center | top | bottom | left | right (default: center)
     --no-text                      Prefer scenes WITHOUT burned-in captions/on-screen text
                                    (scene selection — NEVER GhostCut on the long-form source)
@@ -52,25 +52,25 @@ export const CLIPS_HELP = `vidfarm clips — build & search a local clip library
     --embed-provider gemini|openai --embed-key <key>       Embeddings for agent/openrouter scans
     --home <dir>                   Library dir (default: ~/.vidfarm or VIDFARM_HOME)
 
-  clips list                       List clips in the library
-    --source <id>                  Only clips from one source video
+  raws list                        List raws in the library
+    --source <id>                  Only raws from one source video
     --limit <n> | --json
 
-  clips search "<natural language>"  Hybrid structured + semantic search
+  raws search "<natural language>"   Hybrid structured + semantic search
     --limit <n> | --json | --gemini-key <key>
 
-  clips match "<text>"             Top library clips to REPLACE a scene (vector search)
+  raws match "<text>"              Top library raws to REPLACE a scene (vector search)
     --criteria '<json>'            Match a structured SplicingCriteria instead of text
     --scenes <annotations.json>    Batch: match every scene of a decomposed video
                                    (array of scene annotations, or {annotations|scenes:[…]})
     --limit <n> | --json
 
-  clips preset list                List built-in + saved presets
-  clips preset run <name>          Run a preset query   [--limit <n>] [--json]
-  clips preset save <name> --from-query '<json | natural language>'
+  raws preset list                 List built-in + saved presets
+  raws preset run <name>           Run a preset query   [--limit <n>] [--json]
+  raws preset save <name> --from-query '<json | natural language>'
 
-  clips sources                    List scanned source videos
-  clips export <clip-ids...> --to <dir>   Copy clip mp4s (+ metadata.json) out
+  raws sources                     List scanned source videos
+  raws export <raw-ids...> --to <dir>   Copy raw mp4s (+ metadata.json) out
 `;
 export async function runClipsCommand(argv) {
     const sub = argv[0];
@@ -96,7 +96,7 @@ export async function runClipsCommand(argv) {
         case "-h":
             return runOverview();
         default:
-            console.error(`Unknown clips subcommand: ${sub}\n`);
+            console.error(`Unknown raws subcommand: ${sub}\n`);
             console.log(CLIPS_HELP);
             process.exitCode = 1;
     }
@@ -106,8 +106,8 @@ function runOverview() {
     const store = new ClipStore();
     const stats = store.stats();
     store.close();
-    console.log(`vidfarm clips — library at ${resolveHome()}`);
-    console.log(`  ${stats.clips} clips · ${stats.sources} source videos · ${stats.presets} presets\n`);
+    console.log(`vidfarm raws — library at ${resolveHome()}`);
+    console.log(`  ${stats.clips} raws · ${stats.sources} source videos · ${stats.presets} presets\n`);
     console.log(CLIPS_HELP);
 }
 // ── clips scan ──────────────────────────────────────────────────────────────
@@ -186,12 +186,12 @@ async function runScan(argv) {
     }
     const videoArg = positionals[0];
     if (!videoArg)
-        throw new Error("Usage: vidfarm clips scan <video-path> [--range MM:SS-MM:SS] [--duration 30] [--aspect 9:16] [--dry-run]");
+        throw new Error("Usage: vidfarm raws scan <video-path> [--range MM:SS-MM:SS] [--duration 30] [--aspect 9:16] [--dry-run]");
     const videoPath = path.resolve(process.cwd(), videoArg);
     if (!existsSync(videoPath))
         throw new Error(`No such video: ${videoPath}`);
     if (!(await hasFfmpeg())) {
-        throw new Error("ffmpeg is required for `clips scan` but was not found (bundled ffmpeg-static missing and none on PATH).");
+        throw new Error("ffmpeg is required for `raws scan` but was not found (bundled ffmpeg-static missing and none on PATH).");
     }
     // ── Model resolution: LOCAL-FIRST ─────────────────────────────────────────
     // 1. --provider agent (or no --provider + a local claude/codex CLI installed)
@@ -217,24 +217,24 @@ async function runScan(argv) {
     const embedding = provider === "agent"
         ? resolveAgentEmbeddingConfig(values)
         : apiKey ? resolveEmbeddingConfig(provider, apiKey, values) : null;
-    console.log(`[clips] probing ${path.basename(videoPath)} …`);
+    console.log(`[raws] probing ${path.basename(videoPath)} …`);
     const probe = await probeVideo(videoPath);
-    console.log(`[clips] ${fmtDuration(probe.duration_sec)} · ${probe.width ?? "?"}x${probe.height ?? "?"} · ${probe.codec ?? "?"}`);
+    console.log(`[raws] ${fmtDuration(probe.duration_sec)} · ${probe.width ?? "?"}x${probe.height ?? "?"} · ${probe.codec ?? "?"}`);
     const windows = normalizeWindows(rawWindows, probe.duration_sec);
     if (rawWindows.length && !windows.length) {
         throw new Error("--range produced no usable window inside the video's duration.");
     }
     if (windows.length) {
-        console.log(`[clips] hunting only ${windows.map((w) => `${fmtClock(w.start_sec)}–${fmtClock(w.end_sec)}`).join(", ")} (${fmtDuration(windows.reduce((a, w) => a + w.end_sec - w.start_sec, 0))} of ${fmtDuration(probe.duration_sec)}).`);
+        console.log(`[raws] hunting only ${windows.map((w) => `${fmtClock(w.start_sec)}–${fmtClock(w.end_sec)}`).join(", ")} (${fmtDuration(windows.reduce((a, w) => a + w.end_sec - w.start_sec, 0))} of ${fmtDuration(probe.duration_sec)}).`);
     }
     if (durationBand) {
-        console.log(`[clips] target clip length ~${durationBand.target_sec}s (soft range ${durationBand.min_sec}–${durationBand.max_sec}s).`);
+        console.log(`[raws] target clip length ~${durationBand.target_sec}s (soft range ${durationBand.min_sec}–${durationBand.max_sec}s).`);
     }
     if (aspect && aspect !== "original")
-        console.log(`[clips] cropping clips to ${aspect} (${cropFocus}).`);
+        console.log(`[raws] cropping clips to ${aspect} (${cropFocus}).`);
     if (avoidText)
-        console.log(`[clips] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
-    console.log(`[clips] detecting scenes …`);
+        console.log(`[raws] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
+    console.log(`[raws] detecting scenes …`);
     const detected = await detectScenes(videoPath, { durationSec: probe.duration_sec, windows, ...sceneOptions });
     const scenes = fitScenesToDurationBand(detected, durationBand);
     if (scenes.length === 0)
@@ -247,13 +247,13 @@ async function runScan(argv) {
             embedding,
             tier
         });
-        console.log(`[clips] evaluating scenes with your local ${client.tagModelId} subscription (no API cost).`);
+        console.log(`[raws] evaluating scenes with your local ${client.tagModelId} subscription (no API cost).`);
     }
     else if (apiKey) {
         client = new ClipModelClient({ provider, apiKey, tier, embedding });
     }
     if (client && !client.canEmbed) {
-        console.warn(`[clips] no embedding provider for "${provider}" — clips will be structured-searchable only.`);
+        console.warn(`[raws] no embedding provider for "${provider}" — raws will be structured-searchable only.`);
         console.warn(`        Add --embed-provider gemini|openai --embed-key <key> for semantic search.`);
     }
     // Cost estimate: local-agent scans ride the user's subscription, so only the
@@ -279,7 +279,7 @@ async function runScan(argv) {
         console.log(`  Guidance: "${guidance.replace(/\n/g, " · ")}"`);
     console.log("");
     if (values["dry-run"]) {
-        console.log("[clips] --dry-run: not scanning. Re-run without --dry-run to build the library.");
+        console.log("[raws] --dry-run: not scanning. Re-run without --dry-run to build the library.");
         return;
     }
     // Actually scanning now — an evaluator is required.
@@ -293,7 +293,7 @@ async function runScan(argv) {
     if (estimate && estimate.usd > 1 && !values.yes) {
         const ok = await confirm(`This scan is estimated at $${estimate.usd.toFixed(2)}. Proceed? [y/N] `);
         if (!ok) {
-            console.log("[clips] aborted.");
+            console.log("[raws] aborted.");
             return;
         }
     }
@@ -301,7 +301,7 @@ async function runScan(argv) {
     if (activeClient.embeddingModelId) {
         const existing = store.getLibraryEmbeddingModel();
         if (existing && existing !== activeClient.embeddingModelId) {
-            console.warn(`[clips] WARNING: library was built with "${existing}" embeddings but this scan uses "${activeClient.embeddingModelId}". Semantic search across them will be unreliable.`);
+            console.warn(`[raws] WARNING: library was built with "${existing}" embeddings but this scan uses "${activeClient.embeddingModelId}". Semantic search across them will be unreliable.`);
         }
         else {
             store.rememberEmbeddingModel(activeClient.embeddingModelId);
@@ -319,7 +319,7 @@ async function runScan(argv) {
         reencodeClips: true,
         crop: aspect && aspect !== "original" ? { aspect, focus: cropFocus } : undefined
     };
-    console.log(`[clips] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
+    console.log(`[raws] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
     let errors = 0;
     const started = timestamp();
     const result = await scanVideo({
@@ -333,10 +333,10 @@ async function runScan(argv) {
         concurrency,
         onRefine: (r) => {
             if (r.refined) {
-                console.log(`[clips] guided segmentation: ${scenes.length} → ${r.kept} clips (dropped ${r.dropped}, merged ${r.merged}).`);
+                console.log(`[raws] guided segmentation: ${scenes.length} → ${r.kept} raws (dropped ${r.dropped}, merged ${r.merged}).`);
             }
             else if (r.note) {
-                console.log(`[clips] guided segmentation skipped: ${r.note}.`);
+                console.log(`[raws] guided segmentation skipped: ${r.note}.`);
             }
         },
         onClip: (clip, i, total) => {
@@ -365,10 +365,10 @@ async function runScan(argv) {
         /* ignore */
     }
     store.close();
-    console.log(`\n[clips] done in ${elapsed(started)}: ${result.clips.length} clips${errors ? `, ${errors} scene(s) failed` : ""}.`);
-    console.log(`  clips → ${store.paths.clipsDir}`);
-    console.log(`  db    → ${store.paths.db}`);
-    console.log(`  try:  vidfarm clips search "…"  |  vidfarm clips preset run "funny reaction gifs"`);
+    console.log(`\n[raws] done in ${elapsed(started)}: ${result.clips.length} raws${errors ? `, ${errors} scene(s) failed` : ""}.`);
+    console.log(`  raws → ${store.paths.clipsDir}`);
+    console.log(`  db   → ${store.paths.db}`);
+    console.log(`  try:  vidfarm raws search "…"  |  vidfarm raws preset run "funny reaction gifs"`);
 }
 // ── clips scan --cloud (explicit backup: the deployed pipeline) ─────────────
 // Uploads the local file into the user's temp folder (30-day TTL, auto-removed)
@@ -384,13 +384,13 @@ async function runScanCloud(input) {
     let fileName;
     if (!input.sourceUrl) {
         if (!input.videoArg)
-            throw new Error("Usage: vidfarm clips scan --cloud <video-path> | --cloud --url <video-url>");
+            throw new Error("Usage: vidfarm raws scan --cloud <video-path> | --cloud --url <video-url>");
         const videoPath = path.resolve(process.cwd(), input.videoArg);
         if (!existsSync(videoPath))
             throw new Error(`No such video: ${videoPath}`);
         fileName = path.basename(videoPath);
         const sizeBytes = statSync(videoPath).size;
-        console.log(`[clips] uploading ${fileName} (${(sizeBytes / (1024 * 1024)).toFixed(1)} MB) to your temp folder (auto-deletes in 30 days) …`);
+        console.log(`[raws] uploading ${fileName} (${(sizeBytes / (1024 * 1024)).toFixed(1)} MB) to your temp folder (auto-deletes in 30 days) …`);
         const presignRes = await fetch(`${baseUrl}/api/v1/user/me/temporary-files/presign`, {
             method: "POST",
             headers,
@@ -428,8 +428,8 @@ async function runScanCloud(input) {
         }
         tempFileId = presign.file_id;
     }
-    console.log(`[clips] starting cloud hunt …`);
-    const scanRes = await fetch(`${baseUrl}/clips/scan`, {
+    console.log(`[raws] starting cloud hunt …`);
+    const scanRes = await fetch(`${baseUrl}/raws/scan`, {
         method: "POST",
         headers,
         body: JSON.stringify({
@@ -450,28 +450,28 @@ async function runScanCloud(input) {
     if (!scanRes.ok || !scan.scan_id) {
         throw new Error(`Cloud scan failed to start (${scanRes.status}): ${scan.error ?? "unexpected response"}`);
     }
-    console.log(`[clips] scan ${scan.scan_id} ${scan.status ?? "queued"}${scan.tracer ? ` (tracer ${scan.tracer})` : ""}.`);
+    console.log(`[raws] scan ${scan.scan_id} ${scan.status ?? "queued"}${scan.tracer ? ` (tracer ${scan.tracer})` : ""}.`);
     if (scan.compute_estimate?.estimated_charge_usd != null) {
-        console.log(`[clips] estimated AWS compute charge ~$${scan.compute_estimate.estimated_charge_usd.toFixed(4)} (AI runs on your saved provider keys).`);
+        console.log(`[raws] estimated AWS compute charge ~$${scan.compute_estimate.estimated_charge_usd.toFixed(4)} (AI runs on your saved provider keys).`);
     }
     // Async by design — poll until the pipeline finishes.
     const started = timestamp();
     for (;;) {
         await new Promise((r) => setTimeout(r, 5000));
-        const pollRes = await fetch(`${baseUrl}/clips/scan/${encodeURIComponent(scan.scan_id)}`, { headers });
+        const pollRes = await fetch(`${baseUrl}/raws/scan/${encodeURIComponent(scan.scan_id)}`, { headers });
         if (!pollRes.ok)
             continue;
         const poll = await pollRes.json();
         const status = poll.source?.status ?? poll.scan?.status ?? "running";
         if (status === "complete") {
-            console.log(`\n[clips] cloud hunt done in ${elapsed(started)}: ${poll.source?.clip_count ?? 0} clips.`);
-            console.log(`  browse → ${baseUrl}/clips`);
+            console.log(`\n[raws] cloud hunt done in ${elapsed(started)}: ${poll.source?.clip_count ?? 0} raws.`);
+            console.log(`  browse → ${baseUrl}/library/raws`);
             return;
         }
         if (status === "failed") {
             throw new Error(`Cloud hunt failed: ${poll.scan?.error ?? "unknown error"}`);
         }
-        process.stdout.write(`\r[clips] ${status} … ${elapsed(started)} `);
+        process.stdout.write(`\r[raws] ${status} … ${elapsed(started)} `);
     }
 }
 /**
@@ -523,13 +523,13 @@ async function runList(argv) {
         return;
     }
     if (clips.length === 0) {
-        console.log("No clips yet. Run: vidfarm clips scan <video-path>");
+        console.log("No raws yet. Run: vidfarm raws scan <video-path>");
         return;
     }
     for (const clip of clips) {
         console.log(`${clip.clip_id.slice(0, 14)}  ${fmtRange(clip)}  ${clip.source_filename}  ${summarizeTags(clip)}`);
     }
-    console.log(`\n${clips.length} clips.`);
+    console.log(`\n${clips.length} raws.`);
 }
 // ── clips search ────────────────────────────────────────────────────────────
 async function runSearch(argv) {
@@ -548,12 +548,12 @@ async function runSearch(argv) {
     });
     const query = positionals.join(" ").trim();
     if (!query)
-        throw new Error('Usage: vidfarm clips search "<natural language>"');
+        throw new Error('Usage: vidfarm raws search "<natural language>"');
     const limit = clampInt(values.limit, 10, 1, 200);
     const store = new ClipStore(values.home);
     if (store.stats().clips === 0) {
         store.close();
-        console.log("Library is empty — scan a video first: vidfarm clips scan <video-path>");
+        console.log("Library is empty — scan a video first: vidfarm raws scan <video-path>");
         return;
     }
     const provider = normalizeProvider(values.provider);
@@ -566,7 +566,7 @@ async function runSearch(argv) {
         if (client.canEmbed) {
             const libModel = store.getLibraryEmbeddingModel();
             if (libModel && client.embeddingModelId && libModel !== client.embeddingModelId) {
-                console.warn(`[clips] note: library uses "${libModel}" embeddings but you're searching with "${client.embeddingModelId}" — semantic re-rank may be off; pass --provider to match.`);
+                console.warn(`[raws] note: library uses "${libModel}" embeddings but you're searching with "${client.embeddingModelId}" — semantic re-rank may be off; pass --provider to match.`);
             }
             queryEmbedding = await client.embedQuery(criteria.semantic_text ?? query);
         }
@@ -575,11 +575,11 @@ async function runSearch(argv) {
         // Local-first: no key, but a local agent CLI can still turn the natural-
         // language query into a structured filter (vector re-rank needs a key).
         const agent = new LocalAgentClipClient({});
-        console.log(`[clips] structuring query with your local ${agent.tagModelId} …`);
+        console.log(`[raws] structuring query with your local ${agent.tagModelId} …`);
         criteria = await agent.naturalLanguageToCriteria(query);
     }
     else {
-        console.warn(`[clips] no ${provider} key or local agent CLI — structured/keyword search only.`);
+        console.warn(`[raws] no ${provider} key or local agent CLI — structured/keyword search only.`);
     }
     const t0 = timestamp();
     const hits = store.search({ criteria, queryEmbedding, limit });
@@ -627,7 +627,7 @@ async function runMatch(argv) {
     const store = new ClipStore(values.home);
     if (store.stats().clips === 0) {
         store.close();
-        console.log("Library is empty — scan a video first: vidfarm clips scan <video-path>");
+        console.log("Library is empty — scan a video first: vidfarm raws scan <video-path>");
         return;
     }
     // Embed the match query in the SAME space the library was built with.
@@ -636,7 +636,7 @@ async function runMatch(argv) {
     const embedKey = resolveProviderKey(embedProvider, values, { optional: true });
     const client = embedKey ? new ClipModelClient({ provider: embedProvider, apiKey: embedKey }) : null;
     if (!client)
-        console.warn(`[clips] no ${embedProvider} key — structured match only (set the key for vector re-rank).`);
+        console.warn(`[raws] no ${embedProvider} key — structured match only (set the key for vector re-rank).`);
     if (values.scenes) {
         const filePath = path.resolve(process.cwd(), values.scenes);
         if (!existsSync(filePath))
@@ -670,7 +670,7 @@ async function runMatch(argv) {
             console.log(JSON.stringify(output, null, 2));
             return;
         }
-        console.log(`Matched ${scenes.length} scenes against ${all.length} clips:`);
+        console.log(`Matched ${scenes.length} scenes against ${all.length} raws:`);
         for (const o of output) {
             const rep = o.replaceability ? ` [replaceability: ${o.replaceability}]` : "";
             const dur = typeof o.duration === "number" ? ` (${o.duration.toFixed(1)}s)` : "";
@@ -699,7 +699,7 @@ async function runMatch(argv) {
         text = positionals.join(" ").trim();
         if (!text) {
             store.close();
-            throw new Error('Usage: vidfarm clips match "<text>" | --criteria \'<json>\' | --scenes <annotations.json>');
+            throw new Error('Usage: vidfarm raws match "<text>" | --criteria \'<json>\' | --scenes <annotations.json>');
         }
         criteria = { semantic_text: text };
     }
@@ -724,7 +724,7 @@ async function runPreset(argv) {
         return runPresetRun(rest);
     if (action === "save")
         return runPresetSave(rest);
-    throw new Error("Usage: vidfarm clips preset <list|run <name>|save <name> --from-query '<...>'>");
+    throw new Error("Usage: vidfarm raws preset <list|run <name>|save <name> --from-query '<...>'>");
 }
 async function runPresetList(argv) {
     const { values } = parseArgs({ args: argv, options: { json: { type: "boolean" }, home: { type: "string" } } });
@@ -756,12 +756,12 @@ async function runPresetRun(argv) {
     });
     const name = positionals.join(" ").trim();
     if (!name)
-        throw new Error("Usage: vidfarm clips preset run <name>");
+        throw new Error("Usage: vidfarm raws preset run <name>");
     const store = new ClipStore(values.home);
     const preset = store.findPreset(name);
     if (!preset) {
         store.close();
-        throw new Error(`No preset "${name}". Try: vidfarm clips preset list`);
+        throw new Error(`No preset "${name}". Try: vidfarm raws preset list`);
     }
     const limit = clampInt(values.limit, 10, 1, 200);
     // Presets carry semantic_text; embed it if we have a key for the re-rank.
@@ -800,7 +800,7 @@ async function runPresetSave(argv) {
     const name = positionals.join(" ").trim();
     const fromQuery = values["from-query"];
     if (!name || !fromQuery) {
-        throw new Error("Usage: vidfarm clips preset save <name> --from-query '<json | natural language>'");
+        throw new Error("Usage: vidfarm raws preset save <name> --from-query '<json | natural language>'");
     }
     let criteria;
     const asJson = tryParseJson(fromQuery);
@@ -857,7 +857,7 @@ async function runExport(argv) {
     const ids = positionals;
     const to = values.to;
     if (ids.length === 0 || !to) {
-        throw new Error("Usage: vidfarm clips export <clip-ids...> --to <dir>");
+        throw new Error("Usage: vidfarm raws export <raw-ids...> --to <dir>");
     }
     const outDir = path.resolve(process.cwd(), to);
     mkdirSync(outDir, { recursive: true });
@@ -885,7 +885,7 @@ async function runExport(argv) {
     store.close();
     const { writeFileSync } = await import("node:fs");
     writeFileSync(path.join(outDir, "clips.metadata.json"), JSON.stringify(exported, null, 2));
-    console.log(`\nExported ${exported.length} clips + clips.metadata.json → ${outDir}`);
+    console.log(`\nExported ${exported.length} raws + clips.metadata.json → ${outDir}`);
 }
 // ── helpers ─────────────────────────────────────────────────────────────────
 function normalizeProvider(value) {

package/dist/src/editor-chat.js

@@ -45,7 +45,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "If the user asks to modify an attached image and the message includes an attachment URL, call POST /api/v1/primitives/images/edit with source_image_url inside payload set to that exact URL and instruction inside payload set to the requested edit.",
         "If the user asks to generate a new AI video from text or reference images, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, input_references?, duration? } }. AI video duration is seconds; use duration: 4 for a 4-second video and never use duration_ms on /videos/generate. input_references must be direct image asset URLs, not webpage or social post URLs. Use frame_images for exact first/last-frame image-to-video.",
         "If the user asks to render HTML/design into an image, call POST /api/v1/primitives/images/render-html. If the user asks to turn existing media URLs into a slideshow/video, call POST /api/v1/primitives/videos/render-slides. If the user asks to dedupe, camouflage, or apply small zoom/tilt/rotate/filter/tint transforms to an image or video for reuse, call POST /api/v1/primitives/media/dedupe with body { tracer, payload: { source_media_url, media_type?, effects?: { zoom?, tilt?, rotate?, saturation?, speed?, horizontal_flip?, contrast?, brightness?, hue_rotate?, blur? }, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Primitive media utility routes are also allowed directly here, including /videos/trim, /videos/remove-captions, /videos/extract-audio, /videos/probe, /videos/extract-frame, /videos/mute, /videos/replace-audio, /videos/concat, /audio/trim, /audio/probe, /audio/concat, and /audio/normalize. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or a YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver), aspect crops every clip, and avoid_text prefers text-free scenes via scene SELECTION (never caption removal on the source). The hunt is async (202 + scan_id): poll GET /clips/scan/:scanId, then browse GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys. To erase captions from a finished HUNTED clip, pass that short mp4 to /videos/remove-captions afterwards.",
-        "SPEECH PRIMITIVES (TTS/STT) are first-class here. VOICEOVER / NARRATION: when the user wants a script, hook, caption, or dub read aloud as AI audio, call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? } } — instructions is a free-form voice-STYLE prompt (tone, pacing, accent, emotion, persona; e.g. 'calm warm bedtime narrator' or 'excited sports announcer, fast paced'), and voice picks a provider preset (OpenAI: alloy/ash/coral/...; Gemini: Kore/Puck/Charon/...). When sending a voice you may omit provider — it is inferred from the voice preset; a voice paired with the WRONG provider (e.g. voice 'Kore' with provider 'openai') is rejected with a 400, so never mix families. The finished job returns a durable audio URL — place it on the timeline with editor_action add_layer (kind=audio, src=that URL), typically starting where the narration should begin. TRANSCRIPTION: when the user wants a transcript, subtitles/captions from speech, a translation source, or to know who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language?, prompt? } } — source_url may be a VIDEO or AUDIO URL (video audio is demuxed automatically; pick the fork's source via GET /api/v1/compositions/:forkId/remove-video-captions first when transcribing the current composition). One job returns BOTH formats: a simple subtitle version (plain transcript text + timed SRT cues, stored as transcript.txt/transcript.srt) and an advanced multi-speaker version (speaker-attributed timed segments in output.segments and transcript.json) for multi-narration sources like podcasts and interviews. diarize defaults to true and speaker attribution needs a Gemini key — openai/openrouter keys degrade to a plain single-speaker transcript. For transcript-grounded caption work on THIS fork, the read-only video_context tool may already contain the decompose-time transcript; prefer it before running a new billable-key transcription, and use /audio/transcribe for other URLs, multi-speaker attribution, or SRT output.",
+        "SPEECH PRIMITIVES (TTS/STT) are first-class here. VOICEOVER / NARRATION: when the user wants a script, hook, caption, or dub read aloud as AI audio, call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? } } — instructions is a free-form voice-STYLE prompt (tone, pacing, accent, emotion, persona; e.g. 'calm warm bedtime narrator' or 'excited sports announcer, fast paced'), and voice picks a provider preset (OpenAI: alloy/ash/coral/...; Gemini: Kore/Puck/Charon/...). When sending a voice you may omit provider — it is inferred from the voice preset; a voice paired with the WRONG provider (e.g. voice 'Kore' with provider 'openai') is rejected with a 400, so never mix families. The finished job returns a durable audio URL — place it on the timeline with editor_action add_layer (kind=audio, src=that URL), typically starting where the narration should begin. TRANSCRIPTION: when the user wants a transcript, subtitles/captions from speech, a translation source, or to know who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language?, prompt? } } — source_url may be a VIDEO or AUDIO URL (video audio is demuxed automatically; pick the fork's source via GET /api/v1/compositions/:forkId/remove-video-captions first when transcribing the current composition). One job returns BOTH formats: a simple subtitle version (plain transcript text + timed SRT cues, stored as transcript.txt/transcript.srt) and an advanced multi-speaker version (speaker-attributed timed segments in output.segments and transcript.json) for multi-narration sources like podcasts and interviews. diarize defaults to true and speaker attribution needs a Gemini key — openai/openrouter keys degrade to a plain single-speaker transcript. For transcript-grounded caption work on THIS fork, the read-only video_context tool may already contain the decompose-time transcript; prefer it before running a new billable-key transcription, and use /audio/transcribe for other URLs, multi-speaker attribution, or SRT output. REGENERATE / REVOICE: when the user wants the SAME speaker to say DIFFERENT words (reword the narration, fix a line, change an offer or CTA, redub in the original voice), call POST /api/v1/primitives/audio/regenerate-speech with body { tracer, payload: { source_url (video or audio; video audio is demuxed), rewrite_instruction (how to reword the original transcript) OR text (the exact new script — one of the two is required), voice?, instructions?, provider?, model?, language?, output_format? } }. One job listens to the source, profiles the speaker's voice, rewords the script, and returns a durable audio URL spoken by the CLOSEST PRESET voice with a style prompt matched to the speaker (result fields: audioUrl, script, original_transcript, voice_profile, voice_match). Voice profiling needs a saved Gemini key — with only openai/openrouter keys the job degrades to transcript-only rewording with a default or explicitly passed voice and voice_match 'none'. IMPORTANT HONESTY RULE: OpenAI and Gemini APIs cannot clone voice identity (preset voices only), so always tell the user the regenerated audio APPROXIMATES the original voice rather than clones it. To swap the regenerated audio into the composition, mute the original span (/videos/mute or volume/muted on the layer) and place the new audio with editor_action add_layer (kind=audio, src=audioUrl).",
         "Brainstorm primitives are also available directly here. If the user explicitly asks for hooks, angles, awareness-stage advice, a cold-start strategy questionnaire, or product-placement opportunities in a video, call the matching brainstorm primitive immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart with body { tracer, payload: { user_message }, webhook_url? } when the user is clueless and needs foundational strategy questions. Use /brainstorm/awareness_stages with body { tracer, payload: { offer_description }, webhook_url? } when they are unsure what type of ads to make. Use /brainstorm/angles with body { tracer, payload: { offer_description, problem_awareness, solution_awareness }, webhook_url? } when they want persuasive ad angles; problem_awareness must be problem_unaware or problem_aware, and solution_awareness must be solution_unaware or solution_aware. Use /brainstorm/hooks with body { tracer, payload: { offer_description }, webhook_url? } when they are stuck on openings and want many hooks.",
         "Product placement is a first-class brainstorm primitive, just like angles and hooks. When the user asks to identify product-placement opportunities in a video, or to repurpose a video into a native ad for their product, prefer POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? }. source_video_url is the exact video to analyze — for the current composition, first call GET /api/v1/compositions/:forkId/remove-video-captions to pick the correct source (the ORIGINAL uploaded video vs the DECOMPOSED, caption-free video), then pass that URL. offer_description is the user's product/offer. This primitive watches the video and returns timestamped, native placement opportunities. It prefers a Gemini key for video understanding.",
         "BEFORE calling /brainstorm/product_placement for the CURRENT composition, first call the product_placement_context tool (or GET /api/v1/compositions/:forkId/product-placement.json). Decompose already scouted product-AGNOSTIC placement surfaces for this fork — real, grounded moments (timestamp, surface_type, surface_note, best_for, why_it_works). Use those surfaces to ground your answer and to seed the primitive: fold the strongest surfaces into offer_description (for example append 'Known native placement surfaces: 0:04 empty desk prop; 0:12 phone screen swap') so the product-specific pass builds on grounded moments instead of re-watching blind. If the user just wants a quick conversational take on where their product could go, the surfaces from product_placement_context are often enough to answer directly without the billable primitive.",
@@ -469,7 +469,7 @@ export const EDITOR_CHAT_SKILL_PACKS = [
     { name: "hyperframes-animation", summary: "motion rules catalog, scene blueprints, transition doctrine, runtime adapters" },
     { name: "hyperframes-keyframes", summary: "seek-safe keyframe/CSS animation patterns" },
     { name: "hyperframes-creative", summary: "design specs, palettes, typography, house style, narration craft" },
-    { name: "vidfarm-media", summary: "narration TTS/STT, BGM/SFX/media resolution through vidfarm primitives" },
+    { name: "vidfarm-media", summary: "narration TTS/STT, voice-matched speech regeneration (same speaker, new words), BGM/SFX/media resolution through vidfarm primitives" },
     { name: "embedded-captions", summary: "caption identity catalog + subject-occlusion caption pipeline" },
     { name: "talking-head-recut", summary: "timed graphic overlay cards on existing footage" },
     { name: "product-launch-video", summary: "product/launch promo workflow (time-coded shot sequences)" },