fix(skill): BGM under-VO volume 0.8 → 0.5 (match background-music.md)

assemble-index.mjs's `BGM_VOLUME = hasAnyVoice ? "0.8" : "0.9"` set the
under-VO ducked volume to 0.8 — well outside the 0.4–0.6 band that
references/background-music.md documents as "background music under VO"
(line 26), and triple the ~0.45 value the same doc uses in its example
storyboard "Music direction:" snippet (line 90).

The lived consequence on the heygen TTS run was a BGM bed that materially
competed with narration. The user's recent loudnorm check confirmed VO
was being clipped by music in the 0.8-bed renders.

Fix: 0.5 (mid of 0.4–0.6, top of the "simplest hold-low" 0.4–0.5 band
from background-music.md:37). Pure-music value (0.9) untouched — it
already sits at the top of the 0.7–0.9 doc range, which is correct per
the "or it disappears into the encoder noise floor" guidance (line 31).

Added a block comment above the constant linking back to the doc so
future readers don't re-derive (or re-break) the band.

Agents wanting per-section ducking should still use the documented
pattern-2 approach (embed same music id twice at different volumes);
this single-bed BGM emit is the floor, not the ceiling.
This commit is contained in:
ukimsanov
2026-06-11 19:48:15 -07:00
parent eb76972551
commit 64ed41de25
@@ -183,11 +183,18 @@ const hasGlobalVoice =
existsSync(join(hyperframesDir, globalVoicePath));
// ---------- BGM volume: duck under narration if any voice is present ----------
// Values track references/background-music.md: under-VO sits at 0.4–0.6 (the
// example storyboard line uses ~0.45 — see background-music.md:90), pure-music
// videos sit near full at 0.7–0.9 to clear the encoder noise floor (line 31).
// 0.5 is the mid of the simplest under-VO hold-low band; 0.9 is the top of the
// pure-music band. Agents wanting per-section ducking embed the same id twice
// at different volumes (pattern 2 in background-music.md) — the assembler's
// single-bed BGM emit is the floor, not the ceiling.
const hasPerSceneVoice = playOrder.some(
({ scene }) => scene.voicePath && existsSync(join(hyperframesDir, scene.voicePath)),
);
const hasAnyVoice = hasGlobalVoice || (voiceMode === "per-scene" && hasPerSceneVoice);
const BGM_VOLUME = hasAnyVoice ? "0.8" : "0.9";
const BGM_VOLUME = hasAnyVoice ? "0.5" : "0.9";
// ---------- build <body> elements in track order ----------
const body = [];