@kheleshikhi/studio-agent 0.8.0 → 0.9.0

package/dist/episode.js

@@ -0,0 +1,648 @@
+/**
+ * Shot-based episode production ("Level C").
+ *
+ * An episode is a small, versioned manifest (`kheleshikhi.episode.v1`): an
+ * ordered list of shots, each one presentation render of a Scene or an
+ * Experience, plus episode narration, music, timed sound and subtitles. The
+ * runner renders each shot under a content-addressed key, reuses every shot
+ * whose key is unchanged and whose cached MP4 still verifies, and assembles
+ * the shots into one MP4 with one episode audio mix (narration over a music
+ * bed ducked under it, plus each shot's own sounds), loudness normalised to a
+ * target, an SRT file and a QC report.
+ *
+ * What a shot key covers (and nothing else): the shot's render recipe, the
+ * subject's source hash(es), every dependency-record digest (exact Component,
+ * Behavior and Audio definitions), the runtime fingerprint, the sha256 of
+ * every sound the subject names, the output profile and the encoder
+ * settings. File modification times are never consulted: a cached shot is
+ * valid when its key matches and its MP4 hashes and probes as recorded.
+ *
+ * Everything here is a derivative (`canonical: false`): an episode never
+ * changes a Scene, an Experience or a Component, and never certifies one.
+ */
+import { createHash } from "node:crypto";
+import { CliError } from "./types.js";
+import { canonicalJson, digestOf } from "./shot-provenance.js";
+import { frameCountFor, MIX_SAMPLE_RATE, parseRecipe, RECIPE_KIND, RENDER_PROFILES } from "./video.js";
+export const EPISODE_SCHEMA = "kheleshikhi.episode.v1";
+export const EPISODE_MANIFEST_KIND = "kheleshikhi.episode-render.v1";
+export const SHOT_CACHE_KIND = "kheleshikhi.episode-shot-cache.v1";
+/** Bump when the shot render or its encode changes meaning: every key moves. */
+export const SHOT_KEY_VERSION = 1;
+export const EPISODE_LIMITS = { maxShots: 200, maxSeconds: 3600, maxAudioItems: 128, maxCues: 2000, maxText: 400 };
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.-]{0,79}$/;
+/** Server public ids (asset, revision): URL-safe base64 alphabet. */
+const PUBLIC_ID = /^[A-Za-z0-9_-]{1,80}$/;
+function publicId(value, name) {
+    if (typeof value !== "string" || !PUBLIC_ID.test(value))
+        invalid(`${name} must be a public id (letters, digits, _ -).`);
+    return value;
+}
+function invalid(message) {
+    throw new CliError(message, "EPISODE_INVALID", 2);
+}
+function object(value, name) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        invalid(`${name} must be an object.`);
+    return value;
+}
+function only(value, name, allowed) {
+    const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (unknown.length)
+        invalid(`${name} has unknown fields: ${unknown.sort().join(", ")}.`);
+}
+function number(value, name, minimum, maximum, fallback) {
+    if (value === undefined && fallback !== undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum) {
+        invalid(`${name} must be a number from ${minimum} to ${maximum}.`);
+    }
+    return value;
+}
+function text(value, name, maximum = EPISODE_LIMITS.maxText) {
+    if (typeof value !== "string" || !value.trim() || value.length > maximum)
+        invalid(`${name} must be text of at most ${maximum} characters.`);
+    return value;
+}
+function identifier(value, name) {
+    if (typeof value !== "string" || !IDENTIFIER.test(value))
+        invalid(`${name} must be an identifier (letters, digits, _ . -).`);
+    return value;
+}
+/** Seconds that are a whole number of frames at `fps` (within a billionth of a frame). */
+function wholeFrames(seconds, fps, name) {
+    const frames = seconds * fps;
+    if (Math.abs(frames - Math.round(frames)) > 1e-6)
+        invalid(`${name} must be a whole number of frames at ${fps} fps.`);
+    return Math.round(frames);
+}
+function relativePath(value, name) {
+    const file = text(value, name, 512);
+    if (file.includes("\0"))
+        invalid(`${name} is not a path.`);
+    return file;
+}
+function captions(value, name, allowShot) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > EPISODE_LIMITS.maxCues)
+        invalid(`${name} must be a list of at most ${EPISODE_LIMITS.maxCues} cues.`);
+    return value.map((raw, index) => {
+        const cue = object(raw, `${name}[${index}]`);
+        only(cue, `${name}[${index}]`, allowShot ? ["start", "end", "text", "shot"] : ["start", "end", "text"]);
+        const start = number(cue.start, `${name}[${index}].start`, 0, EPISODE_LIMITS.maxSeconds);
+        const end = number(cue.end, `${name}[${index}].end`, start + 0.001, EPISODE_LIMITS.maxSeconds);
+        return { start, end, text: text(cue.text, `${name}[${index}].text`), ...(cue.shot !== undefined ? { shot: identifier(cue.shot, `${name}[${index}].shot`) } : {}) };
+    });
+}
+function timedAudio(value, name) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > EPISODE_LIMITS.maxAudioItems)
+        invalid(`${name} must be a list of at most ${EPISODE_LIMITS.maxAudioItems}.`);
+    return value.map((raw, index) => {
+        const item = object(raw, `${name}[${index}]`);
+        only(item, `${name}[${index}]`, ["id", "file", "at", "shot", "volume"]);
+        return {
+            id: identifier(item.id, `${name}[${index}].id`),
+            file: relativePath(item.file, `${name}[${index}].file`),
+            at: number(item.at, `${name}[${index}].at`, 0, EPISODE_LIMITS.maxSeconds, 0),
+            ...(item.shot !== undefined ? { shot: identifier(item.shot, `${name}[${index}].shot`) } : {}),
+            volume: number(item.volume, `${name}[${index}].volume`, 0, 4, 1),
+        };
+    });
+}
+/** Parse and bound an episode manifest. Unknown fields are refused, never ignored. */
+export function parseEpisode(value) {
+    const document = object(value, "Episode");
+    only(document, "Episode", ["schema", "id", "title", "context", "output", "shots", "audio", "subtitles"]);
+    if (document.schema !== EPISODE_SCHEMA)
+        invalid(`schema must be ${EPISODE_SCHEMA}.`);
+    const id = identifier(document.id, "id");
+    const title = text(document.title, "title");
+    const contextRaw = document.context === undefined ? {} : object(document.context, "context");
+    only(contextRaw, "context", ["project", "library"]);
+    const context = {
+        project: contextRaw.project === undefined ? null : text(contextRaw.project, "context.project", 120),
+        library: contextRaw.library === undefined ? null : text(contextRaw.library, "context.library", 120),
+    };
+    const outputRaw = object(document.output ?? {}, "output");
+    only(outputRaw, "output", ["profile", "fps", "crf", "audio_bitrate", "loudness"]);
+    const profile = (outputRaw.profile ?? "landscape-720p");
+    if (typeof profile !== "string" || !Object.hasOwn(RENDER_PROFILES, profile))
+        invalid(`output.profile must be one of ${Object.keys(RENDER_PROFILES).join(", ")}.`);
+    const fps = number(outputRaw.fps, "output.fps", 1, 60, 30);
+    if (!Number.isInteger(fps))
+        invalid("output.fps must be a whole number.");
+    const crf = number(outputRaw.crf, "output.crf", 0, 51, 18);
+    const bitrate = outputRaw.audio_bitrate ?? "192k";
+    if (typeof bitrate !== "string" || !/^(96|128|160|192|256|320)k$/.test(bitrate))
+        invalid("output.audio_bitrate must be one of 96k, 128k, 160k, 192k, 256k, 320k.");
+    const loudnessRaw = object(outputRaw.loudness ?? {}, "output.loudness");
+    only(loudnessRaw, "output.loudness", ["integrated", "true_peak", "lra"]);
+    const loudness = {
+        integrated: number(loudnessRaw.integrated, "output.loudness.integrated", -70, -5, -16),
+        true_peak: number(loudnessRaw.true_peak, "output.loudness.true_peak", -9, 0, -1.5),
+        lra: number(loudnessRaw.lra, "output.loudness.lra", 1, 50, 11),
+    };
+    const output = { profile, ...RENDER_PROFILES[profile], fps, crf, audio_bitrate: bitrate, loudness };
+    if (!Array.isArray(document.shots) || !document.shots.length || document.shots.length > EPISODE_LIMITS.maxShots) {
+        invalid(`shots must be a list of 1 to ${EPISODE_LIMITS.maxShots} shots.`);
+    }
+    const seen = new Set();
+    const shots = document.shots.map((raw, index) => {
+        const name = `shots[${index}]`;
+        const shot = object(raw, name);
+        only(shot, name, ["id", "title", "scene", "experience", "start", "duration", "actions", "audio", "sound_volume", "transition", "captions"]);
+        const shotId = identifier(shot.id, `${name}.id`);
+        if (seen.has(shotId))
+            invalid(`${name}.id ${shotId} is used twice.`);
+        seen.add(shotId);
+        if ((shot.scene === undefined) === (shot.experience === undefined))
+            invalid(`${name} needs exactly one of scene or experience.`);
+        let subject;
+        let scene;
+        let experience;
+        if (shot.scene !== undefined) {
+            subject = "scene";
+            const value = object(shot.scene, `${name}.scene`);
+            only(value, `${name}.scene`, ["asset", "source", "revision"]);
+            const source = value.source ?? "local";
+            if (source !== "local" && source !== "approved")
+                invalid(`${name}.scene.source must be local or approved.`);
+            if (value.revision !== undefined && source !== "approved")
+                invalid(`${name}.scene.revision needs source approved.`);
+            scene = { asset: publicId(value.asset, `${name}.scene.asset`), source, ...(value.revision !== undefined ? { revision: publicId(value.revision, `${name}.scene.revision`) } : {}) };
+        }
+        else {
+            subject = "experience";
+            const value = object(shot.experience, `${name}.experience`);
+            only(value, `${name}.experience`, ["id", "source"]);
+            const source = value.source ?? "local";
+            if (source !== "local" && source !== "saved")
+                invalid(`${name}.experience.source must be local or saved.`);
+            experience = { id: identifier(value.id, `${name}.experience.id`), source };
+        }
+        const start = number(shot.start, `${name}.start`, 0, 3600, 0);
+        const duration = number(shot.duration, `${name}.duration`, 1 / fps, 120);
+        if (wholeFrames(duration, fps, `${name}.duration`) < 1)
+            invalid(`${name}.duration is shorter than a frame.`);
+        const audio = shot.audio ?? "scene";
+        if (audio !== "scene" && audio !== "silent")
+            invalid(`${name}.audio must be scene or silent.`);
+        // The shot's recipe is the render's own validation: reuse it.
+        let recipe;
+        try {
+            recipe = parseRecipe({ kind: RECIPE_KIND, fps, start, end: start + duration, profile, audio, crf, actions: shot.actions ?? [] }, subject);
+        }
+        catch (error) {
+            invalid(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const transitionRaw = shot.transition === undefined ? { type: "cut" } : object(shot.transition, `${name}.transition`);
+        only(transitionRaw, `${name}.transition`, ["type", "duration"]);
+        let transition;
+        if (transitionRaw.type === "cut") {
+            if (transitionRaw.duration !== undefined)
+                invalid(`${name}.transition cut takes no duration.`);
+            transition = { type: "cut" };
+        }
+        else if (transitionRaw.type === "crossfade") {
+            if (index === 0)
+                invalid(`${name}: the first shot cannot crossfade from nothing.`);
+            const length = number(transitionRaw.duration, `${name}.transition.duration`, 1 / fps, 5);
+            wholeFrames(length, fps, `${name}.transition.duration`);
+            transition = { type: "crossfade", duration: length };
+        }
+        else {
+            invalid(`${name}.transition.type must be cut or crossfade.`);
+        }
+        const shotCaptions = captions(shot.captions, `${name}.captions`, false);
+        for (const cue of shotCaptions)
+            if (cue.end > duration + 1e-9)
+                invalid(`${name}.captions end after the shot.`);
+        return {
+            id: shotId, ...(shot.title !== undefined ? { title: text(shot.title, `${name}.title`) } : {}),
+            subject, ...(scene ? { scene } : {}), ...(experience ? { experience } : {}),
+            start, duration, actions: recipe.actions, audio, sound_volume: number(shot.sound_volume, `${name}.sound_volume`, 0, 4, 1),
+            transition, captions: shotCaptions,
+        };
+    });
+    // A crossfade overlaps both shots: it must fit inside each.
+    shots.forEach((shot, index) => {
+        if (shot.transition.type !== "crossfade")
+            return;
+        const length = shot.transition.duration;
+        if (length >= shot.duration || length >= shots[index - 1].duration)
+            invalid(`shots[${index}].transition is longer than a shot it joins.`);
+    });
+    const audioRaw = object(document.audio ?? {}, "audio");
+    only(audioRaw, "audio", ["narration", "music", "sfx"]);
+    const narration = timedAudio(audioRaw.narration, "audio.narration");
+    const sfx = timedAudio(audioRaw.sfx, "audio.sfx");
+    const musicRaw = audioRaw.music ?? [];
+    if (!Array.isArray(musicRaw) || musicRaw.length > 8)
+        invalid("audio.music must be a list of at most 8 beds.");
+    const music = musicRaw.map((raw, index) => {
+        const name = `audio.music[${index}]`;
+        const item = object(raw, name);
+        only(item, name, ["id", "file", "at", "shot", "end", "loop", "volume", "duck"]);
+        const at = number(item.at, `${name}.at`, 0, EPISODE_LIMITS.maxSeconds, 0);
+        let duck = { threshold: 0.03, ratio: 8, attack_ms: 20, release_ms: 400 };
+        if (item.duck === false)
+            duck = false;
+        else if (item.duck !== undefined) {
+            const value = object(item.duck, `${name}.duck`);
+            only(value, `${name}.duck`, ["threshold", "ratio", "attack_ms", "release_ms"]);
+            duck = {
+                threshold: number(value.threshold, `${name}.duck.threshold`, 0.001, 1, 0.03),
+                ratio: number(value.ratio, `${name}.duck.ratio`, 1, 20, 8),
+                attack_ms: number(value.attack_ms, `${name}.duck.attack_ms`, 0.01, 2000, 20),
+                release_ms: number(value.release_ms, `${name}.duck.release_ms`, 0.01, 9000, 400),
+            };
+        }
+        if (item.loop !== undefined && typeof item.loop !== "boolean")
+            invalid(`${name}.loop must be boolean.`);
+        return {
+            id: identifier(item.id, `${name}.id`), file: relativePath(item.file, `${name}.file`), at,
+            ...(item.shot !== undefined ? { shot: identifier(item.shot, `${name}.shot`) } : {}),
+            end: item.end === undefined ? null : number(item.end, `${name}.end`, at + 0.001, EPISODE_LIMITS.maxSeconds),
+            loop: item.loop === true, volume: number(item.volume, `${name}.volume`, 0, 4, 0.5), duck,
+        };
+    });
+    const ids = new Set();
+    for (const item of [...narration, ...sfx, ...music]) {
+        if (ids.has(item.id))
+            invalid(`audio id ${item.id} is used twice.`);
+        ids.add(item.id);
+        if (item.shot !== undefined && !seen.has(item.shot))
+            invalid(`audio ${item.id} names unknown shot ${item.shot}.`);
+    }
+    const subtitlesRaw = object(document.subtitles ?? {}, "subtitles");
+    only(subtitlesRaw, "subtitles", ["cues", "include_shot_captions"]);
+    if (subtitlesRaw.include_shot_captions !== undefined && typeof subtitlesRaw.include_shot_captions !== "boolean")
+        invalid("subtitles.include_shot_captions must be boolean.");
+    const cues = captions(subtitlesRaw.cues, "subtitles.cues", true);
+    for (const cue of cues)
+        if (cue.shot !== undefined && !seen.has(cue.shot))
+            invalid(`subtitle cue names unknown shot ${cue.shot}.`);
+    return {
+        schema: EPISODE_SCHEMA, id, title, context, output, shots,
+        audio: { narration, music, sfx },
+        subtitles: { cues, include_shot_captions: subtitlesRaw.include_shot_captions !== false },
+    };
+}
+/** The render recipe of one shot: the same contract `render-video` takes. */
+export function shotRecipe(episode, shot) {
+    return parseRecipe({
+        kind: RECIPE_KIND, fps: episode.output.fps, start: shot.start, end: shot.start + shot.duration,
+        profile: episode.output.profile, audio: shot.audio, crf: episode.output.crf, actions: shot.actions,
+    }, shot.subject);
+}
+/**
+ * Where every shot lands on the episode timeline, in frames. A crossfade
+ * into shot k overlaps it with the end of shot k-1 by its length.
+ */
+export function episodeTimeline(episode) {
+    const { fps } = episode.output;
+    let cursor = 0;
+    const shots = episode.shots.map((shot, index) => {
+        const frames = frameCountFor(shot.start, shot.start + shot.duration, fps);
+        const overlap = shot.transition.type === "crossfade" ? Math.round(shot.transition.duration * fps) : 0;
+        const offset = cursor - overlap;
+        cursor = offset + frames;
+        return { id: shot.id, index, frames, offset_frames: offset, overlap_frames: overlap, offset_seconds: offset / fps, duration_seconds: frames / fps };
+    });
+    return { shots, total_frames: cursor, total_seconds: cursor / fps };
+}
+/** An item's episode second: absolute, or relative to its anchoring shot's first frame. */
+export function anchoredSeconds(timeline, at, shot) {
+    if (shot === undefined)
+        return at;
+    const timing = timeline.shots.find((item) => item.id === shot);
+    if (!timing)
+        throw new CliError(`Unknown shot ${shot}.`, "EPISODE_INVALID", 2);
+    return timing.offset_seconds + at;
+}
+/** Every encode setting a shot's MP4 depends on (part of every key). */
+export function encoderSettings(episode, encoderVersion) {
+    return { encoder: encoderVersion, video: "libx264 High preset medium yuv420p CFR", crf: episode.output.crf, audio: "aac 128k 48kHz stereo", key_version: SHOT_KEY_VERSION };
+}
+/** The content-addressed key of one shot: sha256 over its canonical inputs, nothing else. */
+export function shotCacheKey(inputs) {
+    return createHash("sha256").update(canonicalJson({ v: SHOT_KEY_VERSION, ...inputs })).digest("hex");
+}
+/**
+ * A cached shot is reusable only when its record names this key, its MP4
+ * hashes to the recorded sha256 and probes to the expected frame count.
+ * Missing or corrupt means rerender. Modification times are not read.
+ */
+export function checkCachedShot(record, key, expectedFrames, videoSha256, probedFrames) {
+    const value = record;
+    if (!value || value.kind !== SHOT_CACHE_KIND)
+        return { valid: false, reason: "no cache record" };
+    if (value.key !== key)
+        return { valid: false, reason: "cache record names another key" };
+    if (videoSha256 === null)
+        return { valid: false, reason: "cached MP4 missing" };
+    if (value.video_sha256 !== videoSha256)
+        return { valid: false, reason: "cached MP4 does not hash as recorded" };
+    if (probedFrames === null)
+        return { valid: false, reason: "cached MP4 does not probe" };
+    if (probedFrames !== expectedFrames || value.frames !== expectedFrames)
+        return { valid: false, reason: `cached MP4 has ${probedFrames} frames, expected ${expectedFrames}` };
+    return { valid: true };
+}
+/**
+ * Split the shots into segments: shots joined to a neighbour by a crossfade
+ * form one re-encoded segment; every other shot is stream-copied as it was
+ * rendered. Only crossfade boundaries are ever re-encoded.
+ */
+export function videoSegments(episode) {
+    const segments = [];
+    episode.shots.forEach((shot, index) => {
+        const last = segments.at(-1);
+        if (shot.transition.type === "crossfade" && last) {
+            if (last.kind === "crossfade")
+                last.shots.push(index);
+            else {
+                last.shots.pop();
+                if (!last.shots.length)
+                    segments.pop();
+                segments.push({ kind: "crossfade", shots: [index - 1, index] });
+            }
+            return;
+        }
+        if (last?.kind === "copy")
+            last.shots.push(index);
+        else
+            segments.push({ kind: "copy", shots: [index] });
+    });
+    return segments;
+}
+const samples = (seconds) => Math.round(seconds * MIX_SAMPLE_RATE);
+/** FFmpeg arguments that crossfade consecutive shots into one segment (video only). */
+export function crossfadeArguments(episode, timeline, segment, files, output) {
+    const { fps, crf } = episode.output;
+    const chains = [];
+    let label = "0:v";
+    let length = timeline.shots[segment[0]].frames;
+    segment.slice(1).forEach((shotIndex, position) => {
+        const timing = timeline.shots[shotIndex];
+        const overlap = timing.overlap_frames;
+        const next = `x${position + 1}`;
+        if (overlap > 0) {
+            chains.push(`[${label}][${position + 1}:v]xfade=transition=fade:duration=${(overlap / fps).toFixed(6)}:offset=${((length - overlap) / fps).toFixed(6)}[${next}]`);
+        }
+        else {
+            chains.push(`[${label}][${position + 1}:v]concat=n=2:v=1:a=0[${next}]`);
+        }
+        label = next;
+        length += timing.frames - overlap;
+    });
+    return [
+        "-hide_banner", "-loglevel", "error", "-y",
+        ...files.flatMap((file) => ["-i", file]),
+        "-filter_complex", `${chains.join(";")};[${label}]settb=1/${fps * 1000},setpts=N/(${fps}*TB),format=yuv420p[v]`,
+        "-map", "[v]", "-an", "-frames:v", String(length),
+        "-c:v", "libx264", "-preset", "medium", "-crf", String(crf), "-profile:v", "high", "-pix_fmt", "yuv420p",
+        "-r", String(fps), "-fps_mode", "cfr", output,
+    ];
+}
+/** FFmpeg arguments that copy one shot's picture unchanged (video only). */
+export function copyVideoArguments(file, output) {
+    return ["-hide_banner", "-loglevel", "error", "-y", "-i", file, "-map", "0:v:0", "-an", "-c:v", "copy", output];
+}
+/** The concat-demuxer list for the segments, in order. */
+export function concatList(files) {
+    return files.map((file) => `file '${file.replaceAll("'", "'\\''")}'`).join("\n") + "\n";
+}
+export function concatArguments(list, output, frames) {
+    return ["-hide_banner", "-loglevel", "error", "-y", "-f", "concat", "-safe", "0", "-i", list,
+        "-map", "0:v:0", "-an", "-c:v", "copy", "-frames:v", String(frames), output];
+}
+/**
+ * The episode audio mix as FFmpeg arguments: three buses summed without
+ * normalisation into exactly `total_samples` of 48 kHz stereo float PCM.
+ *
+ * - shots: each shot's own sounds at its episode offset (faded across a
+ *   crossfade), plus episode-level sound effects;
+ * - narration: every narration item at its second;
+ * - music: each bed (looped when asked), ducked under the narration bus by
+ *   `sidechaincompress` keyed on the narration.
+ *
+ * Every placement is counted in samples. Returns the arguments and the
+ * label of the narration-only bus written to `narrationOutput` (QC uses it
+ * to find narration onsets without the music under it).
+ */
+export function episodeMixArguments(input) {
+    const inputs = [];
+    const chains = [];
+    let index = 0;
+    const total = input.total_samples;
+    const chain = (item, label) => {
+        if (item.loop)
+            inputs.push("-stream_loop", "-1");
+        inputs.push("-i", item.file);
+        const from = samples(item.trim_seconds ?? 0);
+        const length = item.length_seconds === null || item.length_seconds === undefined ? null : samples(item.length_seconds);
+        const fades = [
+            item.fade_in ? `afade=t=in:ss=0:d=${item.fade_in.toFixed(6)}` : null,
+            item.fade_out && length !== null ? `afade=t=out:st=${(length / MIX_SAMPLE_RATE - item.fade_out).toFixed(6)}:d=${item.fade_out.toFixed(6)}` : null,
+        ].filter(Boolean);
+        chains.push(`[${index}:a]aresample=${MIX_SAMPLE_RATE},aformat=sample_fmts=fltp:channel_layouts=stereo,asetpts=N/SR/TB,` +
+            `atrim=start_sample=${from}${length !== null ? `:end_sample=${from + length}` : ""},asetpts=N/SR/TB,` +
+            `${fades.length ? `${fades.join(",")},` : ""}volume=${item.volume.toFixed(4)},adelay=delays=${samples(item.at_seconds)}S:all=1[${label}]`);
+        index += 1;
+    };
+    const bus = (labels, name) => {
+        if (!labels.length) {
+            chains.push(`anullsrc=channel_layout=stereo:sample_rate=${MIX_SAMPLE_RATE},atrim=end_sample=${total}[${name}]`);
+            return;
+        }
+        chains.push(`${labels.map((label) => `[${label}]`).join("")}amix=inputs=${labels.length}:normalize=0:dropout_transition=0,` +
+            `asetpts=N/SR/TB,apad=whole_len=${total},atrim=end_sample=${total}[${name}]`);
+    };
+    input.shots.forEach((item, position) => chain(item, `s${position}`));
+    input.narration.forEach((item, position) => chain(item, `n${position}`));
+    input.music.forEach((item, position) => chain(item, `m${position}`));
+    bus(input.shots.map((_, position) => `s${position}`), "shots");
+    bus(input.narration.map((_, position) => `n${position}`), "narration");
+    // The narration bus feeds the mix, one ducking key per ducked bed and
+    // (optionally) the QC copy.
+    const ducked = input.narration.length ? input.music.map((item, position) => item.duck ? position : -1).filter((position) => position >= 0) : [];
+    const copies = ["[nmix]", ...ducked.map((position) => `[nk${position}]`), ...(input.narrationOutput ? ["[nqc]"] : [])];
+    chains.push(copies.length === 1 ? "[narration]anull[nmix]" : `[narration]asplit=${copies.length}${copies.join("")}`);
+    for (const position of ducked) {
+        const { threshold, ratio, attack_ms, release_ms } = input.music[position].duck;
+        chains.push(`[m${position}][nk${position}]sidechaincompress=threshold=${threshold}:ratio=${ratio}:attack=${attack_ms}:release=${release_ms}:makeup=1[d${position}]`);
+    }
+    const musicLabels = input.music.map((_, position) => ducked.includes(position) ? `d${position}` : `m${position}`);
+    bus(musicLabels, "music");
+    chains.push(`[shots][nmix][music]amix=inputs=3:normalize=0:dropout_transition=0,asetpts=N/SR/TB,apad=whole_len=${total},atrim=end_sample=${total}[mix]`);
+    return [
+        "-hide_banner", "-loglevel", "error", "-y",
+        ...inputs,
+        "-filter_complex", chains.join(";"),
+        "-map", "[mix]", "-ar", String(MIX_SAMPLE_RATE), "-ac", "2", "-c:a", "pcm_f32le", input.output,
+        ...(input.narrationOutput ? ["-map", "[nqc]", "-ar", String(MIX_SAMPLE_RATE), "-ac", "2", "-c:a", "pcm_s16le", input.narrationOutput] : []),
+    ];
+}
+/** Pass one of two-pass `loudnorm`: measure only. */
+export function loudnessMeasureArguments(file, target) {
+    return ["-hide_banner", "-nostats", "-i", file, "-af",
+        `loudnorm=I=${target.integrated}:TP=${target.true_peak}:LRA=${target.lra}:print_format=json`, "-f", "null", "-"];
+}
+/** The JSON block `loudnorm` prints at the end of stderr. */
+export function parseLoudnorm(stderr) {
+    const start = stderr.lastIndexOf("{");
+    const end = stderr.lastIndexOf("}");
+    if (start < 0 || end < start)
+        throw new CliError("loudnorm printed no measurement.", "EPISODE_LOUDNESS_FAILED", 1, { stderr: stderr.slice(-600) });
+    const value = JSON.parse(stderr.slice(start, end + 1));
+    for (const key of ["input_i", "input_tp", "input_lra", "input_thresh", "target_offset"]) {
+        if (typeof value[key] !== "string")
+            throw new CliError(`loudnorm measurement lacks ${key}.`, "EPISODE_LOUDNESS_FAILED", 1);
+    }
+    return value;
+}
+/**
+ * Pass two: normalise with the measured values (linear when possible), back
+ * to 48 kHz, padded and trimmed to exactly `total_samples`.
+ */
+/**
+ * The loudness range `loudnorm` is given in pass two: the target, or the
+ * mix's own range when that is wider. loudnorm normalises linearly (one
+ * gain, dynamics kept) only when the input range fits the target range;
+ * otherwise it compresses dynamically, which undershoots the integrated
+ * target on short programmes (a 7 s episode measured -17.2 LUFS for a
+ * -16 target). Keeping the mix's own range keeps it linear.
+ */
+export function loudnormRange(target, measured) {
+    const range = Number(measured.input_lra);
+    return Number.isFinite(range) ? Math.min(50, Math.max(target.lra, Math.ceil(range * 10) / 10)) : target.lra;
+}
+export function loudnessApplyArguments(file, target, measured, totalSamples, output) {
+    // A silent mix measures -inf; there is nothing to normalise.
+    const finite = Number.isFinite(Number(measured.input_i)) && Number(measured.input_i) > -70;
+    const filter = finite
+        ? `loudnorm=I=${target.integrated}:TP=${target.true_peak}:LRA=${loudnormRange(target, measured)}:measured_I=${measured.input_i}:measured_TP=${measured.input_tp}` +
+            `:measured_LRA=${measured.input_lra}:measured_thresh=${measured.input_thresh}:offset=${measured.target_offset}:linear=true:print_format=json,`
+        : "";
+    return ["-hide_banner", "-nostats", "-y", "-i", file, "-af",
+        `${filter}aresample=${MIX_SAMPLE_RATE},asetpts=N/SR/TB,apad=whole_len=${totalSamples},atrim=end_sample=${totalSamples}`,
+        "-ar", String(MIX_SAMPLE_RATE), "-ac", "2", "-c:a", "pcm_f32le", output];
+}
+/**
+ * The safety pass after normalisation: when the result is still more than
+ * 0.5 LU from target (loudnorm could not stay linear under the true-peak
+ * ceiling), one gain to the target and a peak limiter 0.5 dB under the
+ * ceiling, at the exact sample count. Null when no correction is needed.
+ */
+export function loudnessCorrectionArguments(file, target, measuredIntegrated, totalSamples, output) {
+    if (measuredIntegrated === null || !Number.isFinite(measuredIntegrated) || measuredIntegrated < -70)
+        return null;
+    const gain = target.integrated - measuredIntegrated;
+    if (Math.abs(gain) <= 0.5)
+        return null;
+    const limit = Math.pow(10, (target.true_peak - 0.5) / 20);
+    return ["-hide_banner", "-loglevel", "error", "-y", "-i", file, "-af",
+        `volume=${gain.toFixed(2)}dB,alimiter=limit=${limit.toFixed(4)}:attack=1:release=50:level=false,` +
+            `asetpts=N/SR/TB,apad=whole_len=${totalSamples},atrim=end_sample=${totalSamples}`,
+        "-ar", String(MIX_SAMPLE_RATE), "-ac", "2", "-c:a", "pcm_f32le", output];
+}
+/** Mux the assembled picture and the episode mix: the picture is copied, the audio encoded once. */
+export function muxArguments(video, audio, episode, totalFrames, output) {
+    return ["-hide_banner", "-loglevel", "error", "-y", "-i", video, "-i", audio,
+        "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy", "-frames:v", String(totalFrames),
+        "-c:a", "aac", "-b:a", episode.output.audio_bitrate, "-ar", String(MIX_SAMPLE_RATE),
+        "-movflags", "+faststart",
+        "-metadata", `title=${episode.title}`,
+        "-metadata", "comment=KheleShikhi episode derivative; not canonical content",
+        output];
+}
+/** Every subtitle cue in episode seconds: episode cues (absolute or shot-anchored) and shot captions. */
+export function episodeCues(episode, timeline = episodeTimeline(episode)) {
+    const cues = episode.subtitles.cues.map((cue) => {
+        const offset = anchoredSeconds(timeline, 0, cue.shot);
+        return { start: offset + cue.start, end: offset + cue.end, text: cue.text, source: cue.shot ? `shot:${cue.shot}` : "episode" };
+    });
+    if (episode.subtitles.include_shot_captions) {
+        episode.shots.forEach((shot, index) => {
+            const offset = timeline.shots[index].offset_seconds;
+            for (const cue of shot.captions)
+                cues.push({ start: offset + cue.start, end: offset + cue.end, text: cue.text, source: `shot:${shot.id}` });
+        });
+    }
+    return cues
+        .map((cue) => ({ ...cue, end: Math.min(cue.end, timeline.total_seconds) }))
+        .filter((cue) => cue.end > cue.start)
+        .sort((a, b) => a.start - b.start || a.end - b.end);
+}
+export function srtTimestamp(seconds) {
+    const total = Math.max(0, Math.round(seconds * 1000));
+    const ms = total % 1000;
+    const s = Math.floor(total / 1000) % 60;
+    const m = Math.floor(total / 60000) % 60;
+    const h = Math.floor(total / 3600000);
+    const pad = (value, width = 2) => String(value).padStart(width, "0");
+    return `${pad(h)}:${pad(m)}:${pad(s)},${pad(ms, 3)}`;
+}
+/** SubRip text: numbered cues, CRLF-free, one blank line between cues. */
+export function toSrt(cues) {
+    return cues.map((cue, index) => `${index + 1}\n${srtTimestamp(cue.start)} --> ${srtTimestamp(cue.end)}\n${cue.text.replace(/\r?\n/g, "\n").trim()}\n`).join("\n");
+}
+/** The episode QC verdict: frames, size, codecs, duration, A/V sync, loudness, narration placement. */
+export function qcChecks(input) {
+    const frame = 1 / input.fps;
+    const { probe } = input;
+    const checks = [
+        { check: "frame_count", pass: probe.frames === input.expected_frames, detail: `${probe.frames} of ${input.expected_frames}` },
+        { check: "size", pass: probe.width === input.width && probe.height === input.height, detail: `${probe.width}x${probe.height}` },
+        { check: "codecs", pass: probe.video_codec === "h264" && probe.audio_codec === "aac", detail: `${probe.video_codec}/${probe.audio_codec}` },
+        { check: "duration", pass: Math.abs((probe.video_duration ?? probe.duration) - input.expected_frames / input.fps) <= frame / 2 + 1e-6,
+            detail: `video ${probe.video_duration ?? probe.duration}s, expected ${(input.expected_frames / input.fps).toFixed(6)}s` },
+        { check: "av_sync_start", pass: Math.abs(probe.video_start ?? 0) <= 1e-3 && Math.abs(probe.audio_start ?? 0) <= frame,
+            detail: `video starts ${probe.video_start}s, audio ${probe.audio_start}s` },
+        { check: "av_sync_length", pass: probe.audio_duration !== null && Math.abs(probe.audio_duration - (probe.video_duration ?? probe.duration)) <= frame,
+            detail: `audio ${probe.audio_duration}s vs video ${probe.video_duration ?? probe.duration}s` },
+        { check: "loudness_integrated", pass: input.loudness.integrated !== null && Math.abs(input.loudness.integrated - input.target.integrated) <= 1,
+            detail: `${input.loudness.integrated} LUFS, target ${input.target.integrated}` },
+        { check: "true_peak", pass: input.loudness.true_peak !== null && input.loudness.true_peak <= input.target.true_peak + 0.5,
+            detail: `${input.loudness.true_peak} dBTP, ceiling ${input.target.true_peak}` },
+    ];
+    for (const onset of input.narration_onsets ?? []) {
+        checks.push({ check: `narration_onset:${onset.id}`, pass: onset.observed !== null && Math.abs(onset.observed - onset.expected) <= 0.025,
+            detail: `expected ${onset.expected.toFixed(3)}s, observed ${onset.observed === null ? "none" : onset.observed.toFixed(3)}s` });
+    }
+    return checks;
+}
+/** Integrated loudness, LRA and true peak from FFmpeg `ebur128=peak=true` stderr. */
+export function parseEbur128(stderr) {
+    const summary = stderr.slice(stderr.lastIndexOf("Summary:"));
+    const read = (pattern) => { const match = pattern.exec(summary); return match ? Number(match[1]) : null; };
+    return { integrated: read(/I:\s*(-?[0-9.]+) LUFS/), lra: read(/LRA:\s*(-?[0-9.]+) LU/), true_peak: read(/Peak:\s*(-?[0-9.]+) dBFS/) };
+}
+/**
+ * Where sound begins, from FFmpeg `silencedetect` stderr: 0 when the file
+ * does not open silent, then every `silence_end`.
+ */
+export function onsets(stderr) {
+    const starts = [...stderr.matchAll(/silence_start:\s*(-?[0-9.]+)/g)].map((match) => Number(match[1]));
+    const ends = [...stderr.matchAll(/silence_end:\s*(-?[0-9.]+)/g)].map((match) => Number(match[1]));
+    return [...(starts.length && starts[0] <= 0.001 ? [] : [0]), ...ends].sort((a, b) => a - b);
+}
+/** The onset nearest `expected`, or null when there is none within a second. */
+export function nearestOnset(values, expected) {
+    let best = null;
+    for (const value of values)
+        if (best === null || Math.abs(value - expected) < Math.abs(best - expected))
+            best = value;
+    return best !== null && Math.abs(best - expected) <= 1 ? best : null;
+}
+/** The identity of a whole assembly: shot keys, timeline, audio and subtitle inputs, loudness and output settings. */
+export function assemblyKey(episode, shotKeys, audioSha256) {
+    return digestOf({ shots: shotKeys, transitions: episode.shots.map((shot) => shot.transition), sound_volume: episode.shots.map((shot) => shot.sound_volume),
+        audio: { narration: episode.audio.narration, music: episode.audio.music, sfx: episode.audio.sfx }, audio_sha256: audioSha256,
+        subtitles: episodeCues(episode), output: episode.output, key_version: SHOT_KEY_VERSION });
+}
+//# sourceMappingURL=episode.js.map