videobook 0.0.0-stage → 0.2.0

package/dist/acestep/process.js

@@ -0,0 +1,175 @@
+import { spawn } from "node:child_process";
+import { isHealthy } from "./client.js";
+import { aceStepConfig, checkLocalAvailability } from "./config.js";
+import { logger } from "../logger.js";
+import { AceStepError } from "./errors.js";
+const state = {
+    child: null,
+    handle: null,
+    starting: null,
+    spawnFailure: null,
+    lock: Promise.resolve(),
+};
+const HEALTH_POLL_INTERVAL_MS = 500;
+const HEALTH_POLL_TIMEOUT_MS = 30_000;
+const PROBE_TIMEOUT_MS = 700;
+const EXTERNAL_HEALTH_ATTEMPTS = 3;
+const STOP_GRACE_MS = 2_000;
+async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+function drainOutput(stream) {
+    if (stream === null)
+        return;
+    stream.resume();
+}
+// Identity check before adopting a listener on our port: /health must return the
+// documented {"status":"ok"} shape and /props must serve JSON, so we never treat
+// an unrelated local service as ace-server.
+async function probeAceServer(baseUrl) {
+    try {
+        const health = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        if (!health.ok)
+            return false;
+        const healthBody = (await health.json());
+        if (healthBody?.status !== "ok")
+            return false;
+        const props = await fetch(`${baseUrl}/props`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        if (!props.ok)
+            return false;
+        const propsBody = await props.json();
+        return typeof propsBody === "object" && propsBody !== null;
+    }
+    catch {
+        return false;
+    }
+}
+async function startServer(config, signal) {
+    const baseUrl = `http://127.0.0.1:${config.port}`;
+    if (await probeAceServer(baseUrl)) {
+        const adopted = { baseUrl, owned: false };
+        state.handle = adopted;
+        return adopted;
+    }
+    const availability = checkLocalAvailability(config);
+    if (!availability.available) {
+        throw new AceStepError(availability.kind === "models_missing" ? "models_missing" : "binary_missing", availability.reason);
+    }
+    const serverArgs = [
+        "--models",
+        config.modelsDir,
+        "--host",
+        "127.0.0.1",
+        "--port",
+        String(config.port),
+    ];
+    if (config.keepLoaded)
+        serverArgs.push("--keep-loaded");
+    const child = spawn(config.serverPath, serverArgs, { stdio: ["ignore", "pipe", "pipe"] });
+    drainOutput(child.stdout);
+    drainOutput(child.stderr);
+    state.child = child;
+    state.spawnFailure = null;
+    child.on("error", (error) => {
+        state.spawnFailure = new AceStepError("spawn_failed", `Failed to start ace-server at ${config.serverPath}: ${error.message}`);
+    });
+    child.on("exit", (code, exitSignal) => {
+        logger.error("ace-server-exited", { exitCode: code, signal: exitSignal });
+        if (state.child === child) {
+            state.child = null;
+            state.handle = null;
+        }
+    });
+    const deadline = Date.now() + HEALTH_POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (signal?.aborted) {
+            child.kill("SIGKILL");
+            state.child = null;
+            signal.throwIfAborted();
+        }
+        if (state.spawnFailure !== null)
+            throw state.spawnFailure;
+        if (child.exitCode !== null) {
+            throw new AceStepError("spawn_failed", `ace-server exited during startup (code ${child.exitCode}); run the configured server directly to inspect its output`);
+        }
+        if (await isHealthy(baseUrl, PROBE_TIMEOUT_MS)) {
+            const owned = { baseUrl, owned: true };
+            state.handle = owned;
+            return owned;
+        }
+        await delay(HEALTH_POLL_INTERVAL_MS);
+    }
+    child.kill("SIGKILL");
+    state.child = null;
+    throw new AceStepError("health_timeout", `ace-server did not become healthy on ${baseUrl} within ${HEALTH_POLL_TIMEOUT_MS}ms`);
+}
+export async function ensureAceServer(options = {}) {
+    const config = aceStepConfig();
+    if (config.baseUrl !== null) {
+        for (let attempt = 0; attempt < EXTERNAL_HEALTH_ATTEMPTS; attempt += 1) {
+            if (await probeAceServer(config.baseUrl))
+                return { baseUrl: config.baseUrl, owned: false };
+            if (attempt < EXTERNAL_HEALTH_ATTEMPTS - 1)
+                await delay(PROBE_TIMEOUT_MS);
+        }
+        throw new AceStepError("unreachable", `ace-server at ${config.baseUrl} is not responding (VIDEOBOOK_ACESTEP_BASE_URL). Start it or unset the variable.`);
+    }
+    if (state.handle !== null && (await isHealthy(state.handle.baseUrl, PROBE_TIMEOUT_MS))) {
+        return state.handle;
+    }
+    if (state.starting !== null)
+        return state.starting;
+    state.starting = startServer(config, options.signal);
+    try {
+        return await state.starting;
+    }
+    finally {
+        state.starting = null;
+    }
+}
+// ace-server runs one GPU job at a time on a FIFO worker thread and evicts
+// completed jobs past a small cap while holding every result in memory, so we
+// keep at most one videobook synthesis in flight: queued covers wait here
+// instead of piling result buffers onto the server.
+export async function withSynthLock(fn) {
+    const previous = state.lock;
+    let release;
+    state.lock = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release?.();
+    }
+}
+export async function stopAceServer() {
+    const child = state.child;
+    state.child = null;
+    state.handle = null;
+    state.starting = null;
+    if (child === null || child.exitCode !== null)
+        return;
+    const exited = new Promise((resolve) => {
+        child.once("exit", () => resolve());
+    });
+    child.kill("SIGTERM");
+    const outcome = await Promise.race([
+        exited.then(() => "exited"),
+        delay(STOP_GRACE_MS).then(() => "timeout"),
+    ]);
+    if (outcome === "timeout") {
+        child.kill("SIGKILL");
+        await exited;
+    }
+}
+export function resetAceStepForTests() {
+    state.child?.kill("SIGKILL");
+    state.child = null;
+    state.handle = null;
+    state.starting = null;
+    state.spawnFailure = null;
+    state.lock = Promise.resolve();
+}

