@kheleshikhi/studio-agent 0.8.0 → 0.9.1

package/dist/episode.d.ts

@@ -0,0 +1,332 @@
+import { type RenderAction, type RenderProfile, type RenderRecipe, type RenderSubject } from "./video.js";
+export declare const EPISODE_SCHEMA = "kheleshikhi.episode.v1";
+export declare const EPISODE_MANIFEST_KIND = "kheleshikhi.episode-render.v1";
+export declare const SHOT_CACHE_KIND = "kheleshikhi.episode-shot-cache.v1";
+/** Bump when the shot render or its encode changes meaning: every key moves. */
+export declare const SHOT_KEY_VERSION = 1;
+export declare const EPISODE_LIMITS: {
+    maxShots: number;
+    maxSeconds: number;
+    maxAudioItems: number;
+    maxCues: number;
+    maxText: number;
+};
+export type Caption = {
+    start: number;
+    end: number;
+    text: string;
+};
+export type EpisodeShot = {
+    id: string;
+    title?: string;
+    subject: RenderSubject;
+    /** Scene shots: a Studio asset; `local` renders the workspace checkout, `approved` the asset's approved source. */
+    scene?: {
+        asset: string;
+        source: "local" | "approved";
+        revision?: string;
+    };
+    /** Experience shots: a stable id; `local` renders the workspace source, `saved` the saved head. */
+    experience?: {
+        id: string;
+        source: "local" | "saved";
+    };
+    /** The subject's own clock second the shot starts at. */
+    start: number;
+    /** Seconds of video: a whole number of frames at the episode fps. */
+    duration: number;
+    /** Learner actions at the subject's own clock seconds (camera cues, events, pause/play). */
+    actions: RenderAction[];
+    /** `scene` keeps the subject's own sounds (shot SFX) in the episode mix. */
+    audio: "scene" | "silent";
+    /** Gain on the shot's own sounds in the episode mix. */
+    sound_volume: number;
+    /** How this shot begins: a cut, or a crossfade from the previous shot. */
+    transition: {
+        type: "cut";
+    } | {
+        type: "crossfade";
+        duration: number;
+    };
+    /** Captions, in seconds from the shot's own first frame. */
+    captions: Caption[];
+};
+export type TimedAudio = {
+    id: string;
+    file: string;
+    at: number;
+    shot?: string;
+    volume: number;
+};
+export type MusicBed = {
+    id: string;
+    file: string;
+    at: number;
+    shot?: string;
+    end: number | null;
+    loop: boolean;
+    volume: number;
+    duck: false | {
+        threshold: number;
+        ratio: number;
+        attack_ms: number;
+        release_ms: number;
+    };
+};
+export type Episode = {
+    schema: typeof EPISODE_SCHEMA;
+    id: string;
+    title: string;
+    /** Library and project context: labels only, never cache inputs. */
+    context: {
+        project: string | null;
+        library: string | null;
+    };
+    output: {
+        profile: RenderProfile;
+        width: number;
+        height: number;
+        fps: number;
+        crf: number;
+        audio_bitrate: string;
+        loudness: {
+            integrated: number;
+            true_peak: number;
+            lra: number;
+        };
+    };
+    shots: EpisodeShot[];
+    audio: {
+        narration: TimedAudio[];
+        music: MusicBed[];
+        sfx: TimedAudio[];
+    };
+    subtitles: {
+        cues: Array<Caption & {
+            shot?: string;
+        }>;
+        include_shot_captions: boolean;
+    };
+};
+/** Parse and bound an episode manifest. Unknown fields are refused, never ignored. */
+export declare function parseEpisode(value: unknown): Episode;
+/** The render recipe of one shot: the same contract `render-video` takes. */
+export declare function shotRecipe(episode: Episode, shot: EpisodeShot): RenderRecipe;
+export type ShotTiming = {
+    id: string;
+    index: number;
+    frames: number;
+    offset_frames: number;
+    overlap_frames: number;
+    offset_seconds: number;
+    duration_seconds: number;
+};
+/**
+ * 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 declare function episodeTimeline(episode: Episode): {
+    shots: ShotTiming[];
+    total_frames: number;
+    total_seconds: number;
+};
+/** An item's episode second: absolute, or relative to its anchoring shot's first frame. */
+export declare function anchoredSeconds(timeline: ReturnType<typeof episodeTimeline>, at: number, shot?: string): number;
+/** Every encode setting a shot's MP4 depends on (part of every key). */
+export declare function encoderSettings(episode: Episode, encoderVersion: string): Record<string, unknown>;
+export type ShotKeyInputs = {
+    subject: RenderSubject;
+    recipe: RenderRecipe;
+    /** Scene: { main: source hash }; Experience: Experience source hash plus each Scene's identity. */
+    sources: Record<string, string | null>;
+    /** Dependency-record digests by Scene. Null when unknown (then the Scene's revision identity carries it). */
+    dependency_digests: Record<string, string | null>;
+    runtime_fingerprint: string | null;
+    /** sha256 of every sound the subject names, by id. */
+    audio_sha256: Record<string, string>;
+    profile: {
+        profile: RenderProfile;
+        width: number;
+        height: number;
+        fps: number;
+    };
+    encoder: Record<string, unknown>;
+};
+/** The content-addressed key of one shot: sha256 over its canonical inputs, nothing else. */
+export declare function shotCacheKey(inputs: ShotKeyInputs): string;
+export type ShotCacheRecord = {
+    kind: typeof SHOT_CACHE_KIND;
+    key: string;
+    shot: string;
+    inputs: ShotKeyInputs;
+    video_sha256: string;
+    frames: number;
+    bytes: number;
+    created_at: string;
+    canonical: false;
+};
+export type CachedShotCheck = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * 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 declare function checkCachedShot(record: unknown, key: string, expectedFrames: number, videoSha256: string | null, probedFrames: number | null): CachedShotCheck;
+/** One stretch of the episode video: a copied shot, or a re-encoded crossfade run. */
+export type VideoSegment = {
+    kind: "copy";
+    shots: number[];
+} | {
+    kind: "crossfade";
+    shots: number[];
+};
+/**
+ * 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 declare function videoSegments(episode: Episode): VideoSegment[];
+/** FFmpeg arguments that crossfade consecutive shots into one segment (video only). */
+export declare function crossfadeArguments(episode: Episode, timeline: ReturnType<typeof episodeTimeline>, segment: number[], files: string[], output: string): string[];
+/** FFmpeg arguments that copy one shot's picture unchanged (video only). */
+export declare function copyVideoArguments(file: string, output: string): string[];
+/** The concat-demuxer list for the segments, in order. */
+export declare function concatList(files: string[]): string;
+export declare function concatArguments(list: string, output: string, frames: number): string[];
+export type MixInput = {
+    file: string;
+    at_seconds: number;
+    volume: number;
+    loop?: boolean;
+    length_seconds?: number | null;
+    fade_in?: number;
+    fade_out?: number;
+    trim_seconds?: number;
+};
+/**
+ * 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 declare function episodeMixArguments(input: {
+    shots: MixInput[];
+    narration: MixInput[];
+    music: Array<MixInput & {
+        duck: MusicBed["duck"];
+    }>;
+    total_samples: number;
+    output: string;
+    narrationOutput?: string;
+}): string[];
+export type LoudnessTarget = Episode["output"]["loudness"];
+export type LoudnessMeasurement = {
+    input_i: string;
+    input_tp: string;
+    input_lra: string;
+    input_thresh: string;
+    target_offset: string;
+};
+/** Pass one of two-pass `loudnorm`: measure only. */
+export declare function loudnessMeasureArguments(file: string, target: LoudnessTarget): string[];
+/** The JSON block `loudnorm` prints at the end of stderr. */
+export declare function parseLoudnorm(stderr: string): LoudnessMeasurement;
+/**
+ * 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 declare function loudnormRange(target: LoudnessTarget, measured: LoudnessMeasurement): number;
+export declare function loudnessApplyArguments(file: string, target: LoudnessTarget, measured: LoudnessMeasurement, totalSamples: number, output: string): string[];
+/**
+ * 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 declare function loudnessCorrectionArguments(file: string, target: LoudnessTarget, measuredIntegrated: number | null, totalSamples: number, output: string): string[] | null;
+/** Mux the assembled picture and the episode mix: the picture is copied, the audio encoded once. */
+export declare function muxArguments(video: string, audio: string, episode: Episode, totalFrames: number, output: string): string[];
+export type EpisodeCue = Caption & {
+    source: string;
+};
+/** Every subtitle cue in episode seconds: episode cues (absolute or shot-anchored) and shot captions. */
+export declare function episodeCues(episode: Episode, timeline?: {
+    shots: ShotTiming[];
+    total_frames: number;
+    total_seconds: number;
+}): EpisodeCue[];
+export declare function srtTimestamp(seconds: number): string;
+/** SubRip text: numbered cues, CRLF-free, one blank line between cues. */
+export declare function toSrt(cues: Caption[]): string;
+export type QcInput = {
+    expected_frames: number;
+    fps: number;
+    width: number;
+    height: number;
+    probe: {
+        frames: number;
+        width: number;
+        height: number;
+        video_codec: string;
+        audio_codec: string | null;
+        duration: number;
+        video_duration: number | null;
+        audio_duration: number | null;
+        video_start: number | null;
+        audio_start: number | null;
+    };
+    loudness: {
+        integrated: number | null;
+        true_peak: number | null;
+        lra: number | null;
+    };
+    target: LoudnessTarget;
+    narration_onsets?: Array<{
+        id: string;
+        expected: number;
+        observed: number | null;
+    }>;
+};
+export type QcCheck = {
+    check: string;
+    pass: boolean;
+    detail: string;
+};
+/** The episode QC verdict: frames, size, codecs, duration, A/V sync, loudness, narration placement. */
+export declare function qcChecks(input: QcInput): QcCheck[];
+/** Integrated loudness, LRA and true peak from FFmpeg `ebur128=peak=true` stderr. */
+export declare function parseEbur128(stderr: string): {
+    integrated: number | null;
+    lra: number | null;
+    true_peak: number | null;
+};
+/**
+ * Where sound begins, from FFmpeg `silencedetect` stderr: 0 when the file
+ * does not open silent, then every `silence_end`.
+ */
+export declare function onsets(stderr: string): number[];
+/** The onset nearest `expected`, or null when there is none within a second. */
+export declare function nearestOnset(values: number[], expected: number): number | null;
+/** The identity of a whole assembly: shot keys, timeline, audio and subtitle inputs, loudness and output settings. */
+export declare function assemblyKey(episode: Episode, shotKeys: string[], audioSha256: Record<string, string>): string;