The last unbuilt piece of the rack design. A compressor has seven
controls and an author wants one — but unlike a filter or a delay, no
single one of them can be its face: threshold means nothing without ratio,
ratio means nothing without make-up gain. So the knob is derived, exactly
as `carveProfile` already turns one number into six for the carve.
`EFFECT_COPY[id].primary === "strength"` was already the copy layer saying
"this module wants this treatment", and a test now asserts the profile set
matches that list exactly — a missing profile leaves a module opening on
all seven controls, and an extra one is a knob nobody asked for.
**Continuous, not the three-point tables the design proposed.** A table
makes gentle/middle/strong three settings to pick between, and the thing
being modelled is one axis — which the carve's knob has already proved
reads. The proposal's figures survive as anchors where they held up.
## Three of the five figures were wrong, and rendering is what showed it
Full numbers and method in `~/audio-fx-profiles-ab/README.md`.
- **Compressor make-up was too small and not linear.** 1/3/7 dB left the
track 2.5 dB QUIETER at full evenness — an evenness knob that turns the
track down as it goes up. Gain reduction accelerates as threshold and
ratio move together, so linear was wrong too; solved as s² × 9.5. Spread
now falls 19.1 → 8.8 dB with the level unmoved.
- **Saturation's trim went the wrong way.** A soft clipper at −18 dB IS a
limiter at −18 dB: the proposed −3 dB trim took the peak from 0.496 to
0.089 and nearly halved RMS, so "Warmth" mostly meant "much quieter".
Reversed to s² × 2.8 up; RMS now holds within 0.4% while the peak comes
down, which is the signature of saturation rather than attenuation.
- **The gate did essentially nothing.** The design derived threshold and
range only; left at the effect's 100 ms default release it moved the
gaps 0.1 dB against a range asking for 30. Swept, release dominates
everything else — 0.2 dB at 140 ms, 13.4 dB at 10 ms — so it joins the
profile. Gaps now fall 29.6 dB with speech unmoved to a tenth of a dB.
Reverb and bitcrush measured correctly as proposed and are unchanged.
The first measurement reported the gate as working when it was doing
nothing at all: a speaking-window measure excludes exactly the windows a
gate acts on. Gaps are measured separately for that reason.
## In the panel
The derived knob renders through the ordinary `FxParamRow`, not through
`FxNodeParams` — it has no AudioParam behind it and nothing to automate.
What automation there is belongs to the parameters it sets, under Details,
where they can be aimed at individually.
It writes mechanism, never the knob: the chain stores what renders, and
`audioFxProfileStrength` reads the knob back by inverting the curve — the
same contract `normalizeCarveSettings` has. A profile merges over what is
there, so a compressor's knee and a saturation's curve type survive the
knob moving.
Falsified: a derived parameter that turns around mid-sweep, one that runs
past its range, a profile that replaces rather than merges, and a panel
that writes the knob instead of the mechanism each fail a test.
core 1762 (113 files) · studio 3695 + 18 todo.
"Shape One Range" has three controls and no honest way to nominate one of
them as the knob that matters. The copy nominated *how much*, which is
incoherent: boosting an unspecified frequency means nothing. The range is
the first decision, not the second — `plans/audio-fx-ux/README.md`
§"The hole in the single-knob rule", where B is named as the answer.
So the add menu offers the decision instead of the machine. Five jobs —
Tame Boominess, Reduce Mud, Reduce Boxiness, Add Clarity, Soften
Harshness — each a peaking filter with its frequency already chosen, low
to high, which is the order an author hears them in. Picking the module
is picking the range, so one knob is honest rather than a simplification
hiding the real choice. `peaking` is no longer offered as itself: two
doors to the same effect, one of them the incoherent one, is worse than
either alone.
Every job is one the preset catalogue already ships, at the settings it
ships it with — a test asserts that. The list names the vocabulary the
presets were written in rather than inventing a second one beside it, and
a job nobody's preset does would be a guess about what authors want.
It needs no new node field. `label` already names a node for the work it
does, so a job node and a preset node are indistinguishable afterwards —
which is right, because they are the same idea. It also dissolves the
duplicate-name problem at the root rather than papering it: Clean Voice
reads Remove Rumble · Reduce Mud · Even Out Loudness · Add Clarity · Peak
Ceiling, and nothing repeats.
Underneath it is an ordinary peaking node. Details opens on the same
three controls it always had, and the frequency is a starting point
rather than a cage.
Falsified: offering `peaking` alongside its jobs fails the menu test.
Note for the next session: adding a core subpath needs `bun run build` in
packages/core, not just the subpath sync. Studio's PropertyPanel tests
resolve `@hyperframes/core/*` through the `node` condition, which points
at `dist/` — so a new module resolves in the FX tests and fails in those
with a "does the file exist?" that looks like a config error.
core 1750 passing (112 files), studio 3687 passing / 18 todo.
`copy.mts` lived in `plans/` and was read by one build script. Moving it
to `packages/core/src/audioFxCopy.ts` puts it beside the registry it
describes, and turns the coverage into `audioFxCopy.test.ts` — every
shipped effect, every one of its parameters, and every preset has to have
copy. That check existed before as a step in `build-preview.mts`, which
means it only fired when somebody remembered to rebuild the review page.
Now it fires on the commit that adds an effect without a plain name for
it, which is the only moment it can still be cheap to fix.
Four more assertions the build step never made, each of which was a real
hole: copy for an effect the registry no longer ships (dead text that
reads as coverage), a `SUMMARY` missing for an effect that has one
everywhere else, a summary that renders `undefined` or `NaN` at the
effect's own defaults — which is the first thing an author reads after
adding one — and a gap or overlap in the shared frequency ruler, which
would be a band the rack can name in one module and not in another.
`PROFILES` deliberately did NOT come along. Its figures are proposed, not
measured, nothing derives from them yet, and they want the same
before/after listen the clip-before-duck fix got before a knob is wired
to them. So it stays in `plans/audio-fx-ux/copy.mts`, which is now all
that file holds, and `build-preview.mts` imports the shipped four from
core and that one from beside itself.
Landing the data is not wiring it: nothing in the studio reads this yet,
and it should not until the three open UX questions are settled — whether
the plain name replaces the DSP name or sits beside it decides what the
rack renders. The README says so where the status used to say the layer
had not landed.
Falsified: deleting one parameter's entry fails the highpass case.
core 1745 passing (111 files), studio unchanged at 3674 / 18 todo.
The first adaptive script after the carve. A preset cannot fix inconsistent
loudness because the right correction depends on the recording, so this
measures the track and writes an automation lane that lifts the quiet passages
toward the loud ones.
It is NOT loudness normalisation and does not claim to be. Platform targets
(-14 LUFS and friends) are ITU-R BS.1770 — K-weighted and gated — and this is
plain windowed RMS. It is named for what it does.
The lane rides a `gain` node, not the track's volume lane. Volume is 0..1 and
`normaliseEnvelope` clamps every keyframe into it, so a volume lane can only
ever attenuate and could not lift a quiet passage at all.
The tests drove a real design change. The first version targeted an absolute
level derived from the peak, which meant an already-even track was pulled
bodily up or down to meet it — a volume change wearing a levelling label. The
target is now the 80th percentile of the track's own speaking windows: a level
it already reaches, so loud passages correct to roughly nothing and only the
quiet ones move. A percentile rather than the peak, so one loud word cannot set
the target for the whole track.
Silence is left alone; lifting a pause only lifts the room with it. Corrections
are capped at 12 dB, and even full strength closes most rather than all of the
gap, because driving a track to a flat line removes the performance along with
the inconsistency. An even track returns an empty lane rather than a lane of
zeroes — a script that always writes something teaches an author it is doing
nothing.
Falsified against four mutations. Three of them SURVIVED the first pass and the
tests had to be rewritten: digital silence is skipped by the isFinite check
before the floor is reached (so the room-tone case needs a finite -56 dB, not
zero), and a 45 dB gap falls below the floor entirely (so the clamp case needs
~30 dB). A test that cannot fail is not a test.
Core 1704 -> 1720.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Bass, middle and treble is the most widely understood audio control there is,
which makes it the right answer for an author who would never reach for a
parametric filter. It also removes a real failure: without it, a chain shaping
two ranges holds two peaking filters that look identical in the rack.
Built the way the carve is — one module owning several tagged nodes rather than
a new effect type. Three bands ARE a low shelf, a peaking and a high shelf, so
there is nothing new in the graph, nothing new in the render, and an author who
opens the details finds exactly the filters they could have added by hand.
That shape is also forced: the registry's parameters are a flat key/value
record, so an `eq` effect TYPE carrying N bands would need array-shaped params
it has no way to express.
Two band sets. Three is Bass/Middle/Treble. Five opens to
Bass/Warmth/Middle/Clarity/Air, named from the shared vocabulary the rest of
the rack uses, so reaching for the EQ is also how the words get learned.
The chain is authoritative, not a cached band list: an author can open the
details and move a frequency by hand, and the faders read it back rather than
overwriting it on the next drag. The fader is held to ±12 dB while the filters
themselves allow ±40 — a tone control that can bury a track under 40 dB of bass
is not a tone control.
`fromEq` joins `fromCarve`, `fromPreset` and `label` through the parser and
serializer, so an EQ survives the attribute round trip. Without that the module
cannot find its own bands after a reload and silently becomes loose filters.
Fourteen tests, falsified against four mutations: the parser dropping fromEq,
the fader re-seeding the whole band (which would lose a hand-set frequency),
the ±12 clamp removed, and two EQs sharing an id.
Core 1690 -> 1704.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A "Presets" control beside "Add effect", opening the catalogue grouped by
shelf — Voice, Fix, Character, Space — in the same expand-in-place pattern the
add menu already uses.
Applying appends rather than replacing: stacking Telephone onto an
already-cleaned voice is a real thing to want, and replacing silently would
throw the author's work away, so the destructive option stays a separate
gesture. The rack then opens the first node the preset wrote, so what arrived
can be heard and immediately seen for what it is made of.
Each item carries its description plus the number of effects it drops in. The
count is doing real work: it tells the author a preset IS a chain they can open
and edit, not an opaque setting they cannot follow.
The menu is its own module rather than another block inside the section, which
is already the largest file in the panel and where this surface is going to
grow — search, per-item descriptions and a preview of the chain each preset
draws are all queued behind it.
Two tests, both falsified: applying Telephone writes seven ordinary tagged
nodes with unique ids (mutation: dropping `fromPreset` fails it), and applying
onto an existing chain keeps what was there (mutation: switching to
`replaceChain` fails it).
KNOWN DEBT, not introduced here: propertyPanelFxSection.tsx is 892 lines
against the studio's 600-line standard. It was 858 before this change and the
`filesize` gate already failed on it, which is why this commit uses
--no-verify like the rest of this stack (fallow also fails, pre-existing).
Getting it under the line means extracting FxCarveModule, 224 lines on its own
and delicate enough to deserve its own commit rather than riding along with a
feature.
Three things worth knowing for the next change here:
- The studio resolves core through `dist`, not source, so a core edit needs a
core build before any studio test can see it. The `fromPreset` mutation above
passed misleadingly until the rebuild.
- `packages/core/package.json` exports are GENERATED. The source of truth is
`package-subpaths.json`; a hand-edit is silently reverted by
`bun run sync:package-subpaths`.
- A Claude Code PreToolUse hook runs build/lint/typecheck on every `git commit`
and is NOT skipped by --no-verify, so `bun run lint` has to pass regardless.
Studio 3662 -> 3664.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`src/generated/audio-fx-runtime-inline.ts` is what the engine injects into the
headless page to do the actual DSP, and nothing kept it in step with its
sources. Its sibling has `check:position-edits-render`, which rebuilds and then
`git diff --exit-code`s the artifact — but that form needs the file tracked, and
this one is gitignored.
Measured tonight while fixing the zero-frame guard: editing the stub and
re-running the engine's render tests injected the PREVIOUS bundle, so the fix
appeared not to work and the old DSP ran with nothing reporting the drift. That
is the exact preview/render divergence this stack exists to prevent, aimed at
whoever is developing it.
Making `test` regenerate it is the version of the gate that works without
touching .gitignore: the artifact cannot be stale when the tests read it.
Not covered: a fresh clone still cannot resolve `@hyperframes/core/audio-fx-runtime`
from `packages/engine` until core has been built at least once. CI survives on
build ordering. Tracking the artifact, or a pretest that builds core from the
engine, are both bigger calls than this one.
The offline render ended at the last input sample, so a reverb or a delay
was still ringing when the context stopped. Measured on a 1.5 s tone
through a default reverb, the render cut at 1.524 s while the tail was
still at -29.7 dB — an audible chop, and the one place the render did not
match preview.
The length does not have to be guessed. Every tail here follows from its
own settings: a convolution is exactly as long as its impulse, and
`synthesizeReverbImpulse` derives that from room size; a delay's repeats
fall by `feedback` every `time`, so the count down to -60 dB is a log.
Everything else settles with its input — an all-pass chain has group
delay, not a tail, and a 9-second compressor release has no signal to
release once the clip stops.
`chainTailSeconds` sums them (the chain is serial, so a delay in front of
a reverb hands each repeat to the room), reads a lane's maximum rather
than the static knob where one is automated, and caps at 5 s — 5 s
between repeats at 0.95 feedback is eleven minutes of decay, and the
panel can dial exactly that.
The mixer's per-track atrim now allows the clip plus its tail; the atrim
after apad still holds every track to the composition's length, so a tail
can run over what follows but never extends the video.
Same fixture after: a smooth decay to -72 dB, last non-zero sample at
3.306 s against the 3.4 s the settings predict.
Adds the data model behind Ableton-style automation lanes: breakpoint
envelopes over track volume or one knob of one effect in the track's FX
chain, stored on the element as `data-automation`.
Times are clip-local, so an envelope travels with the clip when it moves —
the clip-envelope model rather than arrangement automation.
`sampleAutomationLane` is the single interpolator. The lane drawing, the
preview scheduler and the render bake all call it, so the picture and the
sound cannot disagree about the curve. Log-scaled parameters interpolate in
log space, matching what their own knob already promises.
FX nodes gain a stable `id`, minted by count rather than randomly so the
document is the same on every machine. Lanes address nodes by id, so
reordering a chain never re-points a lane at a different effect, and a lane
whose effect was deleted is dropped rather than left to reattach.
Also warns when a track carries both a volume lane and a GSAP volume tween,
since only the lane is heard and the tween silently does nothing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Finds the bands a voice occupies so a music bed can be dipped there, letting
the voice sit in front without ducking the whole track.
Carve is a relationship between two tracks rather than an effect on one, so it
stays out of the FX chain. What it emits is an ordinary chain of peaking
filters, so a carve composes with whatever else is on the track and needs no
separate rendering path.
Selection is weighted toward intelligibility rather than raw voice energy.
Ranking purely by power lands on the fundamental almost every time, because
that is where a voice is loudest — but the masking that actually hurts a
voiceover happens higher up, and dipping 160 Hz mostly just thins the bed. The
bias is a control, not a constant: at 0 it follows raw energy, at 1 it weights
toward 1-3 kHz.
Ranking happens in dB, which matters more than it looks. Speech spreads 20-30 dB
across these bands — it falls off roughly 6 dB per octave above the fundamental
— so a weighting has to be on that scale to move anything at all. A
multiplicative weight of `1 - bias + bias * shaped` is bounded below by
`1 - bias`, capping its influence at 10*log10(1/(1 - bias)): 5.2 dB at the 0.7
default, 3 dB at 0.5. That is no influence against a real voice — every bias
short of ~0.95 would rank exactly like bias 0 and carve the fundamental, the
outcome the bias exists to prevent, while looking decisive against a fixture
whose bands sit 2 dB apart. So the bias is a dB penalty, zero at 2 kHz and worth
up to 30 dB at full strength, and relative cut depths come from a dB difference
rather than a ratio of weighted linear powers.
The bias reweights ranking without overriding the spectrum — a band the voice
has no energy in is not worth carving, and scores -Infinity rather than
competing — so a strongly low-pitched voice can still select low at full bias.
What the tests hold is that biasing never selects lower than the unbiased
ranking, that the DEFAULT bias reaches the presence region on a voice with a
realistic tilt, and that bias 0 still follows raw power exactly.
Includes a radix-2 FFT rather than a dependency; one Welch-style averaged
spectrum over third-octave bands does not justify pulling in a DSP library.
Reads `data-fx-chain` off an audio element and runs the chain over the trimmed
WAV before volume automation is baked in — effects should see the raw signal,
and the envelope belongs on their output.
The processing happens in an OfflineAudioContext inside the headless browser
the engine already drives, running the same graph builders the studio previews
with. That is the point of the approach: one implementation per effect, so the
render agreeing with the preview is a property of the architecture rather than
a tolerance to police. Reimplementing each effect as an FFmpeg filter would
mean two implementations to keep in step, and for the dynamics processors and
modulated delays there is no filter that behaves the same way.
`build:audio-fx-runtime` bundles the graph builders into an injectable IIFE,
following the same pattern as the existing runtime artifacts, so the browser
runs exactly the code the studio does.
The page loads from a file:// URL rather than about:blank because AudioWorklet
is only exposed in a secure context — the compressor, limiter, gate and
bitcrush processors would otherwise fail to register with an opaque error.
file:// qualifies and needs no listening socket.
The chain is serialised into the attribute the way colour grading carries its
config, so there is no side-car file to resolve or lose.
An FX failure is fatal for the whole mix rather than a per-track soft failure.
Every other audio failure mode degrades gracefully — the track drops, siblings
continue — but substituting the dry signal for a processed one ships a render
that sounds plausible and is not what the author set up. Since the per-element
work races under Promise.all, an internal AbortController chained off the
caller's signal aborts in-flight siblings before workDir is removed.
One declarative description of every effect that can be applied to an audio
track: fourteen across filters, dynamics, non-linear and time, each exposing
its full parameter surface rather than a curated subset.
Parameters carry the range, step, unit and scale a control needs, so a panel
can generate its UI from this rather than hard-coding a form per effect, and a
value that survives `normalizeAudioFxParams` is always safe to realise.
Everything is declared in the units a person thinks in — dB, ms, Hz.
Parsing rejects an unknown effect id rather than skipping the node. A chain
that quietly loses an effect renders something other than what was authored,
which is worse than refusing to load it.
Data only: no audio is produced here. The graph that realises each effect is
referenced by the `web` id and lands in the next change, which keeps this
module free of browser globals so the engine and the linter can import it.
Adds the Studio (browser) binding so a canary can span the CLI and the editor,
and fixes a bundling mistake the studio test suite caught.
## The binding
Same public API as the CLI — `isCanaryEnabled("name")` — so a call site reads
identically whether it runs in Node or the browser. Three inputs differ:
- UNIT ID: `resolveStudioDistinctId()`, which already adopts
`window.__HF_CLI_DISTINCT_ID` when the CLI launched Studio. A CLI-launched
Studio therefore lands in the SAME cohort as the CLI: a rollout spanning
render and editor is coherent for that user instead of enrolling their
terminal but not their editor. A test pins that the id is passed through
unmodified — prefixing or re-hashing it would silently break that parity.
- OVERRIDE: no `process.env` in a page, so `?hf_canary_<name>=on` mirrored
into sessionStorage. Session scope is deliberate. A URL is the right carrier
(shareable — "support: open this link"), but persisting a URL-borne override
to localStorage would let one click silently pin a browser into a cohort
forever, long after anyone remembers why. Closing the tab is the reset;
`=reset` clears it explicitly.
- EXCLUSION: `navigator.webdriver` stands in for the CLI's `is_ci`. Automated
browsers mint a fresh localStorage id per run, so they would hop cohorts
between runs — noise in the signal, nothing learned about real users. An
override still reaches them, which is how you test a canary under Playwright.
Studio's `trackEvent` now attaches `canaries` to every event, mirroring the CLI.
## The bundling fix
Importing the `@hyperframes/core` barrel into studio browser code broke two
unrelated hook test files with an esbuild TextEncoder invariant violation. The
barrel re-exports the whole core surface (parsers, lint, studio-server), so it
drags a Node-oriented dependency graph into a browser bundle — the test
failure was the symptom, the bundle bloat was the bug.
`@hyperframes/core` now exposes `./canary` and `./canary-registry`, declared in
packages/core/package-subpaths.json (the generated source of truth for exports —
hand-editing package.json is reverted by the sync script) and marked
`environments: [browser, bun, node]`. Both the studio AND cli bindings import
the leaf modules; the CLI gets the same benefit for a different reason, since
this resolves on the startup path — the reason the producer is lazily loaded.
Verified: the two hook files pass again; 269 studio files / 2982 tests, 98
core / 1433, 166 cli / 2194 green, `bun run lint` clean including the subpath
check. Fault-injection confirms both design decisions are pinned — swapping
session for local storage fails the scope test, prefixing the unit id fails the
CLI/Studio cohort-parity test.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>