package/dist/alive-captions/analyze.js

@@ -0,0 +1,117 @@
+import { join } from "node:path";
+import { findVideoFile } from "videobook-engine";
+import { getApiKey } from "../api-key.js";
+import { probeVideo } from "../ffmpeg.js";
+import { logger } from "../logger.js";
+import { parseSegments } from "../remotion/subtitles/segments.js";
+import { buildPhraseLines, phraseFrameTime } from "../remotion/subtitles/alive-layout.js";
+import { HOP_SECONDS, VOCAL_SAMPLE_RATE, decodeVocalPcm, detectOnsets, envelopeSeries, rmsFrames, snapWordStarts, wordEnergies, } from "./audio.js";
+import { detectPhraseRegions, extractPhraseFrames } from "./frames.js";
+import { aliveFingerprint, readAliveAnalysis, writeAliveAnalysis } from "./model.js";
+import { ALIVE_ANALYSIS_VERSION } from "./schema.js";
+const ENVELOPE_HZ = 20;
+function segmentInputs(segments, audio, onsets) {
+    const words = segments.flatMap((segment) => segment.words);
+    const starts = snapWordStarts(words, onsets);
+    const energies = audio ? wordEnergies(words, audio.rms, audio.hopSeconds) : words.map(() => 0.5);
+    let cursor = 0;
+    return segments.map((segment) => segment.words.map((word) => {
+        const index = cursor++;
+        return { raw: word.word, start: word.start, end: word.end, onsetStart: starts[index], energy: energies[index] };
+    }));
+}
+function toPhrase(lines, index) {
+    const frameTime = phraseFrameTime(lines);
+    return { id: `p${index + 1}`, frameTime: Math.round(frameTime * 1000) / 1000, regions: [], lines };
+}
+/** Phrases, vocal onsets and energy for a transcript; regions are attached separately. */
+function buildAliveAnalysis(input) {
+    const { audio } = input;
+    const onsets = audio ? detectOnsets(audio.rms, audio.hopSeconds) : [];
+    return {
+        version: ALIVE_ANALYSIS_VERSION,
+        fingerprint: input.fingerprint,
+        analyzedAt: new Date().toISOString(),
+        durationSeconds: input.durationSeconds,
+        sourceWidth: input.sourceWidth,
+        sourceHeight: input.sourceHeight,
+        envelopeHz: ENVELOPE_HZ,
+        envelope: audio ? envelopeSeries(audio.rms, ENVELOPE_HZ, audio.hopSeconds) : [],
+        onsets,
+        regionsAnalyzed: false,
+        phrases: buildPhraseLines(segmentInputs(input.segments, audio, onsets)).map(toPhrase),
+    };
+}
+function attachRegions(analysis, regions) {
+    return {
+        ...analysis,
+        regionsAnalyzed: true,
+        phrases: analysis.phrases.map((phrase) => ({ ...phrase, regions: regions.get(phrase.id) ?? [] })),
+    };
+}
+/** Locate the video file and timed transcript an analysis is keyed on. */
+export async function aliveSource(engine, assetId) {
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const videoFile = findVideoFile(manifest.value.files);
+    if (!videoFile)
+        throw new Error(`No video file found in ${assetId}.`);
+    const transcript = await engine.files.read(assetId, "elevenlabs.json");
+    if (!transcript.ok)
+        throw new Error(`No timed transcript found for ${assetId}. Run /transcribe @${assetId} first.`);
+    return {
+        videoPath: join(manifest.value.path, videoFile.name),
+        fingerprint: aliveFingerprint(videoFile, transcript.value),
+        transcript: transcript.value,
+    };
+}
+export async function cachedAliveAnalysis(engine, assetId, fingerprint) {
+    const cached = await readAliveAnalysis(engine, assetId);
+    return cached && cached.fingerprint === fingerprint ? cached : null;
+}
+async function readAudio(videoPath, hasAudio, signal) {
+    if (!hasAudio)
+        return null;
+    const pcm = await decodeVocalPcm(videoPath, signal);
+    return pcm ? { rms: rmsFrames(pcm, VOCAL_SAMPLE_RATE, HOP_SECONDS), hopSeconds: HOP_SECONDS } : null;
+}
+async function withRegions(analysis, videoPath, signal) {
+    const apiKey = getApiKey("OPENAI_API_KEY");
+    if (!apiKey || analysis.phrases.length === 0)
+        return analysis;
+    try {
+        const frames = await extractPhraseFrames(videoPath, analysis.phrases, analysis.durationSeconds, signal);
+        return attachRegions(analysis, await detectPhraseRegions(frames, apiKey, signal));
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        // Placement degrades to the default columns; captions must not fail on vision.
+        logger.warn("alive-captions-regions-failed", { error });
+        return analysis;
+    }
+}
+/**
+ * Full analysis for one video: transcript phrases, vocal onsets and energy,
+ * then per-phrase face/text regions when a vision provider is configured.
+ * Persists and returns the result; a fresh cache hit is returned as-is.
+ */
+export async function analyzeAliveCaptions(engine, assetId, signal, force = false) {
+    const source = await aliveSource(engine, assetId);
+    const cached = force ? null : await cachedAliveAnalysis(engine, assetId, source.fingerprint);
+    if (cached)
+        return cached;
+    const probe = await probeVideo(source.videoPath, { signal });
+    const segments = parseSegments(JSON.parse(source.transcript.toString()));
+    const base = buildAliveAnalysis({
+        segments,
+        audio: await readAudio(source.videoPath, probe.hasAudio, signal),
+        durationSeconds: probe.duration,
+        sourceWidth: probe.width,
+        sourceHeight: probe.height,
+        fingerprint: source.fingerprint,
+    });
+    const analysis = await withRegions(base, source.videoPath, signal);
+    await writeAliveAnalysis(engine, assetId, analysis);
+    return analysis;
+}

