@mevdragon/vidfarm-devcli 0.18.0 → 0.19.0

package/dist/src/services/clip-curation/hunt.js

@@ -6,6 +6,66 @@
 // NEVER GhostCut on the long-form source). Shared by devcli (local), the Hono
 // API, and the cloud scan Lambda so every surface parses and normalizes
 // identically. All helpers are pure/deterministic — no AI calls here.
+// ── Unspecified-prompt defaults ─────────────────────────────────────────────
+// When a user imports a source video without saying what they want, we bias
+// toward the short-form product default: a handful of DISTINCT, vertical,
+// text-free 5–15s clips rather than every raw cut. These fill only the gaps —
+// any field the user (or their prompt) sets always wins.
+/** Default soft clip length when unspecified: ~10s, 5–15s band. */
+export const DEFAULT_CLIP_DURATION_BAND = { min_sec: 5, max_sec: 15, target_sec: 10 };
+/** Default mining density when neither max_clips nor clips_per_10min is set. */
+export const DEFAULT_CLIPS_PER_10_MIN = 10;
+/** Default output aspect when unspecified (vertical / shorts). */
+export const DEFAULT_CLIP_ASPECT = "9:16";
+/**
+ * Fill the unspecified-prompt defaults on a normalized hunt spec: a 5–15s
+ * duration band, vertical 9:16 crop, and avoid-text ON. Only fills gaps — an
+ * explicit user choice (including avoid_text:false) is preserved.
+ */
+export function applyHuntSpecDefaults(spec) {
+    const out = { ...spec };
+    if (!out.duration_band)
+        out.duration_band = { ...DEFAULT_CLIP_DURATION_BAND };
+    if (out.avoid_text === undefined)
+        out.avoid_text = true;
+    if (!out.aspect)
+        out.aspect = DEFAULT_CLIP_ASPECT;
+    return out;
+}
+/**
+ * The number of clips to aim for given the (effective, windowed) source
+ * duration. A hard max_clips wins; otherwise density (default 10 per 10 min ≈
+ * one clip per minute) scales with length. Always ≥ 1.
+ */
+export function resolveTargetClipCount(effectiveDurationSec, spec) {
+    if (spec.max_clips && spec.max_clips > 0)
+        return Math.max(1, Math.round(spec.max_clips));
+    const per10 = spec.clips_per_10min && spec.clips_per_10min > 0 ? spec.clips_per_10min : DEFAULT_CLIPS_PER_10_MIN;
+    const tenMinBlocks = Math.max(0, effectiveDurationSec) / 600;
+    return Math.max(1, Math.round(tenMinBlocks * per10));
+}
+/**
+ * Deterministic count cap / uniqueness backstop: when more scenes survived than
+ * the target, keep an EVENLY-SPACED subset across the timeline. Spread-out
+ * scenes are far less likely to be near-duplicates of each other than adjacent
+ * ones, so this doubles as a cheap "distinct clips" filter when the AI refine
+ * pass is skipped (>60 scenes) or over-returns. Re-indexes the survivors.
+ */
+export function capScenesEvenlyToCount(scenes, target) {
+    if (!Number.isFinite(target) || target <= 0 || scenes.length <= target)
+        return scenes;
+    const step = scenes.length / target;
+    const picked = [];
+    const seen = new Set();
+    for (let i = 0; i < target; i++) {
+        const idx = Math.min(scenes.length - 1, Math.floor(i * step + step / 2));
+        if (seen.has(idx))
+            continue;
+        seen.add(idx);
+        picked.push(scenes[idx]);
+    }
+    return picked.map((s, i) => ({ ...s, index: i }));
+}
 // ── Duration band ───────────────────────────────────────────────────────────
 /**
  * Map a spoken target ("10 sec", "30 sec", "60 sec", "120 sec") to a soft
@@ -242,7 +302,7 @@ export function buildEffectiveGuidance(input) {
  */
 export function parseClipHuntPrompt(prompt) {
     const text = (prompt ?? "").trim();
-    const result = { windows: [], target_duration_sec: null, aspect: null, avoid_text: false };
+    const result = { windows: [], target_duration_sec: null, aspect: null, avoid_text: false, max_clips: null };
     if (!text)
         return result;
     const tc = "\\d{1,2}:\\d{2}(?::\\d{2})?(?:\\.\\d+)?";
@@ -277,6 +337,14 @@ export function parseClipHuntPrompt(prompt) {
         /(without|no)\s+(?:any\s+)?(captions?|subtitles?|(?:on[- ]?screen\s+)?text)/i.test(text) ||
             /\b(caption|text)-free\b/i.test(text) ||
             /no\s+text\s+on\s+screen/i.test(text);
+    // "10 clips" / "give me 20 raws" / "top 5 cuts" → a clip-count target.
+    const countMatch = /(\d{1,3})\s*(?:clips?|raws?|shots?|cuts?|segments?)\b/i.exec(text) ??
+        /\b(?:top|best|give me|find|get|pull|grab)\s+(\d{1,3})\b/i.exec(text);
+    if (countMatch) {
+        const n = Number(countMatch[1]);
+        if (Number.isFinite(n) && n > 0)
+            result.max_clips = Math.min(500, Math.round(n));
+    }
     return result;
 }
 // ── Wire normalization (API / SFN / tool payloads) ──────────────────────────
@@ -311,10 +379,22 @@ export function normalizeHuntSpec(raw) {
         spec.aspect = aspect;
     if (rec.crop_focus != null)
         spec.crop_focus = normalizeCropFocus(rec.crop_focus);
+    // Explicit true/false both honored so a caller can opt OUT of the avoid-text
+    // default; only an absent field falls through to applyHuntSpecDefaults.
     if (rec.avoid_text === true || rec.no_text === true || rec.no_captions === true)
         spec.avoid_text = true;
+    else if (rec.avoid_text === false || rec.no_text === false || rec.allow_text === true)
+        spec.avoid_text = false;
+    const maxClips = Number(rec.max_clips ?? rec.clip_count ?? rec.target_clip_count);
+    if (Number.isFinite(maxClips) && maxClips > 0)
+        spec.max_clips = Math.min(500, Math.round(maxClips));
+    const perTen = Number(rec.clips_per_10min ?? rec.clips_per_10_min ?? rec.density);
+    if (Number.isFinite(perTen) && perTen > 0)
+        spec.clips_per_10min = Math.min(200, perTen);
     if (typeof rec.source_url === "string" && rec.source_url.trim())
         spec.source_url = rec.source_url.trim();
+    if (typeof rec.folder_path === "string" && rec.folder_path.trim())
+        spec.folder_path = rec.folder_path.trim().slice(0, 500);
     return spec;
 }
 // ── misc ────────────────────────────────────────────────────────────────────

package/dist/src/services/clip-curation/index.js

@@ -6,12 +6,13 @@ export { ACTIVE_TAXONOMY_VERSION, MULTI_VALUE_CATEGORIES, getTaxonomy, sanitizeT
 export { BUILTIN_PRESETS, findBuiltinPreset } from "./presets.js";
 export { ClipModelClient, ClipGeminiClient, ClipEmbeddingClient, EMBEDDING_DIM, EMBEDDING_MODEL, EMBEDDING_MODELS, TAG_MODEL_BY_TIER, buildClipEmbeddingText, buildQueryPrompt, buildTaggingPrompt, normalize } from "./gemini.js";
 export { LocalAgentClipClient, detectLocalAgent, extractJsonObject } from "./local-agent.js";
-export { AVOID_TEXT_GUIDANCE, buildEffectiveGuidance, cropFilterFor, effectiveHuntDurationSec, fitScenesToDurationBand, normalizeAspect, normalizeCropFocus, normalizeHuntSpec, normalizeWindows, parseClipHuntPrompt, parseTimecode, parseTimeRanges, resolveDurationBand } from "./hunt.js";
+export { AVOID_TEXT_GUIDANCE, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, DEFAULT_CLIPS_PER_10_MIN, applyHuntSpecDefaults, buildEffectiveGuidance, capScenesEvenlyToCount, cropFilterFor, effectiveHuntDurationSec, fitScenesToDurationBand, normalizeAspect, normalizeCropFocus, normalizeHuntSpec, normalizeWindows, parseClipHuntPrompt, parseTimecode, parseTimeRanges, resolveDurationBand, resolveTargetClipCount } from "./hunt.js";
 export { detectScenes, extractClip, extractKeyframes, extractSceneAudio, extractThumbnail, hasFfmpeg, probeVideo, resolveFfmpeg, resolveFfprobe } from "./ffmpeg.js";
 export { cosineSimilarity, matchesCriteria, rankHits, scoreClip, searchClips, structuredMatchRatio } from "./query.js";
 export { estimateScanCostFromDuration, estimateScanCostFromScenes, formatCostEstimate } from "./cost.js";
 export { processSceneToClip, scanVideo } from "./scan.js";
 export { refineScenesWithGuidance } from "./refine.js";
+export { estimateMediaHeight, pickBestVideoMedia } from "./media-select.js";
 // Re-export ClipPreset-related helpers already covered by ./presets and ./types
 // via the wildcard exports above; nothing extra needed here.
 //# sourceMappingURL=index.js.map

package/dist/src/services/clip-curation/local-agent.js

@@ -67,7 +67,8 @@ export class LocalAgentClipClient {
             ...input.keyframePaths.map((p) => `- ${p}`),
             "",
             "Respond with ONLY the JSON object (no prose, no markdown fence) with keys:",
-            `subject, action, emotion, setting, composition, motion (string arrays), energy (string), audio_type (string array), transcript (string), description (string).`
+            `content_type, subject, action, emotion, setting, composition, motion (string arrays), energy (string), audio_type (string array), transcript (string), description (string).`,
+            `content_type is the KIND of shot — pick 1-2 of: talking_head, b_roll, product_shot, screen_recording, demo, reaction, interview, establishing, lifestyle, text_graphic.`
         ].join("\n");
         try {
             const raw = await this.runAgent(prompt);
@@ -75,7 +76,7 @@ export class LocalAgentClipClient {
             if (!parsed)
                 throw new Error("local agent returned no JSON");
             const withDefaults = {
-                subject: [], action: [], emotion: [], setting: [], composition: [], motion: [],
+                content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [],
                 energy: "medium", audio_type: [], transcript: "", description: "",
                 ...parsed
             };
@@ -92,7 +93,7 @@ export class LocalAgentClipClient {
             console.warn(`[clips] tag failed (local-agent/${this.kind}) @${input.scene.start_time_sec.toFixed(1)}s: ${message}`);
             return {
                 tags: {
-                    subject: [], action: [], emotion: [], setting: [], composition: [], motion: [],
+                    content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [],
                     energy: "medium",
                     audio_type: input.transcript ? ["dialogue"] : ["silence"],
                     transcript: input.transcript || ""

package/dist/src/services/clip-curation/media-select.js

@@ -0,0 +1,85 @@
+// Resolution-aware media selection for the RapidAPI social-video downloader.
+// The lookup returns several renditions per source (e.g. 360p / 720p / 1080p,
+// sometimes audio-only or HLS playlists). The clip library's quality is capped
+// by whatever source we ingest, so we must pick the HIGHEST-resolution playable
+// MP4 — not just the first one. Shared by the clip-scan Lambda (infra/lambda)
+// and the in-process serve/import path (src/app.ts) so both stay in lock-step.
+/** True when a candidate is a directly-downloadable MP4 (not HLS/DASH/audio). */
+function isPlayableMp4(m) {
+    if (!m.url)
+        return false;
+    if (m.videoAvailable === false)
+        return false;
+    if (m.type && !/video/i.test(m.type))
+        return false;
+    // HLS/DASH playlists can't be fetched as a single file — skip them.
+    if (/\.(m3u8|mpd)(\?|$)/i.test(m.url))
+        return false;
+    const ext = (m.extension ?? "").toLowerCase();
+    return ext === "mp4" || /\.mp4(\?|$)/i.test(m.url);
+}
+/** Any playable video (mp4 preferred, but a non-HLS fallback still beats nothing). */
+function isPlayableVideo(m) {
+    if (!m.url)
+        return false;
+    if (m.videoAvailable === false)
+        return false;
+    if (m.type && !/video/i.test(m.type))
+        return false;
+    if (/\.(m3u8|mpd)(\?|$)/i.test(m.url))
+        return false;
+    return true;
+}
+/**
+ * Estimate a rendition's vertical resolution (used as the ranking key). Reads an
+ * explicit height first, then parses the quality/label string. Returns 0 when
+ * nothing is parseable so labelled renditions always outrank unknown ones.
+ */
+export function estimateMediaHeight(m) {
+    const h = Number(m.height);
+    if (Number.isFinite(h) && h > 0)
+        return h;
+    const w = Number(m.width);
+    // Assume ~16:9 when only width is known (a coarse but monotonic proxy).
+    if (Number.isFinite(w) && w > 0)
+        return Math.round((w * 9) / 16);
+    const label = `${m.quality ?? ""} ${m.label ?? ""}`.toLowerCase();
+    // "1080p", "720 p", "2160p60", "1440P" → the leading pixel-height number.
+    const pMatch = label.match(/(\d{3,4})\s*p/);
+    if (pMatch)
+        return Number(pMatch[1]);
+    // "4k"/"2k" shorthand.
+    if (/\b4k|uhd\b/.test(label))
+        return 2160;
+    if (/\b2k\b/.test(label))
+        return 1440;
+    // Named tiers.
+    if (/full\s*hd|fhd/.test(label))
+        return 1080;
+    if (/\bhd\b/.test(label))
+        return 720;
+    if (/\bsd\b|low|small/.test(label))
+        return 360;
+    // A bare number (some providers give just "1080" / "720").
+    const nMatch = label.match(/\b(\d{3,4})\b/);
+    if (nMatch)
+        return Number(nMatch[1]);
+    return 0;
+}
+/**
+ * Pick the best rendition to ingest: the highest-resolution playable MP4, with a
+ * non-MP4 playable video as a last resort, else null. Ranking is stable so ties
+ * keep the provider's own ordering (usually its preferred rendition first).
+ */
+export function pickBestVideoMedia(medias) {
+    const list = Array.isArray(medias) ? medias : [];
+    const mp4s = list.filter(isPlayableMp4);
+    const pool = mp4s.length ? mp4s : list.filter(isPlayableVideo);
+    if (!pool.length)
+        return null;
+    // Decorate-sort-undecorate to keep it a stable sort by descending height.
+    return pool
+        .map((m, index) => ({ m, index, h: estimateMediaHeight(m) }))
+        .sort((a, b) => b.h - a.h || a.index - b.index)[0].m;
+}
+//# sourceMappingURL=media-select.js.map

package/dist/src/services/clip-curation/query.js

@@ -9,7 +9,7 @@ const DIALOGUE_AUDIO = new Set(["dialogue", "voiceover"]);
 /** How many categorical facets `criteria` constrains (used for the match-ratio soft score). */
 function constraintCount(criteria) {
     let n = 0;
-    for (const key of ["subject", "action", "emotion", "setting", "composition", "motion", "audio_type", "energy"]) {
+    for (const key of ["content_type", "subject", "action", "emotion", "setting", "composition", "motion", "audio_type", "energy"]) {
         if (Array.isArray(criteria[key]) && criteria[key].length)
             n++;
     }
@@ -31,6 +31,8 @@ function hasDialogue(tags) {
 export function matchesCriteria(clip, criteria) {
     const t = clip.tags;
     const anyOf = (have, want) => !want || want.length === 0 || want.some((w) => have.includes(w));
+    if (!anyOf(t.content_type ?? [], criteria.content_type))
+        return false;
     if (!anyOf(t.subject, criteria.subject))
         return false;
     if (!anyOf(t.action, criteria.action))
@@ -69,6 +71,8 @@ export function structuredMatchRatio(clip, criteria) {
     const t = clip.tags;
     let hit = 0;
     const anyOf = (have, want) => Boolean(want && want.length && want.some((w) => have.includes(w)));
+    if (anyOf(t.content_type ?? [], criteria.content_type))
+        hit++;
     if (anyOf(t.subject, criteria.subject))
         hit++;
     if (anyOf(t.action, criteria.action))

package/dist/src/services/clip-curation/refine.js

@@ -8,39 +8,63 @@
 import { mkdirSync, rmSync } from "node:fs";
 import path from "node:path";
 import { extractKeyframes } from "./ffmpeg.js";
-// Sending one small keyframe per scene; cap the montage so a single call stays
-// affordable/latency-bounded. Longer videos keep their raw segmentation (logged).
-const MAX_SCENES_FOR_REFINE = 60;
+// One small keyframe per scene; cap the montage per LLM call so a single request
+// stays affordable/latency-bounded. Longer videos are refined in consecutive
+// batches of this size (see MAX_REFINE_BATCHES) rather than skipping guidance.
+const MAX_SCENES_PER_BATCH = 60;
+// Bound total cost on very long sources: past this many batches we keep the raw
+// segmentation for the whole video (logged) instead of firing dozens of calls.
+const MAX_REFINE_BATCHES = 6;
 export async function refineScenesWithGuidance(input) {
     const { client, videoPath, scenes, guidancePrompt } = input;
     if (!guidancePrompt.trim() || scenes.length <= 1) {
         return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0 };
     }
-    if (scenes.length > MAX_SCENES_FOR_REFINE) {
+    const batchCount = Math.ceil(scenes.length / MAX_SCENES_PER_BATCH);
+    if (batchCount > MAX_REFINE_BATCHES) {
         return {
             scenes,
             refined: false,
             kept: scenes.length,
             dropped: 0,
             merged: 0,
-            note: `too many scenes (${scenes.length} > ${MAX_SCENES_FOR_REFINE}) for guided refinement — kept raw segmentation`
+            note: `too many scenes (${scenes.length} > ${MAX_SCENES_PER_BATCH * MAX_REFINE_BATCHES}) for guided refinement — kept raw segmentation`
         };
     }
     const framesDir = path.join(input.workDir, "refine-frames");
     mkdirSync(framesDir, { recursive: true });
     try {
-        // One small keyframe per candidate scene, in timeline order.
-        const frames = [];
-        for (const scene of scenes) {
-            const [p] = await extractKeyframes({ videoPath, scene, outDir: framesDir, count: 1, width: 200 });
-            if (p)
-                frames.push({ index: scene.index, path: p });
+        // Decide every scene, batching the LLM calls so a long source still gets
+        // guided keep/drop/merge (instead of falling back to raw cuts). Decisions
+        // are concatenated in timeline order so merge_with_previous still works
+        // across a batch boundary in rebuildScenes.
+        const keepDefault = () => ({ keep: true, merge_with_previous: false });
+        const decisions = [];
+        for (let b = 0; b < batchCount; b++) {
+            const batch = scenes.slice(b * MAX_SCENES_PER_BATCH, (b + 1) * MAX_SCENES_PER_BATCH);
+            // One small keyframe per candidate scene in this batch, in timeline order.
+            const frames = [];
+            for (const scene of batch) {
+                const [p] = await extractKeyframes({ videoPath, scene, outDir: framesDir, count: 1, width: 200 });
+                if (p)
+                    frames.push({ index: scene.index, path: p });
+            }
+            // Couldn't frame this batch — keep its scenes rather than dropping blind.
+            if (frames.length !== batch.length) {
+                for (let i = 0; i < batch.length; i++)
+                    decisions.push(keepDefault());
+                continue;
+            }
+            // Divide the overall clip target across batches by their share of scenes.
+            const batchTarget = input.targetClipCount && input.targetClipCount > 0
+                ? Math.max(1, Math.round((input.targetClipCount * batch.length) / scenes.length))
+                : undefined;
+            const batchDecisions = await askForDecisions(client, guidancePrompt, batch, frames, batchTarget);
+            for (let i = 0; i < batch.length; i++) {
+                decisions.push(batchDecisions?.[i] ?? keepDefault());
+            }
         }
-        if (frames.length !== scenes.length) {
-            return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0, note: "keyframe extraction incomplete" };
-        }
-        const decisions = await askForDecisions(client, guidancePrompt, scenes, frames);
-        if (!decisions || decisions.length === 0) {
+        if (decisions.length === 0) {
             return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0, note: "model returned no plan" };
         }
         return rebuildScenes(scenes, decisions);
@@ -57,20 +81,26 @@ export async function refineScenesWithGuidance(input) {
         }
     }
 }
-async function askForDecisions(client, guidancePrompt, scenes, frames) {
+async function askForDecisions(client, guidancePrompt, scenes, frames, targetClipCount) {
     const listing = scenes
         .map((s, i) => `Scene ${i}: ${s.start_time_sec.toFixed(1)}s–${s.end_time_sec.toFixed(1)}s (${s.duration_sec.toFixed(1)}s)`)
         .join("\n");
+    const target = targetClipCount && targetClipCount > 0 ? Math.round(targetClipCount) : null;
     const prompt = [
-        `You are curating clips from a long video for this goal: "${guidancePrompt.trim()}".`,
+        `You are curating short clips from a long video for this exact goal: "${guidancePrompt.trim()}".`,
         `There are ${scenes.length} candidate scenes, shown as ${scenes.length} keyframes below in timeline order (one per scene).`,
         listing,
         "",
         "For EACH scene (in order) decide:",
-        "- keep: true if the scene is relevant/useful for the goal, false to drop it.",
+        "- keep: true ONLY if the scene clearly and directly serves the goal above; when in doubt, drop it (keep:false). Follow the goal STRICTLY — do not keep loosely-related or generic filler.",
         "- merge_with_previous: true if this scene continues the previous KEPT scene and they should be ONE clip (e.g. a single continuous action split by a minor cut). Otherwise false.",
         "",
-        `Return exactly ${scenes.length} decisions, in the same order as the scenes. Be selective — dropping off-topic scenes and merging fragmented ones is the point.`
+        "UNIQUENESS (important): the output must be DISTINCT clips — no near-duplicates. If several scenes show essentially the same shot (same subject, framing, action, and setting), KEEP ONLY THE SINGLE BEST ONE and set keep:false for the visually-redundant rest. Prefer variety across the kept clips.",
+        target
+            ? `Aim for roughly ${target} kept clip${target === 1 ? "" : "s"} total (a few more or fewer is fine) — keep the strongest, most distinct scenes and drop the weakest/most repetitive.`
+            : "Be selective — dropping off-topic and duplicate scenes and merging fragmented ones is the point.",
+        "",
+        `Return exactly ${scenes.length} decisions, in the same order as the scenes.`
     ].join("\n");
     // The client owns the model call (API providers via structured output, the
     // local devcli agent via CLI) — refine only builds the prompt and rebuilds

package/dist/src/services/clip-curation/scan.js

@@ -9,7 +9,7 @@ import { createIdV7 } from "../../lib/ids.js";
 import { ACTIVE_TAXONOMY_VERSION } from "./taxonomy.js";
 import { buildClipEmbeddingText } from "./gemini.js";
 import { detectScenes, extractClip, extractKeyframes, extractSceneAudio, extractThumbnail, probeVideo } from "./ffmpeg.js";
-import { cropFilterFor, fitScenesToDurationBand, normalizeWindows } from "./hunt.js";
+import { capScenesEvenlyToCount, cropFilterFor, fitScenesToDurationBand, normalizeWindows } from "./hunt.js";
 import { refineScenesWithGuidance } from "./refine.js";
 /** Turn one scene into a Clip. Throws only on unrecoverable extraction failure. */
 export async function processSceneToClip(input) {
@@ -114,20 +114,27 @@ export async function scanVideo(opts) {
             ...opts.sceneOptions
         }), band);
     // Prompt-guided segmentation: let the guidance reshape which scenes become
-    // clips (keep/drop/merge) before we spend tagging tokens on them.
+    // clips (keep/drop/merge/dedup) before we spend tagging tokens on them.
     if (opts.ctx.guidancePrompt?.trim() && opts.ctx.refineSegmentation !== false) {
         const refined = await refineScenesWithGuidance({
             client: opts.ctx.client,
             videoPath: opts.videoPath,
             scenes,
             guidancePrompt: opts.ctx.guidancePrompt,
-            workDir: opts.ctx.workDir
+            workDir: opts.ctx.workDir,
+            targetClipCount: opts.targetClipCount
         });
         // Refine merges can exceed the band max — re-enforce it (fit never merges
         // across the gaps refine's drops created, only contiguous spans).
         scenes = fitScenesToDurationBand(refined.scenes, band);
         opts.onRefine?.(refined);
     }
+    // Deterministic count/uniqueness cap: if more scenes survived than the target
+    // (refine skipped >60 scenes, or the model kept more than asked), keep an
+    // evenly-spaced — hence less duplicative — subset.
+    if (opts.targetClipCount && opts.targetClipCount > 0) {
+        scenes = capScenesEvenlyToCount(scenes, opts.targetClipCount);
+    }
     const sourceVideoId = opts.sourceVideoId ?? createIdV7("srcvid");
     const sourceFilename = opts.sourceFilename ?? path.basename(opts.videoPath);
     const concurrency = Math.max(1, opts.concurrency ?? 3);

package/dist/src/services/clip-curation/taxonomy.js

@@ -16,6 +16,7 @@ export function getTaxonomy(version = ACTIVE_TAXONOMY_VERSION) {
 }
 /** The multi-valued categorical fields (everything except `energy`, which is single). */
 export const MULTI_VALUE_CATEGORIES = [
+    "content_type",
     "subject",
     "action",
     "emotion",
@@ -27,7 +28,7 @@ export const MULTI_VALUE_CATEGORIES = [
 /**
  * Clamp an LLM-produced tag object to the controlled vocabulary: drop any value
  * not in the taxonomy so a hallucinated tag can never poison the index. Returns
- * a fully-populated ClipTags-shaped object (missing categories become []).
+ * a fully-populated RawTags-shaped object (missing categories become []).
  */
 export function sanitizeTagValues(raw, version = ACTIVE_TAXONOMY_VERSION) {
     const tax = getTaxonomy(version);
@@ -49,6 +50,7 @@ export function sanitizeTagValues(raw, version = ACTIVE_TAXONOMY_VERSION) {
         return allowed.includes(s) ? s : fallback;
     };
     return {
+        content_type: clampList(raw.content_type, cats.content_type),
         subject: clampList(raw.subject, cats.subject),
         action: clampList(raw.action, cats.action),
         emotion: clampList(raw.emotion, cats.emotion),

package/dist/src/services/clip-curation/taxonomy.v1.json

@@ -1,7 +1,19 @@
 {
     "version": "v1",
-    "notes": "Controlled vocabulary for VidFarm clip curation. Start small (~50 tags); expand based on real usage. Clips store the version they were tagged against so the vocab can evolve without breaking existing clips.",
+    "notes": "Controlled vocabulary for VidFarm clip curation. Start small (~50 tags); expand based on real usage. Clips store the version they were tagged against so the vocab can evolve without breaking existing clips. content_type was added additively to v1 (2026-07-08) — clips tagged before then simply carry no content_type until re-scanned.",
     "categories": {
+        "content_type": [
+            "talking_head",
+            "b_roll",
+            "product_shot",
+            "screen_recording",
+            "demo",
+            "reaction",
+            "interview",
+            "establishing",
+            "lifestyle",
+            "text_graphic"
+        ],
         "subject": [
             "person",
             "single_speaker",

package/dist/src/services/clip-records.js

@@ -3,7 +3,7 @@
 // entity_type tag, local-dynamo shim in `serve` mode). Same Clip shape as the
 // devcli SQLite store so users move between local and cloud without lock-in.
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { DeleteCommand, DynamoDBDocumentClient, GetCommand, PutCommand, QueryCommand } from "@aws-sdk/lib-dynamodb";
+import { DeleteCommand, DynamoDBDocumentClient, GetCommand, PutCommand, QueryCommand, UpdateCommand } from "@aws-sdk/lib-dynamodb";
 import { config } from "../config.js";
 import { createLocalDynamoClient } from "./local-dynamo.js";
 import { BUILTIN_PRESETS } from "./clip-curation/index.js";
@@ -102,6 +102,47 @@ export class ClipRecordsService {
     async deleteClip(owner, clipId) {
         await dynamodb.send(new DeleteCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: clipSk(clipId) } }));
     }
+    /**
+     * Move a clip between virtual Raws folders. Partial update (doesn't rewrite
+     * the embedding vector). `folderPath` is stored normalized; "" = raws root.
+     */
+    async updateClipFolder(owner, clipId, folderPath) {
+        await dynamodb.send(new UpdateCommand({
+            TableName: requireMainTableName(),
+            Key: { pk: clipPk(owner), sk: clipSk(clipId) },
+            UpdateExpression: "SET folder_path = :fp",
+            ConditionExpression: "attribute_exists(pk)",
+            ExpressionAttributeValues: { ":fp": folderPath }
+        }));
+    }
+    /**
+     * Rename/move a whole Raws folder: re-point every clip whose folder_path is
+     * `fromFolder` OR nested beneath it onto `toFolder` (prefix-preserving), so a
+     * folder rename carries its subfolders too. Returns the count moved.
+     * Paths are compared normalized (trimmed, no leading/trailing slashes).
+     */
+    async moveClipsFolder(owner, fromFolder, toFolder) {
+        const norm = (v) => String(v ?? "").split("/").map((s) => s.trim()).filter(Boolean).join("/");
+        const from = norm(fromFolder);
+        const to = norm(toFolder);
+        if (!from || from === to)
+            return 0;
+        const clips = await this.listClips(owner, { limit: 5000 });
+        let moved = 0;
+        for (const clip of clips) {
+            const fp = norm(clip.folder_path);
+            let next = null;
+            if (fp === from)
+                next = to;
+            else if (fp.startsWith(from + "/"))
+                next = to + fp.slice(from.length);
+            if (next != null) {
+                await this.updateClipFolder(owner, clip.clip_id, next);
+                moved += 1;
+            }
+        }
+        return moved;
+    }
     // ── Presets ──────────────────────────────────────────────────────────────
     async listPresets(owner) {
         const res = await dynamodb.send(new QueryCommand({

package/dist/src/services/clip-search.js

@@ -8,21 +8,51 @@ const vectorIndex = resolveClipVectorIndex((owner) => clipRecords.listClipsWithE
 export async function searchUserClips(owner, input) {
     const limit = input.limit ?? 20;
     const all = await clipRecords.listClips(owner, { limit: 5000 });
-    const structured = all.filter((c) => matchesCriteria(c, input.criteria));
-    if (structured.length > 0) {
-        // Semantic re-rank the survivors (embeddings already ride on the records).
-        const hits = structured.map((c) => scoreClip(c, input.criteria, input.queryEmbedding, false));
-        return rankHits(hits, limit);
+    // ── No semantic signal → pure structured (hard) filter. ──────────────────
+    if (!input.queryEmbedding) {
+        const structured = all.filter((c) => matchesCriteria(c, input.criteria));
+        return rankHits(structured.map((c) => scoreClip(c, input.criteria, undefined, false)), limit);
     }
-    // No structured match — relax to a semantic-only pass via the vector index.
-    if (input.queryEmbedding) {
-        const knn = await vectorIndex.query(owner, input.queryEmbedding, Math.max(limit * 5, 50));
-        const byId = new Map(all.map((c) => [c.clip_id, c]));
-        const pool = knn.map((h) => byId.get(h.clip_id)).filter((c) => Boolean(c));
-        const hits = pool.map((c) => scoreClip(c, input.criteria, input.queryEmbedding, true));
-        return rankHits(hits, limit);
+    // ── Semantic query → SEMANTIC-FIRST hybrid. ──────────────────────────────
+    // The old flow hard-AND-filtered by the (often auto-derived) categorical
+    // criteria BEFORE looking at embeddings, so the true nearest-neighbor clips
+    // were silently excluded whenever the NL→criteria step over-constrained —
+    // the "search doesn't work" symptom. Now: retrieve the nearest neighbors over
+    // the WHOLE library from the vector index, and only UNION in exact structured
+    // matches when the criteria actually constrains something. Everything is
+    // scored with the soft structured boost (`relaxed`), so an exact facet match
+    // floats a clip up without ever gating a strong semantic match out.
+    const knn = await vectorIndex.query(owner, input.queryEmbedding, Math.max(limit * 5, 50));
+    const byId = new Map(all.map((c) => [c.clip_id, c]));
+    const pool = new Map();
+    for (const h of knn) {
+        const c = byId.get(h.clip_id);
+        if (c)
+            pool.set(c.clip_id, c);
     }
-    return [];
+    if (hasStructuredConstraints(input.criteria)) {
+        for (const c of all)
+            if (matchesCriteria(c, input.criteria))
+                pool.set(c.clip_id, c);
+    }
+    // Fallback: an empty vector index (e.g. clips scanned without an embedding
+    // provider) yields no neighbors — degrade to the whole library so keyword /
+    // structured scoring still returns something rather than nothing.
+    const candidates = pool.size > 0 ? [...pool.values()] : all;
+    const hits = candidates.map((c) => scoreClip(c, input.criteria, input.queryEmbedding, true));
+    return rankHits(hits, limit);
+}
+/** True when the criteria constrains any categorical/duration/boolean facet (not just free-text). */
+function hasStructuredConstraints(criteria) {
+    for (const [key, value] of Object.entries(criteria)) {
+        if (key === "semantic_text")
+            continue;
+        if (value == null)
+            continue;
+        if (Array.isArray(value) ? value.length > 0 : true)
+            return true;
+    }
+    return false;
 }
 export { vectorIndex };
 /**