videobook 0.0.0-stage → 0.2.0

package/dist/tools/_media-refs.js

@@ -0,0 +1,84 @@
+import { findAudioFile, findVideoFile } from "videobook-engine";
+import { extname } from "node:path";
+const IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "webp", "bmp", "tif", "tiff", "gif"]);
+function findImageFile(files) {
+    const images = files.filter((f) => {
+        const ext = (f.extension ?? extname(f.name)).replace(/^\./, "").toLowerCase();
+        return IMAGE_EXTENSIONS.has(ext);
+    });
+    return images.find((f) => f.name.startsWith("original")) ?? images[0] ?? null;
+}
+export async function resolveImageRef(engine, raw) {
+    const assetId = raw.replace(/^@/, "");
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok)
+        return { ok: false, error: artifact.error.message };
+    if (artifact.value.kind !== "image") {
+        return { ok: false, error: `image ref must be an image artifact, got ${artifact.value.kind}: ${assetId}` };
+    }
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        return { ok: false, error: manifest.error.message };
+    const file = findImageFile(manifest.value.files);
+    if (!file)
+        return { ok: false, error: `No image file found in asset ${assetId}` };
+    return { ok: true, value: { assetId, filename: file.name } };
+}
+// `@<assetId>/<filename>` addresses a specific sibling file inside an
+// asset. Used by plan-driven render (e.g. `@plan/s1.mp4`); bypasses the
+// artifact-kind gate since the destination asset may hold multiple media
+// files of mixed kinds.
+async function resolveSlashedRef(engine, raw) {
+    const stripped = raw.replace(/^@/, "");
+    const slashIdx = stripped.indexOf("/");
+    if (slashIdx < 0)
+        return null;
+    const assetId = stripped.slice(0, slashIdx);
+    const filename = stripped.slice(slashIdx + 1);
+    if (!assetId || !filename)
+        return { ok: false, error: `Invalid slashed ref: ${raw}` };
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        return { ok: false, error: manifest.error.message };
+    const file = manifest.value.files.find((f) => f.name === filename);
+    if (!file)
+        return { ok: false, error: `File ${filename} not found in asset ${assetId}` };
+    return { ok: true, value: { assetId, filename } };
+}
+export async function resolveVideoRef(engine, raw) {
+    const slashed = await resolveSlashedRef(engine, raw);
+    if (slashed !== null)
+        return slashed;
+    const assetId = raw.replace(/^@/, "");
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok)
+        return { ok: false, error: artifact.error.message };
+    if (artifact.value.kind !== "video") {
+        return { ok: false, error: `video ref must be a video artifact, got ${artifact.value.kind}: ${assetId}` };
+    }
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        return { ok: false, error: manifest.error.message };
+    const file = findVideoFile(manifest.value.files);
+    if (!file)
+        return { ok: false, error: `No video file found in asset ${assetId}` };
+    return { ok: true, value: { assetId, filename: file.name } };
+}
+// Audio replacement always targets a first-class audio artifact. Notebook
+// cells reference artifact identities; they do not expose nested file paths.
+export async function resolveAudioRef(engine, raw) {
+    const assetId = raw.replace(/^@/, "");
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok)
+        return { ok: false, error: artifact.error.message };
+    if (artifact.value.kind !== "audio") {
+        return { ok: false, error: `audio ref must be an audio artifact, got ${artifact.value.kind}: ${assetId}` };
+    }
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        return { ok: false, error: manifest.error.message };
+    const file = findAudioFile(manifest.value.files, "audio");
+    if (!file)
+        return { ok: false, error: `No audio file found in asset ${assetId}` };
+    return { ok: true, value: { assetId, filename: file.name } };
+}

package/dist/tools/_shared.js