package/dist/alive-captions/audio.js

@@ -0,0 +1,179 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runFfmpeg } from "../ffmpeg.js";
+/**
+ * Vocal timing for alive captions: decode a band-limited mono track, then
+ * derive a loudness envelope, vocal onsets and per-word energy from it.
+ */
+export const VOCAL_SAMPLE_RATE = 8_000;
+export const HOP_SECONDS = 0.01;
+const ONSET_HISTORY_FRAMES = 4;
+const ONSET_PEAK_RADIUS = 3;
+const ONSET_MIN_SPACING_SECONDS = 0.06;
+const ONSET_MIN_NOVELTY = 0.35;
+const EPSILON = 1e-4;
+const ENERGY_WINDOW_SECONDS = 0.3;
+const DEFAULT_SNAP_SECONDS = 0.15;
+/** Decode the first audio stream as 8 kHz mono float PCM filtered to the vocal band; callers check the probe for audio first. */
+export async function decodeVocalPcm(inputPath, signal) {
+    const dir = await mkdtemp(join(tmpdir(), "videobook-alive-audio-"));
+    const output = join(dir, "vocal.f32");
+    try {
+        await runFfmpeg([
+            "-y", "-i", inputPath,
+            "-map", "0:a:0", "-vn",
+            "-af", "highpass=f=250,lowpass=f=3500",
+            "-ac", "1", "-ar", String(VOCAL_SAMPLE_RATE),
+            "-f", "f32le", output,
+        ], { signal });
+        const bytes = await readFile(output).catch(() => null);
+        if (!bytes || bytes.length < 4)
+            return null;
+        const aligned = new Uint8Array(bytes.length - (bytes.length % 4));
+        aligned.set(bytes.subarray(0, aligned.length));
+        return new Float32Array(aligned.buffer);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+/** RMS per hop over a two-hop window. */
+export function rmsFrames(samples, sampleRate, hopSeconds = HOP_SECONDS) {
+    const hop = Math.max(1, Math.round(sampleRate * hopSeconds));
+    const window = hop * 2;
+    const count = Math.ceil(samples.length / hop);
+    const frames = new Float32Array(count);
+    for (let frame = 0; frame < count; frame++) {
+        const begin = frame * hop;
+        const end = Math.min(samples.length, begin + window);
+        let sum = 0;
+        for (let index = begin; index < end; index++)
+            sum += samples[index] * samples[index];
+        frames[frame] = Math.sqrt(sum / Math.max(1, end - begin));
+    }
+    return frames;
+}
+function percentile(values, fraction) {
+    if (values.length === 0)
+        return 0;
+    const sorted = Array.from(values).sort((a, b) => a - b);
+    const index = Math.min(sorted.length - 1, Math.max(0, Math.floor(fraction * (sorted.length - 1))));
+    return sorted[index];
+}
+function historyMean(rms, frame) {
+    const from = Math.max(0, frame - ONSET_HISTORY_FRAMES);
+    if (frame === from)
+        return 0;
+    let sum = 0;
+    for (let index = from; index < frame; index++)
+        sum += rms[index];
+    return sum / (frame - from);
+}
+/** Log-energy rise of each frame over its recent history, gated by a noise floor. */
+function onsetNovelty(rms) {
+    const floor = percentile(rms, 0.2) * 2 + EPSILON;
+    const novelty = new Float32Array(rms.length);
+    for (let frame = 0; frame < rms.length; frame++) {
+        if (rms[frame] < floor)
+            continue;
+        novelty[frame] = Math.max(0, Math.log(rms[frame] + EPSILON) - Math.log(historyMean(rms, frame) + EPSILON));
+    }
+    return novelty;
+}
+function noveltyThreshold(novelty) {
+    const active = Array.from(novelty).filter((value) => value > 0);
+    if (active.length === 0)
+        return Infinity;
+    const mean = active.reduce((sum, value) => sum + value, 0) / active.length;
+    const variance = active.reduce((sum, value) => sum + (value - mean) ** 2, 0) / active.length;
+    return Math.max(ONSET_MIN_NOVELTY, mean + Math.sqrt(variance));
+}
+function isLocalPeak(novelty, frame) {
+    const from = Math.max(0, frame - ONSET_PEAK_RADIUS);
+    const to = Math.min(novelty.length - 1, frame + ONSET_PEAK_RADIUS);
+    for (let index = from; index <= to; index++) {
+        if (novelty[index] > novelty[frame])
+            return false;
+    }
+    return true;
+}
+/** Onset times in seconds, ascending. */
+export function detectOnsets(rms, hopSeconds = HOP_SECONDS) {
+    const novelty = onsetNovelty(rms);
+    const threshold = noveltyThreshold(novelty);
+    const onsets = [];
+    for (let frame = 0; frame < novelty.length; frame++) {
+        if (novelty[frame] < threshold || !isLocalPeak(novelty, frame))
+            continue;
+        const time = frame * hopSeconds;
+        if (onsets.length > 0 && time - onsets[onsets.length - 1] < ONSET_MIN_SPACING_SECONDS)
+            continue;
+        onsets.push(Math.round(time * 1000) / 1000);
+    }
+    return onsets;
+}
+function firstAtOrAfter(sorted, value) {
+    let low = 0;
+    let high = sorted.length;
+    while (low < high) {
+        const mid = (low + high) >> 1;
+        if (sorted[mid] < value)
+            low = mid + 1;
+        else
+            high = mid;
+    }
+    return low;
+}
+/** Nearest onset to `start` within ±maxShift that is not before `notBefore`; else `start`. */
+export function snapToOnset(start, onsets, notBefore, maxShift = DEFAULT_SNAP_SECONDS) {
+    const from = firstAtOrAfter(onsets, Math.max(start - maxShift, notBefore));
+    let best = start;
+    let bestDistance = Infinity;
+    for (let index = from; index < onsets.length && onsets[index] <= start + maxShift; index++) {
+        const distance = Math.abs(onsets[index] - start);
+        if (distance < bestDistance) {
+            best = onsets[index];
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+/** Snap each word start to a vocal onset, keeping word order strictly increasing. */
+export function snapWordStarts(words, onsets, maxShift = DEFAULT_SNAP_SECONDS) {
+    const snapped = [];
+    for (const word of words) {
+        const previous = snapped.length > 0 ? snapped[snapped.length - 1] + 0.04 : 0;
+        snapped.push(snapToOnset(word.start, onsets, previous, maxShift));
+    }
+    return snapped;
+}
+function meanRms(rms, start, end, hopSeconds) {
+    const from = Math.max(0, Math.floor(start / hopSeconds));
+    const to = Math.min(rms.length, Math.max(from + 1, Math.ceil(end / hopSeconds)));
+    let sum = 0;
+    for (let index = from; index < to; index++)
+        sum += rms[index];
+    return to > from ? sum / (to - from) : 0;
+}
+/** Per-word vocal energy normalized so the loudest ~5% of words reach 1. */
+export function wordEnergies(words, rms, hopSeconds = HOP_SECONDS) {
+    const raw = words.map((word) => meanRms(rms, word.start, Math.min(word.end, word.start + ENERGY_WINDOW_SECONDS), hopSeconds));
+    const reference = percentile(raw, 0.95);
+    if (reference <= 0)
+        return words.map(() => 0.5);
+    return raw.map((value) => Math.round(Math.min(1, value / reference) * 100) / 100);
+}
+/** Downsample RMS frames to `hz` peak buckets normalized to 0..1. */
+export function envelopeSeries(rms, hz, hopSeconds = HOP_SECONDS) {
+    const perBucket = Math.max(1, Math.round(1 / (hz * hopSeconds)));
+    const peaks = [];
+    for (let begin = 0; begin < rms.length; begin += perBucket) {
+        let peak = 0;
+        for (let index = begin; index < Math.min(rms.length, begin + perBucket); index++)
+            peak = Math.max(peak, rms[index]);
+        peaks.push(peak);
+    }
+    const reference = percentile(peaks, 0.99) || 1;
+    return peaks.map((peak) => Math.round(Math.min(1, peak / reference) * 1000) / 1000);
+}

package/dist/alive-captions/frames.js

@@ -0,0 +1,59 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runFfmpeg } from "../ffmpeg.js";
+import { detectOccupiedRegions } from "../vision-regions.js";
+const FRAMES_PER_REQUEST = 10;
+const SYSTEM_PROMPT = `You are a precise video-layout analyst. Each attached image is a frame from the middle of a sung or spoken phrase that will get large stacked caption typography.
+
+For every frame, identify all occupied regions the captions must not cover:
+- every visible human face, including partial faces and faces on posters or screens
+- every existing visible text block, subtitle, caption, title, logo, watermark, or graphic
+
+Return one entry for every cue_id. Coordinates use a normalized image scale from 0 to 1000: x and y are the top-left corner, followed by width and height. Use tight boxes around the visible occupied content. Do not return boxes for bodies, clothing, scenery, instruments, microphones, or ordinary objects. Return an empty occupied_regions array only when none of the listed content is visible. Never omit, rename, or duplicate a cue_id.`;
+function clampFrameTime(time, duration) {
+    return Math.max(0, Math.min(Math.max(0, duration - 0.05), time));
+}
+export async function extractPhraseFrames(videoPath, phrases, duration, signal) {
+    const dir = await mkdtemp(join(tmpdir(), "videobook-alive-frames-"));
+    try {
+        const frames = [];
+        for (const phrase of phrases) {
+            signal?.throwIfAborted();
+            const frameTime = clampFrameTime(phrase.frameTime, duration);
+            const framePath = join(dir, `${phrase.id}.jpg`);
+            await runFfmpeg([
+                "-y", "-ss", frameTime.toFixed(3), "-i", videoPath,
+                "-frames:v", "1", "-vf", "scale=768:768:force_original_aspect_ratio=decrease", "-q:v", "3",
+                framePath,
+            ], { signal });
+            frames.push({ id: phrase.id, frameTime, buffer: await readFile(framePath) });
+        }
+        return frames;
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+function batches(items, size) {
+    const out = [];
+    for (let index = 0; index < items.length; index += size)
+        out.push(items.slice(index, index + size));
+    return out;
+}
+/** Face/text/graphic boxes per phrase frame, normalized to the source frame. */
+export async function detectPhraseRegions(frames, apiKey, signal) {
+    const regions = new Map();
+    for (const batch of batches(frames, FRAMES_PER_REQUEST)) {
+        const found = await detectOccupiedRegions(batch.map((frame) => ({ id: frame.id, label: `timestamp=${frame.frameTime.toFixed(3)}s`, buffer: frame.buffer })), {
+            apiKey,
+            signal,
+            instructions: SYSTEM_PROMPT,
+            schemaName: "alive_caption_regions",
+            errorLabel: "Alive caption placement",
+        });
+        for (const [id, boxes] of found)
+            regions.set(id, boxes);
+    }
+    return regions;
+}

package/dist/alive-captions/model.js

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { DEFAULT_ALIVE_SETTINGS } from "../remotion/subtitles/alive-types.js";
+import { ALIVE_ANALYSIS_VERSION, aliveAnalysisSchema, aliveSettingsSchema } from "./schema.js";
+const ALIVE_ANALYSIS_METADATA_KEY = "alive-captions.analysis";
+const ALIVE_SETTINGS_METADATA_KEY = "alive-captions.settings";
+export function aliveFingerprint(videoFile, transcript) {
+    return createHash("sha256").update(JSON.stringify({
+        version: ALIVE_ANALYSIS_VERSION,
+        video: { name: videoFile.name, size: videoFile.sizeBytes, objectHash: videoFile.objectHash },
+        transcript: createHash("sha256").update(transcript).digest("hex"),
+    })).digest("hex");
+}
+export async function readAliveAnalysis(engine, assetId) {
+    const result = await engine.metadata.artifacts.read(assetId, ALIVE_ANALYSIS_METADATA_KEY);
+    if (!result.ok)
+        return null;
+    const parsed = aliveAnalysisSchema.safeParse(result.value);
+    return parsed.success ? parsed.data : null;
+}
+export async function writeAliveAnalysis(engine, assetId, analysis) {
+    const result = await engine.metadata.artifacts.write(assetId, ALIVE_ANALYSIS_METADATA_KEY, aliveAnalysisSchema.parse(analysis));
+    if (!result.ok)
+        throw new Error(`Failed to persist alive caption analysis: ${result.error.message}`);
+}
+/** Stored settings merged over the defaults; unreadable fields fall back individually. */
+export async function readAliveSettings(engine, assetId) {
+    const result = await engine.metadata.artifacts.read(assetId, ALIVE_SETTINGS_METADATA_KEY);
+    if (!result.ok)
+        return DEFAULT_ALIVE_SETTINGS;
+    const partial = aliveSettingsSchema.partial().safeParse(result.value);
+    return partial.success ? { ...DEFAULT_ALIVE_SETTINGS, ...partial.data } : DEFAULT_ALIVE_SETTINGS;
+}
+export async function writeAliveSettings(engine, assetId, settings) {
+    const result = await engine.metadata.artifacts.write(assetId, ALIVE_SETTINGS_METADATA_KEY, aliveSettingsSchema.parse(settings));
+    if (!result.ok)
+        throw new Error(`Failed to persist alive caption settings: ${result.error.message}`);
+}

package/dist/alive-captions/schema.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { ALIVE_MOTIONS, ALIVE_STYLES } from "../remotion/subtitles/alive-types.js";
+/** Client-safe (zod only) schemas for stored alive caption analysis and settings. */
+export const ALIVE_ANALYSIS_VERSION = 1;
+const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/);
+export const aliveSettingsSchema = z.object({
+    style: z.enum(ALIVE_STYLES),
+    motion: z.enum(ALIVE_MOTIONS),
+    energySizing: z.boolean(),
+    snapToOnsets: z.boolean(),
+    avoidFaces: z.boolean(),
+    avoidText: z.boolean(),
+    textColor: hexColor,
+    hitColor: hexColor,
+}).strict();
+const regionSchema = z.object({
+    kind: z.enum(["face", "text", "graphic"]),
+    confidence: z.number().min(0).max(1),
+    x: z.number().min(0).max(1),
+    y: z.number().min(0).max(1),
+    width: z.number().positive().max(1),
+    height: z.number().positive().max(1),
+}).strict();
+const wordSchema = z.object({
+    text: z.string().min(1),
+    transcriptStart: z.number().nonnegative(),
+    transcriptEnd: z.number().nonnegative(),
+    onsetStart: z.number().nonnegative(),
+    energy: z.number().min(0).max(1),
+}).strict();
+const phraseSchema = z.object({
+    id: z.string().min(1),
+    frameTime: z.number().nonnegative(),
+    regions: z.array(regionSchema),
+    lines: z.array(z.array(wordSchema).min(1)).min(1),
+}).strict();
+export const aliveAnalysisSchema = z.object({
+    version: z.literal(ALIVE_ANALYSIS_VERSION),
+    fingerprint: z.string().min(1),
+    analyzedAt: z.string().min(1),
+    durationSeconds: z.number().nonnegative(),
+    sourceWidth: z.number().positive(),
+    sourceHeight: z.number().positive(),
+    envelopeHz: z.number().positive(),
+    envelope: z.array(z.number().min(0).max(1)),
+    onsets: z.array(z.number().nonnegative()),
+    regionsAnalyzed: z.boolean(),
+    phrases: z.array(phraseSchema),
+}).strict();

package/dist/alive-captions/track.js

@@ -0,0 +1,9 @@
+import { resolveAliveCues } from "../remotion/subtitles/alive-layout.js";
+import { analyzeAliveCaptions } from "./analyze.js";
+import { readAliveSettings } from "./model.js";
+/** Cues positioned for one render target, analysing the video first when the cache is stale. */
+export async function aliveRenderTrack(engine, assetId, geometry, signal) {
+    const analysis = await analyzeAliveCaptions(engine, assetId, signal);
+    const settings = await readAliveSettings(engine, assetId);
+    return { settings, cues: resolveAliveCues(analysis.phrases, settings, geometry) };
+}

package/dist/api-key.js

@@ -0,0 +1,33 @@
+/**
+ * Defensive readers for provider API keys.
+ *
+ * Tool tests set `process.env.KIE_API_KEY = "test-key"` and enqueue a job
+ * without waiting for it. `afterEach` restores the real key, then the
+ * background worker dequeues and bills real money. These helpers reject
+ * placeholder values at the API call site so the worker fails closed.
+ *
+ * Job handlers MUST go through these — never read `process.env.*_API_KEY`
+ * directly.
+ */
+const PLACEHOLDER_PATTERNS = [/^test-/i, /^sk-test-/i];
+export function isPlaceholderApiKey(value) {
+    return PLACEHOLDER_PATTERNS.some((re) => re.test(value));
+}
+export function requireApiKey(name) {
+    const value = process.env[name];
+    if (!value)
+        throw new Error(`${name} environment variable is not set`);
+    if (isPlaceholderApiKey(value)) {
+        throw new Error(`${name} is a placeholder ("${value}"). Refusing to call the real API. ` +
+            `If a test enqueued this job, the worker dequeued it after the test ended — fix the test, not this guard.`);
+    }
+    return value;
+}
+export function getApiKey(name) {
+    const value = process.env[name];
+    if (!value)
+        return null;
+    if (isPlaceholderApiKey(value))
+        return null;
+    return value;
+}