@anvpx/motion-build 0.0.0-stage → 0.1.0

package/dist/audio/mix.js

@@ -0,0 +1,491 @@
+/**
+ * Narration mixdown: a voice TimingManifest's absolute scene starts become an
+ * ffmpeg filter graph that lays per-scene wavs under a silent render.
+ *
+ * Each scene wav lives at `<audioDir>/<id>.wav` (the `mk voice` layout: the
+ * manifest's sibling `audio/` directory). Gapped scenes mix with one `adelay`
+ * per clip into `amix`; exactly contiguous scenes (the voice-manifest norm)
+ * concatenate without delay. One clip needs no mixer at all.
+ *
+ * All builders are pure and deterministic: the same clips always produce the
+ * same bytes modulo the encoder. Nothing here spawns ffmpeg; `mixAtDeliveryLevel`
+ * takes an injected runner (the CLI passes `session.probe("ffmpeg", …)`) and
+ * then normalizes the mixed file to delivery level. Missing wavs fail closed
+ * via `missingClips` — never a silent fallback when mixing was requested.
+ */
+import { basename, isAbsolute, join, relative, sep } from "node:path";
+import { parseMusicBed, TimingManifestSchema } from "@anvpx/motion-schema";
+import { MIX_TRUE_PEAK_DBTP, SIDECHAIN_ATTACK_MS, SIDECHAIN_RATIO, SIDECHAIN_RELEASE_MS, SIDECHAIN_THRESHOLD, seamlessLoopFor, verifyMusicIdentity, } from "./music.js";
+/** Sibling directory of a voice manifest holding `<scene-id>.wav` files. */
+export const AUDIO_DIR_NAME = "audio";
+/** Wav path for one scene id inside the manifest's audio directory. */
+export const wavPathFor = (audioDir, id) => join(audioDir, `${id}.wav`);
+/** Manifest scenes in order, each resolved to its wav path. */
+export const clipsFromManifest = (manifest, audioDir) => manifest.scenes.map((scene) => ({
+    id: scene.id,
+    start: scene.start,
+    duration: scene.duration,
+    wav: wavPathFor(audioDir, scene.id),
+}));
+/** Clips whose wav is absent; non-empty means refuse to mix (fail closed). */
+export const missingClips = (clips, exists) => clips.filter((clip) => !exists(clip.wav));
+/** Whole seconds to integer ffmpeg milliseconds; refuses nonsense. */
+export const toDelayMs = (seconds) => {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new Error(`invalid narration start ${seconds}: must be finite and >= 0`);
+    }
+    return Math.round(seconds * 1000);
+};
+/** Millisecond tolerance: float starts that survived rounding still join. */
+const CONTIGUITY_EPSILON_MS = 1;
+/** True when every scene starts where the previous one ends (voice norm). */
+export const isContiguous = (scenes) => scenes.every((scene, index) => {
+    if (index === 0)
+        return true;
+    const prev = scenes[index - 1];
+    if (prev === undefined)
+        return false;
+    return (Math.abs(toDelayMs(scene.start) - toDelayMs(prev.start + prev.duration)) <=
+        CONTIGUITY_EPSILON_MS);
+});
+const delayed = (input, ms, label) => `[${input}:a]adelay=${ms}:all=1[${label}]`;
+/**
+ * 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 const buildFilterGraph = (clips) => narrationGraph(clips, "aout");
+const narrationGraph = (clips, outLabel) => {
+    if (clips.length === 0)
+        throw new Error("mixdown needs at least one narration clip");
+    if (clips.length === 1) {
+        const only = clips[0];
+        if (only === undefined)
+            throw new Error("mixdown needs at least one narration clip");
+        return `${delayed(1, toDelayMs(only.start), outLabel)}`;
+    }
+    if (isContiguous(clips)) {
+        const inputs = clips.map((_, index) => `[${index + 1}:a]`).join("");
+        return `${inputs}concat=n=${clips.length}:v=0:a=1[${outLabel}]`;
+    }
+    const labels = clips.map((_, index) => `a${index + 1}`);
+    const delays = clips
+        .map((clip, index) => delayed(index + 1, toDelayMs(clip.start), labels[index]))
+        .join(";");
+    const mixed = labels.map((label) => `[${label}]`).join("");
+    return `${delays};${mixed}amix=inputs=${clips.length}:normalize=0[${outLabel}]`;
+};
+/**
+ * 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 const buildMixArgs = (videoIn, clips, out) => [
+    "-y",
+    "-i",
+    videoIn,
+    ...clips.flatMap((clip) => ["-i", clip.wav]),
+    "-filter_complex",
+    buildFilterGraph(clips),
+    "-map",
+    "0:v:0",
+    "-map",
+    "[aout]",
+    "-c:v",
+    "copy",
+    "-c:a",
+    "aac",
+    "-movflags",
+    "+faststart",
+    "-shortest",
+    out,
+];
+/** Validates an unknown document as a mixable TimingManifest (fail closed). */
+export const parseAudioManifest = (value) => {
+    const parsed = TimingManifestSchema.safeParse(value);
+    if (parsed.success)
+        return { ok: true, manifest: parsed.data };
+    return {
+        ok: false,
+        problems: parsed.error.issues.map((issue) => `${issue.path.join("/")}: ${issue.message}`),
+    };
+};
+/**
+ * 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.js";
+/** Resolve the bed level through the schema guard; anything else fails closed. */
+export const resolveMusicVolume = (music) => {
+    const parsed = parseMusicBed(music);
+    if (!parsed.ok) {
+        throw new Error(`invalid music bed: ${parsed.hint}`);
+    }
+    return parsed.bed.volume;
+};
+/**
+ * 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 const missingMusic = (music, exists) => {
+    if (music === undefined)
+        return [];
+    return exists(music.wav) ? [] : [music.wav];
+};
+/** Reject a bed that never passed the schema guard (fail closed, never silently mix). */
+const requireValidBed = (music) => {
+    const parsed = parseMusicBed(music);
+    if (!parsed.ok) {
+        throw new Error(`invalid music bed: ${parsed.hint}`);
+    }
+};
+/** Timeline length covered by narration; the bed loops (`aloop`) then trims to it. */
+const narrationTotal = (clips) => clips.reduce((max, clip) => Math.max(max, clip.start + clip.duration), 0);
+/**
+ * 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 const buildMusicFilterGraph = (clips, music) => {
+    if (clips.length === 0)
+        throw new Error("mixdown needs at least one narration clip");
+    requireValidBed(music);
+    const volume = resolveMusicVolume(music);
+    const musicIndex = clips.length + 1;
+    const narr = narrationGraph(clips, "narr");
+    const total = toDelayMs(narrationTotal(clips)) / 1000;
+    const sidechain = `sidechaincompress=threshold=${SIDECHAIN_THRESHOLD}:ratio=${SIDECHAIN_RATIO}` +
+        `:attack=${SIDECHAIN_ATTACK_MS}:release=${SIDECHAIN_RELEASE_MS}`;
+    return (`[${musicIndex}:a]volume=${volume},aloop=loop=-1:size=2e9,atrim=duration=${total}[mbed];` +
+        `${narr};[narr]asplit[nkey][nmix];` +
+        `[mbed][nkey]${sidechain}[ducked];` +
+        `[nmix][ducked]amix=inputs=2:normalize=0[aout]`);
+};
+/**
+ * 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 const frozenWavFor = (frozenDir, role, ordinal, wav) => {
+    if (!Number.isInteger(ordinal) || ordinal < 1) {
+        throw new Error(`invalid frozen ordinal ${ordinal}: must be an integer >= 1`);
+    }
+    return join(frozenDir, `${role}-${ordinal}-${basename(wav)}`);
+};
+export const frozenClips = (clips, frozenDir) => clips.map((clip, index) => ({
+    ...clip,
+    wav: frozenWavFor(frozenDir, "narration", index + 1, clip.wav),
+}));
+export const frozenMusic = (music, frozenDir) => ({
+    ...music,
+    wav: frozenWavFor(frozenDir, "music", 1, music.wav),
+});
+/**
+ * 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 const musicBedFromIdentity = (identity, frozenDir, wav) => {
+    const problems = verifyMusicIdentity(identity, identity.sha256, identity.licenceEvidenceSha256);
+    const shape = problems.filter((problem) => !problem.includes("unreadable"));
+    // Self-consistency uses the identity digests, so only shape problems apply
+    // here; content drift vs frozen bytes is checked by `verifyFrozenMusic`.
+    const mapping = shape.filter((problem) => problem.includes("project-local") || problem.includes("64 hex") || problem.includes("volume"));
+    if (mapping.length > 0) {
+        throw new Error(`invalid music identity: ${mapping.join("; ")}`);
+    }
+    if (typeof wav !== "string" || !wav.endsWith(".wav") || wav.includes("..")) {
+        throw new Error("invalid music identity: resolved wav must be a local .wav without traversal");
+    }
+    if (typeof frozenDir !== "string" || frozenDir.length === 0 || !isAbsolute(frozenDir)) {
+        throw new Error("invalid music identity: frozenDir must be an absolute directory");
+    }
+    if (!isAbsolute(wav)) {
+        throw new Error("invalid music identity: resolved wav must be absolute inside frozenDir");
+    }
+    // Defense in depth: relative escape check plus explicit frozenDir prefix assert.
+    const rel = relative(frozenDir, wav);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error("invalid music identity: resolved wav must be inside frozenDir");
+    }
+    const prefix = frozenDir.endsWith(sep) ? frozenDir : frozenDir + sep;
+    if (!wav.startsWith(prefix)) {
+        throw new Error("invalid music identity: resolved wav must be inside frozenDir");
+    }
+    return { wav, volume: identity.volume };
+};
+/**
+ * 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 const verifyFrozenMusic = (identity, frozenBedSha256, frozenLicenceSha256) => verifyMusicIdentity(identity, frozenBedSha256, frozenLicenceSha256);
+/**
+ * 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 const musicLoopFor = (bedDuration, clips) => {
+    if (clips.length === 0)
+        throw new Error("mixdown needs at least one narration clip");
+    return seamlessLoopFor(bedDuration, narrationTotal(clips));
+};
+/**
+ * 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 const buildMusicMixArgs = (videoIn, clips, music, out) => [
+    "-y",
+    "-i",
+    videoIn,
+    ...clips.flatMap((clip) => ["-i", clip.wav]),
+    "-i",
+    music.wav,
+    "-filter_complex",
+    buildMusicFilterGraph(clips, music),
+    "-map",
+    "0:v:0",
+    "-map",
+    "[aout]",
+    "-c:v",
+    "copy",
+    "-c:a",
+    "aac",
+    "-movflags",
+    "+faststart",
+    "-shortest",
+    out,
+];
+/**
+ * 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 const TARGET_LUFS = -14;
+export const TARGET_TRUE_PEAK_DB = -1.5;
+export const TARGET_LRA = 11;
+/** Within this drift the mix already sits at delivery level (idempotence guard). */
+export const AT_TARGET_TOLERANCE_LU = 0.5;
+/** Normalizing passes per mix: the first, plus at most one corrective pass. */
+export const MAX_NORMALIZE_PASSES = 2;
+/** Pass 1 filter: prints the measurement json on stderr and passes audio through. */
+export const LOUDNORM_MEASURE_FILTER = "loudnorm=print_format=json";
+/** Parses one numeric loudnorm field; `-inf`/`-nan`/absent are not numbers. */
+const numeric = (value) => {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== "string")
+        return undefined;
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+};
+/**
+ * Reads the last `{…}` block loudnorm prints. Unreadable or silent input
+ * (integrated `-inf`) yields undefined: an unmeasurable mix is never
+ * "already at target".
+ */
+export const parseLoudnessMeasurement = (output) => {
+    const blocks = output.match(/\{[^{}]*\}/g);
+    const block = blocks?.[blocks.length - 1];
+    if (block === undefined)
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(block);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const record = raw;
+    const integratedLufs = numeric(record.input_i);
+    const truePeakDb = numeric(record.input_tp);
+    const lra = numeric(record.input_lra);
+    const threshold = numeric(record.input_thresh);
+    const offset = numeric(record.target_offset);
+    if (integratedLufs === undefined ||
+        truePeakDb === undefined ||
+        lra === undefined ||
+        threshold === undefined ||
+        offset === undefined) {
+        return undefined;
+    }
+    return { integratedLufs, truePeakDb, lra, threshold, offset };
+};
+/**
+ * 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 const needsNormalization = (measurement) => Math.abs(measurement.integratedLufs - TARGET_LUFS) > AT_TARGET_TOLERANCE_LU ||
+    measurement.truePeakDb > MIX_TRUE_PEAK_DBTP;
+/** Pass 2 filter: one linear gain from the pass-1 measurements plus the target. */
+export const buildLoudnessNormalizeFilter = (measurement) => {
+    const fixed = (value) => value.toFixed(2);
+    return (`loudnorm=linear=true:I=${TARGET_LUFS}:TP=${TARGET_TRUE_PEAK_DB}:LRA=${TARGET_LRA}` +
+        `:measured_I=${fixed(measurement.integratedLufs)}` +
+        `:measured_TP=${fixed(measurement.truePeakDb)}` +
+        `:measured_LRA=${fixed(measurement.lra)}` +
+        `:measured_thresh=${fixed(measurement.threshold)}` +
+        `:offset=${fixed(measurement.offset)}`);
+};
+/** Pass 1 argv: measure the mixed file; `-vn` keeps the video stream undecoded. */
+export const buildLoudnessMeasureArgs = (input) => [
+    "-hide_banner",
+    "-nostats",
+    "-v",
+    "info",
+    "-vn",
+    "-i",
+    input,
+    "-filter:a",
+    LOUDNORM_MEASURE_FILTER,
+    "-f",
+    "null",
+    "-",
+];
+/**
+ * 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 const buildLoudnessNormalizeArgs = (input, measurement, out) => [
+    "-hide_banner",
+    "-nostats",
+    "-y",
+    "-v",
+    "error",
+    "-i",
+    input,
+    "-filter:a",
+    buildLoudnessNormalizeFilter(measurement),
+    "-map",
+    "0:v:0",
+    "-map",
+    "0:a:0",
+    "-c:v",
+    "copy",
+    "-c:a",
+    "aac",
+    "-b:a",
+    "192k",
+    "-movflags",
+    "+faststart",
+    out,
+];
+const firstLine = (text) => text.split(/\r?\n/).find((line) => line.trim() !== "") ?? "";
+/**
+ * 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 const mixAtDeliveryLevel = async (run, plan) => {
+    const skipped = (problems = [], measurement = null) => ({ ok: true, out: plan.out, normalized: false, measurement, problems });
+    const failed = (problems, measurement = null) => ({ ok: false, out: plan.out, normalized: false, measurement, problems });
+    const measure = async () => {
+        const probed = await run(buildLoudnessMeasureArgs(plan.out));
+        return probed.code === 0
+            ? parseLoudnessMeasurement(`${probed.stdout}\n${probed.stderr}`)
+            : undefined;
+    };
+    if (plan.clips.length === 0)
+        return skipped();
+    const mixArgs = plan.music === undefined
+        ? buildMixArgs(plan.videoIn, plan.clips, plan.out)
+        : buildMusicMixArgs(plan.videoIn, plan.clips, plan.music, plan.out);
+    const mixed = await run(mixArgs);
+    if (mixed.code !== 0)
+        return failed([`mix failed: ${firstLine(mixed.stderr)}`]);
+    let measurement = await measure();
+    if (measurement === undefined)
+        return skipped(["loudness unmeasured: no loudnorm json"]);
+    if (!needsNormalization(measurement))
+        return skipped([], measurement);
+    const normalized = `${plan.out}.loudnorm.mp4`;
+    for (let pass = 0; pass < MAX_NORMALIZE_PASSES; pass += 1) {
+        const current = measurement;
+        const encoded = await run(buildLoudnessNormalizeArgs(plan.out, current, normalized));
+        if (encoded.code !== 0) {
+            return failed([`loudnorm failed: ${firstLine(encoded.stderr) || "non-zero exit"}`], current);
+        }
+        try {
+            await plan.swap(normalized, plan.out);
+        }
+        catch (error) {
+            return failed([`cannot replace the mix: ${error.message}`], current);
+        }
+        const confirmed = await measure();
+        if (confirmed === undefined) {
+            return {
+                ok: true,
+                out: plan.out,
+                normalized: true,
+                measurement: current,
+                problems: ["loudness unconfirmed after normalizing"],
+            };
+        }
+        measurement = confirmed;
+        if (!needsNormalization(measurement)) {
+            return { ok: true, out: plan.out, normalized: true, measurement, problems: [] };
+        }
+    }
+    return {
+        ok: true,
+        out: plan.out,
+        normalized: true,
+        measurement,
+        problems: [
+            `loudness ${measurement.integratedLufs.toFixed(2)} LUFS after ` +
+                `${MAX_NORMALIZE_PASSES} normalizing passes (target ${TARGET_LUFS})`,
+        ],
+    };
+};

package/dist/audio/music.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pinned music-bed mix constants (T-AU-01a, current-only).
+ *
+ * Single measurement source: the qc-lufs pack proof.
+ * LUFS target comes from the verified `youtube` platform policy
+ * (`lufsTarget: -14`, `truePeakDb: -1`, `verified: true`); the ducked bed
+ * depth is the static schema level `DEFAULT_MUSIC_VOLUME = 0.5`, measured
+ * on this machine as `20*log10(0.5) = -6.0206 dB`, before the frozen
+ * sidechain stage. Tolerances mirror the `qc-lufs` measurement seam
+ * (`LOUDNESS_TOLERANCE_LU = 1`, `TRUE_PEAK_TOLERANCE_DB = 0.5`).
+ * Nothing here runs ffmpeg; measurement stays in the verify chain (LC-04).
+ */
+/** Ducked bed level, re-exported from the schema single source. */
+export declare const DEFAULT_MUSIC_VOLUME: number;
+/** Pinned integrated-loudness target for the mixed output (qc-lufs). */
+export declare const MIX_LUFS_TARGET = -14;
+/** Pinned true-peak ceiling for the mixed output (qc-lufs). */
+export declare const MIX_TRUE_PEAK_DBTP = -1;
+/** Accepted drift for integrated loudness vs the pinned target. */
+export declare const MIX_LOUDNESS_TOLERANCE_LU = 1;
+/** Accepted excess for true peak above the pinned ceiling. */
+export declare const MIX_TRUE_PEAK_TOLERANCE_DB = 0.5;
+/** Static bed gain of the default ducked level, dB (measured receipt). */
+export declare const DUCKING_DB = -6.0206;
+/** Frozen sidechain stage (pinned by mix.test.ts, qc-lufs §Ducking dB). */
+export declare const SIDECHAIN_THRESHOLD = 0.03;
+export declare const SIDECHAIN_RATIO = 4;
+export declare const SIDECHAIN_ATTACK_MS = 200;
+export declare const SIDECHAIN_RELEASE_MS = 500;
+/** Only CC0 beds are supported (licence gate, current-only). */
+export declare const MUSIC_LICENCE = "CC0-1.0";
+/** sha256 of zero bytes: a silent/empty wav can never qualify as a bed. */
+export declare const EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/**
+ * Current-only music identity: project-relative bed path plus the frozen
+ * content hashes the approval gate hashed. `relativePath` is always
+ * forward-slash project-relative (never absolute, never a machine path);
+ * `sha256` is the bed wav bytes; `licenceEvidenceSha256` is the CC0
+ * evidence receipt bytes (null only when no receipt was supplied).
+ */
+export interface MusicIdentity {
+    readonly relativePath: string;
+    readonly sha256: string;
+    readonly volume: number;
+    readonly licenceEvidenceSha256: string | null;
+}
+/** Static gain of a bed level in dB; refuses nonsense (fail closed). */
+export declare const musicGainDb: (volume: number) => number;
+/** True when a level sits at the pinned ducking depth within 0.001 dB. */
+export declare const isPinnedDuckingDepth: (volume: number) => boolean;
+export interface SeamlessLoop {
+    readonly loops: number;
+    readonly trimDuration: number;
+    readonly phaseError: number;
+    readonly isSeamless: boolean;
+}
+/**
+ * Seamless-loop phase math: how many bed repeats cover `totalDuration`
+ * seconds and where the trim lands in the bed cycle. `phaseError` is the
+ * fractional cycle cut by the trim (0 = trim lands on the loop boundary,
+ * seamless); `loops` is `ceil(total / bed)`. Refuses nonsense (fail closed).
+ */
+export declare const seamlessLoopFor: (bedDuration: number, totalDuration: number) => SeamlessLoop;
+/**
+ * Fail-closed identity check (current-only): malformed identity fields,
+ * a missing/unreadable bed digest, a mutated bed sha, or a drifted licence
+ * receipt each yield a problem. Empty means the frozen bytes match the
+ * identity. An ABA restore (mutate then restore the source) still passes
+ * only when the frozen copy consumed by the mix matches — the check reads
+ * the frozen digest, never the mutable source.
+ */
+export declare const verifyMusicIdentity: (identity: MusicIdentity, actualBedSha256: string | undefined, actualLicenceSha256: string | null | undefined) => string[];
+export interface MixLoudnessAssessment {
+    readonly ok: boolean;
+    readonly problems: string[];
+}
+/**
+ * Judges one integrated-loudness + true-peak measurement against the pinned
+ * qc-lufs constants. Mirrors the verify-chain tolerances; measurement itself
+ * stays in the CLI verify seam (LC-04).
+ */
+export declare const assessMixLoudness: (integratedLufs: number, truePeakDb: number) => MixLoudnessAssessment;