@@ -0,0 +1,59 @@
+// Stand-in https URL for pre-upload apicity safeParse. Asset fields are typed
+// as z.string().url() on the wire, but tools pass local @img-*/@vid-*/@aud-*
+// slugs until the job uploads and substitutes real CDN URLs. Use this only
+// for schema validation — never as the outbound provider payload.
+export function refAsPlaceholderUrl(slug) {
+    const bare = slug.replace(/^@/, "").trim();
+    return `https://placeholder.local/${bare || "asset"}`;
+}
+// Convert a ZodError from an @apicity provider safeParse into an MCP tool
+// `isError` result. Strips the leading `input.` path segment so the surfaced
+// message reads as "image_url: ..." rather than "input.image_url: ..." —
+// MCP callers don't care about apicity's internal request envelope.
+export function zodErrorToToolResult(err) {
+    const lines = err.issues.map((issue) => {
+        const path = issue.path.filter((seg) => seg !== "input").join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    });
+    return {
+        isError: true,
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}
+// Standard MCP tool error from a plain message. Replaces the inline
+// `{ isError: true as const, content: [{ type: "text" as const, text }] }`
+// literals scattered through the tool handlers.
+export function toolError(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+// "provided" = a non-blank string, or an array with at least one non-blank entry.
+function isProvided(value) {
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.some(isProvided);
+    return value !== undefined && value !== null;
+}
+// Enforce a cross-field "at least one of these inputs must be provided" rule —
+// the kind MCP's flat JSON-Schema input can't express. Returns a tool error
+// naming every candidate when none are present, else null.
+export function requireAtLeastOne(label, inputs) {
+    if (inputs.some((i) => isProvided(i.value)))
+        return null;
+    return toolError(`${label} requires at least one of: ${inputs.map((i) => i.name).join(", ")}`);
+}
+// Artifact kind gate. Media kind used to be readable from a slug prefix
+// (`vid-`, `img-`, …); references are artifact ids now, so the kind has to
+// come from the catalog row.
+export async function requireArtifactKind(engine, assetId, allowed, label) {
+    const artifact = engine.artifacts.get(assetId.replace(/^@/u, ""));
+    if (!artifact.ok)
+        return toolError(`${label}: ${artifact.error.message}`);
+    return allowed.includes(artifact.value.kind)
+        ? null
+        : toolError(`${label} requires ${allowed.join(" or ")} media; ${assetId} is ${artifact.value.kind}`);
+}
+export function artifactKindOf(engine, assetId) {
+    const artifact = engine.artifacts.get(assetId.replace(/^@/u, ""));
+    return artifact.ok ? artifact.value.kind : null;
+}

package/dist/tools/_suggest-shared.js

@@ -0,0 +1,279 @@
+import { z } from "zod";
+import { findVideoFile } from "videobook-engine";
+const MAX_FRAMES = 15;
+const SILENCE_MARKER_THRESHOLD_S = 0.5;
+export const DEAD_AIR_THRESHOLD_S = 1.5;
+export const TRIM_BUDGET_FRACTION = 0.4;
+const CANDIDATE_TOLERANCE_S = 0.3;
+export const TrimSchema = z.object({
+    cut_start: z.number().min(0),
+    cut_end: z.number().min(0),
+    reason: z.string(),
+    severity: z.enum(["low", "med", "high"]),
+});
+export const SfxSchema = z.object({
+    timestamp: z.number().min(0),
+    type: z.string(),
+    description: z.string(),
+});
+function decodeBuffer(buf) {
+    if (typeof buf === "string")
+        return buf;
+    return new TextDecoder().decode(buf);
+}
+export function sampleFrames(frames) {
+    if (frames.length <= MAX_FRAMES)
+        return frames;
+    const step = (frames.length - 1) / (MAX_FRAMES - 1);
+    return Array.from({ length: MAX_FRAMES }, (_, i) => frames[Math.round(i * step)]);
+}
+export function extractSilenceCandidates(words, minDurationS) {
+    const wordEntries = words.filter((w) => w.type === "word");
+    const out = [];
+    for (let i = 1; i < wordEntries.length; i++) {
+        const prev = wordEntries[i - 1];
+        const curr = wordEntries[i];
+        const gap = curr.start - prev.end;
+        if (gap >= minDurationS) {
+            out.push({ start: prev.end, end: curr.start, duration: gap });
+        }
+    }
+    return out;
+}
+function formatCandidatesBlock(candidates) {
+    if (candidates.length === 0)
+        return "Silence candidates: none (transcript has no gaps >= 1.5s)";
+    const lines = candidates.map((c, i) => `  ${i + 1}. ${c.start.toFixed(2)}s -> ${c.end.toFixed(2)}s (duration ${c.duration.toFixed(2)}s)`);
+    return `Silence candidates (the only valid sources for severity "high" trims):\n${lines.join("\n")}`;
+}
+function condenseElevenLabsWords(words) {
+    const wordEntries = words.filter((w) => w.type === "word");
+    if (wordEntries.length === 0)
+        return "(no words)";
+    const lines = [];
+    let currentSpeaker = undefined;
+    let currentTurn = [];
+    let turnStart = 0;
+    let prevEnd = null;
+    const flush = () => {
+        if (currentTurn.length === 0)
+            return;
+        const spk = currentSpeaker ?? "?";
+        lines.push(`[t=${turnStart.toFixed(2)} spk=${spk}] ${currentTurn.join(" ")}`);
+        currentTurn = [];
+    };
+    for (const w of wordEntries) {
+        if (prevEnd !== null) {
+            const gap = w.start - prevEnd;
+            if (gap > SILENCE_MARKER_THRESHOLD_S) {
+                flush();
+                lines.push(`[silence=${gap.toFixed(2)}s]`);
+                currentSpeaker = undefined;
+            }
+        }
+        if (w.speaker_id !== currentSpeaker) {
+            flush();
+            currentSpeaker = w.speaker_id;
+            turnStart = w.start;
+        }
+        if (currentTurn.length === 0)
+            turnStart = w.start;
+        currentTurn.push(w.text.trim());
+        prevEnd = w.end;
+    }
+    flush();
+    return lines.join("\n");
+}
+async function loadTranscript(engine, assetId) {
+    const elevenRead = await engine.files.read(assetId, "elevenlabs.json");
+    if (elevenRead.ok) {
+        try {
+            const parsed = JSON.parse(decodeBuffer(elevenRead.value));
+            if (Array.isArray(parsed.words) && parsed.words.length > 0) {
+                return { source: "elevenlabs", words: parsed.words, text: parsed.text ?? "" };
+            }
+        }
+        catch {
+            // fall through to gpt4otrans
+        }
+    }
+    const gptRead = await engine.files.read(assetId, ".analysis.gpt4otrans.json");
+    if (gptRead.ok) {
+        try {
+            const parsed = JSON.parse(decodeBuffer(gptRead.value));
+            if (parsed.text) {
+                return { source: "gpt4otrans", text: parsed.text };
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return null;
+}
+async function loadPriorAnalysis(engine, assetId) {
+    const read = await engine.files.read(assetId, ".original.analysis.json");
+    if (!read.ok)
+        return null;
+    try {
+        return JSON.parse(decodeBuffer(read.value));
+    }
+    catch {
+        return null;
+    }
+}
+function isWithinCandidate(cutStart, cutEnd, candidates) {
+    return candidates.some((c) => cutStart >= c.start - CANDIDATE_TOLERANCE_S
+        && cutEnd <= c.end + CANDIDATE_TOLERANCE_S);
+}
+export function filterValidTrims(trims, candidates, trimBudgetS, evidence) {
+    const dropped = [];
+    const sorted = [...trims].sort((a, b) => a.cut_start - b.cut_start);
+    const kept = [];
+    let totalDuration = 0;
+    let lastEnd = -Infinity;
+    for (const t of sorted) {
+        if (evidence.duration !== null && t.cut_end > evidence.duration) {
+            dropped.push({ trim: t, reason: "cut_end exceeds video duration" });
+            continue;
+        }
+        if (t.cut_end <= t.cut_start) {
+            dropped.push({ trim: t, reason: "cut_end <= cut_start" });
+            continue;
+        }
+        if (t.cut_start < lastEnd) {
+            dropped.push({ trim: t, reason: `overlaps previous kept trim ending at ${lastEnd.toFixed(2)}s` });
+            continue;
+        }
+        if (t.severity === "high" && !isWithinCandidate(t.cut_start, t.cut_end, candidates)) {
+            dropped.push({
+                trim: t,
+                reason: `severity:"high" trim ${t.cut_start.toFixed(2)}->${t.cut_end.toFixed(2)} is not contained in any silence candidate`,
+            });
+            continue;
+        }
+        if (t.severity === "med" && evidence.transcriptSource !== "elevenlabs") {
+            dropped.push({ trim: t, reason: "filler trims require a word-timed transcript" });
+            continue;
+        }
+        if (t.severity === "med" && t.cut_end - t.cut_start > 1.5) {
+            dropped.push({
+                trim: t,
+                reason: `severity:"med" trim is ${(t.cut_end - t.cut_start).toFixed(2)}s — fillers must be < 1.5s`,
+            });
+            continue;
+        }
+        const dur = t.cut_end - t.cut_start;
+        if (totalDuration + dur > trimBudgetS) {
+            dropped.push({
+                trim: t,
+                reason: `trim budget exceeded (${(totalDuration + dur).toFixed(2)}s > ${trimBudgetS.toFixed(2)}s)`,
+            });
+            continue;
+        }
+        kept.push(t);
+        totalDuration += dur;
+        lastEnd = t.cut_end;
+    }
+    return { kept, dropped };
+}
+function metaLine(meta) {
+    if (!meta)
+        return null;
+    const dims = meta.width && meta.height ? `${meta.width}x${meta.height}` : "unknown size";
+    const dur = typeof meta.duration === "number" ? `${meta.duration.toFixed(1)}s` : "unknown duration";
+    return `Video metadata: ${dims}, duration ${dur}, hasAudio=${meta.hasAudio ?? "unknown"}`;
+}
+function priorLine(prior) {
+    if (!prior)
+        return null;
+    const scenes = (prior.scenes ?? [])
+        .map((s) => `t=${(s.timestamp ?? 0).toFixed(1)}s: ${s.description ?? ""}`)
+        .join("; ");
+    return `Prior analysis — summary: ${prior.summary ?? "n/a"}; mood: ${prior.mood ?? "n/a"}; scenes: ${scenes || "n/a"}`;
+}
+function transcriptLine(transcript) {
+    if (transcript.source === "none") {
+        return "Transcript: unavailable. Assess visual pacing only; do not infer speech, silence, filler words, or audio events from missing transcription.";
+    }
+    if (transcript.source === "elevenlabs") {
+        return `Transcript (word-level, with silence markers):\n${condenseElevenLabsWords(transcript.words)}`;
+    }
+    return `Transcript (no word timings):\n${transcript.text}`;
+}
+export function buildCutsContext(meta, prior, transcript, frameCount, candidates, trimBudgetS, instructions) {
+    const parts = [];
+    if (instructions?.trim())
+        parts.push(`Editing request: ${instructions.trim()}`);
+    const m = metaLine(meta);
+    if (m)
+        parts.push(m);
+    parts.push(`Trim budget: total trim duration must be <= ${trimBudgetS.toFixed(1)}s.`);
+    if (transcript.source === "elevenlabs") {
+        parts.push(formatCandidatesBlock(candidates));
+    }
+    else if (transcript.source === "gpt4otrans") {
+        parts.push("Silence candidates: none (transcript has no word timings; only visually supported severity \"low\" trims are allowed).");
+    }
+    else {
+        parts.push("Silence candidates: none (no transcript; only visually supported severity \"low\" trims are allowed).");
+    }
+    const p = priorLine(prior);
+    if (p)
+        parts.push(p);
+    parts.push(transcriptLine(transcript));
+    parts.push(`${frameCount} timestamped frames follow.`);
+    return parts.join("\n\n");
+}
+export function buildSfxContext(meta, prior, transcript, frameCount) {
+    const parts = [];
+    const m = metaLine(meta);
+    if (m)
+        parts.push(m);
+    const p = priorLine(prior);
+    if (p)
+        parts.push(p);
+    parts.push(transcriptLine(transcript));
+    parts.push(`${frameCount} frames at low detail follow.`);
+    return parts.join("\n\n");
+}
+export async function loadAssetForAnalysis(engine, assetId, options = {}) {
+    const manifestResult = await engine.files.manifest(assetId);
+    if (!manifestResult.ok) {
+        return { ok: false, error: { kind: "manifest", message: manifestResult.error.message } };
+    }
+    const manifest = manifestResult.value;
+    const videoFile = findVideoFile(manifest.files);
+    if (!videoFile) {
+        return { ok: false, error: { kind: "no-video", message: "No video file found. Wait for the selected video's generation or upload to finish." } };
+    }
+    const frameNames = (manifest.directories?.["original_frames"] ?? [])
+        .filter((f) => f.endsWith(".jpg"))
+        .sort((a, b) => parseFloat(a) - parseFloat(b));
+    if (frameNames.length === 0) {
+        return {
+            ok: false,
+            error: { kind: "no-frames", message: "The selected video has no frames yet. Run /process-video for its notebook cell first." },
+        };
+    }
+    const transcript = await loadTranscript(engine, assetId);
+    if (!transcript && options.requireTranscript !== false) {
+        return {
+            ok: false,
+            error: { kind: "no-transcript", message: "No transcript found. Run /transcribe for the selected video's notebook cell first." },
+        };
+    }
+    const metaResult = await engine.metadata.artifacts.read(assetId, "original");
+    const meta = metaResult.ok ? metaResult.value : null;
+    const prior = await loadPriorAnalysis(engine, assetId);
+    return {
+        ok: true,
+        value: {
+            manifest,
+            frameNames,
+            transcript: transcript ?? { source: "none" },
+            meta,
+            prior,
+        },
+    };
+}

package/dist/tools/add-timeline-audio.js

@@ -0,0 +1,73 @@
+import { join } from "node:path";
+import { findAudioFile } from "videobook-engine";
+import { v7 as uuidv7 } from "uuid";
+import { z } from "zod";
+import { probeVideo } from "../ffmpeg.js";
+import { readTimeline, resolveArtifact, timelineFailure, timelineInput, timelinePayload, writeTimeline, } from "../timeline-helpers.js";
+export function addTimelineAudioDef(engine) {
+    return {
+        name: "add_timeline_audio",
+        description: "Add a typed audio overlay to the selected book timeline",
+        schema: {
+            book_id: z.string().uuid(),
+            asset_id: z.string(),
+            start_frame: z.number().int().min(0),
+            duration_frames: z.number().int().positive().optional(),
+            volume: z.number().min(0).max(100).optional(),
+            fade_in: z.number().min(0).optional(),
+            fade_out: z.number().min(0).optional(),
+        },
+        handler: async (args) => {
+            const asset = resolveArtifact(engine, String(args.asset_id));
+            if (!asset || asset.kind !== "audio") {
+                return timelineFailure(`Audio artifact not found: ${String(args.asset_id)}`);
+            }
+            const manifest = await engine.files.manifest(asset.artifactId);
+            if (!manifest.ok)
+                return timelineFailure(manifest.error.message);
+            const audioFile = findAudioFile(manifest.value.files, asset.kind);
+            if (!audioFile)
+                return timelineFailure(`No audio file found in ${asset.label ?? asset.artifactId}`);
+            let durationFrames = args.duration_frames;
+            if (durationFrames === undefined) {
+                try {
+                    const probe = await probeVideo(join(manifest.value.path, audioFile.name));
+                    const { frameRate } = engine.sequences.getPrimary();
+                    durationFrames = Math.max(1, Math.round((probe.audioDuration ?? probe.duration) * frameRate.numerator / frameRate.denominator));
+                }
+                catch (error) {
+                    return timelineFailure(error instanceof Error ? error.message : String(error));
+                }
+            }
+            const timeline = readTimeline(engine);
+            const clipId = uuidv7();
+            const audio = [
+                ...timeline.audio.map((clip) => ({
+                    id: clip.id,
+                    artifactId: clip.artifactId,
+                    startFrame: clip.startFrame,
+                    durationFrames: clip.durationFrames,
+                    ...(clip.volume === undefined ? {} : { volume: clip.volume }),
+                    ...(clip.fadeIn === undefined ? {} : { fadeIn: clip.fadeIn }),
+                    ...(clip.fadeOut === undefined ? {} : { fadeOut: clip.fadeOut }),
+                })),
+                {
+                    id: clipId,
+                    artifactId: asset.artifactId,
+                    startFrame: args.start_frame,
+                    durationFrames,
+                    ...(args.volume === undefined ? {} : { volume: args.volume }),
+                    ...(args.fade_in === undefined ? {} : { fadeIn: args.fade_in }),
+                    ...(args.fade_out === undefined ? {} : { fadeOut: args.fade_out }),
+                },
+            ];
+            const result = await writeTimeline(engine, { ...timelineInput(timeline), audio });
+            if (!result.ok)
+                return timelineFailure(result.error.message);
+            const clip = result.value.audio.find((item) => item.id === clipId);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ...timelinePayload(result.value), clip }) }],
+            };
+        },
+    };
+}

