Skip to content

fix(cli): preserve ducking gain when music starts later - #5318

Open
user-github-me wants to merge 5 commits into
heygen-com:mainfrom
user-github-me:fix/duck-lane-clip-origin
Open

user-github-me wants to merge 5 commits into
heygen-com:mainfrom
user-github-me:fix/duck-lane-clip-origin

Conversation

@user-github-me

@user-github-me user-github-me commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

What

Make the existing audio-duck tool preserve its composition-time gain when the background music starts during or after narration.

Why

--composition reads the background audio's data-start. Subtracting that start from each ramp and clamping negative times independently replays earlier narration at the music's beginning. For speech at 1–3s and music starting at 4s, the generated lane dips despite there being no overlapping speech. Music beginning halfway through a release also gets a new downward attack instead of continuing the release.

Related work

The audio-duck tool was introduced in ac0153cb3; #4230 moved its engine into CLI source while retaining the standalone copy. #5271 fixed empty-transcript placement before lane generation. This correction addresses the existing tool's clip-origin conversion. Closed #3657 proposed a separate core ducking API; no new API is added here. Current open PRs contain no competing duck-lane correction.

How

Build the envelope in composition time first, interpolate its value at the music's start, then retain and rebase only the points after that start. This preserves the remaining duration of a ramp and discards narration that has already finished. Keep the standalone skill and CLI module identical.

Test plan

  • Six regressions fail on current main. Self-contained point/timing assertions cover starts before an attack, during the attack, during speech, at/during release, after narration, and between two speech spans.
  • All 58 ducking, cut-list, token, capability and source-parity tests pass. All 58 core automation/scheduler tests pass.
  • The dependency-free skills job runs all 100 skills test files from a clean export: 883 pass, two skip. Both standalone import-boundary checks pass. The initial CI failure came from a test importing core in the dependency-free skills job; the follow-up replaces that import with explicit expected points and times. Production code is unchanged by the follow-up.
  • Standalone and built audio-duck commands produce the correct lane for five clip placements, verified through the shared automation sampler.
  • Chrome 152's actual OfflineAudioContext and shared native AudioParam scheduler confirm the corrected gain. At 0.1s into music that starts after narration, main produces 0.30 and fixed produces the authored 0.60.
  • Six full CLI renders at 64×64, 10fps, 7s verify release continuation and removal of the unnecessary post-narration dip. In the latter fixture, main falls to 28% of steady gain and fixed stays at steady gain. The before-speech control has identical decoded PCM. All fixture lint and browser checks pass.
  • Fresh full workspace build, CLI rebuild/typecheck, root lint, formatting, test reachability and normal commit hooks pass. Fallow reports no introduced issues.
  • Skill manifest/source parity and comment citation/share checks pass.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant