@glissade/cli 0.15.0-pre.0 → 0.15.0-pre.1

package/dist/cli.js

@@ -73,7 +73,7 @@ const USAGE = `usage:
   gs narration-lint <scene-module|script.narration.timing.json> [--json] [--fix] [--max-cps <n>]
   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>]
+  gs measure-loudness <scene-module> [--profile <youtube|shorts|podcast|broadcast|ebu>] [--locale <code>]
   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)
 
@@ -147,6 +147,9 @@ measure-loudness options (the explicit publish-loudness measure step; commits *.
   --profile <id>   youtube (default) | shorts (both -14 LUFS) | podcast (-16) | broadcast/ebu (-23); all cap at -1 dBTP
                    measures the final mix (ebur128) and commits a deterministic peak-clamped gain; render applies it
                    as a pure scalar. Needs ffmpeg. Brickwall limiter deferred — peaky un-normalized profiles warn.
+  --locale <code>  (0.15) measure the per-locale mix (the localized narration sibling) and commit
+                   <stem>.<locale>.loudness.json. A localized 'gs render --locale <code>' REQUIRES this per-locale
+                   file (the base measurement can't gate the per-locale mix). No --locale measures the base mix.
 
 narrate options (the explicit TTS prepare step; render itself stays offline):
   --provider <id>  fake | espeak | piper | kokoro | openai (default: the script's provider, else espeak)
@@ -294,12 +297,14 @@ async function main() {
 	if (command === "measure-loudness") {
 		const { measureLoudnessCommand } = await import("./loudness.js").then((n) => n.c);
 		try {
+			const mlLocale = flags.get("locale");
 			const result = await measureLoudnessCommand({
 				modulePath,
 				...flags.has("profile") ? { profile: flags.get("profile") } : {},
 				...flags.get("narration") === "off" ? { narration: "off" } : {},
 				...flags.get("music") === "off" ? { music: "off" } : {},
-				...flags.get("sfx") === "off" ? { sfx: "off" } : {}
+				...flags.get("sfx") === "off" ? { sfx: "off" } : {},
+				...mlLocale !== void 0 && mlLocale !== "" ? { locale: mlLocale } : {}
 			});
 			const m = result.measurement;
 			process.stderr.write(`gs measure-loudness: profile '${m.profileId}' — in ${m.inputI} LUFS / ${m.inputTp} dBTP → gain ${m.gain >= 0 ? "+" : ""}${m.gain} dB (out ~${(m.inputI + m.gain).toFixed(2)} LUFS / ~${(m.inputTp + m.gain).toFixed(2)} dBTP) → ${result.loudnessPath}\n`);

package/dist/index.d.ts

@@ -269,6 +269,11 @@ declare function localeOutPath(out: string, locale: string, format?: 'png-seq'):
  * `UnknownLocaleError` (naming the bad locale) from inside `render()`, aborting
  * the whole fan-out — locales already rendered keep their artifacts, but the
  * process exits non-zero so a missing-asset locale is never silently skipped.
+ *
+ * 0.15 FIX 2: a per-locale loudness dead-end (no `<stem>.<locale>.loudness.json`
+ * committed) also aborts the batch — but a bare error mid-fan-out reads like a
+ * generic crash, so each per-locale failure is wrapped to NAME the failing locale.
+ * It still fails loudly (never swallowed): the wrapped message stays actionable.
  */
 declare function renderLocales(opts: Omit<RenderOptions, 'locale'>, locales: readonly string[]): Promise<{
   locale: string;
@@ -326,8 +331,16 @@ declare function collectAudioClips(opts: Pick<RenderOptions, 'modulePath' | 'nar
  * `.wav`/music stem invalidates the measurement here too (the §5.3 stale-gain
  * gate). `timelineClips` defaults to the scene's compiled timeline audio when
  * omitted, so a bare `{ modulePath }` call still gates correctly.
+ *
+ * 0.15 FIX 2 (localized loudness): a localized render (`--locale zh`) mixes the
+ * per-locale narration → a DIFFERENT mixHash than the base measurement. So when a
+ * locale is set it reads the per-locale file `<stem>.<locale>.loudness.json` FIRST.
+ * When that per-locale file is MISSING it throws an ACTIONABLE per-locale error
+ * (naming the file + the `gs measure-loudness … --locale` to run) instead of the
+ * 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'>, timelineClips?: AudioClip[]): Promise<number | null>;
+declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' | 'loudness' | 'narration' | 'music' | 'sfx' | 'locale'>, timelineClips?: AudioClip[]): Promise<number | null>;
 /**
  * Collect audio clips + auto-mixed siblings and plan the FFmpeg audio graph,
  * returning the `-i`/`-filter_complex`/`-map` argument fragments. Shared by the
@@ -353,7 +366,7 @@ declare function planFinalAudio(opts: RenderOptions, timelineClips: AudioClip[],
  * gain — measurement is of the un-gained mix), so the measured content is exactly
  * what render will later mix. Returns false when the scene has no audio.
  */
-declare function buildMixWav(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx'>, wavOut: string): Promise<boolean>;
+declare function buildMixWav(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx' | 'locale'>, wavOut: string): Promise<boolean>;
 //#endregion
 //#region src/loudness.d.ts
 /**
@@ -462,10 +475,18 @@ declare function peakClampBinds(profile: PublishProfile, inputI: number, inputTp
  * hash. The scene module path itself is excluded.
  */
 declare function computeMixHash(modulePath: string, extraInputs?: readonly string[]): string;
-/** `<module>.loudness.json` for a scene module. */
-declare function loudnessPathFor(modulePath: 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): LoudnessMeasurement | null;
+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),
@@ -495,6 +516,13 @@ interface MeasureLoudnessOptions {
   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;

package/dist/loudness.js

@@ -146,13 +146,22 @@ function computeMixHash(modulePath, extraInputs = []) {
 	}
 	return `sha256:${h.digest("hex")}`;
 }
-/** `<module>.loudness.json` for a scene module. */
-function loudnessPathFor(modulePath) {
-	return modulePath.replace(/\.[jt]sx?$/, "") + ".loudness.json";
+/**
+* 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).
+*/
+function loudnessPathFor(modulePath, locale) {
+	const stem = modulePath.replace(/\.[jt]sx?$/, "");
+	return locale !== void 0 && locale !== "" ? `${stem}.${locale}.loudness.json` : `${stem}.loudness.json`;
 }
 /** Read + validate a committed measurement, or null when none is committed. */
-function readLoudness(modulePath) {
-	const path = loudnessPathFor(modulePath);
+function readLoudness(modulePath, locale) {
+	const path = loudnessPathFor(modulePath, locale);
 	if (!existsSync(path)) return null;
 	const raw = JSON.parse(readFileSync(path, "utf8"));
 	if (raw.loudnessVersion !== 1) throw new LoudnessError(`${path}: unsupported loudnessVersion ${String(raw.loudnessVersion)} (expected 1); re-run gs measure-loudness`);
@@ -222,7 +231,8 @@ async function measureLoudnessCommand(opts) {
 			modulePath: opts.modulePath,
 			narration: opts.narration ?? "auto",
 			music: opts.music ?? "auto",
-			sfx: opts.sfx ?? "auto"
+			sfx: opts.sfx ?? "auto",
+			...opts.locale !== void 0 && opts.locale !== "" ? { locale: opts.locale } : {}
 		}, wavPath)) throw new LoudnessError(`${opts.modulePath} has no audio to measure (no timeline audio and no narration/music/sfx manifests)`);
 		const { inputI, inputTp, inputLra } = measureFile(wavPath);
 		const gain = computeGainDb(profile, inputI, inputTp);
@@ -232,7 +242,8 @@ async function measureLoudnessCommand(opts) {
 			modulePath: opts.modulePath,
 			narration: opts.narration ?? "auto",
 			music: opts.music ?? "auto",
-			sfx: opts.sfx ?? "auto"
+			sfx: opts.sfx ?? "auto",
+			...opts.locale !== void 0 && opts.locale !== "" ? { locale: opts.locale } : {}
 		});
 		const mixHash = computeMixHash(opts.modulePath, extraInputs);
 		const measurement = {
@@ -244,7 +255,7 @@ async function measureLoudnessCommand(opts) {
 			gain: floorGain2(gain),
 			mixHash
 		};
-		const loudnessPath = loudnessPathFor(opts.modulePath);
+		const loudnessPath = loudnessPathFor(opts.modulePath, opts.locale);
 		writeFileSync(loudnessPath, JSON.stringify(measurement, null, 2) + "\n");
 		return {
 			measurement,

package/dist/render.js

@@ -162,15 +162,27 @@ function localeOutPath(out, locale, format) {
 * `UnknownLocaleError` (naming the bad locale) from inside `render()`, aborting
 * the whole fan-out — locales already rendered keep their artifacts, but the
 * process exits non-zero so a missing-asset locale is never silently skipped.
+*
+* 0.15 FIX 2: a per-locale loudness dead-end (no `<stem>.<locale>.loudness.json`
+* committed) also aborts the batch — but a bare error mid-fan-out reads like a
+* generic crash, so each per-locale failure is wrapped to NAME the failing locale.
+* It still fails loudly (never swallowed): the wrapped message stays actionable.
 */
 async function renderLocales(opts, locales) {
 	const results = [];
 	for (const locale of locales) {
-		const result = await render({
-			...opts,
-			out: localeOutPath(opts.out, locale, opts.format),
-			locale
-		});
+		let result;
+		try {
+			result = await render({
+				...opts,
+				out: localeOutPath(opts.out, locale, opts.format),
+				locale
+			});
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			if (err instanceof Error && msg.includes(`'${locale}'`)) throw err;
+			throw new Error(`--locales: locale '${locale}' failed — ${msg}`, { cause: err });
+		}
 		results.push({
 			locale,
 			result
@@ -542,7 +554,7 @@ async function collectMixAudioInputs(opts, timelineClips) {
 	return preservingMessageTable(async () => {
 		let tl = timelineClips;
 		if (tl === void 0) try {
-			const mod = await loadSceneModule(opts.modulePath);
+			const mod = await loadSceneModule(opts.modulePath, opts.locale);
 			const { compileTimeline } = await import("@glissade/core");
 			tl = [...compileTimeline(mod.timeline).audio];
 		} catch {
@@ -571,15 +583,34 @@ async function collectMixAudioInputs(opts, timelineClips) {
 * `.wav`/music stem invalidates the measurement here too (the §5.3 stale-gain
 * gate). `timelineClips` defaults to the scene's compiled timeline audio when
 * omitted, so a bare `{ modulePath }` call still gates correctly.
+*
+* 0.15 FIX 2 (localized loudness): a localized render (`--locale zh`) mixes the
+* per-locale narration → a DIFFERENT mixHash than the base measurement. So when a
+* locale is set it reads the per-locale file `<stem>.<locale>.loudness.json` FIRST.
+* When that per-locale file is MISSING it throws an ACTIONABLE per-locale error
+* (naming the file + the `gs measure-loudness … --locale` to run) instead of the
+* 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.
 */
 async function resolveLoudnessGainDb(opts, timelineClips) {
 	if ((opts.loudness ?? "auto") === "off") return null;
 	const { readLoudness, computeMixHash, loudnessPathFor } = await import("./loudness.js").then((n) => n.c);
-	const measurement = readLoudness(opts.modulePath);
-	if (!measurement) return null;
+	const hasLocale = opts.locale !== void 0 && opts.locale !== "";
+	const measurement = readLoudness(opts.modulePath, opts.locale);
+	if (!measurement) {
+		if (hasLocale && readLoudness(opts.modulePath) !== null) {
+			const perLocale = loudnessPathFor(opts.modulePath, opts.locale);
+			throw new Error(`loudness: no ${perLocale} for locale '${opts.locale}' — a localized render mixes the per-locale narration, which has a different loudness than the base mix, so it needs its OWN measurement. Run \`gs measure-loudness ${opts.modulePath} --locale ${opts.locale}\` to commit it (or pass --loudness off to render this locale without normalization).`);
+		}
+		return null;
+	}
 	const extraInputs = await collectMixAudioInputs(opts, timelineClips);
 	const actual = computeMixHash(opts.modulePath, extraInputs);
-	if (actual !== measurement.mixHash) throw new Error(`loudness: ${loudnessPathFor(opts.modulePath)} is stale — the mix inputs changed since it was measured (committed mixHash ${measurement.mixHash.slice(0, 23)}…, current ${actual.slice(0, 23)}…). Re-run \`gs measure-loudness ${opts.modulePath}\` (or pass --loudness off to render without normalization).`);
+	if (actual !== measurement.mixHash) {
+		const path = loudnessPathFor(opts.modulePath, opts.locale);
+		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).`);
+	}
 	return measurement.gain;
 }
 /**
@@ -636,7 +667,7 @@ async function buildMixWav(opts, wavOut) {
 	if (!ffmpegAvailable()) throw new Error("gs measure-loudness needs FFmpeg on PATH and none was found.");
 	const { preservingMessageTable } = await import("@glissade/core/i18n");
 	return preservingMessageTable(async () => {
-		const mod = await loadSceneModule(opts.modulePath);
+		const mod = await loadSceneModule(opts.modulePath, opts.locale);
 		const scene = mod.createScene();
 		const { compileTimeline } = await import("@glissade/core");
 		const compiled = compileTimeline(mod.timeline);

package/package.json

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