@mevdragon/vidfarm-devcli 0.7.1 → 0.9.0

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

@@ -0,0 +1,59 @@
+{
+    "version": "v1",
+    "presets": [
+        {
+            "preset_id": "preset_funny_reactions",
+            "name": "funny reaction gifs",
+            "description": "Short single-subject reactions facing the camera — the raw material for reaction cutaways.",
+            "criteria": {
+                "emotion": ["surprised", "amused", "deadpan", "exasperated"],
+                "subject": ["person", "single_speaker"],
+                "composition": ["close_up", "medium_shot", "centered"],
+                "max_duration_sec": 2.5,
+                "has_subject": true,
+                "semantic_text": "funny reaction, person reacting to the camera"
+            }
+        },
+        {
+            "preset_id": "preset_broll_transitions",
+            "name": "b-roll transitions",
+            "description": "Quiet low-motion cutaways with no talking — good glue between beats.",
+            "criteria": {
+                "motion": ["static", "low"],
+                "max_duration_sec": 1.5,
+                "has_dialogue": false,
+                "semantic_text": "short b-roll transition, no dialogue"
+            }
+        },
+        {
+            "preset_id": "preset_establishing_shots",
+            "name": "establishing shots",
+            "description": "Wide scene-setters with no clear subject.",
+            "criteria": {
+                "composition": ["wide_shot"],
+                "has_subject": false,
+                "semantic_text": "wide establishing shot of a location"
+            }
+        },
+        {
+            "preset_id": "preset_typing_hands",
+            "name": "typing hands",
+            "description": "Close-ups of hands on a keyboard — classic productivity b-roll.",
+            "criteria": {
+                "action": ["typing", "hands_on_keyboard"],
+                "composition": ["close_up"],
+                "semantic_text": "close up of hands typing on a keyboard"
+            }
+        },
+        {
+            "preset_id": "preset_money_shots",
+            "name": "money shots",
+            "description": "High-energy hero shots — the payoff frames.",
+            "criteria": {
+                "composition": ["close_up", "medium_shot"],
+                "energy": ["high"],
+                "semantic_text": "high energy hero product money shot"
+            }
+        }
+    ]
+}

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

