@mevdragon/vidfarm-devcli 0.7.1 → 0.9.0

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

@@ -0,0 +1,258 @@
+// ffmpeg/ffprobe helpers for clip curation — scene detection, keyframe/clip/
+// thumbnail extraction, per-scene audio for ASR. Same flags on devcli (local
+// ffmpeg-static) and cloud (bundled ffmpeg-static in the scan Lambda), so both
+// targets cut identical clips. Resolution order matches the rest of the repo:
+// HYPERFRAMES_FFMPEG_PATH/FFPROBE env → ffmpeg-static/ffprobe-static → PATH.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+let cachedFfmpeg;
+let cachedFfprobe;
+export async function resolveFfmpeg() {
+    if (cachedFfmpeg !== undefined)
+        return cachedFfmpeg ?? "ffmpeg";
+    const envPath = process.env.HYPERFRAMES_FFMPEG_PATH?.trim();
+    if (envPath && existsSync(envPath))
+        return (cachedFfmpeg = envPath);
+    try {
+        const mod = (await import("ffmpeg-static"));
+        const resolved = typeof mod === "string" ? mod : mod.default;
+        if (typeof resolved === "string" && resolved && existsSync(resolved))
+            return (cachedFfmpeg = resolved);
+    }
+    catch {
+        /* fall through to PATH */
+    }
+    cachedFfmpeg = null;
+    return "ffmpeg";
+}
+export async function resolveFfprobe() {
+    if (cachedFfprobe !== undefined)
+        return cachedFfprobe ?? "ffprobe";
+    const envPath = process.env.HYPERFRAMES_FFPROBE_PATH?.trim() ?? process.env.FFPROBE_PATH?.trim();
+    if (envPath && existsSync(envPath))
+        return (cachedFfprobe = envPath);
+    try {
+        const mod = (await import("ffprobe-static"));
+        const p = (mod.path ?? mod.default?.path);
+        if (typeof p === "string" && p && existsSync(p))
+            return (cachedFfprobe = p);
+    }
+    catch {
+        /* fall through to PATH */
+    }
+    cachedFfprobe = null;
+    return "ffprobe";
+}
+/** True if a usable ffmpeg is available (bundled or on PATH). */
+export async function hasFfmpeg() {
+    const bin = await resolveFfmpeg();
+    const { code } = await run(bin, ["-version"]).catch(() => ({ code: 1, stdout: "", stderr: "" }));
+    return code === 0;
+}
+function run(bin, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code: code ?? 0, stdout, stderr }));
+    });
+}
+/** Probe a source video for duration/dimensions/codec/size/fps. */
+export async function probeVideo(videoPath) {
+    const ffprobe = await resolveFfprobe();
+    const { stdout } = await run(ffprobe, [
+        "-v", "error",
+        "-print_format", "json",
+        "-show_format",
+        "-show_streams",
+        videoPath
+    ]);
+    let parsed = {};
+    try {
+        parsed = JSON.parse(stdout || "{}");
+    }
+    catch {
+        parsed = {};
+    }
+    const streams = Array.isArray(parsed.streams) ? parsed.streams : [];
+    const video = streams.find((s) => s.codec_type === "video");
+    const format = parsed.format ?? {};
+    const duration = Number(format.duration ?? video?.duration ?? 0) || 0;
+    let fps = null;
+    if (video?.avg_frame_rate && typeof video.avg_frame_rate === "string") {
+        const [num, den] = video.avg_frame_rate.split("/").map(Number);
+        if (num && den)
+            fps = num / den;
+    }
+    return {
+        duration_sec: duration,
+        width: video?.width ?? null,
+        height: video?.height ?? null,
+        codec: video?.codec_name ?? null,
+        size_bytes: format.size ? Number(format.size) : null,
+        fps
+    };
+}
+/**
+ * Detect scene boundaries with the portable `select='gt(scene,T)',showinfo`
+ * pass, parsing pts_time from ffmpeg's stderr. Falls back to fixed-interval
+ * chunking when nothing is detected (e.g. a single continuous take), so a scan
+ * always yields clips. Same command shape on devcli and cloud.
+ */
+export async function detectScenes(videoPath, opts = {}) {
+    const threshold = opts.threshold ?? 0.3;
+    const minScene = opts.minSceneSec ?? 0.6;
+    const maxScene = opts.maxSceneSec ?? 8;
+    const duration = opts.durationSec ?? (await probeVideo(videoPath)).duration_sec;
+    if (!Number.isFinite(duration) || duration <= 0)
+        return [];
+    const ffmpeg = await resolveFfmpeg();
+    const { stderr } = await run(ffmpeg, [
+        "-hide_banner",
+        "-i", videoPath,
+        "-filter:v", `select='gt(scene,${threshold})',showinfo`,
+        "-f", "null",
+        "-"
+    ]);
+    const cuts = [];
+    const re = /pts_time:([0-9.]+)/g;
+    let m;
+    while ((m = re.exec(stderr)) !== null) {
+        const t = Number(m[1]);
+        if (Number.isFinite(t) && t > 0 && t < duration)
+            cuts.push(t);
+    }
+    cuts.sort((a, b) => a - b);
+    // Build [0, cut1, cut2, …, duration] boundaries.
+    let bounds = [0, ...cuts, duration];
+    // If nothing detected, chunk at maxScene.
+    if (cuts.length === 0) {
+        bounds = [0];
+        for (let t = maxScene; t < duration; t += maxScene)
+            bounds.push(t);
+        bounds.push(duration);
+    }
+    // Merge boundaries closer than minScene.
+    const merged = [bounds[0]];
+    for (let i = 1; i < bounds.length; i++) {
+        if (bounds[i] - merged[merged.length - 1] >= minScene || i === bounds.length - 1) {
+            merged.push(bounds[i]);
+        }
+    }
+    const scenes = [];
+    for (let i = 0; i < merged.length - 1; i++) {
+        let start = merged[i];
+        const end = merged[i + 1];
+        // Split over-long scenes so clips stay usable and tagging stays cheap.
+        const span = end - start;
+        if (span > maxScene) {
+            const chunks = Math.ceil(span / maxScene);
+            const step = span / chunks;
+            for (let c = 0; c < chunks; c++) {
+                const s = start + c * step;
+                const e = c === chunks - 1 ? end : s + step;
+                scenes.push(makeScene(scenes.length, s, e));
+            }
+        }
+        else {
+            scenes.push(makeScene(scenes.length, start, end));
+        }
+    }
+    return scenes;
+}
+function makeScene(index, start, end) {
+    const s = Math.max(0, start);
+    const e = Math.max(s + 0.01, end);
+    return { index, start_time_sec: round3(s), end_time_sec: round3(e), duration_sec: round3(e - s) };
+}
+/** Extract up to `count` small keyframe JPEGs across a scene (for low-cost tagging). */
+export async function extractKeyframes(input) {
+    const count = Math.max(1, Math.min(3, input.count ?? 2));
+    const width = input.width ?? 384;
+    mkdirSync(input.outDir, { recursive: true });
+    const ffmpeg = await resolveFfmpeg();
+    const { start_time_sec: start, duration_sec: dur } = input.scene;
+    // Sample points inside the clip, avoiding the very edges.
+    const points = count === 1
+        ? [start + dur / 2]
+        : Array.from({ length: count }, (_, i) => start + dur * ((i + 1) / (count + 1)));
+    const outPaths = [];
+    for (let i = 0; i < points.length; i++) {
+        const out = path.join(input.outDir, `scene-${input.scene.index}-kf${i}.jpg`);
+        const { code } = await run(ffmpeg, [
+            "-y",
+            "-ss", points[i].toFixed(3),
+            "-i", input.videoPath,
+            "-frames:v", "1",
+            "-vf", `scale=${width}:-2`,
+            "-q:v", "5",
+            out
+        ]);
+        if (code === 0 && existsSync(out))
+            outPaths.push(out);
+    }
+    return outPaths;
+}
+/** Cut the scene into a standalone mp4 (re-encoded for frame-accurate boundaries). */
+export async function extractClip(input) {
+    mkdirSync(path.dirname(input.outPath), { recursive: true });
+    const ffmpeg = await resolveFfmpeg();
+    const { start_time_sec: start, duration_sec: dur } = input.scene;
+    const args = input.reencode === false
+        ? ["-y", "-ss", start.toFixed(3), "-i", input.videoPath, "-t", dur.toFixed(3), "-c", "copy", "-avoid_negative_ts", "make_zero", input.outPath]
+        : [
+            "-y",
+            "-ss", start.toFixed(3),
+            "-i", input.videoPath,
+            "-t", dur.toFixed(3),
+            "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-pix_fmt", "yuv420p",
+            "-c:a", "aac", "-b:a", "128k",
+            "-movflags", "+faststart",
+            input.outPath
+        ];
+    const { code } = await run(ffmpeg, args);
+    return code === 0 && existsSync(input.outPath);
+}
+/** Single representative thumbnail for the scene. */
+export async function extractThumbnail(input) {
+    mkdirSync(path.dirname(input.outPath), { recursive: true });
+    const ffmpeg = await resolveFfmpeg();
+    const mid = input.scene.start_time_sec + input.scene.duration_sec / 2;
+    const { code } = await run(ffmpeg, [
+        "-y",
+        "-ss", mid.toFixed(3),
+        "-i", input.videoPath,
+        "-frames:v", "1",
+        "-vf", `scale=${input.width ?? 320}:-2`,
+        "-q:v", "3",
+        input.outPath
+    ]);
+    return code === 0 && existsSync(input.outPath);
+}
+/** Extract a small mono/16k audio clip for the scene (feeds Gemini ASR). Returns null if no audio track. */
+export async function extractSceneAudio(input) {
+    mkdirSync(path.dirname(input.outPath), { recursive: true });
+    const ffmpeg = await resolveFfmpeg();
+    const { start_time_sec: start, duration_sec: dur } = input.scene;
+    const { code } = await run(ffmpeg, [
+        "-y",
+        "-ss", start.toFixed(3),
+        "-i", input.videoPath,
+        "-t", dur.toFixed(3),
+        "-vn",
+        "-ac", "1",
+        "-ar", "16000",
+        "-c:a", "libmp3lame",
+        "-b:a", "32k",
+        input.outPath
+    ]);
+    return code === 0 && existsSync(input.outPath) ? input.outPath : null;
+}
+function round3(n) {
+    return Math.round(n * 1000) / 1000;
+}
+//# sourceMappingURL=ffmpeg.js.map

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

