@mevdragon/vidfarm-devcli 0.17.0 → 0.18.1

package/dist/src/devcli/clips.js

@@ -12,11 +12,11 @@ import { homedir } from "node:os";
 import { parseArgs } from "node:util";
 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 { buildEffectiveGuidance, ClipModelClient, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, detectLocalAgent, detectScenes, effectiveHuntDurationSec, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, resolveTargetClipCount, 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,30 @@ 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
+    --content-type <a,b>           Only raws whose shot-KIND tag matches (comma-separated,
+                                   exact): talking_head, b_roll, product_shot, screen_recording,
+                                   demo, reaction, interview, establishing, lifestyle, text_graphic
+    --offset <n>                   Skip the first N (paginate with --limit)
     --limit <n> | --json
 
-  clips search "<natural language>"  Hybrid structured + semantic search
+  raws search "<natural language>"   Hybrid structured + semantic search
+    --content-type <a,b>           Post-filter hits by shot-KIND tag (see \`raws list\`)
     --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 +101,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 +111,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 ──────────────────────────────────────────────────────────────
@@ -125,6 +130,8 @@ async function runScan(argv) {
             aspect: { type: "string" },
             "crop-focus": { type: "string" },
             "no-text": { type: "boolean" },
+            "allow-text": { type: "boolean" },
+            "max-clips": { type: "string" },
             "no-refine": { type: "boolean" },
             cloud: { type: "boolean" },
             url: { type: "string" },
@@ -153,16 +160,22 @@ async function runScan(argv) {
     const rawWindows = values.range?.length
         ? parseTimeRanges(values.range)
         : parsedPrompt.windows;
-    const durationBand = values.duration
+    // Explicit flags / prompt hints win; otherwise fall back to the same
+    // unspecified-prompt product defaults (5–15s clips, vertical 9:16, avoid text,
+    // ~10 clips / 10 min). Opt out with `--aspect original` / `--allow-text`.
+    const explicitBand = values.duration
         ? resolveDurationBand(Number(values.duration))
         : parsedPrompt.target_duration_sec != null
             ? resolveDurationBand(parsedPrompt.target_duration_sec)
             : null;
-    const aspect = values.aspect
-        ? (normalizeAspect(values.aspect) ?? (() => { throw new Error(`--aspect must be 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square), got "${values.aspect}"`); })())
+    const durationBand = explicitBand ?? { ...DEFAULT_CLIP_DURATION_BAND };
+    const explicitAspect = values.aspect
+        ? (normalizeAspect(values.aspect) ?? (() => { throw new Error(`--aspect must be 9:16 | 16:9 | 4:3 | 1:1 | original (or vertical/horizontal/square), got "${values.aspect}"`); })())
         : parsedPrompt.aspect;
+    const aspect = explicitAspect ?? DEFAULT_CLIP_ASPECT;
     const cropFocus = normalizeCropFocus(values["crop-focus"]);
-    const avoidText = Boolean(values["no-text"]) || parsedPrompt.avoid_text;
+    const avoidText = values["allow-text"] ? false : (Boolean(values["no-text"]) || parsedPrompt.avoid_text || true);
+    const maxClips = values["max-clips"] ? Math.max(1, Math.round(Number(values["max-clips"]))) : parsedPrompt.max_clips ?? undefined;
     const guidance = buildEffectiveGuidance({ contentPrompt: guidancePromptRaw, avoidText }) || undefined;
     // ── BACKUP path: run the hunt on the deployed pipeline (--cloud) ──────────
     if (values.cloud) {
@@ -181,17 +194,18 @@ async function runScan(argv) {
             durationBand,
             aspect,
             cropFocus,
-            avoidText
+            avoidText,
+            maxClips
         });
     }
     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 +231,27 @@ 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.");
     }
+    // Density/uniqueness target: ~10 clips / 10 min unless --max-clips / "N clips".
+    const targetClipCount = resolveTargetClipCount(effectiveHuntDurationSec(probe.duration_sec, windows), { max_clips: maxClips });
     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] aiming for ~${targetClipCount} distinct raw${targetClipCount === 1 ? "" : "s"}${maxClips ? " (--max-clips)" : " (~10 / 10 min)"}.`);
+    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 +264,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 +296,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 +310,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 +318,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 +336,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({
@@ -329,14 +346,15 @@ async function runScan(argv) {
         probe,
         windows,
         durationBand,
+        targetClipCount,
         sourceFilename: path.basename(videoPath),
         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 +383,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 +402,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 +446,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({
@@ -442,7 +460,10 @@ async function runScanCloud(input) {
                 ...(input.durationBand ? { duration_band: input.durationBand } : {}),
                 ...(input.aspect ? { aspect: input.aspect } : {}),
                 crop_focus: input.cropFocus,
-                ...(input.avoidText ? { avoid_text: true } : {})
+                // Send explicitly (incl. false) so --allow-text can override the
+                // server-side avoid-text default.
+                avoid_text: input.avoidText,
+                ...(input.maxClips ? { max_clips: input.maxClips } : {})
             }
         })
     });
@@ -450,28 +471,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)} `);
     }
 }
 /**
@@ -510,26 +531,33 @@ async function runList(argv) {
         args: argv,
         options: {
             source: { type: "string" },
+            "content-type": { type: "string" },
+            offset: { type: "string" },
             limit: { type: "string" },
             json: { type: "boolean" },
             home: { type: "string" }
         }
     });
     const store = new ClipStore(values.home);
-    const clips = store.listClips({ sourceVideoId: values.source, limit: clampInt(values.limit, 50, 1, 5000) });
+    const clips = store.listClips({
+        sourceVideoId: values.source,
+        contentTypes: parseContentTypes(values["content-type"]),
+        offset: values.offset ? clampInt(values.offset, 0, 0, 1_000_000) : undefined,
+        limit: clampInt(values.limit, 50, 1, 5000)
+    });
     store.close();
     if (values.json) {
         console.log(JSON.stringify(clips, null, 2));
         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) {
@@ -538,6 +566,7 @@ async function runSearch(argv) {
         allowPositionals: true,
         options: {
             provider: { type: "string" },
+            "content-type": { type: "string" },
             limit: { type: "string" },
             json: { type: "boolean" },
             "gemini-key": { type: "string" },
@@ -548,12 +577,13 @@ 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 contentTypes = parseContentTypes(values["content-type"]);
     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 +596,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,14 +605,20 @@ 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 });
+    // Over-fetch when a content-type filter is on so the post-filter still fills
+    // the requested limit (the tag lives in tags_json, not the search index).
+    const searchLimit = contentTypes.length ? Math.min(1000, limit * 5) : limit;
+    let hits = store.search({ criteria, queryEmbedding, limit: searchLimit });
+    if (contentTypes.length) {
+        hits = hits.filter((h) => (h.clip.tags.content_type ?? []).some((t) => contentTypes.includes(String(t).toLowerCase()))).slice(0, limit);
+    }
     const ms = elapsedMs(t0);
     store.close();
     if (values.json) {
@@ -627,7 +663,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 +672,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 +706,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 +735,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 +760,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 +792,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 +836,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 +893,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 +921,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) {
@@ -895,6 +931,13 @@ function normalizeProvider(value) {
         return value;
     throw new Error(`--provider must be gemini | openai | openrouter (got "${value}")`);
 }
+// Parse a comma-separated --content-type flag into lowercase shot-KIND tags for
+// the tags.content_type filter (talking_head, b_roll, product_shot, …).
+function parseContentTypes(value) {
+    if (!value)
+        return [];
+    return value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
 function normalizeTier(value) {
     if (value === "flash")
         return "flash";