@hyperframes/core 0.7.107 → 0.7.109

package/dist/audioFxEq.js

@@ -0,0 +1,153 @@
+/**
+ * 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, } from "./audioFx.js";
+/**
+ * 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 = [
+    { 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 = [
+    { 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.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, eqId, chain) {
+    const out = [];
+    let running = { ...chain, nodes: [...chain.nodes] };
+    for (const band of bands) {
+        const made = {
+            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, bands = HF_AUDIO_EQ_3) {
+    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) {
+    const seen = [];
+    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, eqId) {
+    const out = [];
+    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, eqId, bandName, gain) {
+    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, eqId) {
+    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) {
+    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;
+//# sourceMappingURL=audioFxEq.js.map

package/dist/audioFxEq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioFxEq.js","sourceRoot":"","sources":["../src/audioFxEq.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,GAGvB,MAAM,cAAc,CAAC;AAatB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAA6B;IACrD,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE;IAC3D,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE;IACrE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE;CAChE,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAA6B;IACrD,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE;IAC3D,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;IAClE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE;IACrE,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;IACpE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE;CAC7D,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,EAAU,EAAU,EAAE,CACvC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,oBAAoB,EAAE,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhG,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAC1B,KAA+B,EAC/B,IAAY,EACZ,KAAqB;IAErB,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,IAAI,OAAO,GAAmB,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;IACpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAkB;YAC1B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,EAAE,EAAE,iBAAiB,CAAC,OAAO,CAAC;YAC9B,MAAM,EAAE,IAAI;YACZ,oEAAoE;YACpE,uEAAuE;YACvE,KAAK,EAAE,IAAI,CAAC,IAAI;YAChB,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE;gBACxC,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;gBAC1B,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACvD,CAAC;SACH,CAAC;QACF,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,OAAO,GAAG,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,UAAU,CACxB,KAAqB,EACrB,QAAkC,aAAa;IAE/C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC;QAAE,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;IAC7D,OAAO;QACL,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE;QACjF,IAAI;KACL,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,UAAU,CAAC,KAAqB;IAC9C,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAqB,EAAE,IAAY;IAClE,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;YAAE,SAAS;QACnC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;YAAE,SAAS;QAC/F,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI;YAC7B,SAAS,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;YACjD,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACzC,GAAG,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CAChC,KAAqB,EACrB,IAAY,EACZ,QAAgB,EAChB,IAAY;IAEZ,OAAO;QACL,GAAG,KAAK;QACR,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAC9B,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ;YAC7C,CAAC,CAAC;gBACE,GAAG,IAAI;gBACP,MAAM,EAAE,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE;oBACxC,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;oBACtB,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC;iBACtB,CAAC;aACH;YACH,CAAC,CAAC,IAAI,CACT;KACF,CAAC;AACJ,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,aAAa,CAAC,KAAqB,EAAE,IAAY;IAC/D,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAA+B;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,4BAA4B,CAAC;IAC5D,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACvF,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAyB,CAAC"}

package/dist/audioFxJobs.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Named jobs: the range IS the module.
+ *
+ * "Shape One Range" has three controls — where, how much, how wide — and no
+ * honest way to nominate one of them as the knob that matters. Nominating *how
+ * much* is incoherent, because boosting an unspecified frequency means nothing:
+ * the range is the first decision, not the second.
+ *
+ * So the menu offers the decision instead of the machine. Each job is a peaking
+ * filter with its frequency already chosen — Reduce Mud, Add Clarity, Soften
+ * Harshness — and picking the module IS picking the range, which makes one knob
+ * honest rather than a simplification hiding the real choice. It also dissolves
+ * the duplicate-name problem at the root: a preset that cuts mud and then lifts
+ * clarity used to read "Shape One Range" twice with nothing to tell them apart.
+ *
+ * Every job here is one the preset catalogue already ships, at the settings it
+ * ships them with, so this names the vocabulary the presets were written in
+ * rather than inventing a second one. Reasoning in
+ * `plans/audio-fx-ux/README.md` §"The hole in the single-knob rule".
+ *
+ * The frequency is a starting point, not a cage — it is an ordinary peaking node
+ * underneath, and Details opens on the same three controls it always had.
+ */
+import { type HfAudioFxChain, type HfAudioFxNode, type HfAudioFxParamValues } from "./audioFx.js";
+export interface HfAudioFxJob {
+    id: string;
+    /** What the rack calls the node this makes. */
+    label: string;
+    /** The complaint that leads here, in the author's words. */
+    does: string;
+    /** The registry effect underneath. */
+    type: string;
+    /** Where it acts, and how hard — the decision the author is spared. */
+    params: HfAudioFxParamValues;
+}
+/**
+ * Ordered low to high, which is the order an author hears them in: weight and
+ * mud at the bottom, clarity and harshness at the top.
+ */
+export declare const HF_AUDIO_FX_JOBS: readonly HfAudioFxJob[];
+export declare function getAudioFxJob(id: string): HfAudioFxJob | undefined;
+/** Effect ids the job list covers, which the add menu offers as jobs instead. */
+export declare const HF_AUDIO_FX_JOB_TYPES: ReadonlySet<string>;
+/**
+ * The node a job adds: an ordinary effect carrying the job's name.
+ *
+ * `label` is the field a preset already uses to name a node for the work it
+ * does, so a job needs nothing new — and a job node and a preset node are
+ * indistinguishable afterwards, which is right. They are the same idea.
+ */
+export declare function audioFxJobNode(job: HfAudioFxJob, chain: HfAudioFxChain): HfAudioFxNode;
+//# sourceMappingURL=audioFxJobs.d.ts.map