package/dist/tools/alive-captions.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { aliveSource, cachedAliveAnalysis } from "../alive-captions/analyze.js";
+import { readAliveSettings, writeAliveSettings } from "../alive-captions/model.js";
+import { queue } from "../queue.js";
+import { isValidHex } from "../remotion/util.js";
+import { ALIVE_MOTIONS, ALIVE_STYLES } from "../remotion/subtitles/alive-types.js";
+import { artifactKindOf } from "./_shared.js";
+import { RENDER_ORIENTATIONS } from "./reconcile-project-work.js";
+const ANALYSIS_TIMEOUT_MS = 600_000;
+function errorResult(status, message) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify({ status, message }) }],
+    };
+}
+function textResult(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+}
+function videoGate(engine, assetId, tool) {
+    const kind = artifactKindOf(engine, assetId);
+    if (kind === null)
+        return errorResult("asset_not_found", `Artifact ${assetId} was not found.`);
+    if (kind !== "video")
+        return errorResult("invalid_asset", `${tool} requires a video artifact; ${assetId} is ${kind}`);
+    return null;
+}
+async function runAnalysis(engine, bookId, assetId, force) {
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const clear = await engine.jobs.failures.clear(assetId);
+    if (!clear.ok)
+        throw new Error(clear.error.message);
+    const result = await queue.enqueueAndWait(`alive-captions-${assetId}-${Date.now()}`, {
+        type: "analyze_alive_captions",
+        assetId,
+        assetDir: manifest.value.path,
+        bookId,
+        force,
+    }, ANALYSIS_TIMEOUT_MS);
+    return result.analysis;
+}
+export function aliveCaptionsDef(engine) {
+    return {
+        name: "alive_captions",
+        description: "Read a video's alive-caption analysis (phrases, vocal onsets, per-word energy, loudness, face and text regions) and its saved caption settings, analyzing first when it is missing or stale.",
+        schema: {
+            asset_id: z.string().describe("Video artifact id"),
+            book_id: z.string().describe("Book id"),
+            reanalyze: z.boolean().optional().describe("Re-run the analysis even when the cached one is current (default false)"),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id, reanalyze = false } = args;
+            const gate = videoGate(engine, asset_id, "alive_captions");
+            if (gate)
+                return gate;
+            let fingerprint;
+            try {
+                fingerprint = (await aliveSource(engine, asset_id)).fingerprint;
+            }
+            catch (error) {
+                return errorResult("missing_transcript", error instanceof Error ? error.message : String(error));
+            }
+            const cached = reanalyze ? null : await cachedAliveAnalysis(engine, asset_id, fingerprint);
+            let analysis = cached;
+            if (!analysis) {
+                try {
+                    analysis = await runAnalysis(engine, book_id, asset_id, reanalyze);
+                }
+                catch (error) {
+                    return errorResult("analysis_failed", error instanceof Error ? error.message : String(error));
+                }
+            }
+            return textResult({
+                asset_id,
+                status: "ready",
+                cached: cached !== null,
+                regions_analyzed: analysis.regionsAnalyzed,
+                settings: await readAliveSettings(engine, asset_id),
+                analysis,
+            });
+        },
+    };
+}
+function mergeSettings(current, args) {
+    return {
+        style: args.style ?? current.style,
+        motion: args.motion ?? current.motion,
+        energySizing: args.energy_sizing ?? current.energySizing,
+        snapToOnsets: args.snap_to_onsets ?? current.snapToOnsets,
+        avoidFaces: args.avoid_faces ?? current.avoidFaces,
+        avoidText: args.avoid_text ?? current.avoidText,
+        textColor: args.text_color ?? current.textColor,
+        hitColor: args.hit_color ?? current.hitColor,
+    };
+}
+function invalidColor(args) {
+    if (args.text_color !== undefined && !isValidHex(args.text_color))
+        return `Invalid text_color hex: ${args.text_color}`;
+    if (args.hit_color !== undefined && !isValidHex(args.hit_color))
+        return `Invalid hit_color hex: ${args.hit_color}`;
+    return null;
+}
+/** Point every orientation's stored render settings at alive subtitles. */
+async function applyToRenders(engine, assetId) {
+    for (const orientation of RENDER_ORIENTATIONS) {
+        const key = `${orientation}.render`;
+        const existing = await engine.metadata.artifacts.read(assetId, key);
+        const write = await engine.metadata.artifacts.write(assetId, key, {
+            ...(existing.ok ? existing.value : {}),
+            subtitlesEnabled: true,
+            highlightStyle: "alive",
+        });
+        if (!write.ok)
+            throw new Error(`Failed to persist ${orientation} render settings: ${write.error.message}`);
+    }
+}
+export function setAliveCaptionsDef(engine) {
+    return {
+        name: "set_alive_captions",
+        description: "Save a video's alive caption style (stack, punch or karaoke), word entrance (pop, slam or rise), energy sizing, onset snapping, face and text avoidance and colors; by default its renders switch to alive subtitles.",
+        schema: {
+            asset_id: z.string().describe("Video artifact id"),
+            book_id: z.string().describe("Book id"),
+            style: z.enum(ALIVE_STYLES).optional()
+                .describe("stack builds a stacked block word by word; punch shows one big word at a time; karaoke shows the phrase dimmed and lights words"),
+            motion: z.enum(ALIVE_MOTIONS).optional()
+                .describe("Word entrance animation"),
+            energy_sizing: z.boolean().optional().describe("Size lines by the vocal energy under each word"),
+            snap_to_onsets: z.boolean().optional().describe("Start words on detected vocal onsets instead of raw transcript times"),
+            avoid_faces: z.boolean().optional().describe("Keep captions off detected faces"),
+            avoid_text: z.boolean().optional().describe("Keep captions off detected on-screen text and graphics"),
+            text_color: z.string().optional().describe("Caption text color hex"),
+            hit_color: z.string().optional().describe("Color for the sung word and loud words, hex"),
+            apply_to_renders: z.boolean().optional().describe("Enable alive subtitles in stored render settings (default true)"),
+        },
+        handler: async (args) => {
+            const input = args;
+            const gate = videoGate(engine, input.asset_id, "set_alive_captions");
+            if (gate)
+                return gate;
+            const colorError = invalidColor(input);
+            if (colorError)
+                return errorResult("invalid_color", colorError);
+            const settings = mergeSettings(await readAliveSettings(engine, input.asset_id), input);
+            try {
+                await writeAliveSettings(engine, input.asset_id, settings);
+                if (input.apply_to_renders !== false)
+                    await applyToRenders(engine, input.asset_id);
+            }
+            catch (error) {
+                return errorResult("settings_write_failed", error instanceof Error ? error.message : String(error));
+            }
+            return textResult({ asset_id: input.asset_id, status: "configured", settings, applied_to_renders: input.apply_to_renders !== false });
+        },
+    };
+}