From 9f676205239a4e1ce03498223ef9f6ce5448aeec Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 13 Aug 2026 06:57:24 -0700 Subject: [PATCH] feat(core): name every preset node, and add a multi-band EQ over existing filters (#3178) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(studio): pull TimelineLanes under the 600-line cap TimelineLanes.tsx hit 620 lines. Extracted the three per-clip pointer gestures (resize-start, pointer-down move-arm, click/razor-split) into createClipGestureHandlers — one factory call per rendered clip instead of ~120 lines of inline handler bodies in the render loop. 529 lines now. * fix(studio): split the extracted pointerdown handler under the CRAP threshold Moving the ~120-line gesture logic into timelineClipGestureHandlers.ts concentrated it into two functions fallow flagged (onPointerDown at CRAP 63.6, onResizeStart at 31.6). Split the decision logic (which gesture a pointerdown implies) into a pure resolvePointerDownAction, then split its own intent-blocking check into isIntentBlocked. onResizeStart's guard moved into canStartResize. Every function now scores under 30. * fix(studio): drop the unused DomEditSelection import in PropertyPanelFlat CI caught it on PR #3026 (wa-12-panel-params); a later refactor in the stack removed the last use of the type here without removing the import. * fix(studio): close the typecheck and fallow gaps wa-18b-reschedule opened useAutomationLanes.ts's write() assumed gesture-scoped coalescing and a preview-only commit that useDomEditAttributeCommits.ts never grew — backported that option support from its own later commit so the two sides of the API agree. The paste path and its tests were missing the box selection's v0/v1 bounds a sibling commit added to AutomationSelection. The FX panel's carve controls still edited the six mechanism numbers (maxCutDb, bands, intelligibilityBias) after carveProfile() collapsed authoring to one Strength knob, so those fields no longer existed on HfCarveSettings; UI now edits strength, and analyseCarveBands is called with carveProfile(strength). Also closes fallow's complexity, dead-code and duplication findings on this PR's diff: extracted automationLaneDragMath.ts (pure group/point-move math) and useAutomationRangeDrag.ts (the marquee-select gesture) out of useAutomationLaneGestures.ts, pulled a couple of render-loop ternaries and a resolver into named functions, dropped an export nothing outside its file used, and shared a step-simplifier between audioCarve's two envelope builders. The edge-stretch vs. box-select priority test in TimelineAutomationLane.test was still pinning the pre-box-select rule (edge wins over a point sitting on it) that a sibling commit deliberately reversed — a point inside the box is now selected content, so grabbing it drags the group instead. Updated the test to the shipped rule instead of the old one. Co-Authored-By: Claude Opus 5 (1M context) * fix(core): cap the via conic's weight so an edge-clamped via point can't NaN A via point pulled out past the segment (viaX: 5, viaY: -3) clamps to (0.999, 0.001) — exactly on the steady region's edge, where edge - viaX is 0. viaConic divided by that zero to get an infinite weight, and shapeVia turned Infinity into NaN a few steps later (Infinity - Infinity in the quadratic coefficient). NaN reaching setValueCurveAtTime silences the automated parameter for the rest of the render. Capped the weight at 1e6 instead of leaving it unbounded — past that point the arc already reads as touching the via point, so nothing visible is lost. Also hardened shapeVia's existing denominator guard (`<= 0`) to `!(> 0)`, since NaN fails the original comparison and fell through it. Review by Miga (PR #3208). * fix(studio-server): fingerprint the proactive waveform cache key too The route already keys the waveform cache on the asset's size and mtime as well as its path, so a rebuilt-in-place file gets fresh peaks instead of stale ones. generateWaveformCache — the proactive path that runs on upload — still called buildWaveformCacheKey with the path alone, so it wrote to a different key than the route reads from (making the pre-generated cache never found) and kept the exact collision bug this fingerprint exists to fix on its own path. Review by Miga (PR #3211). * style(docs): run oxfmt on the /hyperframes-audio skill docs Table column widths had drifted out of alignment with oxfmt's own rules, failing format:check and blocking the Preflight gate every downstream branch inherits. Whitespace only, no content change. * fix(core): stop \b from missing underscore-separated names, guard clipsOverlap's negative duration \b treats `_` as a word character, so \bbed\b never matched bed_01, music_bed_loop, or theme_song, and \bvo\b/\bvox\b/\btts\b had the same gap — an underscore-separated bed classified as "unknown" and could end up offered as its own carve source. Replaced the short hints with a boundary that actually excludes letters and digits on both sides. clipsOverlap computed end = start + duration without guarding sign, so a negative duration put end before start — an interval that does not describe anything, and one specific case showed it silently dropping a real overlap (a shorter, earlier broken end rejected a clip that genuinely contained the point). Duration clamps to zero instead: a clip cannot un-play time, and a zero-length clip at its start is the sane reading of "duration nobody wrote down as positive." Review by Miga (PR #3212). * fix(studio): widen PropertyPanel's resetModules render timeout again The 20s margin (already once widened for the same reason) is timing out in CI's full-monorepo Test run — the resetModules()+fresh-import render this test needs is uncached and competes with every other package's test suite for the same worker pool, and the same test passes in well under 2s standalone. Went to 45s rather than re-tuning to whatever number happens to clear the current CI load, since that number moves every time CI gains a package. * fix(studio): stop the single-candidate auto-apply carve firing twice Two auto-apply effects both fire when sourceOptions.length === 1: the multi-candidate effect only guards length === 0, so a single candidate passes it too, and the single-candidate effect passes its own guard right after — both compute the same sources list and both call setCarve, so the common case (one narrator, one bed) triggered two decodes, two FFT runs, and two concurrent attribute writes for one decision. The multi-candidate effect now defers to its sibling for exactly one candidate, which already has its own detailed handling for that case. Review by Miga (PR #3213). * feat(core): carve against every voice over a bed, always (#3212) * feat(core): carve against every voice over a bed, always dynamically A bed usually runs under a whole sequence — a narrator, an interview answer, a second presenter — and carving against one of them left the others fighting it. `source` becomes `sources`, and `mixCarveSources` sums every voice onto the BED's clock before anything is measured. That is what keeps one analysis sufficient: the chain is fixed, so there is no per-voice filter to switch between, and bands drawn from all the speech there is with envelopes that rise wherever any of it happens answer the actual question — where and when is speech masking this bed. Summed rather than averaged: two people talking at once mask more than either alone. Audio before the bed starts is dropped rather than folded in at zero, since it plays over nothing and shifting it would put a cut where there is no voice. `dynamic` is gone. A fixed depth thins the bed through every pause, and once both have been heard there is no reason to want it, so every carve follows the speech. Two helpers the panel and the headless script now share instead of each carrying a copy — two definitions of "what does this name suggest" drift, and then the two disagree about which track is the voice: - `classifyAudioName` reads a track's kind from its id and filename together. `unknown` is deliberately common: treating an unrecognised name as "not a voice" would hide the one track somebody needs to pick. - `clipsOverlap` keeps out a voice that never plays while the bed does. An unwritten duration counts as unbounded, not zero — refusing a clip whose length the composition leaves to the media would drop the commonest case there is. Files written before this still load: a single `source` reads as a one-voice list, a stored `dynamic` is ignored, and an absent attribute means the defaults whole. Co-Authored-By: Claude Opus 5 (1M context) * fix(core): stop \b from missing underscore-separated names, guard clipsOverlap's negative duration \b treats `_` as a word character, so \bbed\b never matched bed_01, music_bed_loop, or theme_song, and \bvo\b/\bvox\b/\btts\b had the same gap — an underscore-separated bed classified as "unknown" and could end up offered as its own carve source. Replaced the short hints with a boundary that actually excludes letters and digits on both sides. clipsOverlap computed end = start + duration without guarding sign, so a negative duration put end before start — an interval that does not describe anything, and one specific case showed it silently dropping a real overlap (a shorter, earlier broken end rejected a clip that genuinely contained the point). Duration clamps to zero instead: a clip cannot un-play time, and a zero-length clip at its start is the sane reading of "duration nobody wrote down as positive." Review by Miga (PR #3212). --------- Co-authored-by: Claude Opus 5 (1M context) * fix(studio): port the carve UI off the removed source/dynamic fields #3212 (accidentally squash-merged into this branch instead of main) changed HfCarveSettings from a single `source` + `dynamic` toggle to a `sources` list with dynamic mode removed outright — the multi-voice UI consumer that goes with that shape lands in the very next PR, so this branch was left with a type that no longer matched its own code. Minimal port, not the multi-voice redesign that PR does properly: the "Listen to" picker and analyse() treat sources[0] as the one voice this UI still understands, and every dynamic-mode branch (the automated envelope lanes, the toggle, the checkbox) is gone along with the field — a carve is now always the static value the analysis computes, matching what the type change made permanent. Test suite trimmed the same way: the automation-lane and toggle tests covered behavior that no longer exists. --------- Co-authored-by: Claude Opus 5 (1M context) --- packages/core/package-subpaths.json | 6 + packages/core/package.json | 10 + packages/core/src/audioFx.ts | 33 +++ packages/core/src/audioFxEq.test.ts | 157 ++++++++++++++ packages/core/src/audioFxEq.ts | 192 ++++++++++++++++++ packages/core/src/audioFxPresets.test.ts | 51 ++++- packages/core/src/audioFxPresets.ts | 191 ++++++++++++----- .../editor/propertyPanelFxSection.test.tsx | 32 +++ .../editor/propertyPanelFxSection.tsx | 4 +- 9 files changed, 617 insertions(+), 59 deletions(-) create mode 100644 packages/core/src/audioFxEq.test.ts create mode 100644 packages/core/src/audioFxEq.ts diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json index 936fb0520..83ae2ba1d 100644 --- a/packages/core/package-subpaths.json +++ b/packages/core/package-subpaths.json @@ -98,6 +98,12 @@ "types": "./dist/audioFx.d.ts", "environments": ["browser", "bun", "node"] }, + "./audio-fx-eq": { + "source": "./src/audioFxEq.ts", + "runtime": "./dist/audioFxEq.js", + "types": "./dist/audioFxEq.d.ts", + "environments": ["browser", "bun", "node"] + }, "./audio-fx-presets": { "source": "./src/audioFxPresets.ts", "runtime": "./dist/audioFxPresets.js", diff --git a/packages/core/package.json b/packages/core/package.json index daecd009e..b9f8f5ecd 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -112,6 +112,12 @@ "import": "./src/audioFx.ts", "types": "./src/audioFx.ts" }, + "./audio-fx-eq": { + "bun": "./src/audioFxEq.ts", + "node": "./dist/audioFxEq.js", + "import": "./src/audioFxEq.ts", + "types": "./src/audioFxEq.ts" + }, "./audio-fx-presets": { "bun": "./src/audioFxPresets.ts", "node": "./dist/audioFxPresets.js", @@ -408,6 +414,10 @@ "import": "./dist/audioFx.js", "types": "./dist/audioFx.d.ts" }, + "./audio-fx-eq": { + "import": "./dist/audioFxEq.js", + "types": "./dist/audioFxEq.d.ts" + }, "./audio-fx-presets": { "import": "./dist/audioFxPresets.js", "types": "./dist/audioFxPresets.d.ts" diff --git a/packages/core/src/audioFx.ts b/packages/core/src/audioFx.ts index 26487ab8e..87531da23 100644 --- a/packages/core/src/audioFx.ts +++ b/packages/core/src/audioFx.ts @@ -813,6 +813,25 @@ export interface HfAudioFxNode { * and each has to be able to find its own. */ fromPreset?: string; + /** + * What the rack calls this node, when the effect's own name is not specific + * enough to be useful. + * + * A peaking filter is "Shape One Range" wherever it appears, so a chain that + * cuts mud at 250 Hz and lifts clarity at 3 kHz shows the same words twice + * and an author cannot tell the two apart. A preset names each node for the + * JOB it is doing instead — "Reduce Mud", "Add Clarity" — and the rack reads + * as a list of things that were done rather than a list of filter types. + */ + label?: string; + /** + * Id of the multi-band EQ that owns this node, when it is one of its bands. + * + * Same device as `fromCarve`: the module gathers its own nodes out of the + * chain and presents them as one control surface, so an EQ needs no new + * effect type and its bands stay ordinary filters underneath. + */ + fromEq?: string; /** Absent means enabled — chain files written before the field existed still load. */ enabled?: boolean; params?: HfAudioFxParamValues; @@ -862,6 +881,9 @@ export function parseAudioFxChain(json: string): HfAudioFxChain { enabled?: unknown; params?: unknown; fromCarve?: unknown; + fromPreset?: unknown; + label?: unknown; + fromEq?: unknown; }; if (typeof node.type !== "string" || !BY_ID.has(node.type)) { throw new AudioFxChainError(`Node ${i} has unknown effect type: ${String(node.type)}`); @@ -870,6 +892,14 @@ export function parseAudioFxChain(json: string): HfAudioFxChain { type: node.type, ...(typeof node.id === "string" && node.id ? { id: node.id } : {}), ...(node.fromCarve === true ? { fromCarve: true as const } : {}), + // Both survive the round trip or a preset stops being able to find its + // own nodes after a reload: re-applying would stack a second copy and + // the rack would lose the grouping it braces them with. + ...(typeof node.fromPreset === "string" && node.fromPreset + ? { fromPreset: node.fromPreset } + : {}), + ...(typeof node.label === "string" && node.label ? { label: node.label } : {}), + ...(typeof node.fromEq === "string" && node.fromEq ? { fromEq: node.fromEq } : {}), enabled: node.enabled !== false, params: normalizeAudioFxParams( node.type, @@ -893,6 +923,9 @@ export function serializeAudioFxChain(chain: HfAudioFxChain): string { type: node.type, ...(node.id ? { id: node.id } : {}), ...(node.fromCarve === true ? { fromCarve: true } : {}), + ...(node.fromPreset ? { fromPreset: node.fromPreset } : {}), + ...(node.label ? { label: node.label } : {}), + ...(node.fromEq ? { fromEq: node.fromEq } : {}), ...(node.enabled === false ? { enabled: false } : {}), params: normalizeAudioFxParams(node.type, node.params), })), diff --git a/packages/core/src/audioFxEq.test.ts b/packages/core/src/audioFxEq.test.ts new file mode 100644 index 000000000..ff7b52d93 --- /dev/null +++ b/packages/core/src/audioFxEq.test.ts @@ -0,0 +1,157 @@ +import { describe, expect, it } from "vitest"; +import { + HF_AUDIO_FX_CHAIN_VERSION, + parseAudioFxChain, + serializeAudioFxChain, + type HfAudioFxChain, +} from "./audioFx.js"; +import { + addAudioEq, + audioEqIds, + audioEqSummary, + HF_AUDIO_EQ_3, + HF_AUDIO_EQ_5, + HF_AUDIO_EQ_RANGE_DB, + readAudioEqBands, + removeAudioEq, + setAudioEqBandGain, +} from "./audioFxEq.js"; + +const empty = (): HfAudioFxChain => ({ version: HF_AUDIO_FX_CHAIN_VERSION, nodes: [] }); + +describe("adding an EQ", () => { + it("writes one ordinary filter per band, in band order", () => { + const { chain } = addAudioEq(empty()); + expect(chain.nodes.map((n) => n.type)).toEqual(["lowshelf", "peaking", "highshelf"]); + // Ordinary nodes: an author who opens the details finds filters they could + // have added by hand, not an opaque "eq" the graph has to special-case. + expect(chain.nodes.every((n) => n.enabled)).toBe(true); + expect(chain.nodes.map((n) => n.label)).toEqual(["Bass", "Middle", "Treble"]); + }); + + it("gives every band an id, because a lane addresses effects by id", () => { + const { chain } = addAudioEq(empty(), HF_AUDIO_EQ_5); + const ids = chain.nodes.map((n) => n.id); + expect(ids.every(Boolean)).toBe(true); + expect(new Set(ids).size).toBe(ids.length); + }); + + it("starts flat, so adding one changes nothing until a fader moves", () => { + const { chain, eqId } = addAudioEq(empty()); + for (const band of readAudioEqBands(chain, eqId)) expect(band.gain).toBe(0); + expect(audioEqSummary(readAudioEqBands(chain, eqId))).toMatch(/^Flat/); + }); + + it("keeps two EQs apart", () => { + const first = addAudioEq(empty()); + const second = addAudioEq(first.chain, HF_AUDIO_EQ_5); + expect(second.eqId).not.toBe(first.eqId); + expect(audioEqIds(second.chain)).toEqual([first.eqId, second.eqId]); + expect(readAudioEqBands(second.chain, first.eqId)).toHaveLength(3); + expect(readAudioEqBands(second.chain, second.eqId)).toHaveLength(5); + expect(new Set(second.chain.nodes.map((n) => n.id)).size).toBe(second.chain.nodes.length); + }); + + it("leaves effects that were already there alone", () => { + const before: HfAudioFxChain = { + version: HF_AUDIO_FX_CHAIN_VERSION, + nodes: [{ type: "reverb", id: "mine", enabled: true }], + }; + const { chain } = addAudioEq(before); + expect(chain.nodes[0]?.id).toBe("mine"); + expect(chain.nodes).toHaveLength(4); + }); +}); + +describe("moving a fader", () => { + it("changes only that band", () => { + const { chain, eqId } = addAudioEq(empty()); + const next = setAudioEqBandGain(chain, eqId, "Bass", 4.5); + const bands = readAudioEqBands(next, eqId); + expect(bands.find((b) => b.name === "Bass")?.gain).toBe(4.5); + expect(bands.find((b) => b.name === "Middle")?.gain).toBe(0); + expect(bands.find((b) => b.name === "Treble")?.gain).toBe(0); + }); + + it("leaves the band's frequency and width alone", () => { + // The fader is one control. Moving it must not quietly re-seed the rest of + // the band, or an author who set a frequency by hand loses it on the next drag. + const { chain, eqId } = addAudioEq(empty(), HF_AUDIO_EQ_5); + const before = readAudioEqBands(chain, eqId).find((b) => b.name === "Clarity")!; + const next = setAudioEqBandGain(chain, eqId, "Clarity", -3); + const after = readAudioEqBands(next, eqId).find((b) => b.name === "Clarity")!; + expect(after.frequency).toBe(before.frequency); + expect(after.q).toBe(before.q); + expect(after.gain).toBe(-3); + }); + + it("holds the fader to a tone control's range, not a repair tool's", () => { + // The filters themselves allow ±40 dB. A tone control that can bury a + // track under 40 dB of bass is not a tone control. + const { chain, eqId } = addAudioEq(empty()); + const hot = setAudioEqBandGain(chain, eqId, "Bass", 40); + const cold = setAudioEqBandGain(chain, eqId, "Bass", -40); + expect(readAudioEqBands(hot, eqId)[0]?.gain).toBe(HF_AUDIO_EQ_RANGE_DB); + expect(readAudioEqBands(cold, eqId)[0]?.gain).toBe(-HF_AUDIO_EQ_RANGE_DB); + }); + + it("ignores a band name that is not in this EQ", () => { + const { chain, eqId } = addAudioEq(empty()); + const next = setAudioEqBandGain(chain, eqId, "Nonsense", 6); + expect(readAudioEqBands(next, eqId).every((b) => b.gain === 0)).toBe(true); + }); +}); + +describe("the chain is the truth", () => { + it("reads a frequency the author moved by hand", () => { + // The nodes are authoritative, not a cached band list: opening the details + // and moving a frequency has to show up on the fader's own band. + const { chain, eqId } = addAudioEq(empty()); + const edited: HfAudioFxChain = { + ...chain, + nodes: chain.nodes.map((n) => + n.label === "Middle" ? { ...n, params: { ...n.params, frequency: 700 } } : n, + ), + }; + expect(readAudioEqBands(edited, eqId).find((b) => b.name === "Middle")?.frequency).toBe(700); + }); + + it("survives being written to an attribute and read back", () => { + const { chain, eqId } = addAudioEq(empty(), HF_AUDIO_EQ_5); + const moved = setAudioEqBandGain(chain, eqId, "Air", 2.5); + const back = parseAudioFxChain(serializeAudioFxChain(moved)); + // Without fromEq surviving, the module cannot find its own bands after a + // reload and the EQ silently becomes five loose filters. + expect(audioEqIds(back)).toEqual([eqId]); + expect(readAudioEqBands(back, eqId).map((b) => b.name)).toEqual([ + "Bass", + "Warmth", + "Middle", + "Clarity", + "Air", + ]); + expect(readAudioEqBands(back, eqId).find((b) => b.name === "Air")?.gain).toBe(2.5); + }); + + it("removes a whole EQ without touching anything else", () => { + const before: HfAudioFxChain = { + version: HF_AUDIO_FX_CHAIN_VERSION, + nodes: [{ type: "reverb", id: "mine", enabled: true }], + }; + const { chain, eqId } = addAudioEq(before); + const gone = removeAudioEq(chain, eqId); + expect(gone.nodes.map((n) => n.id)).toEqual(["mine"]); + }); +}); + +describe("what it says when closed", () => { + it("names only the bands that were moved", () => { + const { chain, eqId } = addAudioEq(empty()); + const next = setAudioEqBandGain(setAudioEqBandGain(chain, eqId, "Bass", 3), eqId, "Treble", -2); + expect(audioEqSummary(readAudioEqBands(next, eqId))).toBe("Bass +3, Treble −2"); + }); + + it("says so when nothing has been touched", () => { + expect(audioEqSummary(HF_AUDIO_EQ_3)).toMatch(/^Flat/); + }); +}); diff --git a/packages/core/src/audioFxEq.ts b/packages/core/src/audioFxEq.ts new file mode 100644 index 000000000..c1fbcea6a --- /dev/null +++ b/packages/core/src/audioFxEq.ts @@ -0,0 +1,192 @@ +/** + * A multi-band EQ, as a composite over effects that already ship. + * + * Bass, middle and treble is the most widely understood audio control there is + * — everyone has used one — 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 is also forced by the registry: 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. + */ + +import { + HF_AUDIO_FX_CHAIN_VERSION, + mintAudioFxNodeId, + normalizeAudioFxParams, + type HfAudioFxChain, + type HfAudioFxNode, +} from "./audioFx.js"; + +/** A band is one node. `name` is what the fader is labelled, and its handle. */ +export interface HfAudioEqBand { + name: string; + /** Corner for a shelf, centre for a peak. */ + frequency: number; + /** The only value a fader moves. Everything else is fixed when the band is made. */ + gain: number; + q?: number; + kind: "lowshelf" | "peaking" | "highshelf"; +} + +/** + * How far a fader travels. The registry allows ±40 dB on these filters, which + * is a repair tool's range — a tone control that can bury a track under 40 dB + * of bass is not a tone control. ±12 is the span a hi-fi offers, and it is + * enough to fix a voice. + */ +export const HF_AUDIO_EQ_RANGE_DB = 12; + +/** Bass, middle, treble — the set nobody needs taught. */ +export const HF_AUDIO_EQ_3: readonly HfAudioEqBand[] = [ + { name: "Bass", frequency: 200, gain: 0, kind: "lowshelf" }, + { name: "Middle", frequency: 1000, gain: 0, q: 0.9, kind: "peaking" }, + { name: "Treble", frequency: 4000, gain: 0, kind: "highshelf" }, +]; + +/** + * Five bands, named from the shared vocabulary the rest of the rack uses — so + * reaching for the EQ is also how an author learns the words. + */ +export const HF_AUDIO_EQ_5: readonly HfAudioEqBand[] = [ + { name: "Bass", frequency: 160, gain: 0, kind: "lowshelf" }, + { name: "Warmth", frequency: 350, gain: 0, q: 1, kind: "peaking" }, + { name: "Middle", frequency: 1000, gain: 0, q: 0.9, kind: "peaking" }, + { name: "Clarity", frequency: 3000, gain: 0, q: 1, kind: "peaking" }, + { name: "Air", frequency: 9000, gain: 0, kind: "highshelf" }, +]; + +const clampGain = (db: number): number => + Number.isFinite(db) ? Math.max(-HF_AUDIO_EQ_RANGE_DB, Math.min(HF_AUDIO_EQ_RANGE_DB, db)) : 0; + +/** Realise bands as ordinary nodes, tagged so the module can find them again. */ +export function audioEqNodes( + bands: readonly HfAudioEqBand[], + eqId: string, + chain: HfAudioFxChain, +): HfAudioFxNode[] { + const out: HfAudioFxNode[] = []; + let running: HfAudioFxChain = { ...chain, nodes: [...chain.nodes] }; + for (const band of bands) { + const made: HfAudioFxNode = { + type: band.kind, + id: mintAudioFxNodeId(running), + fromEq: eqId, + // The band name IS the node's job name, so a rack showing the bands + // individually still reads as words rather than as three filter types. + label: band.name, + enabled: true, + params: normalizeAudioFxParams(band.kind, { + frequency: band.frequency, + gain: clampGain(band.gain), + ...(band.kind === "peaking" ? { q: band.q ?? 1 } : {}), + }), + }; + out.push(made); + running = { ...running, nodes: [...running.nodes, made] }; + } + return out; +} + +/** Add an EQ to a chain. Returns the chain and the id the module addresses it by. */ +export function addAudioEq( + chain: HfAudioFxChain, + bands: readonly HfAudioEqBand[] = HF_AUDIO_EQ_3, +): { chain: HfAudioFxChain; eqId: string } { + const taken = new Set(chain.nodes.map((n) => n.fromEq).filter(Boolean)); + let eqId = "eq1"; + for (let i = 1; taken.has(eqId); i += 1) eqId = `eq${i + 1}`; + return { + chain: { ...chain, nodes: [...chain.nodes, ...audioEqNodes(bands, eqId, chain)] }, + eqId, + }; +} + +/** Every EQ in a chain, in the order their first band appears. */ +export function audioEqIds(chain: HfAudioFxChain): string[] { + const seen: string[] = []; + for (const node of chain.nodes) { + if (node.fromEq && !seen.includes(node.fromEq)) seen.push(node.fromEq); + } + return seen; +} + +/** + * Read one EQ's bands back out of the chain. + * + * The nodes are the truth, not a cached band list: an author can open the + * details and move a frequency by hand, and the faders have to reflect that + * rather than silently overwrite it on the next drag. + */ +export function readAudioEqBands(chain: HfAudioFxChain, eqId: string): HfAudioEqBand[] { + const out: HfAudioEqBand[] = []; + for (const node of chain.nodes) { + if (node.fromEq !== eqId) continue; + if (node.type !== "lowshelf" && node.type !== "peaking" && node.type !== "highshelf") continue; + const params = node.params ?? {}; + const freq = params["frequency"]; + const gain = params["gain"]; + const q = params["q"]; + out.push({ + name: node.label ?? node.type, + frequency: typeof freq === "number" ? freq : 1000, + gain: typeof gain === "number" ? gain : 0, + ...(typeof q === "number" ? { q } : {}), + kind: node.type, + }); + } + return out; +} + +/** Move one fader. Everything else about the band is left alone. */ +export function setAudioEqBandGain( + chain: HfAudioFxChain, + eqId: string, + bandName: string, + gain: number, +): HfAudioFxChain { + return { + ...chain, + nodes: chain.nodes.map((node) => + node.fromEq === eqId && node.label === bandName + ? { + ...node, + params: normalizeAudioFxParams(node.type, { + ...(node.params ?? {}), + gain: clampGain(gain), + }), + } + : node, + ), + }; +} + +/** Remove a whole EQ, bands and all. */ +export function removeAudioEq(chain: HfAudioFxChain, eqId: string): HfAudioFxChain { + return { ...chain, nodes: chain.nodes.filter((n) => n.fromEq !== eqId) }; +} + +/** + * What the module says when it is closed. + * + * Named for the bands that were actually moved, so a rack of collapsed modules + * still reads as a sentence — and an untouched EQ says so rather than listing + * three zeroes. + */ +export function audioEqSummary(bands: readonly HfAudioEqBand[]): string { + const moved = bands.filter((b) => Math.abs(b.gain) >= 0.1); + if (moved.length === 0) return "Flat — nothing changed yet"; + return moved + .map((b) => `${b.name} ${b.gain > 0 ? "+" : "−"}${Math.abs(Number(b.gain.toFixed(1)))}`) + .join(", "); +} + +export const HF_AUDIO_EQ_CHAIN_VERSION = HF_AUDIO_FX_CHAIN_VERSION; diff --git a/packages/core/src/audioFxPresets.test.ts b/packages/core/src/audioFxPresets.test.ts index 40c874209..2f187ce81 100644 --- a/packages/core/src/audioFxPresets.test.ts +++ b/packages/core/src/audioFxPresets.test.ts @@ -94,14 +94,58 @@ describe("the catalogue is internally valid", () => { } }); - it("survives being written to an attribute and read back", () => { + it("survives being written to an attribute and read back, TAGS AND ALL", () => { + // Comparing only types is what let `fromPreset` be silently dropped by the + // parser: every preset round-tripped its effects while losing the tag that + // lets it find its own nodes again. Compare what the rack actually needs. for (const p of HF_AUDIO_FX_PRESETS) { const chain = applyAudioFxPreset(empty(), p); const back = parseAudioFxChain(serializeAudioFxChain(chain)); expect( - back.nodes.map((n) => n.type), + back.nodes.map((x) => ({ + type: x.type, + id: x.id, + fromPreset: x.fromPreset, + label: x.label, + })), `${p.id} did not round-trip`, - ).toEqual(chain.nodes.map((n) => n.type)); + ).toEqual( + chain.nodes.map((x) => ({ + type: x.type, + id: x.id, + fromPreset: x.fromPreset, + label: x.label, + })), + ); + } + }); + + it("names every node for the job it is doing", () => { + for (const p of HF_AUDIO_FX_PRESETS) { + for (const node of p.nodes) { + expect(node.label, `${p.id}: a ${node.type} node has no job name`).toBeTruthy(); + } + } + }); + + it("never shows the same name twice in one chain", () => { + // The failure this exists to prevent: a rack reading "Shape One Range" + // twice, once cutting mud and once adding clarity, with nothing to tell + // them apart. Identical CONSECUTIVE nodes are exempt — a stacked pair is + // one stage built from two biquads, not two jobs. + for (const p of HF_AUDIO_FX_PRESETS) { + const seen = new Map(); + p.nodes.forEach((node, i) => { + const key = node.label ?? node.type; + const prev = seen.get(key); + const stackedPair = + prev === i - 1 && JSON.stringify(p.nodes[prev]?.params) === JSON.stringify(node.params); + expect( + prev === undefined || stackedPair, + `${p.id} shows "${key}" twice — an author cannot tell the two apart`, + ).toBe(true); + seen.set(key, i); + }); } }); @@ -156,6 +200,7 @@ describe("applying a preset", () => { // complete node rather than a partial one the graph has to guess at. expect(node.params).toEqual({ ...normalizeAudioFxParams("highpass", {}), frequency: 100 }); expect(node.fromPreset).toBe("rumble-cut"); + expect(node.label).toBe("Cut Rumble"); expect(node.enabled).toBe(true); }); diff --git a/packages/core/src/audioFxPresets.ts b/packages/core/src/audioFxPresets.ts index be74eec93..4f49d4577 100644 --- a/packages/core/src/audioFxPresets.ts +++ b/packages/core/src/audioFxPresets.ts @@ -44,6 +44,15 @@ export type HfAudioFxPresetFamily = "voice" | "repair" | "character" | "space"; export interface HfAudioFxPresetNode { /** Effect id from HF_AUDIO_FX. */ type: string; + /** + * What the rack calls this node — the JOB it is doing, not its filter type. + * + * A peaking filter is "Shape One Range" wherever it appears, so a chain that + * cuts mud and then lifts clarity shows the same words twice and an author + * cannot follow it. Naming each node for its job is what lets a preset read + * as a list of things that were done. + */ + label?: string; /** Only what this preset means to set; the rest come from the effect's defaults. */ params?: HfAudioFxParamValues; } @@ -70,9 +79,13 @@ const preset = ( * because a BiquadFilterNode is two-pole and that is the honest maximum for one * node. The telephone band wants the steeper slope, so it pays for two. */ -const steep = (type: "highpass" | "lowpass", frequency: number): HfAudioFxPresetNode[] => [ - { type, params: { frequency, q: 0.707, poles: "2" } }, - { type, params: { frequency, q: 0.707, poles: "2" } }, +const steep = ( + type: "highpass" | "lowpass", + frequency: number, + label: string, +): HfAudioFxPresetNode[] => [ + { type, label, params: { frequency, q: 0.707, poles: "2" } }, + { type, label, params: { frequency, q: 0.707, poles: "2" } }, ]; export const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[] = [ @@ -83,14 +96,15 @@ export const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[] = [ "Clean Voice", "Cuts rumble and mud, evens out the level, adds a little clarity.", [ - { type: "highpass", params: { frequency: 80, q: 0.707, poles: "2" } }, - { type: "peaking", params: { frequency: 250, gain: -3, q: 1.2 } }, + { type: "highpass", label: "Remove Rumble", params: { frequency: 80, q: 0.707, poles: "2" } }, + { type: "peaking", label: "Reduce Mud", params: { frequency: 250, gain: -3, q: 1.2 } }, { type: "compressor", + label: "Even Out Loudness", params: { threshold: -20, ratio: 3, attack: 12, release: 180, makeup: 3 }, }, - { type: "peaking", params: { frequency: 3000, gain: 2.5, q: 1 } }, - { type: "limiter", params: { limit: -1, attack: 5, release: 50 } }, + { type: "peaking", label: "Add Clarity", params: { frequency: 3000, gain: 2.5, q: 1 } }, + { type: "limiter", label: "Peak Ceiling", params: { limit: -1, attack: 5, release: 50 } }, ], ), preset( @@ -99,16 +113,17 @@ export const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[] = [ "Broadcast", "Denser and more forward — a radio-presenter sound.", [ - { type: "highpass", params: { frequency: 90, q: 0.707, poles: "2" } }, - { type: "peaking", params: { frequency: 400, gain: -3, q: 1.4 } }, + { type: "highpass", label: "Remove Rumble", params: { frequency: 90, q: 0.707, poles: "2" } }, + { type: "peaking", label: "Reduce Boxiness", params: { frequency: 400, gain: -3, q: 1.4 } }, { type: "compressor", + label: "Even Out Loudness", params: { threshold: -24, ratio: 4, attack: 8, release: 150, makeup: 5 }, }, - { type: "peaking", params: { frequency: 2500, gain: 3, q: 0.9 } }, - { type: "highshelf", params: { frequency: 8000, gain: 2 } }, - { type: "saturate", params: { type: "tanh", threshold: -12, output: 0 } }, - { type: "limiter", params: { limit: -1, attack: 5, release: 60 } }, + { type: "peaking", label: "Add Clarity", params: { frequency: 2500, gain: 3, q: 0.9 } }, + { type: "highshelf", label: "Add Air", params: { frequency: 8000, gain: 2 } }, + { type: "saturate", label: "Warmth", params: { type: "tanh", threshold: -12, output: 0 } }, + { type: "limiter", label: "Peak Ceiling", params: { limit: -1, attack: 5, release: 60 } }, ], ), preset( @@ -117,14 +132,15 @@ export const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[] = [ "Close & Warm", "Intimate and lightly handled, for a voice close to the mic.", [ - { type: "highpass", params: { frequency: 70, q: 0.707, poles: "2" } }, - { type: "lowshelf", params: { frequency: 180, gain: 2 } }, + { type: "highpass", label: "Remove Rumble", params: { frequency: 70, q: 0.707, poles: "2" } }, + { type: "lowshelf", label: "Add Weight", params: { frequency: 180, gain: 2 } }, { type: "compressor", + label: "Even Out Loudness", params: { threshold: -18, ratio: 2.5, attack: 20, release: 250, makeup: 2 }, }, - { type: "peaking", params: { frequency: 3000, gain: 1.5, q: 0.8 } }, - { type: "limiter", params: { limit: -1.5 } }, + { type: "peaking", label: "Add Clarity", params: { frequency: 3000, gain: 1.5, q: 0.8 } }, + { type: "limiter", label: "Peak Ceiling", params: { limit: -1.5 } }, ], ), @@ -137,28 +153,34 @@ export const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[] = [ "repair", "Cut Rumble", "Removes traffic, handling and air-conditioning from under a voice.", - [{ type: "highpass", params: { frequency: 100, q: 0.707, poles: "2" } }], + [{ type: "highpass", label: "Cut Rumble", params: { frequency: 100, q: 0.707, poles: "2" } }], ), preset( "room-gate", "repair", "Quiet Between Phrases", "Silences the gaps between words. Room tone under speech stays — this closes the pauses, it does not remove noise.", - [{ type: "gate", params: { threshold: -45, range: -18, ratio: 10, attack: 2, release: 180 } }], + [ + { + type: "gate", + label: "Silence the Gaps", + params: { threshold: -45, range: -18, ratio: 10, attack: 2, release: 180 }, + }, + ], ), preset( "boom-tame", "repair", "Tame Boominess", "Takes out the chestiness of a voice too close to the mic.", - [{ type: "peaking", params: { frequency: 200, gain: -4, q: 1.4 } }], + [{ type: "peaking", label: "Tame Boominess", params: { frequency: 200, gain: -4, q: 1.4 } }], ), preset( "harsh-tame", "repair", "Soften Harshness", "Rounds off a brittle upper-mid. Broad and always-on; sibilance proper wants the measuring version.", - [{ type: "peaking", params: { frequency: 3200, gain: -3, q: 1.6 } }], + [{ type: "peaking", label: "Soften Harshness", params: { frequency: 3200, gain: -3, q: 1.6 } }], ), // ------------------------------------------------------------ character -- @@ -168,18 +190,26 @@ export const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[] = [ "Telephone", "Down the line — the narrow band of a phone call.", [ - ...steep("highpass", 300), - ...steep("lowpass", 3400), - { type: "peaking", params: { frequency: 1200, gain: 6, q: 1.2 } }, - { type: "peaking", params: { frequency: 550, gain: -4, q: 1 } }, - { type: "saturate", params: { type: "tanh", threshold: -18, output: -2 } }, + ...steep("highpass", 300, "Strip the Bass"), + ...steep("lowpass", 3400, "Strip the Treble"), + { type: "peaking", label: "Phone Honk", params: { frequency: 1200, gain: 6, q: 1.2 } }, + { type: "peaking", label: "De-mud", params: { frequency: 550, gain: -4, q: 1 } }, + { + type: "saturate", + label: "Circuit Grit", + params: { type: "tanh", threshold: -18, output: -2 }, + }, ], ), preset("radio-am", "character", "AM Radio", "Narrow, gritty and a little crushed.", [ - { type: "highpass", params: { frequency: 400, q: 0.707, poles: "2" } }, - { type: "lowpass", params: { frequency: 3000, q: 0.707, poles: "2" } }, - { type: "saturate", params: { type: "tanh", threshold: -15, output: -2 } }, - { type: "bitcrush", params: { bits: 10, samples: 1, mix: 0.25 } }, + { type: "highpass", label: "Strip the Bass", params: { frequency: 400, q: 0.707, poles: "2" } }, + { + type: "lowpass", + label: "Strip the Treble", + params: { frequency: 3000, q: 0.707, poles: "2" }, + }, + { type: "saturate", label: "Radio Grit", params: { type: "tanh", threshold: -15, output: -2 } }, + { type: "bitcrush", label: "Crunch", params: { bits: 10, samples: 1, mix: 0.25 } }, ]), preset( "megaphone", @@ -187,11 +217,23 @@ export const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[] = [ "Megaphone", "Shouted through a horn, with the slap that comes with it.", [ - { type: "highpass", params: { frequency: 500, q: 0.707, poles: "2" } }, - { type: "lowpass", params: { frequency: 4000, q: 0.707, poles: "2" } }, - { type: "peaking", params: { frequency: 1800, gain: 8, q: 1.5 } }, - { type: "saturate", params: { type: "hard", threshold: -12, output: -3 } }, - { type: "delay", params: { time: 40, feedback: 0.15, mix: 0.15 } }, + { + type: "highpass", + label: "Strip the Bass", + params: { frequency: 500, q: 0.707, poles: "2" }, + }, + { + type: "lowpass", + label: "Strip the Treble", + params: { frequency: 4000, q: 0.707, poles: "2" }, + }, + { type: "peaking", label: "Horn Honk", params: { frequency: 1800, gain: 8, q: 1.5 } }, + { + type: "saturate", + label: "Overdrive", + params: { type: "hard", threshold: -12, output: -3 }, + }, + { type: "delay", label: "Horn Slap", params: { time: 40, feedback: 0.15, mix: 0.15 } }, ], ), preset( @@ -200,48 +242,86 @@ export const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[] = [ "Tape", "Worn, warm and slightly unsteady, like a played-out cassette.", [ - { type: "lowpass", params: { frequency: 6500, q: 0.707, poles: "2" } }, - { type: "lowshelf", params: { frequency: 120, gain: 2 } }, - { type: "saturate", params: { type: "tanh", threshold: -14, output: 0 } }, - { type: "bitcrush", params: { bits: 12, samples: 2, mix: 0.35 } }, + { type: "lowpass", label: "Tape Rolloff", params: { frequency: 6500, q: 0.707, poles: "2" } }, + { type: "lowshelf", label: "Add Weight", params: { frequency: 120, gain: 2 } }, + { + type: "saturate", + label: "Tape Warmth", + params: { type: "tanh", threshold: -14, output: 0 }, + }, + { type: "bitcrush", label: "Tape Noise", params: { bits: 12, samples: 2, mix: 0.35 } }, // A slow, shallow chorus is what wow and flutter actually are. - { type: "chorus", params: { delay: 6, depth: 0.6, speed: 0.4, mix: 0.15 } }, + { + type: "chorus", + label: "Wow & Flutter", + params: { delay: 6, depth: 0.6, speed: 0.4, mix: 0.15 }, + }, ], ), preset("pa-system", "character", "Tannoy", "Announced across a concourse.", [ - { type: "highpass", params: { frequency: 350, q: 0.707, poles: "2" } }, - { type: "lowpass", params: { frequency: 3500, q: 0.707, poles: "2" } }, - { type: "peaking", params: { frequency: 1500, gain: 5, q: 1.2 } }, - { type: "saturate", params: { type: "tanh", threshold: -16, output: -1 } }, - { type: "reverb", params: { size: 0.5, damping: 0.7, wet: 0.25, dry: 0.8 } }, + { type: "highpass", label: "Strip the Bass", params: { frequency: 350, q: 0.707, poles: "2" } }, + { + type: "lowpass", + label: "Strip the Treble", + params: { frequency: 3500, q: 0.707, poles: "2" }, + }, + { type: "peaking", label: "Tannoy Honk", params: { frequency: 1500, gain: 5, q: 1.2 } }, + { + type: "saturate", + label: "Driver Grit", + params: { type: "tanh", threshold: -16, output: -1 }, + }, + { + type: "reverb", + label: "Concourse", + params: { size: 0.5, damping: 0.7, wet: 0.25, dry: 0.8 }, + }, ]), preset("intercom", "character", "Intercom", "Buzzed through a door panel, squelch and all.", [ - { type: "gate", params: { threshold: -40, range: -30, ratio: 10, attack: 1, release: 120 } }, - { type: "highpass", params: { frequency: 500, q: 0.707, poles: "2" } }, - { type: "lowpass", params: { frequency: 3000, q: 0.707, poles: "2" } }, - { type: "peaking", params: { frequency: 2000, gain: 6, q: 2 } }, - { type: "bitcrush", params: { bits: 11, samples: 1, mix: 0.3 } }, + { + type: "gate", + label: "Squelch", + params: { threshold: -40, range: -30, ratio: 10, attack: 1, release: 120 }, + }, + { type: "highpass", label: "Strip the Bass", params: { frequency: 500, q: 0.707, poles: "2" } }, + { + type: "lowpass", + label: "Strip the Treble", + params: { frequency: 3000, q: 0.707, poles: "2" }, + }, + { type: "peaking", label: "Panel Honk", params: { frequency: 2000, gain: 6, q: 2 } }, + { type: "bitcrush", label: "Crunch", params: { bits: 11, samples: 1, mix: 0.3 } }, ]), // ---------------------------------------------------------------- space -- preset("room-tight", "space", "Tight Room", "A small hard room — presence without wash.", [ - { type: "reverb", params: { size: 0.25, damping: 0.6, wet: 0.18, dry: 0.9 } }, + { + type: "reverb", + label: "Tight Room", + params: { size: 0.25, damping: 0.6, wet: 0.18, dry: 0.9 }, + }, ]), preset( "room-natural", "space", "Natural Room", "Sounds recorded somewhere rather than nowhere.", - [{ type: "reverb", params: { size: 0.5, damping: 0.5, wet: 0.25, dry: 0.85 } }], + [ + { + type: "reverb", + label: "Natural Room", + params: { size: 0.5, damping: 0.5, wet: 0.25, dry: 0.85 }, + }, + ], ), preset("hall", "space", "Hall", "Long and open, for something that should sit far back.", [ - { type: "reverb", params: { size: 0.9, damping: 0.3, wet: 0.4, dry: 0.75 } }, + { type: "reverb", label: "Hall", params: { size: 0.9, damping: 0.3, wet: 0.4, dry: 0.75 } }, ]), preset("slap-echo", "space", "Slap Echo", "One quick repeat — rockabilly vocal, not a wash.", [ - { type: "delay", params: { time: 110, feedback: 0.12, mix: 0.22 } }, + { type: "delay", label: "Slap Echo", params: { time: 110, feedback: 0.12, mix: 0.22 } }, ]), preset("dub-throw", "space", "Dub Throw", "Repeats that trail off well behind the beat.", [ - { type: "delay", params: { time: 375, feedback: 0.55, mix: 0.3 } }, + { type: "delay", label: "Dub Throw", params: { time: 375, feedback: 0.55, mix: 0.3 } }, ]), ]; @@ -289,6 +369,7 @@ export function audioFxPresetNodes( type: node.type, id: mintAudioFxNodeId(running), fromPreset: preset.id, + ...(node.label ? { label: node.label } : {}), enabled: true, params: normalizeAudioFxParams(node.type, node.params), }; diff --git a/packages/studio/src/components/editor/propertyPanelFxSection.test.tsx b/packages/studio/src/components/editor/propertyPanelFxSection.test.tsx index 6428f05c6..8b3ee1230 100644 --- a/packages/studio/src/components/editor/propertyPanelFxSection.test.tsx +++ b/packages/studio/src/components/editor/propertyPanelFxSection.test.tsx @@ -252,6 +252,38 @@ describe("FxSection chain", () => { expect(next.nodes.map((n) => n.type)).toEqual(["reverb", "highpass"]); }); + it("shows a preset node by the job it is doing, not its filter type", () => { + const { host } = mount({ + chain: { + version: 1, + nodes: [ + { + type: "peaking", + id: "a", + label: "Reduce Mud", + enabled: true, + params: defaultAudioFxParams("peaking"), + }, + { + type: "peaking", + id: "b", + label: "Add Clarity", + enabled: true, + params: defaultAudioFxParams("peaking"), + }, + ], + } as HfAudioFxChain, + }); + const names = Array.from(host.querySelectorAll(".hf-fx-node-name")).map((e) => + e.textContent?.trim(), + ); + // Without the label both rows read "Peaking EQ" and an author cannot tell + // which one is cutting and which is lifting. + expect(names).toContain("Reduce Mud"); + expect(names).toContain("Add Clarity"); + expect(names).not.toContain("Peaking EQ"); + }); + it("cannot move the ends past themselves", () => { const { host } = mount({ chain: chainOf("peaking", "reverb") }); const ups = host.querySelectorAll('.hf-fx-move[title="Move up"]'); diff --git a/packages/studio/src/components/editor/propertyPanelFxSection.tsx b/packages/studio/src/components/editor/propertyPanelFxSection.tsx index 1c51a8430..dfab7346b 100644 --- a/packages/studio/src/components/editor/propertyPanelFxSection.tsx +++ b/packages/studio/src/components/editor/propertyPanelFxSection.tsx @@ -591,7 +591,9 @@ function FxNodeRow({ data-fx-node={node.type} >