@@ -0,0 +1,163 @@
+// Structured filter + hybrid semantic re-rank. Same logic on devcli and cloud
+// so a preset or NL query returns the same clips regardless of target.
+//
+// Search flow (handoff): structured filter FIRST (cheap, exact), then semantic
+// re-rank the survivors by embedding similarity. If the structured filter
+// matches nothing but the query carries semantic intent, we relax to a
+// semantic-only pass so natural-language queries still return their best guess.
+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"]) {
+        if (Array.isArray(criteria[key]) && criteria[key].length)
+            n++;
+    }
+    if (criteria.min_duration_sec != null || criteria.max_duration_sec != null)
+        n++;
+    if (criteria.has_dialogue != null)
+        n++;
+    if (criteria.has_subject != null)
+        n++;
+    return n;
+}
+function hasSubject(tags) {
+    return tags.subject.length > 0 && !(tags.subject.length === 1 && tags.subject[0] === "no_subject");
+}
+function hasDialogue(tags) {
+    return tags.audio_type.some((a) => DIALOGUE_AUDIO.has(a)) || Boolean(tags.transcript.trim());
+}
+/** Hard structured filter: does this clip satisfy every constraint in `criteria`? */
+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.subject, criteria.subject))
+        return false;
+    if (!anyOf(t.action, criteria.action))
+        return false;
+    if (!anyOf(t.emotion, criteria.emotion))
+        return false;
+    if (!anyOf(t.setting, criteria.setting))
+        return false;
+    if (!anyOf(t.composition, criteria.composition))
+        return false;
+    if (!anyOf(t.motion, criteria.motion))
+        return false;
+    if (!anyOf(t.audio_type, criteria.audio_type))
+        return false;
+    if (criteria.energy && criteria.energy.length && !criteria.energy.includes(t.energy))
+        return false;
+    if (criteria.min_duration_sec != null && clip.duration_sec < criteria.min_duration_sec)
+        return false;
+    if (criteria.max_duration_sec != null && clip.duration_sec > criteria.max_duration_sec)
+        return false;
+    if (criteria.has_dialogue === true && !hasDialogue(t))
+        return false;
+    if (criteria.has_dialogue === false && hasDialogue(t))
+        return false;
+    if (criteria.has_subject === true && !hasSubject(t))
+        return false;
+    if (criteria.has_subject === false && hasSubject(t))
+        return false;
+    return true;
+}
+/** Fraction of constrained facets this clip satisfies (0..1); 1 when there are no constraints. */
+export function structuredMatchRatio(clip, criteria) {
+    const total = constraintCount(criteria);
+    if (total === 0)
+        return 1;
+    const t = clip.tags;
+    let hit = 0;
+    const anyOf = (have, want) => Boolean(want && want.length && want.some((w) => have.includes(w)));
+    if (anyOf(t.subject, criteria.subject))
+        hit++;
+    if (anyOf(t.action, criteria.action))
+        hit++;
+    if (anyOf(t.emotion, criteria.emotion))
+        hit++;
+    if (anyOf(t.setting, criteria.setting))
+        hit++;
+    if (anyOf(t.composition, criteria.composition))
+        hit++;
+    if (anyOf(t.motion, criteria.motion))
+        hit++;
+    if (anyOf(t.audio_type, criteria.audio_type))
+        hit++;
+    if (criteria.energy && criteria.energy.length && criteria.energy.includes(t.energy))
+        hit++;
+    if ((criteria.min_duration_sec != null || criteria.max_duration_sec != null) &&
+        (criteria.min_duration_sec == null || clip.duration_sec >= criteria.min_duration_sec) &&
+        (criteria.max_duration_sec == null || clip.duration_sec <= criteria.max_duration_sec))
+        hit++;
+    if (criteria.has_dialogue != null && hasDialogue(t) === criteria.has_dialogue)
+        hit++;
+    if (criteria.has_subject != null && hasSubject(t) === criteria.has_subject)
+        hit++;
+    return hit / total;
+}
+/** Cosine similarity of two vectors (safe on unnormalized input). */
+export function cosineSimilarity(a, b) {
+    if (!a || !b || a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/**
+ * Run the two-stage search over an in-memory clip set. Cloud can push the
+ * structured part into DynamoDB and the semantic part into a vector index; this
+ * pure function is the reference implementation devcli uses directly.
+ */
+export function searchClips(clips, opts) {
+    const { criteria, queryEmbedding } = opts;
+    const limit = opts.limit ?? 20;
+    const relax = opts.relaxWhenEmpty ?? true;
+    let candidates = clips.filter((c) => matchesCriteria(c, criteria));
+    let relaxed = false;
+    if (candidates.length === 0 && relax && (queryEmbedding || criteria.semantic_text)) {
+        candidates = clips.slice();
+        relaxed = true;
+    }
+    const hits = candidates.map((clip) => scoreClip(clip, criteria, queryEmbedding, relaxed));
+    return rankHits(hits, limit);
+}
+/**
+ * Score a single clip against a query. `relaxed` = the structured filter was
+ * bypassed (semantic-only pass), so factor in how well it still matches the
+ * criteria; when not relaxed the clip already passed the hard filter (ratio 1).
+ * Exported so the devcli SQLite store can reuse the exact scoring after doing
+ * the structured filter / KNN prefilter in SQL.
+ */
+export function scoreClip(clip, criteria, queryEmbedding, relaxed) {
+    const similarity = queryEmbedding ? cosineSimilarity(clip.embedding, queryEmbedding) : undefined;
+    const ratio = relaxed ? structuredMatchRatio(clip, criteria) : 1;
+    let score;
+    if (similarity != null) {
+        // Blend: mostly semantic, with a structured-match boost. Normalize cosine
+        // (-1..1) into 0..1 so scores read sensibly.
+        const sim01 = (similarity + 1) / 2;
+        score = 0.8 * sim01 + 0.2 * ratio;
+    }
+    else {
+        score = ratio;
+    }
+    return { clip, score, similarity };
+}
+/** Sort hits by score (newer clips break ties) and take the top `limit`. */
+export function rankHits(hits, limit) {
+    hits.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return (b.clip.created_at || "").localeCompare(a.clip.created_at || "");
+    });
+    return hits.slice(0, limit);
+}
+//# sourceMappingURL=query.js.map

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