@@ -0,0 +1,342 @@
+// Model client shared by devcli + cloud. Multi-provider: the TAGGING model
+// (vision + optional audio ASR) is swappable across gemini / openai / openrouter
+// so users pick their cost/quality tradeoff; EMBEDDINGS ride on a resolvable
+// embedding provider (gemini or openai — OpenRouter has no /embeddings) so a
+// library stays in ONE vector space. BYOK: the caller passes provider keys.
+//
+// One place for the prompt templates so every provider produces byte-identical
+// clip metadata (same taxonomy, same schema).
+import { readFile } from "node:fs/promises";
+import { embedMany, generateObject } from "ai";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { z } from "zod";
+import { ACTIVE_TAXONOMY_VERSION, getTaxonomy, sanitizeTagValues, taxonomyForPrompt } from "./taxonomy.js";
+// Tag model per provider/tier. Overridable via env so pinned models can move
+// forward without a code change. Handoff: gemini flash-lite (cheap, low media_resolution).
+function resolveTagModel(provider, tier) {
+    switch (provider) {
+        case "openai":
+            return process.env.VIDFARM_CLIP_TAG_MODEL_OPENAI ?? "gpt-5.4-nano";
+        case "openrouter":
+            return process.env.VIDFARM_CLIP_TAG_MODEL_OPENROUTER ?? "google/gemini-2.5-flash";
+        case "gemini":
+        default:
+            return tier === "flash"
+                ? process.env.VIDFARM_CLIP_TAG_MODEL_FLASH ?? "gemini-2.5-flash"
+                : process.env.VIDFARM_CLIP_TAG_MODEL_LITE ?? "gemini-2.5-flash-lite";
+    }
+}
+export const EMBEDDING_MODELS = {
+    gemini: process.env.VIDFARM_CLIP_EMBEDDING_MODEL ?? "gemini-embedding-001",
+    openai: process.env.VIDFARM_CLIP_EMBEDDING_MODEL_OPENAI ?? "text-embedding-3-small"
+};
+// gemini-embedding-001 and text-embedding-3-small both support reducing to 768
+// dims, so every provider's vectors fit the same fixed-width index. Cosine is
+// dimension-agnostic; still, vectors from DIFFERENT models are NOT comparable —
+// a library should stay on one embedding model (callers store embedding_model
+// and warn on mismatch).
+export const EMBEDDING_DIM = Number(process.env.VIDFARM_CLIP_EMBEDDING_DIM ?? 768);
+export class ClipModelClient {
+    provider;
+    tier;
+    taxonomyVersion;
+    tagModelId;
+    embeddingProvider;
+    embeddingModelId;
+    tagModel;
+    embedModel;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error(`A ${opts.provider ?? "gemini"} API key is required.`);
+        this.provider = opts.provider ?? "gemini";
+        this.tier = opts.tier ?? "flash-lite";
+        this.taxonomyVersion = opts.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION;
+        this.tagModelId = resolveTagModel(this.provider, this.tier);
+        this.tagModel = buildLanguageModel(this.provider, opts.apiKey, this.tagModelId, opts.publicBaseUrl);
+        const embedding = resolveEmbeddingConfig(this.provider, opts.apiKey, opts.embedding);
+        if (embedding) {
+            this.embeddingProvider = embedding.provider;
+            this.embeddingModelId = EMBEDDING_MODELS[embedding.provider];
+            this.embedModel = buildEmbeddingModel(embedding.provider, embedding.apiKey, this.embeddingModelId);
+        }
+        else {
+            this.embeddingProvider = null;
+            this.embeddingModelId = null;
+            this.embedModel = null;
+        }
+    }
+    /** True when this client can produce embeddings (semantic search available). */
+    get canEmbed() {
+        return this.embedModel !== null;
+    }
+    /** The underlying tagging LanguageModel — used by the guided-segmentation pass. */
+    get taggingModel() {
+        return this.tagModel;
+    }
+    tagSchema() {
+        const cats = getTaxonomy(this.taxonomyVersion).categories;
+        const enumArray = (values) => z.array(z.enum(values)).default([]);
+        return z.object({
+            subject: enumArray(cats.subject),
+            action: enumArray(cats.action),
+            emotion: enumArray(cats.emotion),
+            setting: enumArray(cats.setting),
+            composition: enumArray(cats.composition),
+            motion: enumArray(cats.motion),
+            energy: z.enum(cats.energy),
+            audio_type: enumArray(cats.audio_type),
+            transcript: z.string().default(""),
+            description: z.string()
+        });
+    }
+    /**
+     * Tag one scene from its keyframes (+ audio on Gemini, which transcribes in
+     * the same call). OpenAI/OpenRouter get frames only — their chat models don't
+     * take raw audio, so transcript stays empty unless supplied. Degrades to an
+     * empty-but-valid tag set on error so one bad scene never kills a scan.
+     */
+    async tagScene(input) {
+        const supportsAudio = this.provider === "gemini";
+        const hasAudio = supportsAudio && Boolean(input.audioPath);
+        const prompt = buildTaggingPrompt(input.transcript, this.taxonomyVersion, hasAudio, input.guidancePrompt);
+        const images = await Promise.all(input.keyframePaths.map((p) => readFile(p)));
+        const audio = hasAudio && input.audioPath ? await readFile(input.audioPath).catch(() => null) : null;
+        try {
+            const { object } = await generateObject({
+                model: this.tagModel,
+                schema: this.tagSchema(),
+                maxOutputTokens: this.provider === "openai" ? 1500 : 500,
+                providerOptions: this.taggingProviderOptions(),
+                messages: [
+                    {
+                        role: "user",
+                        content: [
+                            { type: "text", text: prompt },
+                            ...images.map((image) => this.imagePart(image)),
+                            ...(audio ? [{ type: "file", data: audio, mediaType: "audio/mpeg" }] : [])
+                        ]
+                    }
+                ]
+            });
+            const sanitized = sanitizeTagValues(object, this.taxonomyVersion);
+            const tags = {
+                ...sanitized,
+                transcript: (input.transcript || object.transcript || "").trim()
+            };
+            return { tags, description: String(object.description ?? "").trim() };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`[clips] tag failed (${this.provider}) @${input.scene.start_time_sec.toFixed(1)}s: ${message}`);
+            return {
+                tags: {
+                    subject: [],
+                    action: [],
+                    emotion: [],
+                    setting: [],
+                    composition: [],
+                    motion: [],
+                    energy: "medium",
+                    audio_type: input.transcript ? ["dialogue"] : ["silence"],
+                    transcript: input.transcript || ""
+                },
+                description: input.transcript ? input.transcript.slice(0, 120) : ""
+            };
+        }
+    }
+    taggingProviderOptions() {
+        if (this.provider === "gemini") {
+            return { google: { mediaResolution: "MEDIA_RESOLUTION_LOW", structuredOutputs: true } };
+        }
+        return undefined;
+    }
+    imagePart(image) {
+        // Low image detail on OpenAI keeps the token cost near the Gemini low-res target.
+        if (this.provider === "openai") {
+            return { type: "image", image, providerOptions: { openai: { imageDetail: "low" } } };
+        }
+        return { type: "image", image };
+    }
+    async embedDocuments(texts) {
+        return this.embed(texts, "RETRIEVAL_DOCUMENT");
+    }
+    async embedQuery(text) {
+        const [vec] = await this.embed([text], "RETRIEVAL_QUERY");
+        return vec;
+    }
+    /** Batch-embed many retrieval queries (e.g. one per scene annotation) in a single call. */
+    async embedQueries(texts) {
+        return this.embed(texts, "RETRIEVAL_QUERY");
+    }
+    async embed(texts, taskType) {
+        if (texts.length === 0 || !this.embedModel)
+            return [];
+        const providerOptions = this.embeddingProvider === "gemini"
+            ? { google: { taskType, outputDimensionality: EMBEDDING_DIM } }
+            : { openai: { dimensions: EMBEDDING_DIM } };
+        const { embeddings } = await embedMany({
+            model: this.embedModel,
+            values: texts.map((t) => (t.trim() ? t.trim() : " ")),
+            providerOptions
+        });
+        return embeddings.map((e) => normalize(e));
+    }
+    /** Convert a natural-language query into a structured SplicingCriteria (categoricals constrained to the taxonomy). */
+    async naturalLanguageToCriteria(query) {
+        const cats = getTaxonomy(this.taxonomyVersion).categories;
+        const opt = (values) => z.array(z.enum(values)).optional();
+        const schema = z.object({
+            subject: opt(cats.subject),
+            action: opt(cats.action),
+            emotion: opt(cats.emotion),
+            setting: opt(cats.setting),
+            composition: opt(cats.composition),
+            motion: opt(cats.motion),
+            audio_type: opt(cats.audio_type),
+            energy: z.array(z.enum(cats.energy)).optional(),
+            min_duration_sec: z.number().optional(),
+            max_duration_sec: z.number().optional(),
+            has_dialogue: z.boolean().optional(),
+            has_subject: z.boolean().optional()
+        });
+        try {
+            const { object } = await generateObject({
+                model: this.tagModel,
+                schema,
+                maxOutputTokens: this.provider === "openai" ? 1200 : 300,
+                prompt: buildQueryPrompt(query, this.taxonomyVersion)
+            });
+            return { ...pruneUndefined(object), semantic_text: query };
+        }
+        catch {
+            return { semantic_text: query };
+        }
+    }
+}
+/** Back-compat alias — the client used to be Gemini-only. */
+export const ClipGeminiClient = ClipModelClient;
+function buildLanguageModel(provider, apiKey, modelId, publicBaseUrl) {
+    switch (provider) {
+        case "openai":
+            return createOpenAI({ apiKey })(modelId);
+        case "openrouter":
+            return createOpenAICompatible({
+                name: "openrouter",
+                apiKey,
+                baseURL: "https://openrouter.ai/api/v1",
+                headers: { "HTTP-Referer": publicBaseUrl ?? "https://vidfarm.cc", "X-Title": "Vidfarm Clips" }
+            }).chatModel(modelId);
+        case "gemini":
+        default:
+            return createGoogleGenerativeAI({ apiKey })(modelId);
+    }
+}
+function buildEmbeddingModel(provider, apiKey, modelId) {
+    return provider === "openai"
+        ? createOpenAI({ apiKey }).textEmbeddingModel(modelId)
+        : createGoogleGenerativeAI({ apiKey }).textEmbeddingModel(modelId);
+}
+function resolveEmbeddingConfig(provider, apiKey, explicit) {
+    if (explicit === null)
+        return null; // caller explicitly disabled embeddings
+    if (explicit)
+        return explicit;
+    if (provider === "gemini")
+        return { provider: "gemini", apiKey };
+    if (provider === "openai")
+        return { provider: "openai", apiKey };
+    return null; // openrouter: no embeddings unless an explicit config is given
+}
+/** The document text embedded for a clip: description + transcript + salient tags. */
+export function buildClipEmbeddingText(tags, description) {
+    const parts = [];
+    if (description)
+        parts.push(description);
+    if (tags.transcript)
+        parts.push(`Transcript: ${tags.transcript}`);
+    const tagBits = [
+        ...tags.subject,
+        ...tags.action,
+        ...tags.emotion,
+        ...tags.setting,
+        ...tags.composition,
+        ...tags.motion,
+        ...tags.audio_type,
+        `energy:${tags.energy}`
+    ];
+    if (tagBits.length)
+        parts.push(tagBits.join(", "));
+    return parts.join("\n").trim() || "video clip";
+}
+function buildTaggingPrompt(transcript, version, hasAudio = false, guidancePrompt) {
+    const speech = transcript?.trim()
+        ? `The scene's spoken audio (ASR transcript) is: "${transcript.trim()}"`
+        : hasAudio
+            ? `An audio clip of the scene is attached — transcribe any speech into the transcript field (use "" if there is no speech).`
+            : `There is no clear speech in this scene (no dialogue).`;
+    const guidance = guidancePrompt?.trim()
+        ? `\nThe user is curating clips for this goal: "${guidancePrompt.trim()}". Bias the description and tags toward what matters for that goal (stay accurate — never invent tags not visible in the scene).\n`
+        : "";
+    return [
+        "You are tagging one short video scene for a searchable clip library.",
+        "You are given 1-3 keyframes from the scene and its audio transcript.",
+        speech,
+        guidance,
+        "",
+        "Return JSON matching the schema. Use ONLY values from this controlled vocabulary:",
+        taxonomyForPrompt(version),
+        "",
+        "Rules:",
+        "- Pick only tags you are confident about from the keyframes/audio. Omit a category (empty list) rather than guess.",
+        "- If there is no clear person/subject, use subject: [\"no_subject\"].",
+        "- If there is no speech, set audio_type appropriately (e.g. music/ambient/silence) and leave transcript empty.",
+        "- `energy` is a single value: low | medium | high.",
+        "- `transcript` should echo the spoken words verbatim (or \"\" if none).",
+        "- `description`: one short factual sentence (<= 20 words) describing what happens — this drives semantic search, so be concrete.",
+        "Keep the whole response under ~200 tokens."
+    ].join("\n");
+}
+function buildQueryPrompt(query, version) {
+    return [
+        "Convert this clip-search request into a structured filter.",
+        `Request: "${query}"`,
+        "",
+        "Use ONLY values from this controlled vocabulary (omit a field if the request doesn't constrain it):",
+        taxonomyForPrompt(version),
+        "",
+        "Only include fields the request clearly implies. Prefer fewer, high-precision constraints.",
+        "Set has_dialogue/has_subject only when the request is explicit about speech or a subject.",
+        "Durations are in seconds."
+    ].join("\n");
+}
+function pruneUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v === undefined)
+            continue;
+        if (Array.isArray(v) && v.length === 0)
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/** L2-normalize a vector so cosine == dot product (and reduced-dim embeddings compare correctly). */
+export function normalize(vec) {
+    let sum = 0;
+    for (const v of vec)
+        sum += v * v;
+    const norm = Math.sqrt(sum);
+    if (norm === 0)
+        return vec;
+    return vec.map((v) => v / norm);
+}
+// Legacy export kept for callers that referenced the old constant.
+export const TAG_MODEL_BY_TIER = {
+    "flash-lite": resolveTagModel("gemini", "flash-lite"),
+    flash: resolveTagModel("gemini", "flash")
+};
+export const EMBEDDING_MODEL = EMBEDDING_MODELS.gemini;
+//# sourceMappingURL=gemini.js.map

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

