[WaterrrForever]

What

One subsection in the audio effects reference, "Tracks add up; nothing averages them": the render sums every track at unity, data-volume scales only its own track, nothing limits the sum, and PRODUCER_AUDIO_GAIN multiplies the sum once before the master bus.

Why

While testing viral-clone in HyperFrames Desktop, an agent read amix=…${useNormalize ? ":normalize=0" : ""} in the built chunk as "the render averages its tracks." It then spent two full renders chasing loudness, and its skill text (heygen-com/hyperframes-internal#4136) now tells agents the mix sits 8.6 dB under source with a dozen tracks. The reference documented data-volume and the master bus but never said how tracks combine, so nothing contradicted the guess.

The guess is wrong. useNormalize is true by default and means add normalize=0. The fallback, for ffmpeg builds without the option, pads every input and multiplies by N. No code change is needed.

Related work

Refs heygen-com/hyperframes-internal#4136. That skill note should be corrected there.

How

Measured, not assumed:

• Desktop's renderer: HyperFrames Canary bundles hyperframes 0.8.158 and ffmpeg 8.1.2. That ffmpeg lists normalize on amix, so it takes the unity path.
• The project from that run (12 tracks): voice 0.8, music 0.22, ten SFX. I ran processCompositionAudio on main over it. In a voice+music-only window (18–31 s), the render reads −18.1 dB mean. A reference built by hand (0.8·voice + 0.22·music, amix normalize=0) also reads −18.1 dB. The "8.6 dB under" was the authored data-volume values, not the mixer.
• The existing guard catches the bug: I dropped :normalize=0 from mixAudioTracks (the averaging bug). Three tests in audioMixer.grouping.test.ts then failed, among them "keeps every track at its authored level regardless of how many there are" (expected +6.02 dB, got 0). After restoring the line, 16/16 pass. So no new test is added.

Test plan

• Unit tests added/updated (not needed: the existing real-ffmpeg level test fails on the regression, shown above)
• Manual testing performed (12-track mix measured against a hand-built unity sum)
• Documentation updated
• Comments follow CONTRIBUTING.md "Comments" (no code comments touched)

node scripts/check-docs-snippet-motion.mjs passes. I did not check the anchor #the-master-bus-data-fx-chain-on-the-composition-root in a Mintlify build.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 15, 2026, 12:33 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[miguel-heygen]

Thanks for this. It fills a real gap: the reference explained data-volume and the master bus but never said how tracks combine.

I checked each claim against the engine and they hold: the mixer runs amix with normalize=0 (and the fallback for older ffmpeg pads every input and multiplies by the track count, so it is also a unity sum), groups mix the same way, PRODUCER_AUDIO_GAIN defaults to 1 and is applied once to the sum before the master chain, and nothing in the default path limits the sum. Both anchors resolve in the preview build.

One small suggestion, not blocking: the last bullet ("compare the export against its source scaled by the data-volume you wrote") only holds when that track has no effect chain of its own, no automation or fade in the window, no master-bus chain, and the default master gain. Naming those conditions would stop someone checking a compressed voice, or a mix with a master limiter, from reading the difference as a mixer bug.

Verdict: APPROVE
Reasoning: Docs-only change whose every claim matches the mixer code at this head, with all required checks green; the one suggestion is a wording refinement.