Commit Graph
911 Commits
Author SHA1 Message Date
Vance Ingalls 12a67ab82e feat: one knob for the five effects that cannot honestly have one
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.
2026-08-10 15:39:03 -07:00
Vance Ingalls 13f574f3e6 feat: the shared frequency ruler, so the vocabulary gets taught
`BANDS` has named the ranges since the copy layer landed — rumble,
weight, mud, middle, presence, edge, air — and nothing showed them. The
rack spoke entirely in Hz, which mean nothing to somebody who has not
been taught them, and the words that would teach them sat unread in core.

Every spectral module now shows where it acts on one ruler. Two things at
once, deliberately: the bar says where this module works relative to
everything else, and the caption names the range and what lives there.
A bar alone is decoration; a caption alone does not teach the shape.

Log-spaced, because hearing is. Rumble is 20–80 Hz — three tenths of one
percent of the range linearly and about a fifth of it by ear — so laid
out linearly the bottom six bands collapse into a sliver and the ruler
teaches nothing. A test asserts the bottom segment is over a tenth of the
bar, which a linear layout fails.

Segments outside what the module can reach are dimmed rather than hidden:
a filter that only works in the bottom three bands should not look like
it could move anywhere, and it should still be legible against the whole
range.

`audioBandAt` clamps past both ends rather than returning nothing — 15 Hz
is still rumble to anybody who can hear it, and the alternative is a
filter parked at the edge of its range having no name at all. Boundaries
belong to the band they open, or a filter at exactly 250 Hz reads as
Weight while the ruler beside it highlights Mud.

Nothing under an effect with no range to place: there is nothing spectral
about a limiter, and a bar under one would be a decoration claiming to be
information.

core 1754 passing (112 files), studio 3690 passing / 18 todo.
2026-08-10 15:39:01 -07:00
Vance Ingalls 8281023170 feat: offer the job, not the machine — the range IS the module
"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.
2026-08-10 15:39:00 -07:00
Vance Ingalls aa53c6d8bc feat(core): land the plain-language layer, and test that it covers the rack
`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.
2026-08-10 15:38:57 -07:00
Vance Ingalls 601d30e569 fix(core): unwire an LFO when its effect is disposed
The §4c item here was "four hand-rolled wet/dry shells whose dispose
lists have already drifted". Reading them, the drift is one specific
thing and it is a leak, not an untidiness: the chorus and the phaser
stopped their LFO and left it out of the nodes they disconnect. So every
chain rebuild that dropped a modulated effect left a modulator still
wired to the delay or the allpass bank it had been driving. Nothing
audible came of it — the shell around it was disconnected — but the nodes
stayed reachable, and a session of edits to a modulated track piled them
up. Same shape as the worklet leak fixed earlier on this stack.

`stopLfo` becomes `retireLfo` and does both halves, which is the whole
fix. The consolidation the item also asks for is not here: the four
shells are wired differently enough (a feedback loop, a modulated delay,
six allpass stages between two trims, a convolver) that one factory over
them would need a config surface bigger than the four dispose lines it
replaces. The leak was the part with a defect behind it.

Also folds the two artifact build scripts together — 50 lines each,
differing in five names. That one is a genuine copy, and the copy is
where a divergence would hide: whichever stopped being edited would go on
producing a subtly different artifact with nothing to say so. Output is
byte-identical, which `check:position-edits-render` proves by diffing the
tracked artifact.

Falsified: dropping the `disconnect` fails the new test.

core 1726 passing (110 files), engine services 736 passing / 3 skipped.
2026-08-10 15:38:57 -07:00
Vance Ingalls 1b93359330 fix(core): give the chorus and phaser LFOs a phase
`lfo.start()` with no argument puts an OscillatorNode at phase zero at
*attach* time. Offline that is clip-relative — the graph is built at ctx
time 0 and the source starts at 0 — but preview rebuilds the graph
whenever the shape changes, and a seek or a scrub does the same. So a
chorus attached 3.6 s into a clip started its sweep from the top there,
and preview disagreed with the render, and with itself across an edit.

An OscillatorNode's phase cannot be set, and `start(when)` clamps a past
`when` to now. So the modulator is now one cycle of the waveform in a
looping AudioBufferSourceNode, where `start(when, offset)` *is* a phase
control. `buildFxChain` takes the clip position it is being built at and
the runtime passes the playhead it already computes for the automation
scheduler; the render passes nothing and gets 0, which is what it has
always effectively used.

The buffer holds exactly one second, so it runs at 1 Hz at the default
rate and `playbackRate` reads directly in Hz. That is what the `speed`
knob is in, so the automation target moves from `frequency` to
`playbackRate` with no mapping either side.

Two consequences worth naming:

- The phaser's waveform is baked into the buffer, so switching Triangular
  to Sinusoidal is a shape change now — `shapeOf` carries it, the same
  way it already carries a one-pole filter's fixed cutoff. Pushed into
  the running graph it would have been a no-op.
- Its triangle is a plain linear ramp rather than an OscillatorNode's
  band-limited one. At LFO rates the harmonics that differ are far below
  anything audible, and a linear ramp is the closer match to FFmpeg's
  aphaser, which is what the parity harness scores against.

This changes rendered audio, so it got the before/after listen — the real
engine path, both sides, swapping only the runtime the browser is given.
Written up with the numbers in `~/audio-fx-lfo-ab/README.md`: the chorus
differs by 76.5 dB down, the Triangular phaser by 63.7, the Sinusoidal
one by 88.1, and a 440 Hz tone with nothing to mask it by 87.6. Worst
single sample anywhere is 0.00027. Inaudible, as expected — a render
builds at position 0, so only the modulator's generation changed.

The half that motivated the fix cannot be rendered at all, since a render
never builds mid-clip, so it is asserted in tests instead. Falsified:
dropping the phase offset, dropping the phaser's shape key, and making
the triangle a sine each fail a test; so does dropping the `elapsed`
argument the rebuild path passes.

Note for whoever runs this next: `src/generated/audio-fx-runtime-inline.ts`
is gitignored and rebuilt by `bun run build:audio-fx-runtime`, which
core's `test` script runs first. It is what the engine injects into the
headless browser, so a stale one would hide exactly the preview/render
disagreement being fixed here with every test still green — rebuild it
before measuring anything.

core 1725 passing (110 files), engine services 736 passing / 3 skipped.
2026-08-10 15:38:56 -07:00
Vance IngallsandClaude Opus 5 3513d6dab7 feat: wire the leveller into the rack, in front of the ceiling
Two fixes and the wiring that makes the script reachable.

CORRECTNESS: the levelling stage now goes in FRONT of a trailing limiter
instead of being appended after it. The likely sequence is "apply Clean Voice,
then even out the levels", and Clean Voice ends in a Peak Ceiling — so
appending put up to 12 dB of lift after the ceiling that exists to bound the
chain. Every quiet-to-loud transition would leave residual lift on material
already at -1 dBFS, and the render shears that flat. A ceiling with something
added after it is not a ceiling. Falsified by reverting to append.

WIRING: "Even Out Levels" sits beside "Tone (EQ)" in the add menu, decoding in
an OfflineAudioContext and locking the rack while it works, exactly as the
carve does. The same control removes it once present, because pressing it twice
never means "add a second levelling stage". The stage itself needs no bespoke
module — it is a gain node carrying a label and a lane, and the rack already
renders that correctly.

THE TRAP, now covered: a script hands back a whole HfAutomation describing only
its OWN lane, so writing it to the attribute would take the carve's per-band
lanes and the track's volume lane with it — silently, totally, and noticed only
later when the mix has lost its ducking. `withLane` merges by target instead,
and removal takes the orphaned lane with the node. This had no test until the
mutation survived; propertyPanelAutomation.test.ts now covers it and fails when
withLane replaces the set.

Core 1720 -> 1721, studio 3668 -> 3674.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:53 -07:00
Vance IngallsandClaude Opus 5 2dd7fdd538 feat(core): add the levelling script — "Even Out Levels"
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>
2026-08-10 15:38:51 -07:00
Vance IngallsandClaude Opus 5 dd80e8d9e6 feat(core): add a multi-band EQ as a composite over existing filters
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>
2026-08-10 15:38:51 -07:00
Vance IngallsandClaude Opus 5 0d04e4cb19 feat(core): name every preset node for the job it is doing
A peaking filter is "Peaking EQ" wherever it appears, so Clean Voice showed the
same two words at node 02 (cutting mud at 250 Hz) and node 04 (lifting clarity
at 3 kHz) with nothing to tell them apart. Reading down the rack, an author
could not follow what had been done for them.

`HfAudioFxNode.label` carries the job name, presets set it per node, and the
rack shows it in place of the effect's own name. Clean Voice now reads: Remove
Rumble, Reduce Mud, Even Out Loudness, Add Clarity, Peak Ceiling.

FIXES A BUG IN a533d1677: `parseAudioFxChain` and `serializeAudioFxChain` were
dropping `fromPreset` entirely — only `fromCarve` survived the attribute. So a
preset could not find its own nodes after a reload: re-applying would stack a
second copy instead of replacing, and the rack would lose the grouping. The
round-trip test compared only node TYPES, so it passed the whole time. It now
compares type, id, fromPreset and label, and fails if any is dropped.

Three tests, all falsified. Re-introducing the fromPreset drop fails the
round-trip; dropping label from the serializer fails it too; and giving two
nodes in one preset the same name fails the no-repeats check, which is the
invariant this whole change exists to hold. Identical CONSECUTIVE nodes are
exempt from that check — a stacked 24 dB/oct pair is one stage built from two
biquads, not two jobs.

Core 1688 -> 1690, studio 3664 -> 3665.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:50 -07:00
Vance IngallsandClaude Opus 5 21ff903b78 feat(studio): apply presets from the FX rack
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>
2026-08-10 15:38:47 -07:00
Vance IngallsandClaude Opus 5 fa321770b0 feat(core): add the audio FX preset catalogue
Twenty named starting points across four shelves — voice, repair, character,
space — so an author who wants "Telephone" does not have to know it is two
stacked filter pairs, a honk band, a de-mud band and a soft clip.

A preset is DATA. Applying one writes ordinary nodes into `data-fx-chain`, the
same nodes hand-building would produce, so there is no second code path beside
the rack, nothing new in the render, and no failure mode the chain does not
already have. Only the parameters a preset means are listed; the rest come from
`normalizeAudioFxParams`, which keeps each entry readable as an intent.

`fromPreset` joins `fromCarve` on the node — the id rather than a flag, because
a chain can carry more than one preset and each has to find its own nodes.
Applying appends (stacking Telephone onto a cleaned voice is a real thing to
want), re-applying replaces that preset's own nodes IN PLACE so it keeps its
position in the signal order, and hand-added effects are never touched.

The repair shelf is named for what it does. None of it is noise reduction —
that needs spectral work this effect set does not have — so "Quiet Between
Phrases" says it closes the pauses and leaves room tone under speech, rather
than implying a denoiser the author only discovers is absent after trusting it.

The tests check the DATA, not just the machinery: every effect real, every
parameter declared, every value inside its own range, every enum a real option,
every chain round-tripping through the attribute, and every preset that lifts
level bounded by a limiter that is actually last. Falsified against four
mutations — a gain past its maximum, an enum the effect does not offer, an
undeclared parameter, and a limiter moved off the end — each caught with the
preset and parameter named.

Core 1670 -> 1688.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:46 -07:00
Vance IngallsandClaude Opus 5 1de1afb2d6 refactor: derive the dataset keys for the FX and automation attributes
The studio writes these attributes through `HF_AUDIO_FX_ATTR` and
`HF_AUDIO_AUTOMATION_ATTR` but reads them out of `dataAttributes`, which is
keyed without the `data-` prefix — so the read side carried its own
`"fx-chain"` and `"automation"` literals in four places. The two spellings had
no link, so a rename could only half-land: the writes would move and the panel
would go on reading an attribute nothing writes any more.

Both keys are now derived from their attribute (`HF_AUDIO_FX_DATA_KEY`,
`HF_AUDIO_AUTOMATION_DATA_KEY`) and the four read sites use them.

Falsified two ways. Repointing the derived key breaks 24 existing panel and
summary tests, which is what proves the reads actually go through it. And the
new one-line pairing assertion in each module fails the moment the derivation
is replaced by a literal again — which is the regression it exists for, since
a hardcoded key that happens to be right today passes every other test in the
suite.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:44 -07:00
Vance IngallsandClaude Opus 5 702dfa59a4 refactor(core): route the graph's enabled-node filter through one helper
`enabledAudioFxNodes()` existed and was used only by the engine, while
audioFxGraph restated the same predicate three times in three shapes —
`.filter((n) => n.enabled !== false)` in `shapeOf`, `if (node.enabled === false)
continue` in `buildFxChain`, and the filter again in `update`. All three now
call the helper.

Also drops the `shape = shapeOf(next)` at the end of `update`. The early return
above it already established that `shapeOf(next)` equals `shape`, so this was a
full normalise-and-join of the chain per observer tick to write back the string
that was already there. `shape` is `const` now, which is the compiler enforcing
the same thing.

Consolidating found a genuine gap: `update`'s filter had NO test. A bypassed
node is not in the graph, so the update must walk the ENABLED nodes to stay
aligned with what was built — walking every node shifts each one's parameters
into its neighbour, and the shape is identical either way so nothing forces a
rebuild that would expose it. Both other call sites failed under mutation; this
one passed. Now covered, and falsified: the lowpass keeps its old cutoff while
the bypassed peaking's values land on it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:44 -07:00
Vance IngallsandClaude Opus 5 0da747e877 refactor: drop the non-null assertion and two casts the guards already cover
Three violations of the repo's "avoid `any`/`as T`" rule and the standing
no-`!` rule, all in the carve's analysis path.

`resolveAutomationRange` cast to `HfAudioFxNumberParam` immediately after
`if (!param || param.kind !== "number") return null` — the discriminated union
was already narrowed, so the cast asserted what the compiler knew. Removing it
leaves tsc clean, which is the proof it was dead.

`analyse` read `doc!.baseURI` and `el.getAttribute("src")!`, and laundered
`getElementById`'s `HTMLElement | null` through `as HTMLAudioElement | null`
into a predicate that only checked for a `src` attribute — so the "is this an
audio element" claim was never actually tested by anything. The document is now
guarded once at the top, and the voices are read out to `{ src, start }` values
as they are found, which makes both fields non-null by construction rather than
by assertion.

The element check is by `tagName`, not `instanceof HTMLAudioElement`: these
elements belong to the composition's iframe document, so this realm's
constructor never matches them. It is not a narrowing either — `sourceOptions`
is built from `doc.querySelectorAll("audio[id]")`, so a carve source is an
`<audio>` element by construction.

No behaviour change, so no new test. The path is covered: forcing the voice
collection to yield nothing fails 8 existing tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:43 -07:00
Vance IngallsandClaude Opus 5 267161cf55 fix(core): stop reading a blank FX parameter as zero
`normalizeAudioFxParams` coerced with a bare `Number(raw)`, and `Number(null)`,
`Number("")`, `Number(false)` and `Number([])` are all 0 — every one of them
finite. So a parameter that arrived missing or blanked clamped to 0 instead of
falling back to the effect's declared default, and because 0 is a legal setting
for most of these knobs nothing downstream could tell the difference: a
compressor whose threshold came through as null sat at 0 dB and never engaged.

Now only a number, or a string that actually spells one, counts — the same rule
`numberOrNull` in audioAutomation.ts already applies. Panel inputs arrive as
strings, so those still work.

Falsified by restoring the bare `Number(raw)`: null reads as 0 dB instead of
-24.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:40 -07:00
Vance IngallsandClaude Opus 5 644633c092 fix(core): retire a worklet processor on dispose instead of only disconnecting it
An AudioWorkletProcessor lives until its `process()` returns false; all four
returned true unconditionally, and `dispose` only called `node.disconnect()`.
So every chain rebuild that dropped a limiter, compressor, gate or bitcrush
left it running on the audio thread for the rest of the session — and a
structural edit rebuilds the whole graph, so a few passes over a carved bed
stacked up abandoned processors that nothing could reach to stop.

`dispose` now posts `__hfDispose`, which each processor treats as its cue to
return false from then on. A later parameter update cannot revive it.

Falsified two ways: dropping the `if (this.dead) return false;` guards (each
processor keeps running after dispose) and dropping the postMessage (dispose
sends nothing).

The processor test evaluates the module source pulled back out of the data:
URL that registration hands to `addModule`, so it exercises what actually
ships rather than a copy.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:39 -07:00
Vance IngallsandClaude Opus 5 674927ac3a fix(core): let a failed worklet registration be retried
`ensureAudioFxWorklets` cached its promise per context and never removed a
rejected one, while `readyContexts` was only written on success. So callers
correctly kept asking and every ask replayed the same rejection: one transient
`addModule` failure left the limiter, compressor, gate and bitcrush silent for
the life of that AudioContext, with no path back short of a page reload. The
entry is now dropped on failure so the next attempt actually retries.

Falsified by removing the `registered.delete(ctx)`: the retry replays the
rejection instead of resolving.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:39 -07:00
Vance IngallsandClaude Opus 5 8b68ce8056 perf(core): reuse the FFT scratch arrays across carve windows
Both analysis loops allocated a fresh `Float64Array(4096)` pair inside the
per-window loop. A 5-minute 48 kHz voiceover is ~7030 windows, so one carve
churned ~460 MB of transient Float64Array through the main thread — the panel's
thread — for a measurement that needs 64 KiB of scratch. Now one pair is reused;
`re` is fully overwritten each window and only `im` has to be cleared.

Wall-clock is unchanged (591 ms vs 596 ms on that file, within noise): the FFT
dominates and a bump allocation is nearly free. This is a GC-pressure fix, not a
latency one, and the band values it produces are bit-identical.

The review's third loop is `analyseCarveDuck`, which runs `windowDb` rather than
an FFT and allocates nothing per window — nothing to fix there.

Striding the Welch hops was tried and REJECTED. It is 27x faster on a 5-minute
voiceover (427 ms -> 15 ms), but it moves the result: at strength 0.9 the chosen
band set changed (630 Hz became 160 Hz), and it did not converge back to the
full read even at 2048 windows. That is the author's carve being silently
redrawn to save time on a measurement that already locks the rack while it runs.
The reason is recorded in the code so it is not re-attempted.

Falsified by deleting `im.fill(0)` from both loops: five tests fail, including
the two added here — a steady tone must measure the same bands whatever its
length, and its dynamics envelope must sit still rather than sliding as the
contamination accumulates.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:38 -07:00
Vance IngallsandClaude Opus 5 b1041a0dc7 fix(core): reschedule FX automation when the transport changes rate
`attachElementFxChain` gets a frozen `{scheduledAt, elapsed, rate}` and commits
every lane to absolute context times from it. `setRate` only assigned
`playbackRate.value`, so the audio changed speed and the envelopes did not: a
lowpass sweeping over 10 clip-seconds, switched to 2x mid-play, eats 20 s of
material in 10 s of wall clock while the sweep keeps its original schedule.

The runtime's recovery — `stopAll()` plus a reschedule — only runs when
`hasBoundedActiveSources()` is true, and a project-level music bed with no
`data-duration` is unbounded, so that case never recovered at all.

The timing a chain measures from is now a mutable reference frame that
`setRate` rebases: `elapsed` is advanced to the playhead the OLD rate carried
it to, then the lanes are replayed from there at the new one. That also fixes
the second consequence — `timingNow()` was advancing `elapsed` with the stale
rate, so every later chain edit re-aimed the envelope at the wrong clip
position for as long as the track played.

`attachElementFxChain`'s return type is now the named `ElementFxHandle`, so the
transport's `ScheduledSource.fx` carries `setRate` rather than a structural
`{ dispose(): void }`.

Falsified against four mutations: `setRate` a no-op (envelope stays 8 s long),
rescheduled without adopting the new rate (6 s instead of 3), rate swapped
without rebasing the frame (booked from t=0 instead of t=2), and the guard
dropped (rate 0 books a NaN span).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:38 -07:00
Vance Ingalls 40679e915c fix(core): dispose a clip's FX graph when it ends, not only when it is stopped
The `ended` listener spliced the source out of `_activeSources` and restored
the element's muted flag, but never disposed the FX handle — and the splice is
what made it unreachable, because `stopAll()` disposes by walking that same
array. So every clip that finished naturally leaked its graph for the rest of
the session.

The leak is not just memory. Each stale handle keeps a MutationObserver bound
to `data-fx-chain`/`data-automation`, so every later panel edit runs rebuild()
against a dead source: a fresh graph per abandoned clip, including a ~576 KB
reverb impulse and chorus/phaser oscillators that are started and never
stopped. Play a five-clip composition three times and fifteen observers answer
every subsequent knob turn.

At this point in the stack `attachElementFxChain` has no chainless early
return — it watches every audio clip, chain or not — so this leaked for all of
them, not only the ones carrying effects.

Disposal is skipped when the entry was already gone: `stopAll()` disposes its
own, and `stop()` is what fires this event.
2026-08-10 15:38:35 -07:00
Vance Ingalls 1b57a95441 build(core): regenerate the audio-fx runtime before the tests run
`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.
2026-08-10 15:38:35 -07:00
Vance Ingalls 2fb80b1da0 fix(core): sample the volume lane at clip-local time, the way the render bakes it
A lane's `t` is "seconds from the start of the clip" — HfAutomationPoint says
so, and the render honours it: prepareAudioTrack cuts the wav with
`-ss mediaStart`, so its t=0 IS the clip's start, and normaliseEnvelope
subtracts trackStart. Preview fed `relTime` instead, which is MEDIA time: it
carries mediaStart, scales by playbackRate and wraps on a loop.