package/dist/audioFxJobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioFxJobs.d.ts","sourceRoot":"","sources":["../src/audioFxJobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,YAAY,EAoCnD,CAAC;AAEF,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAElE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAErD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,GAAG,aAAa,CAatF"}

package/dist/audioFxJobs.js

@@ -0,0 +1,92 @@
+/**
+ * Named jobs: the range IS the module.
+ *
+ * "Shape One Range" has three controls — where, how much, how wide — and no
+ * honest way to nominate one of them as the knob that matters. Nominating *how
+ * much* is incoherent, because boosting an unspecified frequency means nothing:
+ * the range is the first decision, not the second.
+ *
+ * So the menu offers the decision instead of the machine. Each job is a peaking
+ * filter with its frequency already chosen — Reduce Mud, Add Clarity, Soften
+ * Harshness — and picking the module IS picking the range, which makes one knob
+ * honest rather than a simplification hiding the real choice. It also dissolves
+ * the duplicate-name problem at the root: a preset that cuts mud and then lifts
+ * clarity used to read "Shape One Range" twice with nothing to tell them apart.
+ *
+ * Every job here is one the preset catalogue already ships, at the settings it
+ * ships them with, so this names the vocabulary the presets were written in
+ * rather than inventing a second one. Reasoning in
+ * `plans/audio-fx-ux/README.md` §"The hole in the single-knob rule".
+ *
+ * The frequency is a starting point, not a cage — it is an ordinary peaking node
+ * underneath, and Details opens on the same three controls it always had.
+ */
+import { defaultAudioFxParams, mintAudioFxNodeId, normalizeAudioFxParams, } from "./audioFx.js";
+/**
+ * Ordered low to high, which is the order an author hears them in: weight and
+ * mud at the bottom, clarity and harshness at the top.
+ */
+export const HF_AUDIO_FX_JOBS = [
+    {
+        id: "tame-boominess",
+        label: "Tame Boominess",
+        does: "Too much low-end body — it booms.",
+        type: "peaking",
+        params: { frequency: 200, gain: -4, q: 1.4 },
+    },
+    {
+        id: "reduce-mud",
+        label: "Reduce Mud",
+        does: "Muffled, like it is behind cardboard.",
+        type: "peaking",
+        params: { frequency: 250, gain: -3, q: 1.2 },
+    },
+    {
+        id: "reduce-boxiness",
+        label: "Reduce Boxiness",
+        does: "Sounds like a small room, or a box.",
+        type: "peaking",
+        params: { frequency: 400, gain: -3, q: 1.4 },
+    },
+    {
+        id: "add-clarity",
+        label: "Add Clarity",
+        does: "It is hard to make out — it sits back.",
+        type: "peaking",
+        params: { frequency: 3000, gain: 2.5, q: 1 },
+    },
+    {
+        id: "soften-harshness",
+        label: "Soften Harshness",
+        does: "Harsh and tiring to listen to.",
+        type: "peaking",
+        params: { frequency: 3200, gain: -3, q: 1.6 },
+    },
+];
+export function getAudioFxJob(id) {
+    return HF_AUDIO_FX_JOBS.find((job) => job.id === id);
+}
+/** Effect ids the job list covers, which the add menu offers as jobs instead. */
+export const HF_AUDIO_FX_JOB_TYPES = new Set(HF_AUDIO_FX_JOBS.map((job) => job.type));
+/**
+ * The node a job adds: an ordinary effect carrying the job's name.
+ *
+ * `label` is the field a preset already uses to name a node for the work it
+ * does, so a job needs nothing new — and a job node and a preset node are
+ * indistinguishable afterwards, which is right. They are the same idea.
+ */
+export function audioFxJobNode(job, chain) {
+    return {
+        type: job.type,
+        id: mintAudioFxNodeId(chain),
+        enabled: true,
+        label: job.label,
+        // Through the registry, so a job cannot ship a value the effect would clamp
+        // or a key it does not have.
+        params: normalizeAudioFxParams(job.type, {
+            ...defaultAudioFxParams(job.type),
+            ...job.params,
+        }),
+    };
+}
+//# sourceMappingURL=audioFxJobs.js.map

