mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 15:24:19 +00:00
User instruction: "tweak the sfx applying in the way so that it wouldn't
tweak anything for the volume....let them just be as they are...(but it
still need to account for when in the audio actual sound effect starts
and end in order to be able to align, even if colliding into other sfx
or smt...)"
Stance change:
- Volume default → natural catalog-normalized level (no data-volume
attribute emitted, = 1.0). Catalog is loudness-normalized at the file
level, so emitting clips bare lets them ring at the level the catalog
committed to.
- Timing alignment knobs preserved + elevated: data-media-start (skip
dead air at head, = `onsetSec` from `sfx add` analysis) is now the
first-class control. data-start / data-duration / data-media-start
together align the audible attack to the beat frame.
- Multiple SFX may overlap; SFX may stack on VO. The engine has no
auto-ducking — that's by design now, not a hazard to defend against.
- The lone common exception is a "felt, not heard" ambient bed (~0.1
volume) — deliberate texture, not a duck.
- Per-clip nudge (when measured LUFS shows real mismatch) is the only
remaining reason to set data-volume — per-clip override, not per-project
policy.
Files changed:
1. scripts/assemble-index.mjs SFX emit (lines 343-371):
- Was: `const vol = cue.volume != null ? cue.volume : 0.35;`
followed by unconditional `data-volume="${vol}"` emit.
- Now: emit data-volume only when cue.volume is explicitly set; emit
data-media-start when cue.media_start is set. Block comment above
the loop documents the natural-level rationale + the timing-alignment
stance.
2. skills/hyperframes/references/sound-effects.md:
- "The audio contract" section: marked data-volume as Optional;
reordered to put data-media-start before data-volume (timing knob
first, level knob second).
- "Volume hierarchy" → renamed "Volume — default is natural, no
auto-duck." Table reframed as "reference nudge ranges (only if
needed)" instead of defaults. SFX row now reads "0.7-1.0 (default =
natural)."
- "Reading the numbers correctly" item 3: updated to "default is to
omit data-volume" instead of "the volume hierarchy is your baseline."
- Worked examples: removed `data-volume="0.3"` from the basic embed
example; the bed-only example explicitly calls out 0.12 as an
exception that proves the natural-level rule.
3. skills/website-to-hyperframes/references/step-3-storyboard.md SFX
assignment section (lines 286-301):
- Dropped `volume 0.3` / `volume 0.5` from the example list.
- "Volume under narration: keep SFX at 0.2-0.3 under VO" replaced
with "Volume — default natural" + the trust-the-mix prose.
- Added a line emphasizing that timing precision (`data-media-start`)
matters more now that volume defaults to natural.
Sections deliberately kept:
- The "Combining sounds" rule about `data-volume` for stack-clipping
control (genuine audio engineering, not a duck heuristic).
- The accent-the-downbeat data-volume nudge in the "Sequence" pattern
(variation, not ducking).
- All onset/peak/tail/peak-time mechanics — these are the timing
alignment knobs the user explicitly asked to preserve.
Backward-compatible behavior:
- Cues that explicitly set `volume` still get `data-volume` emitted.
- Existing project HTMLs render unchanged — the change affects only how
new assemblies emit SFX.