@@ -0,0 +1,15 @@
+// vidfarm clip-curation core — the shared "third pillar" library consumed by
+// devcli (local), the Hono API (src/app.ts), and the cloud scan Lambdas. Build
+// once, use in both targets (handoff: Shared Components).
+export * from "./types.js";
+export { ACTIVE_TAXONOMY_VERSION, MULTI_VALUE_CATEGORIES, getTaxonomy, sanitizeTagValues, taxonomyForPrompt } from "./taxonomy.js";
+export { BUILTIN_PRESETS, findBuiltinPreset } from "./presets.js";
+export { ClipModelClient, ClipGeminiClient, EMBEDDING_DIM, EMBEDDING_MODEL, EMBEDDING_MODELS, TAG_MODEL_BY_TIER, buildClipEmbeddingText, normalize } from "./gemini.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";
+// 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/presets.js

@@ -0,0 +1,20 @@
+// Starter preset criteria library. Presets are just saved SplicingCriteria
+// (see types.ts). The shipped ones are `builtin: true`; users save their own
+// with `builtin: false` (persisted per-store in devcli/cloud).
+import presetsV1 from "./presets.v1.json" with { type: "json" };
+const SEED = presetsV1;
+/** The shipped built-in presets. Frozen so callers can't mutate the shared array. */
+export const BUILTIN_PRESETS = SEED.presets.map((p) => ({
+    preset_id: p.preset_id,
+    name: p.name,
+    description: p.description,
+    criteria: p.criteria,
+    builtin: true,
+    created_at: "1970-01-01T00:00:00.000Z"
+}));
+/** Look up a built-in preset by its id or (case-insensitive) name. */
+export function findBuiltinPreset(nameOrId) {
+    const needle = nameOrId.trim().toLowerCase();
+    return BUILTIN_PRESETS.find((p) => p.preset_id.toLowerCase() === needle || p.name.toLowerCase() === needle);
+}
+//# sourceMappingURL=presets.js.map