@glissade/cli 0.38.0 → 0.39.0-pre.1

package/README.md

@@ -2,7 +2,7 @@
 
 `gs` — headless rendering and the dev/capture loop. `gs render` evaluates every frame, rasterizes on Skia (no browser anywhere), writes a PNG sequence or muxes mp4/webm via FFmpeg with sample-accurate audio. v2: `gs dev --record` serves a scene with its state machines mounted and writes input-trace sidecars; `gs render --trace/--state` are the deterministic export routes for interactive scenes.
 
-The full command set: `render`, `dev`, `import` (Lottie `.json` / `.svg`), `build`, `mcp` (an MCP server over the engine), `describe`, `migrate`, `repin` (narration-aware golden reviewer), `narrate`, `sfx`, `prepare`, `measure-loudness`, `fonts`, `cache`, `diff`, and `verify-determinism`. Run `gs` with no arguments for the full usage.
+The full command set: `render`, `dev`, `import` (Lottie `.json` / `.svg`), `build`, `mcp` (an MCP server over the engine), `describe`, `migrate`, `repin` (narration-aware golden reviewer), `narrate`, `sfx`, `prepare`, `measure-loudness`, `master` (series loudness + limiter), `fonts`, `cache`, `diff`, and `verify-determinism`. Run `gs` with no arguments for the full usage.
 
 ```sh
 npm i -D @glissade/cli
@@ -33,6 +33,34 @@ The SSIM machinery is also exported from `@glissade/backend-skia`
 (`ssim` / `ssimMap` / `heatmapRgba`) for your own golden tooling. Full guide:
 [Reviewing goldens](https://github.com/tyevco/glissade/blob/main/docs/golden-review.md).
 
+## Series loudness (`gs master`)
+
+`gs measure-loudness` gains one asset at a time and clamps the gain against the
+source peak — so a peaky short lands LUs below target and a whole series ends up
+inconsistent. `gs master` measures a whole set together, picks the loudest shared
+LUFS target the set can hit under a shared true-peak ceiling, and ships a brickwall
+true-peak **limiter** so a peaky member recovers headroom instead of landing low.
+
+```jsonc
+// glissade.master.json
+{ "profile": "youtube",
+  "members": ["episodes/**/e*.ts", "**/*-short.ts"],
+  "limiter": { "mode": "truepeak", "ceilingDb": -1.0 },
+  "consistency": "shared-target" }
+```
+
+```sh
+gs master glissade.master.json
+#   e01        in -22.1/-6.2dBTP -> +6.9dB,+1.2dB GR  out -14.0/-1.0
+#   e07-short  in -11.8/-0.3     -> -2.2dB            out -14.0/-1.0
+#   shared target -14.0 LUFS — wrote <scene>.loudness.json ×16
+```
+
+It writes the same `<scene>.loudness.json` sidecar (plus a `limiter` block), so it
+composes with the render-time mixHash preflight and **applies as a mix-only remux
+(~20 s/asset), never a re-render**. Full guide:
+[Series mastering](https://github.com/tyevco/glissade/blob/main/docs/mastering.md).
+
 ## Part of glissade
 
 *(glide & slide)* — programmatic motion graphics for TypeScript: realtime-first in any web page, deterministic headless video export from the same code, a visual studio over the same document. No generator functions.

package/dist/audioMix.js

@@ -13,6 +13,7 @@ var audioMix_exports = /* @__PURE__ */ __exportAll({
 	applyMixGainDb: () => applyMixGainDb,
 	atempoChain: () => atempoChain,
 	gainExpression: () => gainExpression,
+	loudnessFilterNodes: () => loudnessFilterNodes,
 	planAudioMix: () => planAudioMix,
 	resolveAssetPath: () => resolveAssetPath
 });
@@ -61,19 +62,50 @@ function atempoChain(rate) {
 	if (Math.abs(r - 1) > 1e-9 || chain.length === 0) chain.push(`atempo=${r}`);
 	return chain;
 }
+/** The mix sample rate the limiter oversamples around (glissade mixes at 48 kHz). */
+const MIX_RATE = 48e3;
+/** 4× oversampling for the true-peak limiter — reconstructs inter-sample peaks. */
+const TP_OVERSAMPLE = MIX_RATE * 4;
 /**
-* Append a PURE scalar publish-loudness gain to a mix's `-filter_complex`: the
-* graph's final `[aout]` label is renamed and a `volume=<gain>dB` node feeds the
-* new `[aout]`. This is a single multiply on the FINAL mix node — NOT a second
-* ffmpeg pass — and is bit-deterministic (verified) + golden-hashable. A gain of
-* exactly 0 dB is a no-op (returned unchanged) so an at-target source preserves
-* the prior, un-gained bytes.
+* True-peak guard (dB): the sample-peak limit is set this far BELOW the ceiling so
+* the downsample-reconstructed TRUE peak lands under `ceilingDb`. Empirically the
+* 4× oversample→limit→downsample residue is ~0.5 dB on worst-case (clipped-noise)
+* content; 0.8 gives a comfortable margin (worst case measured −1.31 dBTP for a −1
+* ceiling) without over-attenuating real beds. WITHOUT the oversample, `alimiter`
+* is a SAMPLE-peak brickwall that leaves the true peak clipping over the ceiling
+* (the 0.39.0-pre.0 defect — mode:'truepeak' didn't hold dBTP).
 */
-function applyMixGainDb(filterComplex, gainDb) {
-	if (gainDb === 0) return filterComplex;
+const TP_GUARD_DB = .8;
+/**
+* The publish-loudness filter nodes: a `volume=<gain>dB` multiply, and — for a
+* `gs master` measurement — a REAL true-peak limiter (oversample 4× → `alimiter`
+* at `ceilingDb − guard` → downsample) that actually holds the inter-sample /
+* true peak under `ceilingDb`. Shared by the render `filter_complex` apply and the
+* `gs master` verify pass so the committed limiter and the rendered output are the
+* identical deterministic chain. Empty (a no-op) at 0 dB with no limiter.
+*/
+function loudnessFilterNodes(gainDb, limiter) {
+	const nodes = [];
+	if (gainDb !== 0) nodes.push(`volume=${gainDb}dB`);
+	if (limiter) {
+		const limit = Math.pow(10, (limiter.ceilingDb - TP_GUARD_DB) / 20).toFixed(6);
+		nodes.push(`aresample=${TP_OVERSAMPLE}`, `alimiter=limit=${limit}:level=disabled`, `aresample=${MIX_RATE}`);
+	}
+	return nodes;
+}
+/**
+* Append the publish-loudness stage to a mix's `-filter_complex`: the graph's
+* final `[aout]` label is renamed and the {@link loudnessFilterNodes} (gain +,
+* for a master, the true-peak limiter) feed the new `[aout]`. Bit-deterministic +
+* golden-hashable. A 0 dB gain with NO limiter is a no-op (returned unchanged) so
+* an at-target source preserves the prior, un-gained bytes.
+*/
+function applyMixGainDb(filterComplex, gainDb, limiter) {
+	const nodes = loudnessFilterNodes(gainDb, limiter);
+	if (nodes.length === 0) return filterComplex;
 	const at = filterComplex.lastIndexOf("[aout]");
 	if (at < 0) throw new AudioMixError("mix filter graph has no [aout] to apply the loudness gain to");
-	return `${filterComplex.slice(0, at) + "[apreg]" + filterComplex.slice(at + 6)};[apreg]volume=${gainDb}dB[aout]`;
+	return `${filterComplex.slice(0, at) + "[apreg]" + filterComplex.slice(at + 6)};[apreg]${nodes.join(",")}[aout]`;
 }
 /** Build the FFmpeg mix plan for clips that intersect [0, duration]. */
 function planAudioMix(clips, modulePath, duration) {

package/dist/cli.js

@@ -81,6 +81,7 @@ const USAGE = `usage:
   gs sfx <scene-module|script.sfx.json> [--verbose]
   gs prepare <scene-module>  [--provider <id>] [--align <id>] [--force]
   gs measure-loudness <scene-module> [--profile <youtube|shorts|podcast|broadcast|ebu>] [--locale <code>]
