@anvpx/motion-build 0.0.0-stage → 0.1.0

package/dist/audio/mix.d.ts

@@ -0,0 +1,231 @@
+import { type TimingManifest } from "@anvpx/motion-schema";
+import { type MusicIdentity, type SeamlessLoop } from "./music.ts";
+/** Sibling directory of a voice manifest holding `<scene-id>.wav` files. */
+export declare const AUDIO_DIR_NAME = "audio";
+/** One narration clip: absolute start plus its wav on disk. */
+export interface MixClip {
+    readonly id: string;
+    readonly start: number;
+    readonly duration: number;
+    readonly wav: string;
+}
+/** Opt-in build input: which manifest to mix and where its wavs live. */
+export interface AudioManifestRef {
+    readonly manifest: TimingManifest;
+    readonly audioDir: string;
+    /** Opt-in user CC0 bed; absent means narration-only (never a bundled fallback). */
+    readonly music?: MusicBed;
+}
+export type AudioManifestResult = {
+    ok: true;
+    manifest: TimingManifest;
+} | {
+    ok: false;
+    problems: string[];
+};
+/** Wav path for one scene id inside the manifest's audio directory. */
+export declare const wavPathFor: (audioDir: string, id: string) => string;
+/** Manifest scenes in order, each resolved to its wav path. */
+export declare const clipsFromManifest: (manifest: TimingManifest, audioDir: string) => MixClip[];
+/** Clips whose wav is absent; non-empty means refuse to mix (fail closed). */
+export declare const missingClips: (clips: readonly MixClip[], exists: (path: string) => boolean) => MixClip[];
+/** Whole seconds to integer ffmpeg milliseconds; refuses nonsense. */
+export declare const toDelayMs: (seconds: number) => number;
+/** True when every scene starts where the previous one ends (voice norm). */
+export declare const isContiguous: (scenes: readonly {
+    start: number;
+    duration: number;
+}[]) => boolean;
+/**
+ * Deterministic `-filter_complex` graph mixing the clips onto `[aout]`.
+ * `adelay` takes `ms:all=1` so mono and stereo wavs delay every channel alike;
+ * `amix` runs `normalize=0` because narrated scenes never overlap, so levels
+ * stay exactly as synthesized instead of being divided by the input count.
+ */
+export declare const buildFilterGraph: (clips: readonly MixClip[]) => string;
+/**
+ * Deterministic ffmpeg argv: silent video plus one `-i` per wav, video passed
+ * through (`-c:v copy`), narration mixed to aac, `-shortest` trimming any
+ * sub-frame tail so the output never outruns the picture.
+ */
+export declare const buildMixArgs: (videoIn: string, clips: readonly MixClip[], out: string) => string[];
+/** Validates an unknown document as a mixable TimingManifest (fail closed). */
+export declare const parseAudioManifest: (value: unknown) => AudioManifestResult;
+/** Opt-in user CC0 music bed: explicit wav plus ducked level (narration stays ahead). */
+export interface MusicBed {
+    readonly wav: string;
+    readonly volume?: number;
+}
+export type { MusicIdentity, SeamlessLoop } from "./music.ts";
+/**
+ * Ducked bed level, re-exported from the pinned music single source
+ * (`./music.ts`, itself from the schema); narration stays intelligible
+ * over the bed at the qc-lufs pinned depth of -6.0206 dB.
+ */
+export { DEFAULT_MUSIC_VOLUME } from "./music.ts";
+/** Resolve the bed level through the schema guard; anything else fails closed. */
+export declare const resolveMusicVolume: (music: MusicBed) => number;
+/**
+ * Bed wavs that are absent; non-empty means refuse to mix (fail closed).
+ * An absent bed (`undefined`) means narration-only — never a silent fallback.
+ */
+export declare const missingMusic: (music: MusicBed | undefined, exists: (path: string) => boolean) => string[];
+/**
+ * Deterministic `-filter_complex` graph ducking a user CC0 bed under narration.
+ * Narration mixes onto `[narr]` (same rules as {@link buildFilterGraph}), splits
+ * via `asplit` into `[nkey]` (sidechain key) and `[nmix]` (audible mix input);
+ * the bed loops to the narration length, ducks under `[nkey]` via
+ * `sidechaincompress`, then joins `[nmix]` with `amix … normalize=0` onto
+ * `[aout]`. Each label is defined once and consumed once as input, so ffmpeg
+ * never sees a doubly-consumed `[narr]`.
+ *
+ * The bed is re-validated through the schema single source first: a raw
+ * `{ wav }` that never passed `parseMusicBed`/`validateMusicBed` (traversal,
+ * non-wav, bad level) throws here instead of reaching ffmpeg.
+ */
+export declare const buildMusicFilterGraph: (clips: readonly MixClip[], music: MusicBed) => string;
+/** Role of a frozen wav; the role is part of the injective frozen name. */
+export type FrozenRole = "narration" | "music";
+/**
+ * AU-01 frozen approved mix layout (single authority for preview + render).
+ * After the approval entry-gate, the CLI copies every narration wav plus the
+ * bed wav into one frozen directory and mixes from those copies, so a
+ * mutation of the mutable sources mid-run (even restored before the post-check,
+ * ABA) cannot change the bytes ffmpeg consumes.
+ *
+ * The frozen name is `<role>-<1-based ordinal>-<source basename>`
+ * (`narration-2-intro.wav`, `music-1-intro.wav`). Role + ordinal make the map
+ * injective, so two approved sources that share a basename - a narration wav
+ * and the bed, two narration directories, Windows case aliases - never share
+ * one destination (ADR-0008 D1). The name holds no machine path, timestamp or
+ * absolute path, and the ordinal is the approved `mix.clips` order, which is
+ * itself hashed, so a current approval always maps to the same names.
+ *
+ * `frozenWavFor` maps one source wav to its frozen copy;
+ * `frozenClips`/`frozenMusic` rewrite clip/bed inputs to the frozen copies
+ * while preserving id/start/duration/volume.
+ */
+export declare const frozenWavFor: (frozenDir: string, role: FrozenRole, ordinal: number, wav: string) => string;
+export declare const frozenClips: (clips: readonly MixClip[], frozenDir: string) => MixClip[];
+export declare const frozenMusic: (music: MusicBed, frozenDir: string) => MusicBed;
+/**
+ * T-AU-01a current-only identity bed: maps a pinned `MusicIdentity`
+ * (`relativePath`, `sha256`, `volume`, `licenceEvidenceSha256`) to the
+ * absolute wav the mix graph consumes. The identity itself stays
+ * project-relative with forward slashes (no machine paths, no timestamps);
+ * only the resolved `wav` is absolute and only the frozen copy is consumed
+ * downstream. Rejects absolute/escaping/non-wav refs, malformed hashes, and
+ * out-of-range volumes (fail closed, never a silent fallback). Defense in
+ * depth: `wav` must live inside `frozenDir` (prefix + relative assert), so an
+ * absolute path outside the frozen layout never reaches ffmpeg.
+ */
+export declare const musicBedFromIdentity: (identity: MusicIdentity, frozenDir: string, wav: string) => MusicBed;
+/**
+ * Verifies frozen bytes against the pinned identity. Non-empty means refuse
+ * to mix (fail closed): a mutated bed sha — including an ABA restore of the
+ * mutable source after the freeze — still fails unless the frozen copy
+ * consumed by ffmpeg matches the identity.
+ */
+export declare const verifyFrozenMusic: (identity: MusicIdentity, frozenBedSha256: string | undefined, frozenLicenceSha256: string | null | undefined) => string[];
+/**
+ * Seamless-loop trim for a bed of `bedDuration` seconds over narration
+ * `clips` (phase math in `./music.ts`): repeats via `aloop` then trims to
+ * the narration length, reporting the loop-boundary phase error.
+ */
+export declare const musicLoopFor: (bedDuration: number, clips: readonly MixClip[]) => SeamlessLoop;
+/**
+ * Deterministic ffmpeg argv with a ducked bed: silent video plus one `-i`
+ * per narration wav plus the bed wav last, video passed through
+ * (`-c:v copy`), bed ducked under narration and mixed to aac, `-shortest`.
+ */
+export declare const buildMusicMixArgs: (videoIn: string, clips: readonly MixClip[], music: MusicBed, out: string) => string[];
+/**
+ * Delivery loudness (fixed, no CLI flag). Kokoro narration lands near -26 LUFS,
+ * so the mix would otherwise fail every verified platform policy; the mixed
+ * bed+voice file is normalized once here so preview, draft and render all
+ * deliver at the same level.
+ *
+ * `TARGET_TRUE_PEAK_DB` is loudnorm's *aim*, 0.5 dB under the platform ceiling
+ * so the aac encode keeps its headroom; the delivery ceiling itself stays the
+ * verified policy's -1 dBTP (`MIX_TRUE_PEAK_DBTP`), which is what gates a pass.
+ */
+export declare const TARGET_LUFS = -14;
+export declare const TARGET_TRUE_PEAK_DB = -1.5;
+export declare const TARGET_LRA = 11;
+/** Within this drift the mix already sits at delivery level (idempotence guard). */
+export declare const AT_TARGET_TOLERANCE_LU = 0.5;
+/** Normalizing passes per mix: the first, plus at most one corrective pass. */
+export declare const MAX_NORMALIZE_PASSES = 2;
+/** Pass 1 filter: prints the measurement json on stderr and passes audio through. */
+export declare const LOUDNORM_MEASURE_FILTER = "loudnorm=print_format=json";
+/** One loudnorm measurement, as pass 2 hands it back to pass 1's result. */
+export interface LoudnessMeasurement {
+    readonly integratedLufs: number;
+    readonly truePeakDb: number;
+    readonly lra: number;
+    readonly threshold: number;
+    readonly offset: number;
+}
+/**
+ * Reads the last `{…}` block loudnorm prints. Unreadable or silent input
+ * (integrated `-inf`) yields undefined: an unmeasurable mix is never
+ * "already at target".
+ */
+export declare const parseLoudnessMeasurement: (output: string) => LoudnessMeasurement | undefined;
+/**
+ * True when the mix still needs a normalizing pass: the level is off by more
+ * than the 0.5 LU guard, or the peaks sit above the delivery ceiling (-1 dBTP,
+ * the verified platform policy). loudnorm *aims* at {@link TARGET_TRUE_PEAK_DB}
+ * to leave aac headroom, but its dynamic fallback can settle slightly above the
+ * aim while holding the level; that is delivered, not re-normalized, which is
+ * what keeps a second run a no-op.
+ */
+export declare const needsNormalization: (measurement: LoudnessMeasurement) => boolean;
+/** Pass 2 filter: one linear gain from the pass-1 measurements plus the target. */
+export declare const buildLoudnessNormalizeFilter: (measurement: LoudnessMeasurement) => string;
+/** Pass 1 argv: measure the mixed file; `-vn` keeps the video stream undecoded. */
+export declare const buildLoudnessMeasureArgs: (input: string) => string[];
+/**
+ * Pass 2 argv: rewrite `input` at the target into `out`, copying the video
+ * stream (`-c:v copy`, never decoded). loudnorm's own `linear` fallback keeps
+ * peaks under the ceiling when a single gain would overshoot.
+ */
+export declare const buildLoudnessNormalizeArgs: (input: string, measurement: LoudnessMeasurement, out: string) => string[];
+/** Exit code plus captured output of one ffmpeg run (structured like the CLI's CommandResult). */
+export interface MixRunResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type MixRunner = (argv: readonly string[]) => Promise<MixRunResult>;
+/** One narrated mix at delivery level: same mix argv, same output path as before. */
+export interface MixDeliveryPlan {
+    readonly videoIn: string;
+    readonly clips: readonly MixClip[];
+    readonly music?: MusicBed;
+    /** The path the mix wrote before normalization; normalization rewrites it in place. */
+    readonly out: string;
+    /** Moves the normalized temp file over `out` (fs in the CLI, a fake in tests). */
+    readonly swap: (from: string, to: string) => Promise<void>;
+}
+export interface MixDelivery {
+    readonly ok: boolean;
+    readonly out: string;
+    readonly normalized: boolean;
+    readonly measurement: LoudnessMeasurement | null;
+    readonly problems: readonly string[];
+}
+/**
+ * Mixes to `plan.out`, then normalizes that same file to delivery level.
+ *
+ * Silent films stay silent (no clips → no ffmpeg at all) and an already-levelled
+ * mix skips pass 2, so normalizing twice never moves the level. One linear gain
+ * cannot always reach the target under the peak ceiling (loudnorm then runs its
+ * dynamic fallback and can land ~0.8 LU short), so the level is re-measured
+ * after each pass and one corrective pass may follow: the delivered file sits
+ * inside the 0.5 LU guard whenever the material allows it, which is what keeps
+ * a second normalizing run a no-op. Unmeasurable audio is left exactly as the
+ * mix produced it and reported in `problems`; a failed mix or a failed loudnorm
+ * pass fails delivery.
+ */
+export declare const mixAtDeliveryLevel: (run: MixRunner, plan: MixDeliveryPlan) => Promise<MixDelivery>;