package/dist/audioFxJobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioFxJobs.js","sourceRoot":"","sources":["../src/audioFxJobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,GAIvB,MAAM,cAAc,CAAC;AActB;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA4B;IACvD;QACE,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,gBAAgB;QACvB,IAAI,EAAE,mCAAmC;QACzC,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE;KAC7C;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,uCAAuC;QAC7C,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE;KAC7C;IACD;QACE,EAAE,EAAE,iBAAiB;QACrB,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,qCAAqC;QAC3C,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE;KAC7C;IACD;QACE,EAAE,EAAE,aAAa;QACjB,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,wCAAwC;QAC9C,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE;KAC7C;IACD;QACE,EAAE,EAAE,kBAAkB;QACtB,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,gCAAgC;QACtC,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE;KAC9C;CACF,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,qBAAqB,GAAwB,IAAI,GAAG,CAC/D,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CACxC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAiB,EAAE,KAAqB;IACrE,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,EAAE,EAAE,iBAAiB,CAAC,KAAK,CAAC;QAC5B,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,4EAA4E;QAC5E,6BAA6B;QAC7B,MAAM,EAAE,sBAAsB,CAAC,GAAG,CAAC,IAAI,EAAE;YACvC,GAAG,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC;YACjC,GAAG,GAAG,CAAC,MAAM;SACd,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/audioFxPresets.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Named starting points for the FX rack.
+ *
+ * Voice carve turned a pile of effects into one understandable feature. These
+ * do the same for the cases an analysis cannot decide: a preset is a chain
+ * somebody already tuned, applied in one click and editable immediately
+ * afterwards.
+ *
+ * A preset is DATA, deliberately. Applying one writes ordinary nodes into
+ * `data-fx-chain` — the same nodes hand-building would produce — so there is no
+ * second code path to keep in agreement with the rack, nothing new in the
+ * render, and no failure mode the chain does not already have. The author can
+ * see everything that was written on their behalf and change any of it.
+ *
+ * Only the parameters a preset actually means are listed; `normalizeAudioFxParams`
+ * fills the rest from the effect's own defaults. That keeps each entry readable
+ * as an intent rather than a dump of every knob.
+ *
+ * Node ORDER is load-bearing — the chain is serial, so a limiter first and a
+ * limiter last are different sounds. Every preset below runs
+ * subtractive filtering → dynamics → tone → character → limiter, the order
+ * `skills/hyperframes-audio` already teaches.
+ */
+import { type HfAudioFxChain, type HfAudioFxNode, type HfAudioFxParamValues } from "./audioFx.js";
+/**
+ * Which shelf of the menu a preset sits on.
+ *
+ * Deliberately NOT the effect registry's own `group` (filter/dynamics/…): that
+ * groups by what an effect *is*, and an author picking a preset is shopping for
+ * what they *want*. "Telephone" is filters and saturation; nobody looks for it
+ * under either.
+ */
+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;
+}
+export interface HfAudioFxPreset {
+    id: string;
+    label: string;
+    family: HfAudioFxPresetFamily;
+    /** One line, in the author's language — what it does, not which effects it uses. */
+    description: string;
+    nodes: readonly HfAudioFxPresetNode[];
+}
+export declare const HF_AUDIO_FX_PRESETS: readonly HfAudioFxPreset[];
+export declare const HF_AUDIO_FX_PRESET_IDS: readonly string[];
+export declare function getAudioFxPreset(id: string): HfAudioFxPreset | undefined;
+/** Menu order: the shelves, in the order the panel lists them. */
+export declare const HF_AUDIO_FX_PRESET_FAMILIES: readonly HfAudioFxPresetFamily[];
+export declare function audioFxPresetsByFamily(family: HfAudioFxPresetFamily): HfAudioFxPreset[];
+/**
+ * Realise a preset as nodes ready to splice into `chain`.
+ *
+ * Ids are minted against the chain the nodes are joining, not against the
+ * preset, so applying the same preset twice cannot collide — and every node
+ * gets one, because an automation lane addresses its effect by id and a node
+ * without one can never be automated.
+ *
+ * Params are normalised here rather than at apply time: a preset that names a
+ * value the effect would clamp should land in the file as the value that will
+ * actually be rendered, so the rack never shows a number the graph is not using.
+ */
+export declare function audioFxPresetNodes(preset: HfAudioFxPreset, chain: HfAudioFxChain): HfAudioFxNode[];
+/**
+ * The chain after applying a preset.
+ *
+ * Appends by default: stacking Telephone onto an already-cleaned voice is a
+ * real thing to want, and replacing silently would throw away work. Re-applying
+ * a preset that is already present replaces ITS OWN nodes in place instead of
+ * adding a second copy — which is what `fromPreset` is for, and mirrors how the
+ * carve replaces its own bands rather than stacking new ones on hand-added
+ * effects.
+ */
+export declare function applyAudioFxPreset(chain: HfAudioFxChain, preset: HfAudioFxPreset, options?: {
+    replaceChain?: boolean;
+}): HfAudioFxChain;
+/** Every preset whose nodes are still present, for the rack's group braces. */
+export declare function activeAudioFxPresetIds(chain: HfAudioFxChain): string[];
+//# sourceMappingURL=audioFxPresets.d.ts.map

package/dist/audioFxPresets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioFxPresets.d.ts","sourceRoot":"","sources":["../src/audioFxPresets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAEtB;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAE/E,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,qBAAqB,CAAC;IAC9B,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACvC;AAwBD,eAAO,MAAM,mBAAmB,EAAE,SAAS,eAAe,EAoRzD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAyC,CAAC;AAI9F,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAExE;AAED,kEAAkE;AAClE,eAAO,MAAM,2BAA2B,EAAE,SAAS,qBAAqB,EAKvE,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,EAAE,CAEvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,cAAc,GACpB,aAAa,EAAE,CAiBjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GACvC,cAAc,CAoBhB;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,EAAE,CAMtE"}