So the same envelope played somewhere else than it rendered. `data-media-start`
past the last point held the final value from the first frame and never faded;
`playbackRate: 2` ran the envelope at double speed in preview only; a looping
clip restarted the envelope every lap in preview while the render baked it once.

The FX lanes shipped in this same stack already use clip-local elapsed. There
is one time base for automation, and this makes the volume lane use it.
2026-08-10 15:38:33 -07:00
Vance Ingalls f83b20e142 fix(core): move a node's id with its slot when the chain updates in place
Reordering two effects of the same type leaves `shapeOf` identical — it carries
type, poles and the one-pole frequency, but no id — so the chain updates in
place instead of rebuilding. That is right for the audio: the params move with
the position. The ids did not move with them. They were captured once at build
time, so after a reorder each handle named whichever effect used to sit in that
slot, and scheduleChainAutomation built its byId map from those stale names:
a lane on `fx.n2.frequency` drove the band that is now n1.

This is the invariant HfAudioFxNode.id documents itself as protecting —
"reordering the chain never re-points a lane at a different effect" — and it is
easiest to hit on the all-peaking chains the voiceover carve produces. Preview
only, since the render rebuilds from scratch, so the symptom is preview
quietly ceasing to predict the render.

Fixed by following the id, not by adding it to the shape: a same-type reorder
genuinely does not need a rebuild, only a correct id map.
2026-08-10 15:38:33 -07:00
Vance Ingalls 213c5f6715 fix(core): aim the phaser's trim lanes at the trims, not at the pinned wet/dry
`in_gain` and `out_gain` trim the signal entering and leaving the phaser, and
apply() drives them through inTrim/outTrim while pinning wet and dry to 1. The
automation map aimed both lanes at wet.gain and dry.gain instead — so an
envelope on either knob modulated a constant, the trim it was supposed to move
stayed wherever apply() last left it, and any values-only edit re-ran apply()
and slammed wet/dry back to 1 over the running ramp.

Heard as: "fade the phaser to silence" ends at full dry signal. Wrong in
preview and in the render, since both share this builder.

The builder's own comment records that wiring these knobs to wet/dry was
already found wrong once and moved to the trims; that refactor updated apply()
and missed the map. The existing exposure test only asserted that SOME param
was present under each key, which a mis-aimed target passes — the new test
asserts by value, which is the only thing a lane actually cares about.
2026-08-10 15:38:33 -07:00
Vance Ingalls 726fd1354f fix(engine): hand an empty audio track back instead of failing the render
ffmpeg exits 0 and writes a structurally valid but EMPTY wav whenever a clip's
trim starts past the end of its source — `-ss 10 -t 5` on a 2 s file. That
track reached `new OfflineAudioContext(channels, 0, rate)`, which throws
NotSupportedError, and the error travels past the mixer's per-track failure
collector: one mis-set `data-media-start` on one clip with one enabled effect
took the WHOLE render down with a RenderQualityError.

An empty track has nothing to process, so applyAudioFxChain now hands the input
back the way it already does for a chain with nothing enabled — before paying
for a browser to decide it. The runtime stub guards the same case at the point
the constructor would actually blow up, since it is reachable by any other
caller of the injected script.

The test falsifies against the real browser path: removing the guard
reproduces `NotSupportedError: The number of frames provided (0) is less than
the minimum bound (1)`.
2026-08-10 15:38:32 -07:00
Vance IngallsandClaude Opus 5 2d22c6ba8c 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>
2026-08-07 16:54:26 -07:00
Vance IngallsandClaude Opus 5 82036d869c fix(core): make audio automation survive being rescheduled mid-playback
Anything landing inside a running value curve is refused unless the parameter is
cancelled first, and two paths were not cancelling: the chain observer wrote each
knob straight onto its AudioParam before rescheduling, and a bent segment read as
straight because only the curve exponent was checked, never the via point the
timeline actually writes. The first threw NotSupportedError into the console and
abandoned the rest of the envelope; the second played a dragged bend as a ramp.