@@ -0,0 +1,136 @@
+// 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 { readFile } from "node:fs/promises";
+import path from "node:path";
+import { generateObject } from "ai";
+import { z } from "zod";
+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;
+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) {
+        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`
+        };
+    }
+    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 });
+        }
+        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) {
+            return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0, note: "model returned no plan" };
+        }
+        return rebuildScenes(scenes, decisions);
+    }
+    catch {
+        return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0, note: "refinement failed; using raw scenes" };
+    }
+    finally {
+        try {
+            rmSync(framesDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+async function askForDecisions(client, guidancePrompt, scenes, frames) {
+    const images = await Promise.all(frames.map((f) => readFile(f.path)));
+    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 prompt = [
+        `You are curating clips from a long video for this 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.",
+        "- 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.`
+    ].join("\n");
+    // No fixed-length constraint — Gemini's structured-output schema translation
+    // rejects minItems==maxItems; we align by index instead (rebuildScenes).
+    const schema = z.object({
+        decisions: z.array(z.object({ keep: z.boolean(), merge_with_previous: z.boolean() }))
+    });
+    try {
+        const { object } = await generateObject({
+            model: client.taggingModel,
+            schema,
+            maxOutputTokens: Math.max(1000, scenes.length * 40),
+            messages: [
+                {
+                    role: "user",
+                    content: [{ type: "text", text: prompt }, ...images.map((image) => ({ type: "image", image }))]
+                }
+            ]
+        });
+        return object.decisions;
+    }
+    catch (error) {
+        if (process.env.VIDFARM_DEBUG_LOGS === "true") {
+            // eslint-disable-next-line no-console
+            console.warn(`[clips] refine call failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return null;
+    }
+}
+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;
+        }
+        if (d.merge_with_previous && out.length > 0) {
+            // Extend the previous kept clip to cover this scene.
+            const prev = out[out.length - 1];
+            prev.end_time_sec = scenes[i].end_time_sec;
+            prev.duration_sec = round3(prev.end_time_sec - prev.start_time_sec);
+            merged++;
+            continue;
+        }
+        out.push({ ...scenes[i], index: out.length });
+    }
+    // Never return an empty plan — if the model dropped everything, keep the raw scenes.
+    if (out.length === 0) {
+        return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0, note: "model dropped every scene; using raw scenes" };
+    }
+    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,137 @@
+// 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, extractClip, extractKeyframes, extractSceneAudio, extractThumbnail, probeVideo } from "./ffmpeg.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");
+    // 1. Keyframes for visual tagging (small, low-res).
+    const keyframePaths = await extractKeyframes({
+        videoPath,
+        scene,
+        outDir: framesDir,
+        count: ctx.framesPerScene ?? 2
+    });
+    // 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
+    });
+    // 4. Cut the clip + thumbnail.
+    const clipLocal = path.join(ctx.clipsDir, `${clipId}.mp4`);
+    const thumbLocal = path.join(ctx.thumbsDir, `${clipId}.jpg`);
+    const clipOk = await extractClip({ videoPath, scene, outPath: clipLocal, reencode: ctx.reencodeClips !== false });
+    if (!clipOk)
+        throw new Error(`ffmpeg failed to extract clip for scene @${scene.start_time_sec}s`);
+    await extractThumbnail({ videoPath, scene, outPath: thumbLocal });
+    // 5. Embed the document text for semantic search (skipped when the client can't embed).
+    let embedding;
+    if (ctx.client.canEmbed) {
+        const embedText = buildClipEmbeddingText(tagResult.tags, tagResult.description);
+        [embedding] = await ctx.client.embedDocuments([embedText]);
+    }
+    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: tagResult.tags,
+        description: tagResult.description,
+        embedding,
+        taxonomy_version: ctx.client.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION,
+        tier: ctx.client.tier,
+        provider: ctx.client.provider,
+        embedding_model: ctx.client.embeddingModelId ?? 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));
+    let scenes = opts.scenes ??
+        (await detectScenes(opts.videoPath, {
+            durationSec: probe.duration_sec,
+            ...opts.sceneOptions
+        }));
+    // Prompt-guided segmentation: let the guidance reshape which scenes become
+    // clips (keep/drop/merge) 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
+        });
+        scenes = refined.scenes;
+        opts.onRefine?.(refined);
+    }
+    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/taxonomy.js

@@ -0,0 +1,71 @@
+// 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 = [
+    "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 ClipTags-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 {
+        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,90 @@
+{
+    "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.",
+    "categories": {
+        "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