mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-05 10:14:30 +00:00
Vance IngallsandClaude Opus 5
e3ec48adce
* fix(studio): close the typecheck and fallow gaps wa-18b-reschedule opened useAutomationLanes.ts's write() assumed gesture-scoped coalescing and a preview-only commit that useDomEditAttributeCommits.ts never grew — backported that option support from its own later commit so the two sides of the API agree. The paste path and its tests were missing the box selection's v0/v1 bounds a sibling commit added to AutomationSelection. The FX panel's carve controls still edited the six mechanism numbers (maxCutDb, bands, intelligibilityBias) after carveProfile() collapsed authoring to one Strength knob, so those fields no longer existed on HfCarveSettings; UI now edits strength, and analyseCarveBands is called with carveProfile(strength). Also closes fallow's complexity, dead-code and duplication findings on this PR's diff: extracted automationLaneDragMath.ts (pure group/point-move math) and useAutomationRangeDrag.ts (the marquee-select gesture) out of useAutomationLaneGestures.ts, pulled a couple of render-loop ternaries and a resolver into named functions, dropped an export nothing outside its file used, and shared a step-simplifier between audioCarve's two envelope builders. The edge-stretch vs. box-select priority test in TimelineAutomationLane.test was still pinning the pre-box-select rule (edge wins over a point sitting on it) that a sibling commit deliberately reversed — a point inside the box is now selected content, so grabbing it drags the group instead. Updated the test to the shipped rule instead of the old one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(core): cap the via conic's weight so an edge-clamped via point can't NaN A via point pulled out past the segment (viaX: 5, viaY: -3) clamps to (0.999, 0.001) — exactly on the steady region's edge, where edge - viaX is 0. viaConic divided by that zero to get an infinite weight, and shapeVia turned Infinity into NaN a few steps later (Infinity - Infinity in the quadratic coefficient). NaN reaching setValueCurveAtTime silences the automated parameter for the rest of the render. Capped the weight at 1e6 instead of leaving it unbounded — past that point the arc already reads as touching the via point, so nothing visible is lost. Also hardened shapeVia's existing denominator guard (`<= 0`) to `!(> 0)`, since NaN fails the original comparison and fell through it. Review by Miga (PR #3208). * fix(studio-server): fingerprint the proactive waveform cache key too The route already keys the waveform cache on the asset's size and mtime as well as its path, so a rebuilt-in-place file gets fresh peaks instead of stale ones. generateWaveformCache — the proactive path that runs on upload — still called buildWaveformCacheKey with the path alone, so it wrote to a different key than the route reads from (making the pre-generated cache never found) and kept the exact collision bug this fingerprint exists to fix on its own path. Review by Miga (PR #3211). * style(docs): run oxfmt on the /hyperframes-audio skill docs Table column widths had drifted out of alignment with oxfmt's own rules, failing format:check and blocking the Preflight gate every downstream branch inherits. Whitespace only, no content change. * fix(core): stop \b from missing underscore-separated names, guard clipsOverlap's negative duration \b treats `_` as a word character, so \bbed\b never matched bed_01, music_bed_loop, or theme_song, and \bvo\b/\bvox\b/\btts\b had the same gap — an underscore-separated bed classified as "unknown" and could end up offered as its own carve source. Replaced the short hints with a boundary that actually excludes letters and digits on both sides. clipsOverlap computed end = start + duration without guarding sign, so a negative duration put end before start — an interval that does not describe anything, and one specific case showed it silently dropping a real overlap (a shorter, earlier broken end rejected a clip that genuinely contained the point). Duration clamps to zero instead: a clip cannot un-play time, and a zero-length clip at its start is the sane reading of "duration nobody wrote down as positive." Review by Miga (PR #3212). * fix(studio): widen PropertyPanel's resetModules render timeout again The 20s margin (already once widened for the same reason) is timing out in CI's full-monorepo Test run — the resetModules()+fresh-import render this test needs is uncached and competes with every other package's test suite for the same worker pool, and the same test passes in well under 2s standalone. Went to 45s rather than re-tuning to whatever number happens to clear the current CI load, since that number moves every time CI gains a package. * fix(studio): stop the single-candidate auto-apply carve firing twice Two auto-apply effects both fire when sourceOptions.length === 1: the multi-candidate effect only guards length === 0, so a single candidate passes it too, and the single-candidate effect passes its own guard right after — both compute the same sources list and both call setCarve, so the common case (one narrator, one bed) triggered two decodes, two FFT runs, and two concurrent attribute writes for one decision. The multi-candidate effect now defers to its sibling for exactly one candidate, which already has its own detailed handling for that case. Review by Miga (PR #3213). * feat(core): carve against every voice over a bed, always (#3212) * feat(core): carve against every voice over a bed, always dynamically A bed usually runs under a whole sequence — a narrator, an interview answer, a second presenter — and carving against one of them left the others fighting it. `source` becomes `sources`, and `mixCarveSources` sums every voice onto the BED's clock before anything is measured. That is what keeps one analysis sufficient: the chain is fixed, so there is no per-voice filter to switch between, and bands drawn from all the speech there is with envelopes that rise wherever any of it happens answer the actual question — where and when is speech masking this bed. Summed rather than averaged: two people talking at once mask more than either alone. Audio before the bed starts is dropped rather than folded in at zero, since it plays over nothing and shifting it would put a cut where there is no voice. `dynamic` is gone. A fixed depth thins the bed through every pause, and once both have been heard there is no reason to want it, so every carve follows the speech. Two helpers the panel and the headless script now share instead of each carrying a copy — two definitions of "what does this name suggest" drift, and then the two disagree about which track is the voice: - `classifyAudioName` reads a track's kind from its id and filename together. `unknown` is deliberately common: treating an unrecognised name as "not a voice" would hide the one track somebody needs to pick. - `clipsOverlap` keeps out a voice that never plays while the bed does. An unwritten duration counts as unbounded, not zero — refusing a clip whose length the composition leaves to the media would drop the commonest case there is. Files written before this still load: a single `source` reads as a one-voice list, a stored `dynamic` is ignored, and an absent attribute means the defaults whole. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(core): stop \b from missing underscore-separated names, guard clipsOverlap's negative duration \b treats `_` as a word character, so \bbed\b never matched bed_01, music_bed_loop, or theme_song, and \bvo\b/\bvox\b/\btts\b had the same gap — an underscore-separated bed classified as "unknown" and could end up offered as its own carve source. Replaced the short hints with a boundary that actually excludes letters and digits on both sides. clipsOverlap computed end = start + duration without guarding sign, so a negative duration put end before start — an interval that does not describe anything, and one specific case showed it silently dropping a real overlap (a shorter, earlier broken end rejected a clip that genuinely contained the point). Duration clamps to zero instead: a clip cannot un-play time, and a zero-length clip at its start is the sane reading of "duration nobody wrote down as positive." Review by Miga (PR #3212). --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(studio): port the carve UI off the removed source/dynamic fields #3212 (accidentally squash-merged into this branch instead of main) changed HfCarveSettings from a single `source` + `dynamic` toggle to a `sources` list with dynamic mode removed outright — the multi-voice UI consumer that goes with that shape lands in the very next PR, so this branch was left with a type that no longer matched its own code. Minimal port, not the multi-voice redesign that PR does properly: the "Listen to" picker and analyse() treat sources[0] as the one voice this UI still understands, and every dynamic-mode branch (the automated envelope lanes, the toggle, the checkbox) is gone along with the field — a carve is now always the static value the analysis computes, matching what the type change made permanent. Test suite trimmed the same way: the automation-lane and toggle tests covered behavior that no longer exists. * chore: fix markdown formatting --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
217 lines
13 KiB
Markdown
217 lines
13 KiB
Markdown
# Presets, jobs and one-knob profiles
|
||
|
||
Everything here is a shortcut to a chain you could have built by hand. A preset
|
||
writes ordinary nodes tagged with `fromPreset`, a job writes one ordinary node
|
||
with a name, and a profile is one control over several parameters of one effect.
|
||
Nothing is opaque: open any of them and you find effects from
|
||
[`fx-registry.md`](./fx-registry.md) with their parameters showing.
|
||
|
||
Reach for one when it names the problem you actually have. Build by hand when
|
||
none of them does — a preset applied because it was nearby is worse than three
|
||
deliberate nodes.
|
||
|
||
---
|
||
|
||
## Diagnose first: what to listen for, and what fixes it
|
||
|
||
Work from the symptom, not from the effect list. Most bad audio is one or two of
|
||
these, and the fix is usually a job rather than a whole preset.
|
||
|
||
| It sounds like | Where it lives | Reach for |
|
||
| --------------------------------------------- | -------------- | ------------------------------------------------------------ |
|
||
| Hum, rumble, traffic, footsteps, handling | 20–80 Hz | `rumble-cut` preset, or a `highpass` at 80 Hz |
|
||
| Boomy, chesty, too close to the mic | 80–250 Hz | **Tame Boominess** job (200 Hz, −4 dB) |
|
||
| Muffled, like it is behind cardboard | 250–600 Hz | **Reduce Mud** job (250 Hz, −3 dB) |
|
||
| Boxy, like a small room | ~400 Hz | **Reduce Boxiness** job (400 Hz, −3 dB) |
|
||
| Words hard to make out, sits behind the music | 2–5 kHz | **Add Clarity** job (3 kHz, +2.5 dB), or carve the bed |
|
||
| Harsh, brittle, tiring over a whole listen | 3–5 kHz | **Soften Harshness** job (3.2 kHz, −3 dB) |
|
||
| Sibilant — `s` sounds spitting | 5–10 kHz | Nothing shipped does this properly; see "Not covered" below |
|
||
| Dull, closed-in, lifeless | 10–20 kHz | `highshelf` lift, or `voice-broadcast` which includes one |
|
||
| Some words much louder than others | not a band | **Evenness** profile on a `compressor`, or `levellingResult` |
|
||
| Room tone audible between sentences | not a band | `room-gate` preset (**Tightness** profile) |
|
||
| Peaks clipping or spiking | not a band | `limiter` last in the chain — every voice preset ends in one |
|
||
| Voice and music fighting each other | 1–3 kHz mostly | **Voiceover carve**, not an EQ on either track |
|
||
| Dry, stuck to the speaker, recorded nowhere | not a band | `room-tight` or `room-natural` |
|
||
|
||
**The band vocabulary** these map onto — the same names the rack shows:
|
||
|
||
| Range | Name | What lives there |
|
||
| -------------- | -------- | ---------------------------- |
|
||
| 20–80 Hz | Rumble | traffic, footsteps, handling |
|
||
| 80–250 Hz | Weight | chest, body, warmth |
|
||
| 250–600 Hz | Mud | boxy, muffled, cardboard |
|
||
| 600–2000 Hz | Middle | the body of a voice |
|
||
| 2000–5000 Hz | Presence | consonants, intelligibility |
|
||
| 5000–10000 Hz | Edge | sibilance, harshness |
|
||
| 10000–20000 Hz | Air | sparkle, openness |
|
||
|
||
### Order of operations
|
||
|
||
Diagnose in this order, because each step changes what the next one hears:
|
||
|
||
1. **Subtract before you add.** Cut rumble and mud first. A voice that sounds
|
||
dull often has too much low-mid, not too little top — lifting the top of a
|
||
muddy voice makes it muddy _and_ harsh.
|
||
2. **Level after you filter.** A compressor reacts to whatever is loudest, and
|
||
a rumble it can no longer see is a rumble it stops chasing.
|
||
3. **Relationships after level.** Carve a bed against a voice once the voice
|
||
itself is settled, or the analysis measures a problem you are about to fix.
|
||
4. **Character, then ceiling.** Saturation and space go late; a `limiter` goes
|
||
last, where it can actually act as a ceiling. Anything after it is not
|
||
bounded by it.
|
||
|
||
---
|
||
|
||
## Presets
|
||
|
||
Four families, listed in full below. Apply one and it **appends** — stacking a character preset
|
||
onto an already-cleaned voice is a real thing to want. Re-applying one that is
|
||
already present replaces its own nodes in place, because position in the chain
|
||
is signal order.
|
||
|
||
### Voice — make a real voice sound like its better self
|
||
|
||
| Preset | Answers | Chain |
|
||
| ----------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
|
||
| `voice-clean` | "My voice sounds amateur" | Remove Rumble → Reduce Mud → Even Out Loudness → Add Clarity → Peak Ceiling |
|
||
| `voice-broadcast` | "I want it to sound like radio" | Remove Rumble → Reduce Boxiness → Even Out Loudness → Add Clarity → Add Air → Warmth → Peak Ceiling |
|
||
| `voice-warm` | "I want it intimate and close" | Remove Rumble → Add Weight → Even Out Loudness → Add Clarity → Peak Ceiling |
|
||
|
||
`voice-clean` is the default answer to "fix this voiceover". The other two are
|
||
the same idea pushed in one direction: broadcast is denser and more forward,
|
||
warm has body added rather than cut.
|
||
|
||
### Repair — one problem, one node
|
||
|
||
| Preset | Answers | Does |
|
||
| ------------ | --------------------------------------- | --------------------------------------------------------------------------- |
|
||
| `rumble-cut` | "There's a hum or thump underneath" | High-pass under the voice |
|
||
| `room-gate` | "I can hear the room between sentences" | Closes the pauses. **Does not remove noise** — room tone under speech stays |
|
||
| `boom-tame` | "My voice sounds boomy" | Cuts the chestiness of a too-close mic |
|
||
| `harsh-tame` | "It's harsh and tiring to listen to" | Rounds a brittle upper-mid, broad and always-on |
|
||
|
||
### Character — deliberate, not corrective
|
||
|
||
`telephone`, `radio-am`, `megaphone`, `lofi-tape`, `pa-system` (Tannoy),
|
||
`intercom`, `doofus-worble`.
|
||
|
||
These are costumes. Each is a band restriction plus a resonance plus its own kind
|
||
of dirt, and they are tuned to be distinguishable from one another — measured on
|
||
a log sweep, no two sit closer than the signal itself. Do not stack two.
|
||
|
||
### Space — put it somewhere
|
||
|
||
`room-tight` (presence without wash), `room-natural` (recorded somewhere rather
|
||
than nowhere), `hall` (far back and big), `slap-echo` (one quick repeat),
|
||
`dub-throw` (repeats trailing well behind).
|
||
|
||
Use these on whatever should sit _behind_ something else, and keep the wet amount
|
||
lower than sounds right in isolation — a tail occupies the room a voice needs.
|
||
|
||
### The whole preset as one control
|
||
|
||
A preset's nodes are wrapped in a wet/dry blend, so `presetAmount` (0..1) fades
|
||
the entire thing in or out, and `fx.preset.<id>` is an automation target that
|
||
ramps it over time. This is the only way to automate a preset as a unit: its
|
||
nodes share no common parameter, and worklet effects (compressor, limiter, gate,
|
||
bitcrush) expose no automatable parameters at all.
|
||
|
||
---
|
||
|
||
## Jobs — the range IS the module
|
||
|
||
Five named peaking filters with the frequency already chosen. Picking the job is
|
||
picking the range, which is what makes a single "how much" knob honest.
|
||
|
||
| Job | Symptom | Sets |
|
||
| ---------------- | ------------------------------------ | --------------------- |
|
||
| Tame Boominess | Too much chest — it booms | 200 Hz, −4 dB, Q 1.4 |
|
||
| Reduce Mud | Muffled, like it is behind cardboard | 250 Hz, −3 dB, Q 1.2 |
|
||
| Reduce Boxiness | Sounds like a small room, or a box | 400 Hz, −3 dB, Q 1.4 |
|
||
| Add Clarity | Words are hard to make out | 3 kHz, +2.5 dB, Q 1 |
|
||
| Soften Harshness | Harsh and tiring to listen to | 3.2 kHz, −3 dB, Q 1.6 |
|
||
|
||
Each is an ordinary `peaking` node underneath — the frequency is a starting
|
||
point, not a cage. Prefer a job to a bare `peaking` when one matches: it arrives
|
||
already aimed, and the rack names it for the work rather than the mechanism.
|
||
|
||
Writing one by hand, **carry the name in `label`** — `{"type":"peaking","id":"n2",
|
||
"label":"Reduce Mud","params":{"frequency":250,"gain":-3,"q":1.2}}`. The
|
||
parameters alone are not the job. A chain with three unlabelled `peaking` nodes
|
||
shows the author three identical rows, which is the exact problem jobs exist to
|
||
dissolve.
|
||
|
||
**Every job also ships inside a preset, at identical settings** — that is where
|
||
the five came from. `boom-tame` _is_ Tame Boominess; `harsh-tame` _is_ Soften
|
||
Harshness; `voice-clean` contains Reduce Mud and Add Clarity; `voice-broadcast`
|
||
contains Reduce Boxiness. So check what a preset already contains before adding
|
||
a job on top of it, or the cut lands twice — `voice-clean` plus a Reduce Mud job
|
||
is −6 dB at 250 Hz where −3 was meant. The rack shows the contained nodes by
|
||
name once the preset is expanded, which is the fastest way to see it.
|
||
|
||
---
|
||
|
||
## One-knob profiles
|
||
|
||
Five effects have no single parameter that can honestly be their face — a
|
||
compressor's threshold means nothing without its ratio. They get a derived
|
||
control instead, 0..1, which sets several parameters together.
|
||
|
||
| Effect | Knob | 0 → 1 | Sets |
|
||
| ------------ | --------- | ------------------------------------------ | ----------------------------------------- |
|
||
| `compressor` | Evenness | Barely touched → Very even, quite squashed | threshold, ratio, attack, release, makeup |
|
||
| `gate` | Tightness | Only true silence → Cuts quiet words too | threshold, range, release |
|
||
| `saturate` | Warmth | Just a sheen → Openly distorted | threshold, output |
|
||
| `reverb` | Space | A small tight room → A big open hall | size, wet, dry |
|
||
| `bitcrush` | Crush | Slightly gritty → Destroyed | bits, samples, mix |
|
||
|
||
**Evenness, Warmth and Space are level-matched** — the make-up gain, the output
|
||
trim and the dry leg move with the drive, so turning the knob up does not also
|
||
turn the track up or down. Those figures were solved by measurement, not chosen:
|
||
the compressor originally left a track 2.5 dB _quieter_ at full evenness, and
|
||
saturation's trim ran the wrong way entirely.
|
||
|
||
Tightness and Crush are not level-matched, because neither has a trim to move —
|
||
a gate only removes, and Crush's `mix` is the effect itself rather than a
|
||
make-up.
|
||
|
||
The chain stores the mechanism values, not the knob position; the knob is read
|
||
back by inverting the curve. So hand-editing a parameter under a profile is
|
||
allowed and will simply move the knob.
|
||
|
||
---
|
||
|
||
## Measuring scripts, not presets
|
||
|
||
Two things measure the audio before they act, so they cannot be a fixed chain:
|
||
|
||
- **Voiceover carve** — analyses the voice and cuts the bed in the bands the
|
||
voice occupies. The answer to "the music is fighting the voice". See the
|
||
carve section in `SKILL.md`.
|
||
- **Even Out Levels** (`levellingResult`) — measures the track's own speaking
|
||
windows and writes a gain envelope. Its target is the 80th percentile of that
|
||
track, not an absolute level, so an already-even track is left alone. Use it
|
||
over a compressor when the problem is passages drifting over a whole take
|
||
rather than word-to-word dynamics.
|
||
|
||
---
|
||
|
||
## Not covered by anything shipped
|
||
|
||
Name the gap rather than reaching for the nearest preset and calling it the
|
||
thing — but then **ship the honest fallback anyway**, with its cost stated. An
|
||
author who asked for a fix and got only an explanation has been told something
|
||
true and handed nothing. Say what it is, say what it costs, apply it.
|
||
|
||
- **De-essing.** `harsh-tame` is a broad always-on cut centred a band too low,
|
||
not a de-esser. A real one needs a detector faster than the analysis hop
|
||
available here. _Fallback:_ a narrow `peaking` cut in the Edge band — sweep
|
||
5–9 kHz to find where this voice actually spits, Q 3–4, −3 to −5 dB. It is
|
||
always on, so it costs a little air on every word; that trade is usually worth
|
||
it and is the author's to reject.
|
||
- **Tone matching** one track to another. _Fallback:_ the Tone EQ by hand, which
|
||
is predictable in a way a match curve derived from two takes would not be.
|
||
- **Noise removal.** `room-gate` closes the gaps; the noise under speech is
|
||
untouched. There is no fallback for hiss beneath the words — a source with
|
||
audible hiss needs a better source, and saying so is the whole answer.
|