@mevdragon/vidfarm-devcli 0.7.1 → 0.8.0

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

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

@@ -0,0 +1,209 @@
+// Cloud clip records — DynamoDB single-table store for clip curation, mirroring
+// the serverless-records / serverless-jobs conventions (pk/sk + gsi1 overload,
+// 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 { config } from "../config.js";
+import { createLocalDynamoClient } from "./local-dynamo.js";
+import { BUILTIN_PRESETS } from "./clip-curation/index.js";
+// Same client construction as serverless-records.ts: disk shim locally, real
+// client when deployed. Call sites are identical either way.
+const dynamodb = config.RECORDS_DRIVER === "local"
+    ? createLocalDynamoClient()
+    : DynamoDBDocumentClient.from(new DynamoDBClient({}), {
+        marshallOptions: { removeUndefinedValues: true }
+    });
+function requireMainTableName() {
+    if (config.RECORDS_DRIVER === "local") {
+        return config.VIDFARM_SERVERLESS_MAIN_TABLE_NAME || "vidfarm-local-main";
+    }
+    if (!config.VIDFARM_SERVERLESS_MAIN_TABLE_NAME) {
+        throw new Error("Clip record store requires VIDFARM_SERVERLESS_MAIN_TABLE_NAME.");
+    }
+    return config.VIDFARM_SERVERLESS_MAIN_TABLE_NAME;
+}
+const ENTITY_CLIP = "clip_curation_clip";
+const ENTITY_PRESET = "clip_curation_preset";
+const ENTITY_SOURCE = "clip_curation_source";
+const ENTITY_SCAN = "clip_curation_scan";
+// Key scheme (one owner partition, sk-prefixed by entity; gsi1 lists by recency).
+const clipPk = (owner) => `USER#${owner}`;
+const clipSk = (clipId) => `CLIP#${clipId}`;
+const clipListPk = (owner) => `USER#${owner}#CLIPS`;
+const clipSourceListPk = (owner, sourceId) => `USER#${owner}#CLIPS#SRC#${sourceId}`;
+const presetSk = (presetId) => `CLIPPRESET#${presetId}`;
+const presetListPk = (owner) => `USER#${owner}#CLIPPRESETS`;
+const sourceSk = (sourceId) => `CLIPSRC#${sourceId}`;
+const sourceListPk = (owner) => `USER#${owner}#CLIPSRCS`;
+const scanSk = (scanId) => `CLIPSCAN#${scanId}`;
+export class ClipRecordsService {
+    // ── Clips ────────────────────────────────────────────────────────────────
+    async putClip(clip) {
+        const owner = requireOwner(clip.owner_id);
+        await dynamodb.send(new PutCommand({
+            TableName: requireMainTableName(),
+            Item: {
+                pk: clipPk(owner),
+                sk: clipSk(clip.clip_id),
+                entity_type: ENTITY_CLIP,
+                gsi1pk: clipListPk(owner),
+                gsi1sk: `${clip.created_at}#${clip.clip_id}`,
+                gsi2pk: clipSourceListPk(owner, clip.source_video_id),
+                gsi2sk: `${clip.start_time_sec.toFixed(3)}#${clip.clip_id}`,
+                ...clip
+            }
+        }));
+    }
+    async getClip(owner, clipId) {
+        const res = await dynamodb.send(new GetCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: clipSk(clipId) } }));
+        return res.Item ? stripKeys(res.Item) : null;
+    }
+    /** List a user's clips (newest first), optionally scoped to a source video. */
+    async listClips(owner, opts = {}) {
+        const limit = opts.limit ?? 200;
+        if (opts.sourceVideoId) {
+            const res = await dynamodb.send(new QueryCommand({
+                TableName: requireMainTableName(),
+                IndexName: "gsi2",
+                KeyConditionExpression: "gsi2pk = :pk",
+                ExpressionAttributeValues: { ":pk": clipSourceListPk(owner, opts.sourceVideoId) },
+                Limit: limit
+            }));
+            return (res.Items ?? []).map(stripKeys);
+        }
+        const res = await dynamodb.send(new QueryCommand({
+            TableName: requireMainTableName(),
+            IndexName: "gsi1",
+            KeyConditionExpression: "gsi1pk = :pk",
+            ExpressionAttributeValues: { ":pk": clipListPk(owner) },
+            ScanIndexForward: false,
+            Limit: limit
+        }));
+        return (res.Items ?? []).map(stripKeys);
+    }
+    /** All embeddings for a user's clips — feeds the brute-force vector search. */
+    async listClipsWithEmbeddings(owner) {
+        const clips = await this.listClips(owner, { limit: 5000 });
+        return clips.filter((c) => Array.isArray(c.embedding) && c.embedding.length > 0);
+    }
+    /**
+     * The embedding model the library was built with (from the newest embedded
+     * clip). A match query must be embedded with the SAME model to be comparable.
+     */
+    async getLibraryEmbeddingModel(owner) {
+        const clips = await this.listClips(owner, { limit: 20 });
+        for (const c of clips) {
+            if (c.embedding_model && Array.isArray(c.embedding) && c.embedding.length > 0)
+                return c.embedding_model;
+        }
+        return null;
+    }
+    async deleteClip(owner, clipId) {
+        await dynamodb.send(new DeleteCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: clipSk(clipId) } }));
+    }
+    // ── Presets ──────────────────────────────────────────────────────────────
+    async listPresets(owner) {
+        const res = await dynamodb.send(new QueryCommand({
+            TableName: requireMainTableName(),
+            KeyConditionExpression: "pk = :pk AND begins_with(sk, :sk)",
+            ExpressionAttributeValues: { ":pk": clipPk(owner), ":sk": "CLIPPRESET#" }
+        }));
+        const saved = (res.Items ?? []).map((i) => stripKeys(i));
+        return [...BUILTIN_PRESETS, ...saved];
+    }
+    async putPreset(owner, preset) {
+        await dynamodb.send(new PutCommand({
+            TableName: requireMainTableName(),
+            Item: {
+                pk: clipPk(owner),
+                sk: presetSk(preset.preset_id),
+                entity_type: ENTITY_PRESET,
+                gsi1pk: presetListPk(owner),
+                gsi1sk: preset.created_at,
+                ...preset,
+                owner_id: owner
+            }
+        }));
+    }
+    async deletePreset(owner, presetId) {
+        await dynamodb.send(new DeleteCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: presetSk(presetId) } }));
+    }
+    // ── Source videos ──────────────────────────────────────────────────────────
+    async putSource(record) {
+        await dynamodb.send(new PutCommand({
+            TableName: requireMainTableName(),
+            Item: {
+                pk: clipPk(record.owner_id),
+                sk: sourceSk(record.source_video_id),
+                entity_type: ENTITY_SOURCE,
+                gsi1pk: sourceListPk(record.owner_id),
+                gsi1sk: record.created_at,
+                ...record
+            }
+        }));
+    }
+    async getSource(owner, sourceId) {
+        const res = await dynamodb.send(new GetCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: sourceSk(sourceId) } }));
+        return res.Item ? stripKeys(res.Item) : null;
+    }
+    async listSources(owner) {
+        const res = await dynamodb.send(new QueryCommand({
+            TableName: requireMainTableName(),
+            IndexName: "gsi1",
+            KeyConditionExpression: "gsi1pk = :pk",
+            ExpressionAttributeValues: { ":pk": sourceListPk(owner) },
+            ScanIndexForward: false
+        }));
+        return (res.Items ?? []).map((i) => stripKeys(i));
+    }
+    // ── Scan jobs ──────────────────────────────────────────────────────────────
+    async putScan(record) {
+        await dynamodb.send(new PutCommand({
+            TableName: requireMainTableName(),
+            Item: {
+                pk: clipPk(record.owner_id),
+                sk: scanSk(record.scan_id),
+                entity_type: ENTITY_SCAN,
+                ...record
+            }
+        }));
+    }
+    async getScan(owner, scanId) {
+        const res = await dynamodb.send(new GetCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: scanSk(scanId) } }));
+        return res.Item ? stripKeys(res.Item) : null;
+    }
+}
+export const clipRecords = new ClipRecordsService();
+/** Build a user-saved preset record from raw criteria. */
+export function makeUserPreset(input) {
+    return {
+        preset_id: `preset_${Date.now().toString(36)}_${Math.floor(Math.random() * 1e6).toString(36)}`,
+        name: input.name,
+        description: input.description,
+        criteria: input.criteria,
+        builtin: false,
+        owner_id: input.owner,
+        created_at: new Date().toISOString()
+    };
+}
+function requireOwner(owner) {
+    if (!owner)
+        throw new Error("Clip records require an owner_id.");
+    return owner;
+}
+// Drop the DynamoDB key/index attributes so callers get back a clean record.
+function stripKeys(item) {
+    const { pk, sk, entity_type, gsi1pk, gsi1sk, gsi2pk, gsi2sk, gsi3pk, gsi3sk, ...rest } = item;
+    void pk;
+    void sk;
+    void entity_type;
+    void gsi1pk;
+    void gsi1sk;
+    void gsi2pk;
+    void gsi2sk;
+    void gsi3pk;
+    void gsi3sk;
+    return rest;
+}
+//# sourceMappingURL=clip-records.js.map