Measured against Chrome, in a live context and in an offline one suspended
mid-curve: any cancel frees the span, and only a missing cancel is refused.
clearParamLane takes the strongest form on purpose, because curve-over-curve
refusals were reported with a cancel at the new schedule time already in place
and have never reproduced; emit keeps a ramp fallback as the backstop for
whatever that mechanism turns out to be.

Dynamic carve is what exercises all of it, so it lands here too:

- a `gain` primitive, so a carve can match levels as well as carve bands
- carve settings collapse to one `strength`, with carveProfile deriving the six
  numbers that always moved together anyway
- analyseCarveDynamics / analyseCarveDuck turn the analysis into envelopes, with
  a slow release so the bed does not snap back the instant a word ends
- worklets are awaited inside attach, so adding a compressor to a carved bed no
  longer kills its envelopes and freezes every later edit
- per-track failure detail in the render's audio stage, which was being discarded

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-07 13:22:18 -07:00
Vance Ingalls b75c5f56f4 feat(engine): let an FX tail decay instead of cutting it at the clip
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.
2026-08-06 10:59:25 -07:00
Vance IngallsandClaude Opus 5 68ce91057f fix(core): apply chain edits to the running graph
A structural edit — an effect added, removed, bypassed, or a filter's pole
count switched — was dropped. `buildFxChain`'s update reports false when the
change is not merely new values, and the attribute observer ignored that, so
the edit only took hold when the persisting write reloaded the composition.
That reload restarted every playing track, which is what was heard as the
audio chopping.

The graph is now swapped in place: the old effects are detached, the new ones
built and connected between the same source and gain, and any lanes
re-scheduled onto the new nodes. The source node is never touched, so playback
does not restart.

