videobook 0.0.0-stage → 0.2.0

package/dist/srt.js

@@ -0,0 +1,16 @@
+export function srtTimestamp(seconds) {
+    const millis = Math.max(0, Math.round(seconds * 1000));
+    const hours = Math.floor(millis / 3_600_000);
+    const minutes = Math.floor((millis % 3_600_000) / 60_000);
+    const secs = Math.floor((millis % 60_000) / 1000);
+    const remainder = millis % 1000;
+    return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:${String(secs).padStart(2, "0")},${String(remainder).padStart(3, "0")}`;
+}
+export function srtContent(cues) {
+    return cues.map((cue, index) => [
+        String(index + 1),
+        `${srtTimestamp(cue.startSeconds)} --> ${srtTimestamp(cue.endSeconds)}`,
+        cue.text,
+        "",
+    ].join("\n")).join("\n");
+}

package/dist/tag-backfill-state.js

@@ -0,0 +1,121 @@
+/**
+ * Durable state for tagging a library that already exists.
+ *
+ * A backfill is long, interruptible work over a catalog that changes while it
+ * runs: assets get created, deleted and re-cut mid-pass. Two decisions follow
+ * from that.
+ *
+ * The cursor is the last artifact id visited, not an offset. Offsets over a
+ * changing catalog silently skip and repeat rows — delete one asset behind the
+ * cursor and every later page shifts under it — while an id cursor resumes at
+ * exactly the right place whatever happened meanwhile.
+ *
+ * State lives in the book's own settings, so a restart mid-pass resumes rather
+ * than starting over, and a book that is never opened again carries no
+ * orphaned progress anywhere else.
+ */
+const SETTINGS_KEY = "asset-tag-backfill";
+export const EMPTY_COUNTS = {
+    current: 0,
+    tagged: 0,
+    empty: 0,
+    needsAnalysis: 0,
+    unsupported: 0,
+    skipped: 0,
+    failed: 0,
+};
+const IDLE_STATE = {
+    runId: null,
+    status: "idle",
+    cursor: null,
+    scanned: 0,
+    counts: EMPTY_COUNTS,
+    allowAnalysis: false,
+    force: false,
+    startedAt: null,
+    updatedAt: null,
+    finishedAt: null,
+    lastError: null,
+};
+function count(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : 0;
+}
+function counts(value) {
+    const row = (typeof value === "object" && value !== null ? value : {});
+    return {
+        current: count(row.current),
+        tagged: count(row.tagged),
+        empty: count(row.empty),
+        needsAnalysis: count(row.needsAnalysis),
+        unsupported: count(row.unsupported),
+        skipped: count(row.skipped),
+        failed: count(row.failed),
+    };
+}
+function status(value) {
+    return value === "running" || value === "paused" || value === "cancelled"
+        || value === "completed"
+        ? value
+        : "idle";
+}
+function timestamp(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function readBackfillState(engine) {
+    const stored = engine.settings.get(SETTINGS_KEY);
+    if (!stored)
+        return { ...IDLE_STATE };
+    return {
+        runId: typeof stored.runId === "string" ? stored.runId : null,
+        status: status(stored.status),
+        cursor: typeof stored.cursor === "string" ? stored.cursor : null,
+        scanned: count(stored.scanned),
+        counts: counts(stored.counts),
+        allowAnalysis: stored.allowAnalysis === true,
+        force: stored.force === true,
+        startedAt: timestamp(stored.startedAt),
+        updatedAt: timestamp(stored.updatedAt),
+        finishedAt: timestamp(stored.finishedAt),
+        lastError: typeof stored.lastError === "string" ? stored.lastError : null,
+    };
+}
+export function writeBackfillState(engine, state) {
+    const next = { ...state, updatedAt: Date.now() };
+    const written = engine.settings.set(SETTINGS_KEY, next);
+    if (!written.ok)
+        throw new Error(written.error.message);
+    return next;
+}
+/** Adds one asset's outcome to a running tally. */
+export function recordOutcome(current, outcome) {
+    const next = { ...current };
+    switch (outcome) {
+        case "tagged":
+            next.tagged += 1;
+            break;
+        case "already_current":
+            next.current += 1;
+            break;
+        case "no_useful_evidence":
+            next.empty += 1;
+            break;
+        case "no_evidence":
+        case "analysis_requested":
+        case "analysis_unavailable":
+            next.needsAnalysis += 1;
+            break;
+        case "unsupported_kind":
+            next.unsupported += 1;
+            break;
+        case "missing_asset":
+        case "no_source_content":
+            next.skipped += 1;
+            break;
+        default:
+            next.failed += 1;
+            break;
+    }
+    return next;
+}

package/dist/tag-settings.js

@@ -0,0 +1,30 @@
+/**
+ * Per-book configuration for automatic tagging.
+ *
+ * Automatic tagging is on by default for new assets, because an asset nobody
+ * can find is the problem the feature exists to solve. Turning it off stops
+ * the coordinator from being queued at all — it does not disable tags: manual
+ * tagging, filtering and search keep working exactly as before, which is also
+ * what a book with no provider key gets.
+ */
+const SETTINGS_KEY = "asset-tagging";
+const DEFAULT_TAGGING_SETTINGS = {
+    automaticEnabled: true,
+    analysisOnNewAssets: true,
+};
+export function readTaggingSettings(engine) {
+    const stored = engine.settings.get(SETTINGS_KEY);
+    if (!stored)
+        return { ...DEFAULT_TAGGING_SETTINGS };
+    return {
+        automaticEnabled: stored.automaticEnabled !== false,
+        analysisOnNewAssets: stored.analysisOnNewAssets !== false,
+    };
+}
+export function writeTaggingSettings(engine, update) {
+    const next = { ...readTaggingSettings(engine), ...update };
+    const written = engine.settings.set(SETTINGS_KEY, next);
+    if (!written.ok)
+        throw new Error(written.error.message);
+    return next;
+}

package/dist/tag-vocabulary.js

@@ -0,0 +1,237 @@
+/**
+ * The editorial vocabulary automatic tagging is allowed to emit.
+ *
+ * The engine normalizes labels into identities; it does not decide which words
+ * are worth storing. That judgement lives here, because a tag only earns its
+ * place if it helps someone — or a tool — find, group, match or sequence
+ * footage. Letting each model invent its own grouping labels produces
+ * "closeup", "close up" and "tight shot" on three different clips that should
+ * have landed together, so standard terms are pinned to one canonical spelling
+ * and everything outside the vocabulary is dropped rather than guessed at.
+ *
+ * The version below is part of the tag job's fence: bump it whenever the
+ * vocabulary or the selection rules change meaningfully, and previously
+ * tagged assets become eligible for a re-run.
+ */
+import { AUTOMATIC_TAGS_PER_SNAPSHOT_MAX, normalizeTagLabel, normalizeTagPrefix, tagCanonicalKey } from "videobook-engine/tag-values";
+export const TAG_ANALYZER_VERSION = "editorial-tags-v2";
+/** The ceiling is a ceiling, never a quota: sparse evidence emits fewer. */
+export const MAX_AUTOMATIC_TAGS = AUTOMATIC_TAGS_PER_SNAPSHOT_MAX;
+/**
+ * Visible composition and role. Named people never come from a model: a name
+ * in a transcript does not identify who is on screen, so identities may only
+ * arrive from user-confirmed project metadata.
+ */
+const PEOPLE = [
+    { label: "no people", aliases: ["empty", "unpopulated", "nobody", "no one"] },
+    { label: "solo subject", aliases: ["one person", "single person", "solo", "individual"] },
+    { label: "two people", aliases: ["pair", "couple", "duo", "two subjects"] },
+    { label: "small group", aliases: ["group", "three people", "few people", "small gathering"] },
+    { label: "crowd", aliases: ["crowded", "many people", "audience", "large group"] },
+    { label: "interviewer", aliases: ["questioner"] },
+    { label: "interviewee", aliases: ["subject being interviewed", "respondent"] },
+    { label: "presenter", aliases: ["host"] },
+];
+/** Settings useful for matching coverage, plus the two axes worth grouping by. */
+const PLACES = [
+    { label: "interior", aliases: ["indoors", "inside", "indoor"] },
+    { label: "exterior", aliases: ["outdoors", "outside", "outdoor"] },
+    { label: "day", aliases: ["daytime", "daylight", "morning", "afternoon"] },
+    { label: "night", aliases: ["nighttime", "after dark", "evening"] },
+    { label: "kitchen", aliases: ["galley"] },
+    { label: "street", aliases: ["sidewalk", "roadside", "city street"] },
+    { label: "studio", aliases: ["soundstage"] },
+    { label: "office", aliases: ["workplace"] },
+    { label: "bedroom", aliases: [] },
+    { label: "living room", aliases: ["lounge"] },
+    { label: "restaurant", aliases: ["cafe", "diner", "bar"] },
+    { label: "store", aliases: ["shop", "market", "supermarket"] },
+    { label: "car", aliases: ["vehicle interior"] },
+    { label: "beach", aliases: ["shore", "seaside"] },
+    { label: "park", aliases: ["garden"] },
+    { label: "forest", aliases: ["woods", "woodland"] },
+    { label: "stage", aliases: ["venue", "concert stage"] },
+    { label: "gym", aliases: ["fitness studio"] },
+    { label: "rooftop", aliases: ["roof"] },
+];
+/**
+ * Framing, supported camera movement, coverage and audio character. Movement
+ * terms are only ever accepted from evidence that can actually establish them;
+ * sparse, evenly spaced frames cannot, so the extractors do not offer them.
+ */
+const EDITING = [
+    { label: "wide shot", aliases: ["wide", "long shot", "full shot", "establishing wide"] },
+    { label: "medium shot", aliases: ["medium", "mid shot", "waist up"] },
+    { label: "close-up", aliases: ["close up", "closeup", "tight shot", "cu"] },
+    { label: "extreme close-up", aliases: ["extreme close up", "extreme closeup", "macro shot"] },
+    { label: "establishing shot", aliases: ["establishing", "scene setter"] },
+    { label: "insert", aliases: ["insert shot", "cutaway", "detail shot"] },
+    { label: "product shot", aliases: ["product", "packshot"] },
+    { label: "static", aliases: ["locked off", "tripod", "still camera", "fixed camera"] },
+    { label: "pan", aliases: ["panning", "whip pan"] },
+    { label: "tilt", aliases: ["tilting"] },
+    { label: "handheld", aliases: ["hand held", "shaky", "run and gun"] },
+    { label: "tracking", aliases: ["dolly", "steadicam", "follow shot", "tracking shot"] },
+    { label: "interview", aliases: ["sit down interview"] },
+    { label: "talking head", aliases: [] },
+    { label: "dialogue", aliases: ["conversation", "speech", "talking"] },
+    { label: "ambience", aliases: ["ambient", "room tone", "atmosphere", "background sound"] },
+    { label: "music", aliases: ["musical", "score", "soundtrack"] },
+    { label: "voiceover", aliases: ["voice over", "narration", "narrator"] },
+];
+const VOCABULARY = {
+    people: PEOPLE,
+    places: PLACES,
+    editing: EDITING,
+    // Automatic tagging never mints custom tags; that facet is the user's.
+    custom: [],
+};
+/**
+ * Words that describe how footage feels or how good it is. They group nothing:
+ * every clip in a project can be "beautiful", and no editor searches for it.
+ */
+const BANNED_TERMS = new Set([
+    "beautiful", "stunning", "amazing", "gorgeous", "great", "good", "nice",
+    "cool", "epic", "dramatic", "moody", "vibe", "vibes", "aesthetic", "mood",
+    "cinematic", "masterpiece", "high quality", "professional", "hd", "4k",
+    "video", "footage", "clip", "content", "scene", "shot", "media", "image",
+    "photo", "picture", "frame", "camera", "misc", "other", "general",
+    "interesting", "modern", "classic", "colorful", "bright", "dark",
+    "atmospheric", "emotional", "energetic", "calm", "peaceful", "happy", "sad",
+]);
+function normalizeTerm(value) {
+    return value
+        .normalize("NFKC")
+        .toLowerCase()
+        .replace(/[_/]+/gu, " ")
+        .replace(/[^\p{L}\p{N}\s-]+/gu, "")
+        .replace(/\s+/gu, " ")
+        .trim();
+}
+const ALIAS_INDEX = new Map(Object.entries(VOCABULARY)
+    .flatMap(([facet, entries]) => entries.flatMap((entry) => [entry.label, ...entry.aliases].map((term) => [`${facet}:${normalizeTerm(term)}`, { facet, label: entry.label }]))));
+/** Every canonical label a facet may carry, for prompts and documentation. */
+export function vocabularyFor(facet) {
+    return VOCABULARY[facet].map((entry) => entry.label);
+}
+export function isFrameTag(tag) {
+    if (tag.facet === "places")
+        return true;
+    if (tag.facet === "people")
+        return PEOPLE.slice(0, 5).some((entry) => entry.label === tag.label);
+    return tag.facet === "editing" && EDITING.slice(0, 7).some((entry) => entry.label === tag.label);
+}
+export function frameVocabularyFor(facet) {
+    return vocabularyFor(facet).filter((label) => isFrameTag({ facet, label }));
+}
+export function resolveTagInput(input, existing = []) {
+    const label = normalizeTagLabel(input.label);
+    const key = tagCanonicalKey(label);
+    const facets = input.facet ? [input.facet] : ["people", "places", "editing"];
+    for (const facet of facets) {
+        const known = canonicalizeTag(facet, label);
+        if (known)
+            return { ...known, label: tagCanonicalKey(known.label) === key ? label : known.label };
+    }
+    const previous = !input.facet && existing.find((tag) => tagCanonicalKey(tag.label) === key);
+    return { facet: input.facet ?? (previous ? previous.facet : "custom"), label };
+}
+export function matchesTagPrefix(tag, prefix) {
+    const normalized = normalizeTagPrefix(prefix);
+    if (tagCanonicalKey(tag.label).startsWith(normalized))
+        return true;
+    const canonical = canonicalizeTag(tag.facet, tag.label);
+    if (!canonical)
+        return false;
+    return VOCABULARY[tag.facet].some((entry) => entry.label === canonical.label
+        && [entry.label, ...entry.aliases].some((alias) => normalizeTagPrefix(alias).startsWith(normalized)));
+}
+/**
+ * A place the vocabulary does not list can still be worth keeping — "subway",
+ * "rooftop bar" — but only when it reads as a concrete setting rather than an
+ * impression. One or two plain words, nothing banned, nothing numeric.
+ */
+function acceptsUnlistedPlace(term) {
+    if (BANNED_TERMS.has(term))
+        return false;
+    const words = term.split(" ");
+    if (words.length === 0 || words.length > 2)
+        return false;
+    return words.every((word) => word.length >= 3 && word.length <= 20 && /^[\p{L}-]+$/u.test(word)
+        && !BANNED_TERMS.has(word) && !["not", "without", "never", "maybe", "possibly"].includes(word));
+}
+/**
+ * Maps one raw term onto the vocabulary, or rejects it. People and editing are
+ * closed sets: an unrecognized term there is a model inventing a grouping
+ * label, which is exactly what the vocabulary exists to prevent.
+ *
+ * `allowUnlisted` opens the places facet to settings the vocabulary does not
+ * list, and belongs only where the caller knows the term is a setting — a
+ * model that labelled it `places`, or the analysis field that holds nothing
+ * else. Offered speculatively it would accept anything short: try "cooking" as
+ * a place and it becomes one.
+ */
+export function canonicalizeTag(facet, raw, options = {}) {
+    const term = normalizeTerm(raw);
+    if (!term || term.length > 40)
+        return null;
+    const known = ALIAS_INDEX.get(`${facet}:${term}`);
+    if (known)
+        return known;
+    if (options.allowUnlisted && facet === "places" && acceptsUnlistedPlace(term)) {
+        return { facet, label: term };
+    }
+    return null;
+}
+/**
+ * Finds vocabulary terms inside a phrase. Analysis fields are written as prose
+ * — "A domestic kitchen", "shot handheld on a busy street" — so a whole-string
+ * match would discard almost everything useful. Matching is on word
+ * boundaries, so "interior" is found in "interior hallway" while "day" is not
+ * found in "daydream".
+ */
+export function matchVocabularyTerms(facet, phrase) {
+    const text = normalizeTerm(phrase);
+    if (!text || /\b(?:no|not|without|never|isnt|isn't|maybe|possibly)\b/u.test(text))
+        return [];
+    const matches = [];
+    for (const entry of VOCABULARY[facet]) {
+        for (const term of [entry.label, ...entry.aliases]) {
+            const normalized = normalizeTerm(term);
+            if (!normalized)
+                continue;
+            const pattern = new RegExp(`(?<![\\p{L}\\p{N}])${normalized.replace(/[-]/gu, "[- ]")}(?![\\p{L}\\p{N}])`, "u");
+            if (pattern.test(text)) {
+                matches.push({ facet, label: entry.label });
+                break;
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * Final selection: canonical identities, no duplicates across facets, capped.
+ * Order is preserved because extractors offer their best-supported evidence
+ * first, so a cap trims the weakest claims rather than an arbitrary tail.
+ */
+export function selectEditorialTags(candidates, limit = MAX_AUTOMATIC_TAGS) {
+    const selected = [];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (selected.length >= limit)
+            break;
+        // Candidates reaching selection have already been vetted by an extractor,
+        // so an unlisted place here is one that was accepted upstream.
+        const canonical = canonicalizeTag(candidate.facet, candidate.label, {
+            allowUnlisted: true,
+        });
+        if (!canonical)
+            continue;
+        const identity = `${canonical.facet}:${normalizeTerm(canonical.label)}`;
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        selected.push(canonical);
+    }
+    return selected;
+}

package/dist/test-queue-cleanup.js

@@ -0,0 +1 @@
+export const testQueueCleanup = {};

package/dist/time-parse.js

@@ -0,0 +1,50 @@
+// --- Time parsing (port of ~/videocity-mcp/src/time_parse.py) ---
+const COLON_SUFFIX_RE = /\s*(?:s|sec|secs|second|seconds)\s*$/i;
+const H = "(?:h|hr|hrs|hour|hours)";
+const M = "(?:m|min|mins|minute|minutes)";
+const S = "(?:s|sec|secs|second|seconds)";
+const SHORTHAND_RE = new RegExp(`^(?:(\\d+)\\s*${H})?\\s*(?:(\\d+)\\s*${M})?\\s*(?:(\\d+(?:\\.\\d+)?)\\s*${S}?)?\\s*$`, "i");
+function parseBareNumeric(text) {
+    const n = Number(text);
+    return Number.isFinite(n) ? n : undefined;
+}
+function parseColonFormat(text) {
+    if (!text.includes(":"))
+        return undefined;
+    const cleaned = text.replace(COLON_SUFFIX_RE, "");
+    const parts = cleaned.split(":");
+    if (parts.length !== 2 && parts.length !== 3)
+        return undefined;
+    if (!parts.every((p) => /^\d+(\.\d+)?$/.test(p)))
+        return undefined;
+    if (parts.length === 2) {
+        return parseFloat(parts[0]) * 60 + parseFloat(parts[1]);
+    }
+    return parseFloat(parts[0]) * 3600 + parseFloat(parts[1]) * 60 + parseFloat(parts[2]);
+}
+function parseShorthand(text) {
+    const match = SHORTHAND_RE.exec(text);
+    if (!match || !match.slice(1).some(Boolean))
+        return undefined;
+    const hours = parseInt(match[1] || "0", 10);
+    const minutes = parseInt(match[2] || "0", 10);
+    const seconds = parseFloat(match[3] || "0");
+    return hours * 3600 + minutes * 60 + seconds;
+}
+const PARSERS = [parseBareNumeric, parseColonFormat, parseShorthand];
+function parseTime(input) {
+    if (input === undefined || input === "")
+        return undefined;
+    if (typeof input === "number")
+        return input;
+    const text = input.trim();
+    if (!text)
+        return undefined;
+    for (const parser of PARSERS) {
+        const result = parser(text);
+        if (result !== undefined)
+            return result;
+    }
+    throw new Error(`Cannot parse timestamp: ${JSON.stringify(input)}`);
+}
+export { parseTime };