@officexapp/vidfarm-devcli 0.21.10

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

@@ -0,0 +1,165 @@
+// Prompt-guided segmentation. ffmpeg gives us candidate scene cuts by visual
+// change; this optional pass lets a user's guidance prompt actually reshape HOW
+// the video is clipped — one multimodal LLM call sees a keyframe per candidate
+// scene and decides, per scene, keep/drop (is it relevant to the goal?) and
+// merge-with-previous (does it continue the prior kept scene as one clip?). We
+// then rebuild the scene list from those decisions. Falls back to the raw scenes
+// on any mismatch/error so a scan never breaks.
+import { mkdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { extractKeyframes } from "./ffmpeg.js";
+// 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 = 30;
+export async function refineScenesWithGuidance(input) {
+    const { client, videoPath, scenes, guidancePrompt } = input;
+    if (!guidancePrompt.trim() || scenes.length === 0) {
+        return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0 };
+    }
+    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_PER_BATCH * MAX_REFINE_BATCHES}) for guided refinement — kept raw segmentation`
+        };
+    }
+    const framesDir = path.join(input.workDir, "refine-frames");
+    mkdirSync(framesDir, { recursive: true });
+    try {
+        // 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);
+            if (!batchDecisions)
+                throw new Error("model returned no refinement plan");
+            for (let i = 0; i < batch.length; i++) {
+                decisions.push(batchDecisions?.[i] ?? keepDefault());
+            }
+        }
+        if (decisions.length === 0) {
+            return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0, note: "model returned no plan" };
+        }
+        return rebuildScenes(scenes, decisions);
+    }
+    catch (error) {
+        // The provider/model call (or keyframe prep) threw. Keep the raw scenes so
+        // a scan CAN still proceed, but carry the real reason up as providerError
+        // so the caller can decide to fail loudly with a provider-attributed
+        // message instead of silently ignoring the user's guidance prompt.
+        const providerError = error instanceof Error ? error.message : String(error);
+        return {
+            scenes,
+            refined: false,
+            kept: scenes.length,
+            dropped: 0,
+            merged: 0,
+            note: "refinement failed; using raw scenes",
+            providerError
+        };
+    }
+    finally {
+        try {
+            rmSync(framesDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+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 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 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.",
+        "",
+        "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
+    // the scene list from the decisions.
+    return client.decideScenes({
+        prompt,
+        imagePaths: frames.map((f) => f.path),
+        maxOutputTokens: Math.max(1000, scenes.length * 40)
+    });
+}
+export function rebuildScenes(scenes, decisions) {
+    const out = [];
+    let dropped = 0;
+    let merged = 0;
+    for (let i = 0; i < scenes.length; i++) {
+        // Align by index; a missing decision (short array) defaults to keep.
+        const d = decisions[i] ?? { keep: true, merge_with_previous: false };
+        if (!d.keep) {
+            dropped++;
+            continue;
+        }
+        const previous = out[out.length - 1];
+        const isAdjacent = previous
+            ? Math.abs(previous.end_time_sec - scenes[i].start_time_sec) <= 0.05
+            : false;
+        if (d.merge_with_previous && previous && isAdjacent) {
+            // Extend only an ADJACENT previous kept clip. A dropped scene creates a
+            // real timeline gap; bridging that gap would silently put the rejected
+            // footage back into the exported raw.
+            previous.end_time_sec = scenes[i].end_time_sec;
+            previous.duration_sec = round3(previous.end_time_sec - previous.start_time_sec);
+            merged++;
+            continue;
+        }
+        out.push({ ...scenes[i], index: out.length });
+    }
+    // An empty plan is a valid strict-prompt result. Silently restoring every
+    // scene here would completely ignore the user's request.
+    if (out.length === 0) {
+        return { scenes: [], refined: true, kept: 0, dropped, merged };
+    }
+    return { scenes: out, refined: true, kept: out.length, dropped, merged };
+}
+function round3(n) {
+    return Math.round(n * 1000) / 1000;
+}
+//# sourceMappingURL=refine.js.map

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

@@ -0,0 +1,189 @@
+// Scan orchestration shared by devcli and cloud. `processSceneToClip` turns ONE
+// detected scene into a full Clip record (extract clip/keyframes/thumb/audio →
+// Gemini tag+transcribe → embed). devcli calls it in a bounded pool; a cloud
+// Step Functions Map state calls it once per scene. Persistence is the caller's
+// job (SQLite vs DynamoDB+S3) — this stays storage-agnostic.
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { createIdV7 } from "../../lib/ids.js";
+import { ACTIVE_TAXONOMY_VERSION } from "./taxonomy.js";
+import { buildClipEmbeddingText } from "./gemini.js";
+import { detectScenes, extractAudioClip, extractClip, extractKeyframes, extractSceneAudio, extractThumbnail, extractWaveformThumbnail, probeVideo } from "./ffmpeg.js";
+import { applyUserContentTypeHints, 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) {
+    const { ctx, videoPath, scene } = input;
+    const framesDir = path.join(ctx.workDir, "frames");
+    const audioDir = path.join(ctx.workDir, "audio");
+    mkdirSync(ctx.clipsDir, { recursive: true });
+    mkdirSync(ctx.thumbsDir, { recursive: true });
+    const clipId = createIdV7("clip");
+    const cropFilter = ctx.crop ? cropFilterFor(ctx.crop.aspect, ctx.crop.focus) : null;
+    // 1. Keyframes for visual tagging (small, low-res), framed like the output.
+    const keyframePaths = await extractKeyframes({
+        videoPath,
+        scene,
+        outDir: framesDir,
+        count: ctx.framesPerScene ?? 2,
+        cropFilter
+    });
+    // 2. Per-scene audio for ASR (one combined tag+transcribe call).
+    let audioPath;
+    if (ctx.includeAudio ?? true) {
+        const a = await extractSceneAudio({
+            videoPath,
+            scene,
+            outPath: path.join(audioDir, `scene-${scene.index}.mp3`)
+        });
+        audioPath = a ?? undefined;
+    }
+    // 3. Tag (+ transcription when audio present on Gemini), biased by the optional guidance prompt.
+    const tagResult = await ctx.client.tagScene({
+        keyframePaths,
+        transcript: "",
+        audioPath,
+        scene,
+        guidancePrompt: ctx.guidancePrompt
+    });
+    const tags = applyUserContentTypeHints(tagResult.tags, ctx.userNotes, ctx.client.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION);
+    // 4. Cut the clip + thumbnail. Audio-only hunts emit an .m4a (no video) with a
+    //    waveform PNG thumbnail; ordinary hunts emit an .mp4 cropped to the target
+    //    aspect when requested.
+    const audioOnly = ctx.audioOnly === true;
+    const clipLocal = path.join(ctx.clipsDir, `${clipId}.${audioOnly ? "m4a" : "mp4"}`);
+    const thumbLocal = path.join(ctx.thumbsDir, `${clipId}.${audioOnly ? "png" : "jpg"}`);
+    let extractDetail = "";
+    if (audioOnly) {
+        const audioOk = await extractAudioClip({ videoPath, scene, outPath: clipLocal, onError: (detail) => (extractDetail = detail) });
+        if (!audioOk) {
+            throw new Error(`ffmpeg failed to extract audio for scene @${scene.start_time_sec}s${extractDetail ? ` — ${extractDetail}` : ""}`);
+        }
+        await extractWaveformThumbnail({ videoPath, scene, outPath: thumbLocal }).catch(() => false);
+    }
+    else {
+        const clipOk = await extractClip({
+            videoPath,
+            scene,
+            outPath: clipLocal,
+            reencode: ctx.reencodeClips !== false,
+            cropFilter,
+            onError: (detail) => (extractDetail = detail)
+        });
+        if (!clipOk) {
+            throw new Error(`ffmpeg failed to extract clip for scene @${scene.start_time_sec}s${extractDetail ? ` — ${extractDetail}` : ""}`);
+        }
+        await extractThumbnail({ videoPath, scene, outPath: thumbLocal, cropFilter });
+    }
+    // 5. Embed the document text for semantic search (skipped when the client can't embed).
+    const embeddingText = buildClipEmbeddingText(tags, tagResult.description, ctx.userNotes);
+    let embedding;
+    if (ctx.client.canEmbed) {
+        [embedding] = await ctx.client.embedDocuments([embeddingText]);
+    }
+    const clip = {
+        clip_id: clipId,
+        source_video_id: input.sourceVideoId,
+        source_filename: input.sourceFilename,
+        start_time_sec: scene.start_time_sec,
+        end_time_sec: scene.end_time_sec,
+        duration_sec: scene.duration_sec,
+        file_path: ctx.clipStoredPath ? ctx.clipStoredPath(clipId, clipLocal) : clipLocal,
+        thumbnail_path: ctx.thumbStoredPath ? ctx.thumbStoredPath(clipId, thumbLocal) : thumbLocal,
+        tags,
+        description: tagResult.description,
+        embedding_text: embeddingText,
+        embedding,
+        taxonomy_version: ctx.client.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION,
+        tier: ctx.client.tier,
+        provider: ctx.client.provider,
+        embedding_model: ctx.client.embeddingModelId ?? undefined,
+        aspect: !audioOnly && cropFilter && ctx.crop ? ctx.crop.aspect : undefined,
+        media_kind: audioOnly ? "audio" : undefined,
+        user_notes: ctx.userNotes?.trim() || undefined,
+        owner_id: input.ownerId,
+        created_at: new Date().toISOString()
+    };
+    return clip;
+}
+/**
+ * Run the full local scan pipeline for one video with a bounded concurrency
+ * pool. (Cloud replaces this loop with a Step Functions Map over the scenes.)
+ */
+export async function scanVideo(opts) {
+    const probe = opts.probe ?? (await probeVideo(opts.videoPath));
+    const windows = normalizeWindows(opts.windows, probe.duration_sec);
+    const band = opts.durationBand ?? null;
+    // Keep detected shots separate until AFTER prompt refinement. This is
+    // important: judging a multi-shot duration span from one midpoint frame can
+    // approve unrelated opening/closing footage or miss text overlays in them.
+    let scenes = opts.scenes ??
+        await detectScenes(opts.videoPath, {
+            durationSec: probe.duration_sec,
+            windows,
+            ...opts.sceneOptions
+        });
+    // Prompt-guided segmentation: let the guidance reshape which scenes become
+    // 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,
+            targetClipCount: opts.targetClipCount
+        });
+        if (refined.providerError) {
+            // The guidance step failed because the AI provider/model itself errored
+            // (e.g. a text-only key that can't do the vision + structured selection).
+            // Tagging needs the same capability, so surface the provider's own reason
+            // — it's an AI-provider issue, not Vidfarm — instead of pressing on.
+            throw new Error(refined.providerError);
+        }
+        scenes = refined.scenes;
+        opts.onRefine?.(refined);
+    }
+    // Assemble prompt-approved, contiguous shots into useful clip durations.
+    // fitScenesToDurationBand never crosses a dropped gap.
+    scenes = fitScenesToDurationBand(scenes, band);
+    // 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);
+    const clips = [];
+    let cursor = 0;
+    let completed = 0;
+    async function worker() {
+        while (cursor < scenes.length) {
+            const idx = cursor++;
+            const scene = scenes[idx];
+            try {
+                const clip = await processSceneToClip({
+                    ctx: opts.ctx,
+                    videoPath: opts.videoPath,
+                    scene,
+                    sourceVideoId,
+                    sourceFilename,
+                    ownerId: opts.ownerId
+                });
+                clips.push(clip);
+                completed++;
+                await opts.onClip?.(clip, completed, scenes.length);
+            }
+            catch (error) {
+                opts.onError?.(scene, error);
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, scenes.length) }, () => worker()));
+    // Preserve timeline order for a stable library.
+    clips.sort((a, b) => a.start_time_sec - b.start_time_sec);
+    return { source_video_id: sourceVideoId, probe, scenes, clips };
+}
+//# sourceMappingURL=scan.js.map

package/dist/src/services/clip-curation/source-naming.js

@@ -0,0 +1,131 @@
+// Shared naming for imported raw video sources. The historical bug: a raw's
+// display name + folder slug were derived by taking the last path segment of the
+// source URL, so `https://youtube.com/watch?v=abc` collapsed to the useless
+// folder "watch" (shared by every YouTube import). This resolves a human name
+// with a sane preference order and, when a URL yields only routing words, falls
+// back to a uuidv7 so each source still lands in its own stable folder.
+//
+// Shared by the clip-scan Lambda (infra/lambda) and the in-process serve/import
+// path (src/app.ts) so both stay in lock-step.
+import { uuidv7 } from "../../lib/ids.js";
+// URL path segments that are routing words, not content names. Deriving a name
+// from a URL must never keep one of these on its own (youtube.com/watch,
+// tiktok.com/@user/video/<id> → the <id> is what matters, not "video").
+const JUNK_URL_SEGMENTS = new Set([
+    "watch", "embed", "shorts", "short", "video", "videos", "v", "e", "p",
+    "index", "share", "status", "reel", "reels", "story", "stories", "play",
+    "player", "view", "download", "dl", "media", "source", "file", "files",
+    "stream", "streams", "live", "tv", "feed", "home", "www", "clip", "clips",
+    "post", "posts", "photo", "photos", "id", "intl", "m", "amp", "mobile", ""
+]);
+// Generic filenames our own fallbacks produce — treated as "no real name" so the
+// resolver keeps looking (URL-derived → uuidv7) rather than naming a folder
+// "source" / "video".
+const GENERIC_NAMES = new Set([
+    "source", "video", "download", "media", "watch", "index", "clip", "movie",
+    "untitled", "file", "output", "temp", "tmp"
+]);
+function stripExtension(name) {
+    return name.replace(/\.[a-z0-9]{1,5}$/i, "");
+}
+function decodeSegment(seg) {
+    try {
+        return decodeURIComponent(seg);
+    }
+    catch {
+        return seg;
+    }
+}
+/** True when a candidate name is empty, a route word, or one of our generic fallbacks. */
+function isMeaninglessName(name) {
+    const trimmed = stripExtension(name.trim()).toLowerCase();
+    if (!trimmed)
+        return true;
+    if (GENERIC_NAMES.has(trimmed))
+        return true;
+    if (JUNK_URL_SEGMENTS.has(trimmed))
+        return true;
+    return false;
+}
+/**
+ * Derive a human-friendly name from a media URL, or null when the URL yields
+ * only routing words. Examples:
+ *   youtube.com/watch?v=abc      → "youtube-abc"
+ *   youtu.be/abc                 → "youtube-abc"
+ *   tiktok.com/@user/video/7523  → "tiktok-7523"
+ *   cdn.example.com/my-clip.mp4  → "my-clip"
+ *   example.com/watch            → null
+ */
+export function deriveMediaNameFromUrl(rawUrl) {
+    let u;
+    try {
+        u = new URL(rawUrl);
+    }
+    catch {
+        return null;
+    }
+    const host = u.hostname.replace(/^www\./, "").toLowerCase();
+    // YouTube: the stable video id beats any path segment.
+    if (host === "youtube.com" || host.endsWith(".youtube.com") || host === "youtube-nocookie.com") {
+        const vid = u.searchParams.get("v");
+        if (vid)
+            return `youtube-${vid}`;
+    }
+    if (host === "youtu.be") {
+        const seg = u.pathname.split("/").filter(Boolean)[0];
+        if (seg)
+            return `youtube-${decodeSegment(seg)}`;
+    }
+    const segments = u.pathname.split("/").filter(Boolean);
+    // Direct-file URL: the basename (sans extension) is usually the real name.
+    const last = segments[segments.length - 1];
+    if (last) {
+        const base = stripExtension(decodeSegment(last));
+        if (base && !JUNK_URL_SEGMENTS.has(base.toLowerCase())) {
+            return base;
+        }
+    }
+    // Otherwise walk back for the last non-routing segment (e.g. a TikTok/X post
+    // id) and label it with the host so it reads as "<site>-<id>".
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const seg = segments[i];
+        if (!JUNK_URL_SEGMENTS.has(seg.toLowerCase())) {
+            const hostLabel = host.split(".")[0] || "video";
+            return `${hostLabel}-${stripExtension(decodeSegment(seg))}`;
+        }
+    }
+    return null;
+}
+/** Canonical single-segment Raws folder slug, or null when the input is empty. */
+export function slugifyFolderName(value) {
+    const slug = String(value ?? "")
+        .toLowerCase()
+        .replace(/\.[a-z0-9]+$/i, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+    return slug || null;
+}
+/**
+ * Resolve the display name + folder slug for an imported raw source. Preference:
+ *   1. the real media title (page metadata / RapidAPI lookup)
+ *   2. an explicit or uploaded filename
+ *   3. a name derived from the source URL (youtube-<id>, the file basename, …)
+ *   4. a uuidv7 — so a source with no meaningful name anywhere still gets its own
+ *      stable, unique folder instead of a shared "watch"/"source" bucket.
+ */
+export function resolveRawSourceName(input) {
+    const title = (input.title ?? "").trim();
+    const provided = (input.providedFilename ?? "").trim();
+    const fromUrl = input.sourceUrl ? deriveMediaNameFromUrl(input.sourceUrl) : null;
+    const displayName = (title && !isMeaninglessName(title) ? title : "") ||
+        (provided && !isMeaninglessName(provided) ? stripExtension(provided) : "") ||
+        (fromUrl && !isMeaninglessName(fromUrl) ? fromUrl : "");
+    if (displayName) {
+        return { displayName, folderSlug: slugifyFolderName(displayName) || uuidv7() };
+    }
+    // No meaningful name anywhere — mint a stable unique folder/name.
+    const id = uuidv7();
+    return { displayName: `import-${id}`, folderSlug: id };
+}
+//# sourceMappingURL=source-naming.js.map

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

@@ -0,0 +1,73 @@
+// Versioned tag taxonomy loader. The vocabulary lives in taxonomy.v1.json so it
+// can evolve independently; clips record the version they were tagged with
+// (Clip.taxonomy_version) so old clips stay valid when the vocab grows.
+import taxonomyV1 from "./taxonomy.v1.json" with { type: "json" };
+const REGISTRY = {
+    v1: taxonomyV1
+};
+export const ACTIVE_TAXONOMY_VERSION = "v1";
+/** Get a taxonomy by version (defaults to the active one). */
+export function getTaxonomy(version = ACTIVE_TAXONOMY_VERSION) {
+    const found = REGISTRY[version];
+    if (!found) {
+        throw new Error(`Unknown taxonomy version "${version}" (have: ${Object.keys(REGISTRY).join(", ")})`);
+    }
+    return found;
+}
+/** The multi-valued categorical fields (everything except `energy`, which is single). */
+export const MULTI_VALUE_CATEGORIES = [
+    "content_type",
+    "subject",
+    "action",
+    "emotion",
+    "setting",
+    "composition",
+    "motion",
+    "audio_type"
+];
+/**
+ * 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 RawTags-shaped object (missing categories become []).
+ */
+export function sanitizeTagValues(raw, version = ACTIVE_TAXONOMY_VERSION) {
+    const tax = getTaxonomy(version);
+    const cats = tax.categories;
+    const clampList = (values, allowed) => {
+        if (!Array.isArray(values))
+            return [];
+        const set = new Set(allowed);
+        const out = [];
+        for (const v of values) {
+            const s = String(v).trim().toLowerCase().replace(/\s+/g, "_");
+            if (set.has(s) && !out.includes(s))
+                out.push(s);
+        }
+        return out;
+    };
+    const clampOne = (value, allowed, fallback) => {
+        const s = String(value ?? "").trim().toLowerCase().replace(/\s+/g, "_");
+        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),
+        setting: clampList(raw.setting, cats.setting),
+        composition: clampList(raw.composition, cats.composition),
+        motion: clampList(raw.motion, cats.motion),
+        energy: clampOne(raw.energy, cats.energy, "medium"),
+        audio_type: clampList(raw.audio_type, cats.audio_type)
+    };
+}
+/** A compact, prompt-friendly rendering of the vocabulary to inline in the tagging prompt. */
+export function taxonomyForPrompt(version = ACTIVE_TAXONOMY_VERSION) {
+    const tax = getTaxonomy(version);
+    const lines = [];
+    for (const [cat, values] of Object.entries(tax.categories)) {
+        lines.push(`- ${cat}: ${values.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=taxonomy.js.map

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

@@ -0,0 +1,102 @@
+{
+    "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. 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",
+            "multiple_people",
+            "hands",
+            "product",
+            "screen_ui",
+            "text_on_screen",
+            "animal",
+            "food",
+            "vehicle",
+            "no_subject"
+        ],
+        "action": [
+            "talking",
+            "laughing",
+            "looking_at_camera",
+            "reacting",
+            "pointing",
+            "typing",
+            "hands_on_keyboard",
+            "walking",
+            "eating",
+            "holding_product",
+            "unboxing",
+            "gesturing",
+            "still"
+        ],
+        "emotion": [
+            "amused",
+            "surprised",
+            "excited",
+            "confused",
+            "deadpan",
+            "exasperated",
+            "serious",
+            "neutral",
+            "sad",
+            "angry"
+        ],
+        "setting": [
+            "indoor",
+            "outdoor",
+            "office",
+            "home",
+            "studio",
+            "kitchen",
+            "car",
+            "nature",
+            "urban",
+            "abstract_or_graphic"
+        ],
+        "composition": [
+            "close_up",
+            "medium_shot",
+            "wide_shot",
+            "centered",
+            "off_center",
+            "over_the_shoulder",
+            "top_down",
+            "product_shot"
+        ],
+        "motion": [
+            "static",
+            "low",
+            "medium",
+            "high",
+            "camera_shake",
+            "pan_or_tilt",
+            "zoom"
+        ],
+        "energy": [
+            "low",
+            "medium",
+            "high"
+        ],
+        "audio_type": [
+            "dialogue",
+            "voiceover",
+            "music",
+            "sfx",
+            "ambient",
+            "silence"
+        ]
+    }
+}

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

@@ -0,0 +1,7 @@
+// Shared data model for VidFarm clip curation — the "third pillar" library
+// (viral DNA + HTML formats + CLIPS). One scanned scene becomes one Clip
+// record. This shape is IDENTICAL across the two deployment targets
+// (devcli/local SQLite and AWS DynamoDB) so users can move between local and
+// cloud without lock-in. See drafts/clip-hunting/vidfarm_clip_curation_handoff.md.
+export {};
+//# sourceMappingURL=types.js.map