A track with no chain is watched too, rather than wired through and forgotten,
so adding its first effect is heard the same way. That means the function
always returns a disposer instead of null for the empty case.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 10:59:17 -07:00
Vance IngallsandClaude Opus 5 6c48422389 fix(core): make the volume lane audible in preview
The envelope was scheduled onto the transport's gain AudioParam, but the
runtime rewrites that gain every tick from `data-volume` and the GSAP-seeked
value — so it was erased within a frame. Volume automation was correct in the
render and inaudible while previewing.

The lane now feeds the per-tick path where the probed volume keyframes already
sit, checked ahead of them so the two cannot fight, and the transport no
longer schedules volume at all: one mechanism instead of two racing.

The cost is honest — in preview the level steps per tick rather than per
sample, exactly as the existing keyframe path does. The render still bakes it
into the PCM sample-accurately, and FX parameters are still scheduled on their
own AudioParams, since nothing rewrites those.

Parsed lanes are cached by attribute text: the runtime asks once per tick per
track, and parsing there would run the JSON parser 60 times a second for a
value that only changes on an edit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 10:59:16 -07:00
Vance IngallsandClaude Opus 5 c651302322 feat(engine): bake automation envelopes into the render
The offline render schedules FX lanes with the same scheduler preview uses,
inside the OfflineAudioContext that already runs the same graph builders. The
input WAV is the clip's own audio from its first sample, so clip-local time
is offline time and the envelope needs no offset.

Volume lanes take the existing PCM bake rather than a second mechanism: the
lane is converted to keyframes, so a straight fade stays two of them and only
a bent segment is sampled — the baker interpolates linearly and would
otherwise quietly straighten the curve. A volume lane supersedes keyframes
probed from the timeline, which `lint` already warns about.

A browser test sweeps a lowpass from below a 2 kHz tone to well above it and
measures both ends. Parsing the envelope is not the same as scheduling it,
and only running the real thing tells the two apart.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 10:59:16 -07:00
Vance IngallsandClaude Opus 5 0357be5ad6 feat(core): play automation envelopes in preview
Schedules each lane onto the AudioParams behind its knob using native ramps
and value curves. Nothing evaluates the envelope per frame: it is handed to
the audio thread once, so it stays sample-accurate however busy the main
thread is, and the offline render will schedule it the same way.

Timing comes from the transport, so an envelope survives seeking into the
middle of a clip, a clip that has not started yet, and a playback rate that
compresses clip seconds into context seconds.

A straight line is only scheduled as a ramp when nothing bends it — no
curvature, a linear parameter scale, and no unit mapping. Log-scaled
parameters and mapped ones are sampled instead, since a delay knob in
milliseconds and a wet/dry pair moving in opposition are not linear in the
parameter they drive.

Lanes with nowhere to write are skipped rather than reported: a one-pole
filter exposes no frequency param, and the worklet effects expose none at
all. Editing an envelope mid-playback re-aims it at the live playhead rather
than restarting the track.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 10:59:15 -07:00
Vance IngallsandClaude Opus 5 a38753643e feat(core): expose the AudioParams behind automatable FX knobs
Marks the knobs an automation lane can drive and has each graph builder hand
back the AudioParam behind them, so a scheduler can write to a running effect
without knowing what the effect is.

A knob is not always one AudioParam. A wet/dry mix is two gains moving in
opposition, and a knob in milliseconds drives a delay time in seconds, so
each target carries the mapping out of the knob's own declared unit.

What stays unautomatable is stated where it is decided: a WaveShaper curve, a
convolution impulse and a one-pole filter's coefficients are all rebuilt
wholesale rather than scheduled, and the four worklet effects take values by
postMessage rather than through AudioParams.

The registry flag is written by hand, so a test builds every effect and
checks the exposure both ways — nothing flagged is missing, nothing exposed
is unflagged. A flag that lied would offer a lane that silently did nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 10:59:14 -07:00
Vance IngallsandClaude Opus 5 420035e42a feat(core): automation envelope model for audio tracks
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>
2026-08-06 10:59:14 -07:00
Vance IngallsandClaude Opus 5 15dfbda529 refactor(studio): split the FX node row out of FxSection
Clears the health findings the FX stack left behind: the chain-node render
callback was a 70-line closure over half of FxSection's state, and the two
reorder arrows were the same button written twice.

Also drops two exports with no consumers, and registers the audio FX runtime
stub as an entry point — it is bundled by file path, so nothing imports it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 10:59:13 -07:00
Vance Ingalls b2df19f199 fix(core): register FX worklets before building nodes that need them
An AudioWorkletNode cannot be constructed before its processor is registered —
it throws, and the surrounding chain is lost with it. `attachElementFxChain`
built the chain first and only then called `ensureAudioFxWorklets`, so every
worklet-backed effect (compressor, limiter, gate, bitcrush) threw on
construction and the track fell back to dry. Instrumenting the preview showed
`hf-compressor: InvalidStateError` with addModule never called at all.

When the module has not landed yet the track now plays dry and the graph is
swapped in once registration resolves, so the effect arrives a moment late
instead of never.

Registration is also tracked per context rather than in one module-level
promise. A processor registered on one AudioContext does not exist on another,
so the shared promise made every context after the first believe it was ready
when it was not — the studio's transport owns its own context, which is exactly
that case.

With the worklets actually running, the compressor's per-sample log10 and pow
became real audio-thread work. Samples below the knee have a gain of exactly
unity and need neither, so the envelope is now compared in the linear domain
and the transcendentals only run for samples that are actually being
compressed.
2026-08-06 10:59:13 -07:00
Vance Ingalls c777b42176 fix(studio,core): stop parameter drags from restarting playback
Dragging a knob wrote the chain through the persisting attribute path on every
input event. That path refreshes the preview, which reloads the composition and
reschedules audio — so a single drag reloaded dozens of times and playback
stuttered the whole way.