+  gs master <glissade.master.json>   SERIES loudness: measure all members, pick the loudest shared LUFS target the set hits under a shared true-peak ceiling, ship the brickwall limiter, write <scene>.loudness.json ×N (applies as a mix-only remux; mixHash unchanged)
   gs fonts audit <scene-module>   list registered families, formats, and missing-glyph runs (§3.6)
   gs cache verify <scene-module> [--range a..b] [--sample <n>]   assert cache hits == cold renders (§3.5)
   gs mcp <scene-module>   start an MCP stdio server for this scene: describe / list_targets / apply_patch / undo / render_frame (the AI-native write layer)
@@ -184,7 +185,7 @@ async function main() {
 		process.stdout.write(`${describe().version}\n`);
 		return;
 	}
-	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate" && command !== "repin") {
+	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate" && command !== "repin" && command !== "master") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
@@ -225,6 +226,22 @@ async function main() {
 		}
 		return;
 	}
+	if (command === "master") {
+		const { positional: mp } = parseArgs(rest);
+		const configPath = mp[0] || "glissade.master.json";
+		const { masterCommand } = await import("./master.js").then((n) => n.a);
+		try {
+			const r = await masterCommand({
+				configPath,
+				onLog: (line) => process.stderr.write(`${line}\n`)
+			});
+			process.stderr.write(`${r.report}\n`);
+			if (r.members.some((m) => m.overCeiling)) process.exit(1);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
 	if (command === "cache") {
 		const { positional: cp, flags: cf } = parseArgs(rest);
 		const sub = cp[0];

package/dist/index.d.ts

@@ -128,6 +128,200 @@ declare function probeEntryHeader(file: string): {
 /** Remove the whole `.gscache` dir (a `gs cache clear` convenience / test cleanup). */
 declare function clearFrameCache(dir: string): void;
 //#endregion
+//#region src/loudness.d.ts
+/**
+ * gs measure-loudness (0.12, DESIGN §5.3): loudness-normalized PUBLISH profiles
+ * via a deterministic, peak-clamped scalar GAIN — NOT a render-pipeline change.
+ *
+ * The key insight: YouTube/Shorts re-normalize loudness platform-side, so the
+ * publish target is *≤ target-LUFS AND ≤ -1 dBTP*, not exact. So we never need a
+ * two-pass limiter on the render hot path. Instead:
+ *
+ *   1. `gs measure-loudness` runs ffmpeg's `loudnorm` measurement pass (a
+ *      print-only ebur128 + true-peak gate) at MEASURE-time over the final
+ *      mixed PCM, reading `inputI` (integrated LUFS), `inputTp` (true peak
+ *      dBTP), `inputLra`. This is the ONE non-deterministic stage and it is
+ *      QUARANTINED to commit-time — §5.3 already concedes mix-to-PCM bytes are
+ *      per-path only.
+ *   2. It commits a `<scene>.loudness.json` carrying the measured numbers, the
+ *      chosen profile, the resulting `gain` (dB), and a `mixHash` binding the
+ *      measurement to the mix CONTENT (the narration/music/sfx manifests).
+ *   3. `gs render` reads that file and applies `gain` as a PURE scalar
+ *      `volume=<gain>dB` multiply on the FINAL mix node — a single scalar in the
+ *      existing filter graph, NOT a new ffmpeg pass. That stage is bit-exact and
+ *      golden-hashable (a multiply at the same float→Int16 boundary the rest of
+ *      the audio path shares).
+ *
+ * The gain is peak-clamped: `gain = min(gainForTargetLUFS, (-1 dBTP) - inputTp)`.
+ * The clamp uses the MEASURED true-peak, so the published output is guaranteed
+ * ≤ -1 dBTP with no render-time oversampling. (For 0.12 the brickwall true-peak
+ * LIMITER is DEFERRED — un-normalized profiles still get the gain plus an
+ * advisory warning when a peaky source would have needed brickwalling.)
+ */
+declare class LoudnessError extends Error {
+  constructor(detail: string);
+}
+/** A publish target: integrated-loudness goal + the true-peak ceiling. */
+interface PublishProfile {
+  readonly id: string;
+  /** integrated-loudness target, LUFS */
+  readonly targetLufs: number;
+  /** true-peak ceiling, dBTP (the peak clamp is computed against this) */
+  readonly truePeakDb: number;
+  /**
+   * Whether the platform re-normalizes loudness on its side. For
+   * platform-normalized targets (YouTube/Shorts) a peaky source that can't reach
+   * `targetLufs` without clipping is fine — the platform finishes the job. For
+   * un-normalized targets (podcast/broadcast) it earns an advisory warning,
+   * since 0.12 ships no brickwall limiter to recover the headroom.
+   */
+  readonly platformNormalized: boolean;
+}
+declare const PUBLISH_PROFILES: Readonly<Record<string, PublishProfile>>;
+declare const DEFAULT_PROFILE_ID = "youtube";
+/** Resolve a profile id (case-insensitive) or throw with the valid set. */
+declare function resolveProfile(id: string): PublishProfile;
+declare const LOUDNESS_SCHEMA_VERSION: 1;
+/**
+ * The brickwall true-peak limiter a `gs master` pass commits (0.39). Absent on a
+ * plain `gs measure-loudness` measurement (that stays a pure peak-clamped scalar
+ * gain, byte-identical). Present, render/remux applies `volume=<gain>dB` THEN an
+ * `alimiter` holding the true peak at `ceilingDb` — the non-linear stage that lets
+ * a peaky member reach the target instead of landing LUs low. Applied in the mix
+ * filter graph (deterministic ffmpeg), NOT a render-time per-frame scalar.
+ */
+interface CommittedLimiter {
+  readonly mode: 'truepeak';
+  /** the true-peak ceiling the limiter holds, dBTP. */
+  readonly ceilingDb: number;
+}
+/** The committed `<scene>.loudness.json`. */
+interface LoudnessMeasurement {
+  loudnessVersion: typeof LOUDNESS_SCHEMA_VERSION;
+  /** the resolved publish profile id (youtube/shorts/podcast/broadcast/ebu) */
+  profileId: string;
+  /** measured integrated loudness, LUFS (ebur128) */
+  inputI: number;
+  /** measured true peak, dBTP */
+  inputTp: number;
+  /** measured loudness range, LU */
+  inputLra: number;
+  /**
+   * the deterministic gain to apply at render, in dB.
+   * `gain = min(targetLufs - inputI, truePeakDb - inputTp)` — the peak clamp
+   * guarantees the published output is ≤ truePeakDb using the MEASURED peak.
+   */
+  gain: number;
+  /**
+   * binds this measurement to the mix CONTENT version (a hash of the mix input
+   * manifests — narration/music/sfx timing + any wired timeline audio — NOT
+   * mtime). Render recomputes it and HARD-THROWS on mismatch so a re-narrate
+   * invalidates the measurement loudly instead of silently mis-normalizing.
+   */
+  mixHash: string;
+  /**
+   * the true-peak limiter to apply after the gain (0.39 `gs master`). Absent on a
+   * plain `gs measure-loudness` measurement (gain-only, byte-identical). When
+   * present, `gain` may exceed the raw peak clamp (the limiter shaves the
+   * overshoot to `limiter.ceilingDb`).
+   */
+  limiter?: CommittedLimiter;
+}
+/**
+ * The peak-clamped publish gain (dB). `gainForTargetLUFS = target - inputI`
+ * raises/lowers to the integrated target; the clamp `truePeak - inputTp` caps it
+ * so the result never exceeds the true-peak ceiling. We take the min: a source
+ * that can't reach the loudness target without clipping is left below it (the
+ * platform re-normalizes the rest for `youtube`/`shorts`).
+ */
+declare function computeGainDb(profile: PublishProfile, inputI: number, inputTp: number): number;
+/**
+ * True when the peak clamp BOUND the gain — i.e. the source is too peaky to reach
+ * the loudness target without exceeding the true-peak ceiling. For an
+ * un-normalized profile this is where a brickwall limiter would normally recover
+ * the headroom (deferred in 0.12 → advisory warning).
+ */
+declare function peakClampBinds(profile: PublishProfile, inputI: number, inputTp: number): boolean;
+/**
+ * Hash the CONTENT of the mix's inputs so a re-narrate / re-sfx / music change OR
+ * an in-place edit of an audio file invalidates a committed measurement. We hash
+ * the files' BYTES (not mtime): the narration/music/sfx timing manifests AND every
+ * path in `extraInputs` — the resolved mix AUDIO files (timeline clips + the music
+ * stem + narration cache audio), supplied by `collectMixAudioInputs` at both the
+ * measure and render call sites so the two agree. Hashing only the timing manifests
+ * would miss an edited `.wav`/stem (same manifest, changed bytes) and apply a stale
+ * publish gain silently — so `extraInputs` MUST be passed on the gate path. Missing
+ * files are recorded by name with a sentinel so adding one later also changes the
+ * hash. The scene module path itself is excluded.
+ */
+declare function computeMixHash(modulePath: string, extraInputs?: readonly string[]): string;
+/**
+ * The committed loudness measurement path for a scene module.
+ *
+ * Base (no locale): `<stem>.loudness.json` — UNCHANGED. With a locale set (0.15
+ * FIX 2): `<stem>.<locale>.loudness.json`. A localized render mixes the per-locale
+ * narration (e.g. the zh wavs) → a DIFFERENT mixHash than the base, so it needs its
+ * OWN committed measurement; one base file can't gate a localized render (it would
+ * always read as a stale mixHash, with no supported way to commit a per-locale one).
+ */
+declare function loudnessPathFor(modulePath: string, locale?: string): string;
+/** Read + validate a committed measurement, or null when none is committed. */
+declare function readLoudness(modulePath: string, locale?: string): LoudnessMeasurement | null;
+/**
+ * Parse the JSON block ffmpeg's `loudnorm=print_format=json` prints to stderr.
+ * It carries `input_i` / `input_tp` / `input_lra` (the measured loudness),
+ * alongside the would-be normalization params (which we ignore — we apply our
+ * own peak-clamped scalar gain instead).
+ */
+declare function parseLoudnormJson(stderr: string): {
+  inputI: number;
+  inputTp: number;
+  inputLra: number;
+};
+/**
+ * Run ffmpeg's loudnorm measurement pass over a built mix WAV/PCM file and return
+ * the measured loudness. This is the quarantined non-deterministic stage — it
+ * runs ONLY at measure-time (commit), never during render.
+ */
+declare function measureFile(audioPath: string): {
+  inputI: number;
+  inputTp: number;
+  inputLra: number;
+};
+interface MeasureLoudnessOptions {
+  modulePath: string;
+  /** publish profile id; default 'youtube' */
+  profile?: string;
+  /** narration auto-mix toggle (mirrors render); default auto */
+  narration?: 'auto' | 'off';
+  music?: 'auto' | 'off';
+  sfx?: 'auto' | 'off';
+  /**
+   * locale code (0.15 FIX 2). When set, measure the per-locale mix (the localized
+   * narration sibling) and commit `<stem>.<locale>.loudness.json` instead of the
+   * base file. Mirrors `gs render --locale`, so the measured content matches what
+   * a localized render mixes.
+   */
+  locale?: string;
+}
+interface MeasureLoudnessResult {
+  measurement: LoudnessMeasurement;
+  loudnessPath: string;
+  /** profile the measurement was taken against */
+  profile: PublishProfile;
+  /** true when the peak clamp bound the gain (advisory: would need a brickwall limiter on an un-normalized profile) */
+  clampBound: boolean;
+  /** an advisory warning string when an un-normalized profile can't reach its target without clipping; else null */
+  warning: string | null;
+}
+/**
+ * Build the final mix to a WAV, run the ffmpeg loudnorm measurement over it, and
+ * commit a `<scene>.loudness.json` with the peak-clamped publish gain + a mixHash
+ * bound to the mix-input manifests. This is the measure step (commit-time); it is
+ * the only place the non-deterministic ebur128/mix-to-PCM stages run.
+ */
+declare function measureLoudnessCommand(opts: MeasureLoudnessOptions): Promise<MeasureLoudnessResult>;
+//#endregion
 //#region src/render.d.ts
 interface RenderOptions {
   modulePath: string;
@@ -334,7 +528,10 @@ declare function collectAudioClips(opts: Pick<RenderOptions, 'modulePath' | 'nar
  * generic stale-mixHash message — there is otherwise no supported way to commit a
  * per-locale measurement, so a base file would always read as stale and dead-end.
  */
-declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' | 'loudness' | 'narration' | 'music' | 'sfx' | 'locale'>, timelineClips?: AudioClip[]): Promise<number | null>;
+declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' | 'loudness' | 'narration' | 'music' | 'sfx' | 'locale'>, timelineClips?: AudioClip[]): Promise<{
+  gainDb: number;
+  limiter?: CommittedLimiter;
+} | null>;
 /**
  * Collect audio clips + auto-mixed siblings and plan the FFmpeg audio graph,
  * returning the `-i`/`-filter_complex`/`-map` argument fragments. Shared by the
@@ -362,179 +559,125 @@ declare function planFinalAudio(opts: RenderOptions, timelineClips: AudioClip[],
  */
 declare function buildMixWav(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx' | 'locale'>, wavOut: string): Promise<boolean>;
 //#endregion
-//#region src/loudness.d.ts
-/**
- * gs measure-loudness (0.12, DESIGN §5.3): loudness-normalized PUBLISH profiles
- * via a deterministic, peak-clamped scalar GAIN — NOT a render-pipeline change.
- *
- * The key insight: YouTube/Shorts re-normalize loudness platform-side, so the
- * publish target is *≤ target-LUFS AND ≤ -1 dBTP*, not exact. So we never need a
- * two-pass limiter on the render hot path. Instead:
- *
- *   1. `gs measure-loudness` runs ffmpeg's `loudnorm` measurement pass (a
- *      print-only ebur128 + true-peak gate) at MEASURE-time over the final
- *      mixed PCM, reading `inputI` (integrated LUFS), `inputTp` (true peak
- *      dBTP), `inputLra`. This is the ONE non-deterministic stage and it is
- *      QUARANTINED to commit-time — §5.3 already concedes mix-to-PCM bytes are
- *      per-path only.
- *   2. It commits a `<scene>.loudness.json` carrying the measured numbers, the
- *      chosen profile, the resulting `gain` (dB), and a `mixHash` binding the
- *      measurement to the mix CONTENT (the narration/music/sfx manifests).
- *   3. `gs render` reads that file and applies `gain` as a PURE scalar
- *      `volume=<gain>dB` multiply on the FINAL mix node — a single scalar in the
- *      existing filter graph, NOT a new ffmpeg pass. That stage is bit-exact and
- *      golden-hashable (a multiply at the same float→Int16 boundary the rest of
- *      the audio path shares).
- *
- * The gain is peak-clamped: `gain = min(gainForTargetLUFS, (-1 dBTP) - inputTp)`.
- * The clamp uses the MEASURED true-peak, so the published output is guaranteed
- * ≤ -1 dBTP with no render-time oversampling. (For 0.12 the brickwall true-peak
- * LIMITER is DEFERRED — un-normalized profiles still get the gain plus an
- * advisory warning when a peaky source would have needed brickwalling.)
- */
-declare class LoudnessError extends Error {
-  constructor(detail: string);
+//#region src/master.d.ts
+declare class MasterError extends Error {
+  constructor(message: string);
 }
-/** A publish target: integrated-loudness goal + the true-peak ceiling. */
-interface PublishProfile {
+/** How much gain-reduction the limiter may apply to buy headroom (dB). */
+declare const DEFAULT_MAX_GR_DB = 6;
+/** The limiter spec (from `glissade.master.json`). */
+interface MasterLimiter {
+  /** true-peak brickwall (the only mode today). */
+  readonly mode: 'truepeak';
+  /** the true-peak ceiling, dBTP (defaults to the profile's `truePeakDb`). */
+  readonly ceilingDb?: number;
+  /** limiter lookahead, ms (advisory — maps to the ffmpeg attack window). */
+  readonly lookaheadMs?: number;
+  /** max gain-reduction the limiter may apply (dB); beyond this a member can't
+   *  reach the target cleanly and the shared target drops. Default 6. */
+  readonly maxGrDb?: number;
+}
+/** `glissade.master.json`. */
+interface MasterConfig {
+  /** publish profile id (youtube/shorts/podcast/broadcast/ebu). */
+  readonly profile?: string;
+  /** member scene globs (like `gs build`'s `scenes`). */
+  readonly members: readonly string[];
+  /** the limiter (or `false` to keep the legacy peak-clamp behaviour). */
+  readonly limiter?: MasterLimiter | false;
+  /** `shared-target` (all members hit one LUFS) or `per-asset` (each hits its own max). */
+  readonly consistency?: 'shared-target' | 'per-asset';
+}
+/** One member's measured input loudness (from the ffmpeg measure pass). */
+interface MemberMeasure {
   readonly id: string;
-  /** integrated-loudness target, LUFS */
-  readonly targetLufs: number;
-  /** true-peak ceiling, dBTP (the peak clamp is computed against this) */
-  readonly truePeakDb: number;
-  /**
-   * Whether the platform re-normalizes loudness on its side. For
-   * platform-normalized targets (YouTube/Shorts) a peaky source that can't reach
-   * `targetLufs` without clipping is fine — the platform finishes the job. For
-   * un-normalized targets (podcast/broadcast) it earns an advisory warning,
-   * since 0.12 ships no brickwall limiter to recover the headroom.
-   */
-  readonly platformNormalized: boolean;
+  /** integrated loudness, LUFS. */
+  readonly inputI: number;
+  /** true peak, dBTP. */
+  readonly inputTp: number;
 }
-declare const PUBLISH_PROFILES: Readonly<Record<string, PublishProfile>>;
-declare const DEFAULT_PROFILE_ID = "youtube";
-/** Resolve a profile id (case-insensitive) or throw with the valid set. */
-declare function resolveProfile(id: string): PublishProfile;
-declare const LOUDNESS_SCHEMA_VERSION: 1;
-/** The committed `<scene>.loudness.json`. */
-interface LoudnessMeasurement {
-  loudnessVersion: typeof LOUDNESS_SCHEMA_VERSION;
-  /** the resolved publish profile id (youtube/shorts/podcast/broadcast/ebu) */
-  profileId: string;
-  /** measured integrated loudness, LUFS (ebur128) */
-  inputI: number;
-  /** measured true peak, dBTP */
-  inputTp: number;
-  /** measured loudness range, LU */
-  inputLra: number;
-  /**
-   * the deterministic gain to apply at render, in dB.
-   * `gain = min(targetLufs - inputI, truePeakDb - inputTp)` — the peak clamp
-   * guarantees the published output is ≤ truePeakDb using the MEASURED peak.
-   */
-  gain: number;
-  /**
-   * binds this measurement to the mix CONTENT version (a hash of the mix input
-   * manifests — narration/music/sfx timing + any wired timeline audio — NOT
-   * mtime). Render recomputes it and HARD-THROWS on mismatch so a re-narrate
-   * invalidates the measurement loudly instead of silently mis-normalizing.
-   */
-  mixHash: string;
+/** The plan for one member: its target + the gain to apply + predicted limiting. */
+interface MemberPlan extends MemberMeasure {
+  /** the output LUFS this member is driven to. */
+  readonly target: number;
+  /** the gain to apply before the limiter, dB. */
+  readonly gain: number;
+  /** predicted limiter gain-reduction, dB (0 when the raw peak clears the ceiling). */
+  readonly grDb: number;
+  /** predicted output true peak, dBTP (== ceiling when the limiter engages). */
+  readonly predOutTp: number;
+  /** true when this member reaches the shared target within the GR budget. */
+  readonly reachable: boolean;
+}
+interface MasterPlan {
+  /** the LUFS target the set is normalized to (shared-target) or the profile cap. */
+  readonly sharedTarget: number;
+  readonly profileTarget: number;
+  readonly ceilingDb: number;
+  /** true when a limiter is in play (false = legacy peak-clamp). */
+  readonly limiter: boolean;
+  readonly maxGrDb: number;
+  readonly members: readonly MemberPlan[];
 }
 /**
- * The peak-clamped publish gain (dB). `gainForTargetLUFS = target - inputI`
- * raises/lowers to the integrated target; the clamp `truePeak - inputTp` caps it
- * so the result never exceeds the true-peak ceiling. We take the min: a source
- * that can't reach the loudness target without clipping is left below it (the
- * platform re-normalizes the rest for `youtube`/`shorts`).
- */
-declare function computeGainDb(profile: PublishProfile, inputI: number, inputTp: number): number;
-/**
- * True when the peak clamp BOUND the gain — i.e. the source is too peaky to reach
- * the loudness target without exceeding the true-peak ceiling. For an
- * un-normalized profile this is where a brickwall limiter would normally recover
- * the headroom (deferred in 0.12 → advisory warning).
- */
-declare function peakClampBinds(profile: PublishProfile, inputI: number, inputTp: number): boolean;
-/**
- * Hash the CONTENT of the mix's inputs so a re-narrate / re-sfx / music change OR
- * an in-place edit of an audio file invalidates a committed measurement. We hash
- * the files' BYTES (not mtime): the narration/music/sfx timing manifests AND every
- * path in `extraInputs` — the resolved mix AUDIO files (timeline clips + the music
- * stem + narration cache audio), supplied by `collectMixAudioInputs` at both the
- * measure and render call sites so the two agree. Hashing only the timing manifests
- * would miss an edited `.wav`/stem (same manifest, changed bytes) and apply a stale
- * publish gain silently — so `extraInputs` MUST be passed on the gate path. Missing
- * files are recorded by name with a sentinel so adding one later also changes the
- * hash. The scene module path itself is excluded.
- */
-declare function computeMixHash(modulePath: string, extraInputs?: readonly string[]): string;
-/**
- * The committed loudness measurement path for a scene module.
+ * Plan a master pass. Pure: measured members → shared target + per-member gains.
  *
- * Base (no locale): `<stem>.loudness.json` — UNCHANGED. With a locale set (0.15
- * FIX 2): `<stem>.<locale>.loudness.json`. A localized render mixes the per-locale
- * narration (e.g. the zh wavs) → a DIFFERENT mixHash than the base, so it needs its
- * OWN committed measurement; one base file can't gate a localized render (it would
- * always read as a stale mixHash, with no supported way to commit a per-locale one).
+ * - With a limiter, a member reaches `target` by applying `gain = target - inputI`
+ *   and the limiter shaves any overshoot (`grDb`) down to the ceiling.
+ * - Without a limiter (`limiter: null`), the gain is peak-CLAMPED (the legacy
+ *   `min(target-inputI, ceiling-inputTp)`), so a peaky member lands below target.
+ * - `shared-target` normalizes every member to one LUFS (the loudest all reach);
+ *   `per-asset` drives each to its own max.
  */
-declare function loudnessPathFor(modulePath: string, locale?: string): string;
-/** Read + validate a committed measurement, or null when none is committed. */
-declare function readLoudness(modulePath: string, locale?: string): LoudnessMeasurement | null;
+declare function planMaster(measures: readonly MemberMeasure[], profile: PublishProfile, opts: {
+  limiter: MasterLimiter | null;
+  consistency: 'shared-target' | 'per-asset';
+}): MasterPlan;
 /**
- * Parse the JSON block ffmpeg's `loudnorm=print_format=json` prints to stderr.
- * It carries `input_i` / `input_tp` / `input_lra` (the measured loudness),
- * alongside the would-be normalization params (which we ignore — we apply our
- * own peak-clamped scalar gain instead).
+ * The `-af` chain that applies a master's gain + (optional) TRUE-peak limiter to a
+ * WAV — the SAME {@link loudnessFilterNodes} the render `filter_complex` applies,
+ * so the `gs master` verify pass measures exactly what a render will produce.
  */
-declare function parseLoudnormJson(stderr: string): {
-  inputI: number;
-  inputTp: number;
-  inputLra: number;
-};
-/**
- * Run ffmpeg's loudnorm measurement pass over a built mix WAV/PCM file and return
- * the measured loudness. This is the quarantined non-deterministic stage — it
- * runs ONLY at measure-time (commit), never during render.
- */
-declare function measureFile(audioPath: string): {
-  inputI: number;
-  inputTp: number;
-  inputLra: number;
-};
-interface MeasureLoudnessOptions {
-  modulePath: string;
-  /** publish profile id; default 'youtube' */
-  profile?: string;
-  /** narration auto-mix toggle (mirrors render); default auto */
-  narration?: 'auto' | 'off';
-  music?: 'auto' | 'off';
-  sfx?: 'auto' | 'off';
-  /**
-   * locale code (0.15 FIX 2). When set, measure the per-locale mix (the localized
-   * narration sibling) and commit `<stem>.<locale>.loudness.json` instead of the
-   * base file. Mirrors `gs render --locale`, so the measured content matches what
-   * a localized render mixes.
-   */
-  locale?: string;
+declare function masterAfChain(gainDb: number, limiter: CommittedLimiter | null): Promise<string>;
+interface MasterMemberResult {
+  readonly id: string;
+  readonly loudnessPath: string;
+  readonly measurement: LoudnessMeasurement;
+  /** measured input LUFS / dBTP. */
+  readonly inputI: number;
+  readonly inputTp: number;
+  /** VERIFIED output LUFS / dBTP (re-measured after gain+limiter). */
+  readonly outI: number;
+  readonly outTp: number;
+  readonly gain: number;
+  readonly grDb: number;
+  /** true when the verified output true-peak exceeded the ceiling (shouldn't happen). */
+  readonly overCeiling: boolean;
 }
-interface MeasureLoudnessResult {
-  measurement: LoudnessMeasurement;
-  loudnessPath: string;
-  /** profile the measurement was taken against */
-  profile: PublishProfile;
-  /** true when the peak clamp bound the gain (advisory: would need a brickwall limiter on an un-normalized profile) */
-  clampBound: boolean;
-  /** an advisory warning string when an un-normalized profile can't reach its target without clipping; else null */
-  warning: string | null;
+interface MasterResult {
+  readonly sharedTarget: number;
+  readonly ceilingDb: number;
+  readonly limiter: boolean;
+  readonly members: readonly MasterMemberResult[];
+  readonly report: string;
+}
+interface MasterCommandOptions {
+  configPath: string;
+  onLog?: (line: string) => void;
 }
 /**
- * Build the final mix to a WAV, run the ffmpeg loudnorm measurement over it, and
- * commit a `<scene>.loudness.json` with the peak-clamped publish gain + a mixHash
- * bound to the mix-input manifests. This is the measure step (commit-time); it is
- * the only place the non-deterministic ebur128/mix-to-PCM stages run.
+ * `gs master <glissade.master.json>` — measure every member, plan the shared
+ * target + limiter, apply+VERIFY per member, and commit `<scene>.loudness.json`
+ * ×N. Reuses `buildMixWav`/`measureFile` (measure) and `resolveScenes` (globs);
+ * writes the existing sidecar shape + the `limiter` block so render composes it as
+ * a mix-only remux under the mixHash preflight.
  */
-declare function measureLoudnessCommand(opts: MeasureLoudnessOptions): Promise<MeasureLoudnessResult>;
+declare function masterCommand(opts: MasterCommandOptions): Promise<MasterResult>;
+/** Validate + normalize a parsed `glissade.master.json` (fail-loud). */
+declare function normalizeMasterConfig(raw: unknown): Required<Pick<MasterConfig, 'members' | 'consistency'>> & {
+  profile: string;
+  limiter: MasterLimiter | null;
+};
 //#endregion
 //#region src/shards.d.ts
 declare class ShardError extends Error {
@@ -634,14 +777,24 @@ interface AudioMixPlan {
   hasEasedGain: boolean;
 }
 /**
- * Append a PURE scalar publish-loudness gain to a mix's `-filter_complex`: the
- * graph's final `[aout]` label is renamed and a `volume=<gain>dB` node feeds the
- * new `[aout]`. This is a single multiply on the FINAL mix node — NOT a second
- * ffmpeg pass — and is bit-deterministic (verified) + golden-hashable. A gain of
- * exactly 0 dB is a no-op (returned unchanged) so an at-target source preserves
- * the prior, un-gained bytes.
+ * The publish-loudness filter nodes: a `volume=<gain>dB` multiply, and — for a
+ * `gs master` measurement — a REAL true-peak limiter (oversample 4× → `alimiter`
+ * at `ceilingDb − guard` → downsample) that actually holds the inter-sample /
+ * true peak under `ceilingDb`. Shared by the render `filter_complex` apply and the
+ * `gs master` verify pass so the committed limiter and the rendered output are the
+ * identical deterministic chain. Empty (a no-op) at 0 dB with no limiter.
  */
-declare function applyMixGainDb(filterComplex: string, gainDb: number): string;
+
+/**
+ * Append the publish-loudness stage to a mix's `-filter_complex`: the graph's
+ * final `[aout]` label is renamed and the {@link loudnessFilterNodes} (gain +,
+ * for a master, the true-peak limiter) feed the new `[aout]`. Bit-deterministic +
+ * golden-hashable. A 0 dB gain with NO limiter is a no-op (returned unchanged) so
+ * an at-target source preserves the prior, un-gained bytes.
+ */
+declare function applyMixGainDb(filterComplex: string, gainDb: number, limiter?: {
+  readonly ceilingDb: number;
+}): string;
 /** Build the FFmpeg mix plan for clips that intersect [0, duration]. */
 declare function planAudioMix(clips: AudioClip[], modulePath: string, duration: number): AudioMixPlan | null;
 //#endregion
@@ -961,4 +1114,4 @@ declare function cacheVerifyCommand(opts: CacheVerifyOptions): Promise<CacheVeri
 /** The @glissade/cli package version (the glissade VERSION for the cache key). */
 declare function glissadeVersion(): string;
 //#endregion
-export { AudioMixError, type AudioMixPlan, type CacheKeyContext, type CacheMode, type CacheVerifyOptions, type CacheVerifyResult, type CaptionProbe, DEFAULT_CACHE_MAX_SIZE, DEFAULT_FPS, DEFAULT_FRAMES, DEFAULT_PROFILE_ID, type DevOptions, type DevServer, type Diagnostic, type DiffOptions, type DiffResult, type EncoderChoice, FfmpegVideoFrameSource, FrameCache, FrameCacheError, type FrameCacheOptions, type ImportCommandResult, type ImportOptions, LOUDNESS_SCHEMA_VERSION, type LintOptions, type LintRule, LocaleArgsError, LoudnessError, type LoudnessMeasurement, MachineExportError, type MachineRenderFlags, type MeasureLoudnessOptions, type MeasureLoudnessResult, type NarrationLintOptions, type NarrationLintResult, NoEncoderError, PUBLISH_PROFILES, type PublishProfile, type RenderOptions, type RenderShardedArgs, type RepinFrame, type RepinOptions, type RepinResult, type RepinStatus, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, repinCommand, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };
+export { AudioMixError, type AudioMixPlan, type CacheKeyContext, type CacheMode, type CacheVerifyOptions, type CacheVerifyResult, type CaptionProbe, type CommittedLimiter, DEFAULT_CACHE_MAX_SIZE, DEFAULT_FPS, DEFAULT_FRAMES, DEFAULT_MAX_GR_DB, DEFAULT_PROFILE_ID, type DevOptions, type DevServer, type Diagnostic, type DiffOptions, type DiffResult, type EncoderChoice, FfmpegVideoFrameSource, FrameCache, FrameCacheError, type FrameCacheOptions, type ImportCommandResult, type ImportOptions, LOUDNESS_SCHEMA_VERSION, type LintOptions, type LintRule, LocaleArgsError, LoudnessError, type LoudnessMeasurement, MachineExportError, type MachineRenderFlags, type MasterConfig, MasterError, type MasterLimiter, type MasterMemberResult, type MasterPlan, type MasterResult, type MeasureLoudnessOptions, type MeasureLoudnessResult, type MemberMeasure, type MemberPlan, type NarrationLintOptions, type NarrationLintResult, NoEncoderError, PUBLISH_PROFILES, type PublishProfile, type RenderOptions, type RenderShardedArgs, type RepinFrame, type RepinOptions, type RepinResult, type RepinStatus, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, masterAfChain, masterCommand, measureFile, measureLoudnessCommand, narrationLintCommand, normalizeMasterConfig, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, planMaster, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, repinCommand, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { a as ffmpegAvailable, d as render, f as renderLocales, i as collectAudioClips, l as parseLocalesList, m as resolveLoudnessGainDb, n as SceneModuleError, o as loadSceneModule, r as buildMixWav, s as localeOutPath, t as LocaleArgsError, u as planFinalAudio } from "./render.js";
 import { t as glissadeVersion } from "./version.js";
 import { a as computeGainDb, d as parseLoudnormJson, f as peakClampBinds, i as PUBLISH_PROFILES, l as measureFile, m as resolveProfile, n as LOUDNESS_SCHEMA_VERSION, o as computeMixHash, p as readLoudness, r as LoudnessError, s as loudnessPathFor, t as DEFAULT_PROFILE_ID, u as measureLoudnessCommand } from "./loudness.js";
+import { i as masterCommand, n as MasterError, o as normalizeMasterConfig, r as masterAfChain, s as planMaster, t as DEFAULT_MAX_GR_DB } from "./master.js";
 import { a as pickEncoder, i as parseEncoderList, n as availableEncoders, t as NoEncoderError } from "./encoders.js";
 import { a as splitFrameRange, n as renderSharded, r as sceneHasGpuNodes, t as ShardError } from "./shards.js";
 import { n as VideoProbeError, r as probeVideo, t as FfmpegVideoFrameSource } from "./videoSource.js";
@@ -13,4 +14,4 @@ import { n as DEFAULT_FRAMES, r as repinCommand, t as DEFAULT_FPS } from "./repi
 import { a as fixDiff, c as lintNarration, n as lintTimingPathFor, o as formatTable, r as narrationLintCommand, s as hasErrors, t as buildCaptionProbe } from "./narrationLintCommand.js";
 import { a as clearFrameCache, c as parseCacheMaxSize, i as capsId, l as probeEntryHeader, n as FrameCache, o as frameCacheKey, r as FrameCacheError, t as DEFAULT_CACHE_MAX_SIZE } from "./frameCache.js";
 import { t as cacheVerifyCommand } from "./cacheVerify.js";
-export { AudioMixError, DEFAULT_CACHE_MAX_SIZE, DEFAULT_FPS, DEFAULT_FRAMES, DEFAULT_PROFILE_ID, FfmpegVideoFrameSource, FrameCache, FrameCacheError, LOUDNESS_SCHEMA_VERSION, LocaleArgsError, LoudnessError, MachineExportError, NoEncoderError, PUBLISH_PROFILES, SceneModuleError, ShardError, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, repinCommand, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };
+export { AudioMixError, DEFAULT_CACHE_MAX_SIZE, DEFAULT_FPS, DEFAULT_FRAMES, DEFAULT_MAX_GR_DB, DEFAULT_PROFILE_ID, FfmpegVideoFrameSource, FrameCache, FrameCacheError, LOUDNESS_SCHEMA_VERSION, LocaleArgsError, LoudnessError, MachineExportError, MasterError, NoEncoderError, PUBLISH_PROFILES, SceneModuleError, ShardError, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, localeOutPath, loudnessPathFor, masterAfChain, masterCommand, measureFile, measureLoudnessCommand, narrationLintCommand, normalizeMasterConfig, parseCacheMaxSize, parseEncoderList, parseLocalesList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, planMaster, probeEntryHeader, probeVideo, readLoudness, render, renderLocales, renderSharded, repinCommand, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };

package/dist/master.js

@@ -0,0 +1,249 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { l as measureFile, m as resolveProfile, o as computeMixHash, s as loudnessPathFor } from "./loudness.js";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+//#region src/master.ts
+/**
+* `gs master` (0.39) — SERIES-level loudness: measure every member together, pick
+* the loudest shared LUFS target the whole set can hit under a shared true-peak
+* ceiling, and SHIP the deferred brickwall true-peak limiter so a peaky short
+* recovers headroom instead of landing 2 LU low. Writes a committed
+* `<scene>.loudness.json` per member (the existing sidecar shape + an optional
+* `limiter` block), so it composes with the render-time mixHash preflight and
+* applies as a mix-only remux (never a re-render).
+*
+* This module holds the PURE planning core (no ffmpeg / no I/O): given each
+* member's measured `inputI`/`inputTp`, it computes the shared target + per-member
+* gain + predicted gain-reduction. The ffmpeg measure/apply shell + the command
+* orchestration live alongside; this core is unit-tested without a toolchain.
+*
+* The limiter knot: a brickwall limiter is non-linear, so it can't be a render-
+* time scalar. It's applied in the AUDIO MIX filter graph (volume→alimiter) from
+* params COMMITTED in the measurement — mixHash covers the mix INPUTS (unchanged),
+* so the committed gain+limiter still validate and render remuxes audio-only.
+*/
+var master_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_MAX_GR_DB: () => 6,
+	MasterError: () => MasterError,
+	masterAfChain: () => masterAfChain,
+	masterCommand: () => masterCommand,
+	normalizeMasterConfig: () => normalizeMasterConfig,
+	planMaster: () => planMaster
+});
+var MasterError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "MasterError";
+	}
+};
+/** How much gain-reduction the limiter may apply to buy headroom (dB). */
+const DEFAULT_MAX_GR_DB = 6;
+/** The loudest LUFS this member can reach under the ceiling given the GR budget. */
+function maxReachable(m, ceilingDb, maxGrDb, profileTarget) {
+	return Math.min(profileTarget, m.inputI + (ceilingDb - m.inputTp) + maxGrDb);
+}
+/**
+* Plan a master pass. Pure: measured members → shared target + per-member gains.
+*
+* - With a limiter, a member reaches `target` by applying `gain = target - inputI`
+*   and the limiter shaves any overshoot (`grDb`) down to the ceiling.
+* - Without a limiter (`limiter: null`), the gain is peak-CLAMPED (the legacy
+*   `min(target-inputI, ceiling-inputTp)`), so a peaky member lands below target.
+* - `shared-target` normalizes every member to one LUFS (the loudest all reach);
+*   `per-asset` drives each to its own max.
+*/
+function planMaster(measures, profile, opts) {
+	if (measures.length === 0) throw new MasterError("planMaster needs at least one measured member");
+	const ceilingDb = opts.limiter?.ceilingDb ?? profile.truePeakDb;
+	const maxGrDb = opts.limiter ? opts.limiter.maxGrDb ?? 6 : 0;
+	const profileTarget = profile.targetLufs;
+	const reach = measures.map((m) => maxReachable(m, ceilingDb, maxGrDb, profileTarget));
+	const sharedTarget = Math.min(profileTarget, ...reach);
+	const members = measures.map((m, i) => {
+		const target = opts.consistency === "shared-target" ? sharedTarget : reach[i];
+		const rawGain = target - m.inputI;
+		const gain = opts.limiter ? rawGain : Math.min(rawGain, ceilingDb - m.inputTp);
+		const postGainTp = m.inputTp + gain;
+		const grDb = opts.limiter ? Math.max(0, postGainTp - ceilingDb) : 0;
+		const predOutTp = Math.min(ceilingDb, postGainTp);
+		const reachable = opts.limiter ? grDb <= maxGrDb + 1e-6 : rawGain <= ceilingDb - m.inputTp + 1e-6;
+		return {
+			...m,
+			target,
+			gain: round2(gain),
+			grDb: round2(grDb),
+			predOutTp: round2(predOutTp),
+			reachable
+		};
+	});
+	return {
+		sharedTarget: round2(sharedTarget),
+		profileTarget,
+		ceilingDb,
+		limiter: opts.limiter !== null,
+		maxGrDb,
+		members
+	};
+}
+function round2(n) {
+	return Math.round(n * 100) / 100;
+}
+/**
+* The `-af` chain that applies a master's gain + (optional) TRUE-peak limiter to a
+* WAV — the SAME {@link loudnessFilterNodes} the render `filter_complex` applies,
+* so the `gs master` verify pass measures exactly what a render will produce.
+*/
+async function masterAfChain(gainDb, limiter) {
+	const { loudnessFilterNodes } = await import("./audioMix.js").then((n) => n.i);
+	const nodes = loudnessFilterNodes(gainDb, limiter ?? void 0);
+	return nodes.length ? nodes.join(",") : "anull";
+}
+/**
+* `gs master <glissade.master.json>` — measure every member, plan the shared
+* target + limiter, apply+VERIFY per member, and commit `<scene>.loudness.json`
+* ×N. Reuses `buildMixWav`/`measureFile` (measure) and `resolveScenes` (globs);
+* writes the existing sidecar shape + the `limiter` block so render composes it as
+* a mix-only remux under the mixHash preflight.
+*/
+async function masterCommand(opts) {
+	const cfg = normalizeMasterConfig(JSON.parse(readFileSync(opts.configPath, "utf8")));
+	const profile = resolveProfile(cfg.profile);
+	const log = opts.onLog ?? (() => {});
+	const { resolveScenes } = await import("./build.js").then((n) => n.t);
+	const { buildMixWav, collectMixAudioInputs } = await import("./render.js").then((n) => n.p);
+	const members = resolveScenes(cfg.members, process.cwd());
+	if (members.length === 0) throw new MasterError(`master: no scenes matched members ${JSON.stringify(cfg.members)}`);
+	const ceilingDb = cfg.limiter?.ceilingDb ?? profile.truePeakDb;
+	const committedLimiter = cfg.limiter ? {
+		mode: "truepeak",
+		ceilingDb
+	} : null;
+	const tmp = mkdtempSync(join(tmpdir(), "glissade-master-"));
+	try {
+		const measured = [];
+		for (const modulePath of members) {
+			const wavPath = join(tmp, `${measured.length}.wav`);
+			if (!await buildMixWav({
+				modulePath,
+				narration: "auto",
+				music: "auto",
+				sfx: "auto"
+			}, wavPath)) {
+				log(`  skip ${modulePath} (no audio to master)`);
+				continue;
+			}
+			const m = measureFile(wavPath);
+			measured.push({
+				id: modulePath,
+				modulePath,
+				wavPath,
+				...m
+			});
+		}
+		if (measured.length === 0) throw new MasterError("master: no members had any audio to measure");
+		const plan = planMaster(measured.map((m) => ({
+			id: m.id,
+			inputI: m.inputI,
+			inputTp: m.inputTp
+		})), profile, {
+			limiter: cfg.limiter,
+			consistency: cfg.consistency
+		});
+		log(`shared target ${plan.sharedTarget} LUFS, ceiling ${ceilingDb} dBTP${plan.limiter ? "" : " (no limiter — legacy peak-clamp)"}`);
+		const results = [];
+		for (let i = 0; i < measured.length; i++) {
+			const meas = measured[i];
+			const p = plan.members[i];
+			const outWav = join(tmp, `${i}.out.wav`);
+			const af = await masterAfChain(p.gain, committedLimiter);
+			const r = spawnSync("ffmpeg", [
+				"-hide_banner",
+				"-nostats",
+				"-y",
+				"-i",
+				meas.wavPath,
+				"-af",
+				af,
+				"-c:a",
+				"pcm_s16le",
+				"-ar",
+				"48000",
+				outWav
+			], { encoding: "utf8" });
+			if (r.status !== 0) throw new MasterError(`ffmpeg master apply failed for ${meas.id} (exit ${r.status}):\n${(r.stderr ?? "").slice(-800)}`);
+			const out = measureFile(outWav);
+			const extraInputs = await collectMixAudioInputs({
+				modulePath: meas.modulePath,
+				narration: "auto",
+				music: "auto",
+				sfx: "auto"
+			});
+			const measurement = {
+				loudnessVersion: 1,
+				profileId: profile.id,
+				inputI: round2(meas.inputI),
+				inputTp: round2(meas.inputTp),
+				inputLra: round2(meas.inputLra),
+				gain: p.gain,
+				mixHash: computeMixHash(meas.modulePath, extraInputs),
+				...committedLimiter ? { limiter: committedLimiter } : {}
+			};
+			const loudnessPath = loudnessPathFor(meas.modulePath);
+			writeFileSync(loudnessPath, JSON.stringify(measurement, null, 2) + "\n");
+			const overCeiling = round2(out.inputTp) > ceilingDb + .05;
+			results.push({
+				id: meas.id,
+				loudnessPath,
+				measurement,
+				inputI: round2(meas.inputI),
+				inputTp: round2(meas.inputTp),
+				outI: round2(out.inputI),
+				outTp: round2(out.inputTp),
+				gain: p.gain,
+				grDb: p.grDb,
+				overCeiling
+			});
+			log(`  ${short(meas.id)}  in ${round2(meas.inputI)}/${round2(meas.inputTp)}dBTP -> ${p.gain >= 0 ? "+" : ""}${p.gain}dB${p.grDb > 0 ? `,${p.grDb}dB GR` : ""}  out ${round2(out.inputI)}/${round2(out.inputTp)}${overCeiling ? "  ⚠ OVER CEILING" : ""}`);
+		}
+		const report = `gs master: ${results.length} member${results.length === 1 ? "" : "s"} → shared target ${plan.sharedTarget} LUFS / ${ceilingDb} dBTP${plan.limiter ? " (true-peak limiter)" : ""}, wrote <scene>.loudness.json ×${results.length}`;
+		return {
+			sharedTarget: plan.sharedTarget,
+			ceilingDb,
+			limiter: plan.limiter,
+			members: results,
+			report
+		};
+	} finally {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function short(p) {
+	return p.replace(/^.*\//, "").replace(/\.[jt]sx?$/, "");
+}
+/** Validate + normalize a parsed `glissade.master.json` (fail-loud). */
+function normalizeMasterConfig(raw) {
+	if (raw === null || typeof raw !== "object") throw new MasterError("master config must be an object");
+	const c = raw;
+	if (!Array.isArray(c.members) || c.members.length === 0) throw new MasterError("master config needs a non-empty `members` array of scene globs");
+	const consistency = c.consistency ?? "shared-target";
+	if (consistency !== "shared-target" && consistency !== "per-asset") throw new MasterError(`master consistency must be 'shared-target' or 'per-asset' (got '${consistency}')`);
+	let limiter;
+	if (c.limiter === false) limiter = null;
+	else if (c.limiter === void 0) limiter = { mode: "truepeak" };
+	else if (typeof c.limiter === "object" && c.limiter.mode === "truepeak") limiter = c.limiter;
+	else throw new MasterError(`master limiter must be { mode: 'truepeak', ceilingDb?, maxGrDb?, lookaheadMs? } or false`);
+	if (limiter && limiter.maxGrDb !== void 0 && !(limiter.maxGrDb >= 0)) throw new MasterError(`master limiter.maxGrDb must be >= 0 (got ${limiter.maxGrDb})`);
+	return {
+		members: c.members,
+		consistency,
+		profile: c.profile ?? "youtube",
+		limiter
+	};
+}
+//#endregion
+export { master_exports as a, masterCommand as i, MasterError as n, normalizeMasterConfig as o, masterAfChain as r, planMaster as s, DEFAULT_MAX_GR_DB as t };

package/dist/render.js

@@ -784,7 +784,10 @@ async function resolveLoudnessGainDb(opts, timelineClips) {
 		const reRun = hasLocale ? `gs measure-loudness ${opts.modulePath} --locale ${opts.locale}` : `gs measure-loudness ${opts.modulePath}`;
 		throw new Error(`loudness: ${path} is stale — the mix inputs changed since it was measured (committed mixHash ${measurement.mixHash.slice(0, 23)}…, current ${actual.slice(0, 23)}…). Re-run \`${reRun}\` (or pass --loudness off to render without normalization). Note: 0.33 made the mixHash invocation-path-independent — if your mix inputs did NOT change, one re-measure migrates the committed hash.`);
 	}
-	return measurement.gain;
+	return {
+		gainDb: measurement.gain,
+		...measurement.limiter ? { limiter: measurement.limiter } : {}
+	};
 }
 /**
 * Collect audio clips + auto-mixed siblings and plan the FFmpeg audio graph,
@@ -811,9 +814,9 @@ async function planFinalAudio(opts, timelineClips, duration, container) {
 		audioInputs: [],
 		audioArgs: []
 	};
-	const gainDb = await resolveLoudnessGainDb(opts, timelineClips);
-	const filterComplex = gainDb !== null ? applyMixGainDb(mix.filterComplex, gainDb) : mix.filterComplex;
-	if (gainDb !== null) process.stderr.write(`note: applying committed publish loudness gain ${gainDb.toFixed(2)} dB (single-pass scalar)\n`);
+	const loud = await resolveLoudnessGainDb(opts, timelineClips);
+	const filterComplex = loud !== null ? applyMixGainDb(mix.filterComplex, loud.gainDb, loud.limiter) : mix.filterComplex;
+	if (loud !== null) process.stderr.write(`note: applying committed publish loudness gain ${loud.gainDb.toFixed(2)} dB${loud.limiter ? ` + true-peak limiter @ ${loud.limiter.ceilingDb} dBTP` : " (single-pass scalar)"}\n`);
 	const audioEnc = pickEncoder("audio", container);
 	return {
 		audioInputs: mix.inputs.flatMap((p) => ["-i", p]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.38.0",
+  "version": "0.39.0-pre.1",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "engines": {
@@ -28,15 +28,15 @@
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.38.0",
-    "@glissade/core": "0.38.0",
-    "@glissade/interact": "0.38.0",
-    "@glissade/lottie": "0.38.0",
-    "@glissade/narrate": "0.38.0",
-    "@glissade/player": "0.38.0",
-    "@glissade/scene": "0.38.0",
-    "@glissade/sfx": "0.38.0",
-    "@glissade/svg": "0.38.0"
+    "@glissade/backend-skia": "0.39.0-pre.1",
+    "@glissade/core": "0.39.0-pre.1",
+    "@glissade/interact": "0.39.0-pre.1",
+    "@glissade/lottie": "0.39.0-pre.1",
+    "@glissade/narrate": "0.39.0-pre.1",
+    "@glissade/player": "0.39.0-pre.1",
+    "@glissade/scene": "0.39.0-pre.1",
+    "@glissade/sfx": "0.39.0-pre.1",
+    "@glissade/svg": "0.39.0-pre.1"
   },
   "repository": {
     "type": "git",