Drags now go through `onSetAttributeLive`, the same path colour grading uses for
scrubs: it coalesces undo entries and sets `skipRefresh`, so no reload happens.
The persisting write fires once, when the gesture ends — pointer-up or blur for
a slider, Enter or blur for a typed value. A select commits immediately since
there is no drag to wait for.

While dragging, the control is driven from local state. Waiting for the value to
round-trip through the element attribute made the knob lag behind the pointer.

For the change to be audible without a reload, the graph now follows the
attribute: the chain installed by the transport observes the element and
re-parameterises itself in place, so a value change lands on the next
128-sample quantum. A shape change (effect added, bypassed, pole count) cannot
be patched into a running graph, so it still waits for the next schedule rather
than cutting the audio mid-play.

The regression test drags a slider through several values and asserts the
persisting handler is untouched until release.
2026-08-06 10:59:12 -07:00
Vance Ingalls 96413cf88b feat(core,studio): hear the FX chain in preview, and run the carve analysis
Splices an element's FX chain into the playback graph so preview stops being
silent about effects, and wires the carve button that was previously inert.

The chain goes between the decoded source and its gain stage: effects see the
raw signal and volume automation rides on their output, matching the order the
offline render uses. Since preview and render call the same graph builders,
what is heard while scrubbing is what gets written.

The splice lives in the transport rather than on the `<audio>` element. The
transport plays each track from a decoded AudioBuffer and mutes the element to
avoid doubling, so capturing the element with createMediaElementSource would
have processed a stream nothing is listening to — it looked like it worked
because the call succeeded, and the audio was unchanged.

A chain that cannot be built plays dry rather than silencing the track, which
is the right failure in preview: the author keeps working and hears the source.
The render still refuses, because shipping the dry signal there would be wrong.

Carve now analyses for real: it decodes the chosen voice track, ranks its bands
and writes the resulting peaking filters onto this track. Generated nodes are
tagged `fromCarve`, so re-running replaces the previous carve instead of
stacking another set on top of hand-added effects.

Known limitation: the graph is built when a source is scheduled, so a knob
turned mid-playback takes effect on the next play or seek rather than
immediately. Live re-parameterisation needs the transport to hold the handle
and forward updates.
2026-08-06 10:59:12 -07:00
Vance Ingalls 103119025b feat(studio): show the Audio FX section on audio tracks
Adds `audioFx` to the editing-affordances contract and renders the FX panel in
the inspector when an `<audio>` element is selected.

The section is audio-only. A `<video>` carries its sound on a separate
`<audio>` element, so an FX chain on the video would have nothing to process.

Chain and carve settings are written straight back onto the element as
serialised attributes, the way colour grading carries its config, so
persistence is an ordinary attribute write and needs no new server route. A
chain that cannot be parsed renders as empty rather than breaking the panel,
and the attribute is left untouched until the user changes something.

The collapsed group summarises what is on the track ("2 effects + carve") so
the state is visible without expanding it.

Wired into PropertyPanelFlat rather than PropertyPanel: STUDIO_FLAT_INSPECTOR_ENABLED
defaults to true, so the flat inspector is what actually renders.
2026-08-06 10:59:11 -07:00
Vance IngallsandClaude Opus 5 2fc689bd91 fix(engine): keep the FX render 16-bit, stereo, and correctly sized
Three defects in the offline FX path, none of which any test could see.

**Float output silently disabled sample-accurate volume automation.** The writer
emitted 32-bit IEEE float; the very next mixer step bakes the volume envelope
into the samples and accepts only 16-bit PCM, returning null otherwise. So
enabling any effect downgraded that track to the ffmpeg expression path — capped
at 32 straight segments, quantising a curved envelope, and on a dense one falling
back to base volume. It now writes 16-bit PCM, clamped rather than wrapped so a
limiter at 0 dB or a resonant filter cannot turn overshoot into a click. A test
asserts the baker accepts the writer's own output and actually fades it.

**Everything was folded to mono.** `prepareAudioTrack` goes out of its way to
emit stereo — its pan filter exists to dodge ffmpeg's 3 dB mono-to-stereo
rematrix — and this folded it, then wrote one channel. So adding a single peaking
EQ collapsed a bed's width and cost ~3 dB in the render, while preview stayed
stereo. Channels now travel as one plane each, through an OfflineAudioContext of
the same width, and come back interleaved.

**Small results decoded the wrong length.** `new Float32Array(buf.buffer)`
discards byteOffset and byteLength, and Node pools small allocations: a 400-byte
payload sits at offset 8 inside an 8 KiB pool, so a clip under ~1024 samples
decoded as 2048 samples of unrelated memory — and the empty-result guard could
not see it. The reader has the mirror-image fix: a float data chunk on an odd
boundary (ffmpeg's pcm_f32le writes fmt(18) + fact, landing `data` at 58) now
copies instead of throwing RangeError on an unaligned view.

The tail limitation is now stated rather than mis-stated: the context is exactly
as long as the input, so a reverb or delay still ringing is cut there. The old
comment claimed the opposite. How far a tail may run past a clip's end changes
the clip's length in the mix, so it is a product decision, not one to make here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 10:59:09 -07:00
Vance Ingalls 65629692d0 feat(core): voiceover carve analysis
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.
2026-08-06 10:58:46 -07:00
Vance Ingalls 3c33413c04 feat(engine): render audio FX in an OfflineAudioContext
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.
2026-08-04 14:36:31 -07:00
Vance IngallsandClaude Opus 5 c3291f2912 fix(core): reverb level, phaser wiring, per-channel dynamics, one-pole rebuild
Four defects in the graph builders, all found by review rather than by ear.

**Reverb was unusable at its own defaults.** A ConvolverNode applies the
impulse's gain whole — the graph sets `normalize = false` so a room is
deterministic rather than browser-defined — but the impulse was raw decaying
noise. Measured L2 at the registry default (size 0.7 / damping 0.5): 46.4, or
+33.3 dB, putting the wet path ~24 dB over dry at the default `wet: 0.35`. It is
now normalised to unit energy, so the wet knob means what it says. Preview and
render both convolve this buffer, so they stayed identical throughout — equally
deafening before, equally correct now.

**Phaser in_gain/out_gain trim the signal entering and leaving the effect**, not
a wet/dry pair. Wired to the wet and dry legs, "Input" muted the dry path and
the two defaults summed to 1.14, so inserting a phaser raised the track level.
They are now input and output trims with the legs summed at unity. Its declared
waveform is also honoured: `lfo.type` was never assigned, so the default
"Triangular" was silently a sine.

**The dynamics worklets held one envelope across a channel-major loop.** The
followers advance per sample, so on stereo a 20 ms attack behaved as 10 ms, and
the right channel's gain came from an envelope that had already traversed the
left — the two ducked differently from the same input and the image pumped.
State is now per channel, as is the gate's smoothed gain and bitcrush's
sample-hold counter, which previously advanced only on the last channel and left
every earlier one frozen for a whole quantum. The gate also honours the knee it
declares instead of chattering on material sitting at the threshold.

**A one-pole filter's cutoff was swallowed in preview.** Its coefficients are
fixed at construction, so `update` cannot push a new frequency — but the shape
signature carried only type and pole count, so a cutoff change looked like a
values-only edit and went into a no-op updater. Preview kept filtering at the
old frequency while the render used the new one: a preview/render divergence in
exactly the two effects that do not use a BiquadFilterNode.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 14:36:30 -07:00
Vance Ingalls f59612850d feat(core): Web Audio graphs for the FX registry
One graph builder per `web` id, turning the registry's declarations into
running audio.

Every node exposes `update`, so turning a dial re-parameterises the live graph
rather than rebuilding it: an AudioParam change lands on the next 128-sample
quantum, about 2.7 ms at 48 kHz. `buildFxChain` reports whether an update could
be applied in place — adding or bypassing an effect, or switching a filter
between one and two poles (which changes the node type from BiquadFilterNode to
IIRFilterNode), changes the graph's shape and returns false so the caller
rebuilds.

Four effects have no native node and run as AudioWorklet processors:
compressor, limiter, gate and bitcrush. The module is registered from a data:
URL rather than a blob:, because a blob inherits the page origin and is opaque
on a file:// page, where it fails with an unhelpful AbortError.

Reverb has no single node either. `synthesizeReverbImpulse` generates a tail
from the room parameters, seeded so the same room sounds the same on every
machine, and the ConvolverNode uses it.

Tests cover the wiring — which nodes get built, how they connect, parameter
application and clamping, in-place update versus rebuild, disposal — against a
fake AudioContext, since happy-dom has no Web Audio.
2026-08-04 14:36:30 -07:00
Vance IngallsandClaude Opus 5 8e0f63d21b fix(core): stop declaring knobs that move nothing
Three parameters were declared with ranges, defaults and hints, and read by no
builder — dials an author could turn with no audible result.

- `chorus.decay` and `bitcrush.aa`: removed. FFmpeg's chorus feeds a decay back
  into its delay line and a bitcrusher's anti-alias needs a real filter; adding
  either is new DSP, not a fix, so the honest move is to stop advertising them.
- `lowshelf.q` / `highshelf.q`: removed. The Web Audio spec leaves Q unused for
  shelving filters, so the control moved nothing — and because the shared Q
  helper marks it automatable, an author could draw an envelope on it and hear
  nothing at all.

`phaser.decay` and `gate.knee` stay: the first drives the sweep depth, and the
second is now read by the gate's processor.

A test asserts each of these directly, since the existing exposure invariant only
checks that a flagged parameter reaches an AudioParam — a parameter the node then
ignores passes it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 14:36:15 -07:00
Vance Ingalls 0d5abd280a feat(core): audio FX registry
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.
2026-08-04 09:49:34 -07:00
Vance Ingalls 8c6cf90ff9 chore: release v0.7.91 2026-08-03 22:48:00 -07:00
Vance Ingalls 71fd96bbf1 Merge pull request #2854 from heygen-com/feat/canary-rollouts
feat(core): percentage-based canary rollouts + calibration experiment
2026-08-03 22:35:37 -07:00
Miguel Ángel 4e7fcf7f2a fix(core): resolve sub-composition sibling asset paths everywhere (#2994)
Extends the studio-preview fix to the render path and the asset-discovery
utilities, which share the same resolver and had the same defect.

`rewriteAssetPath` takes an optional `assetExists` probe. A plain relative ref
authored in a sub-composition (`_shared.css`, `clip.mp4`) is re-pointed at the
composition's own directory when that sibling exists on disk; project-root refs
with no sibling (the registry's `assets/logo.png` convention) stay as authored.
Callers that can see the filesystem supply the probe, so the module stays free
of node:fs.

Also fixes a second defect in the inliner: `<head>` <link> hrefs and external
script srcs are hoisted into the root document but never went through the
rewrite at all, so even the documented `../` form escaped the project and 404'd
at render time.

Wired into the preview bundler, the producer compiler, the studio preview
builder, the HEVC preview lint, the project lint's asset scans, publish proxy
baking, and media-treatment source resolution.
2026-08-03 21:13:35 -07:00