heygen-com
diff --git a/‎packages/core/package-subpaths.json‎
Lines changed: 6 additions & 0 deletions b/‎packages/core/package-subpaths.json‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎packages/core/package.json‎
Lines changed: 10 additions & 0 deletions b/‎packages/core/package.json‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎packages/core/src/audioFxProfiles.test.ts‎
Lines changed: 122 additions & 0 deletions b/‎packages/core/src/audioFxProfiles.test.ts‎
Lines changed: 122 additions & 0 deletions
diff --git a/‎packages/core/src/audioFxProfiles.ts‎
Lines changed: 209 additions & 0 deletions b/‎packages/core/src/audioFxProfiles.ts‎
Lines changed: 209 additions & 0 deletions
@@ -104,6 +104,12 @@
       "types": "./dist/audioFxCopy.d.ts",
       "environments": ["browser", "bun", "node"]
     },
+    "./audio-fx-profiles": {
+      "source": "./src/audioFxProfiles.ts",
+      "runtime": "./dist/audioFxProfiles.js",
+      "types": "./dist/audioFxProfiles.d.ts",
+      "environments": ["browser", "bun", "node"]
+    },
     "./audio-fx-jobs": {
       "source": "./src/audioFxJobs.ts",
       "runtime": "./dist/audioFxJobs.js",
 
@@ -118,6 +118,12 @@
       "import": "./src/audioFxCopy.ts",
       "types": "./src/audioFxCopy.ts"
     },
+    "./audio-fx-profiles": {
+      "bun": "./src/audioFxProfiles.ts",
+      "node": "./dist/audioFxProfiles.js",
+      "import": "./src/audioFxProfiles.ts",
+      "types": "./src/audioFxProfiles.ts"
+    },
     "./audio-fx-jobs": {
       "bun": "./src/audioFxJobs.ts",
       "node": "./dist/audioFxJobs.js",
@@ -436,6 +442,10 @@
         "import": "./dist/audioFxCopy.js",
         "types": "./dist/audioFxCopy.d.ts"
       },
+      "./audio-fx-profiles": {
+        "import": "./dist/audioFxProfiles.js",
+        "types": "./dist/audioFxProfiles.d.ts"
+      },
       "./audio-fx-jobs": {
         "import": "./dist/audioFxJobs.js",
         "types": "./dist/audioFxJobs.d.ts"
 
@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { defaultAudioFxParams, getAudioFxDef } from "./audioFx.js";
+import { EFFECT_COPY } from "./audioFxCopy.js";
+import {
+  applyAudioFxProfile,
+  audioFxProfileStrength,
+  getAudioFxProfile,
+  HF_AUDIO_FX_PROFILES,
+} from "./audioFxProfiles.js";
+
+describe("derived one-knob profiles", () => {
+  it("covers exactly the effects whose copy asks for one", () => {
+    // `primary: "strength"` is the copy layer saying "this module has no real
+    // parameter that can honestly be its face". A profile missing for one of
+    // those leaves the module opening on all seven of its controls; a profile
+    // for anything else is a knob nobody asked for.
+    const asked = Object.entries(EFFECT_COPY)
+      .filter(([, copy]) => copy.primary === "strength")
+      .map(([id]) => id)
+      .sort();
+    expect(Object.keys(HF_AUDIO_FX_PROFILES).sort()).toEqual(asked);
+  });
+
+  it("derives only parameters the effect actually has", () => {
+    for (const [id, profile] of Object.entries(HF_AUDIO_FX_PROFILES)) {
+      const keys = getAudioFxDef(id)?.params.map((p) => p.key) ?? [];
+      for (const key of profile.derives) {
+        expect(keys, `${id} derives "${key}", which it does not have`).toContain(key);
+      }
+      // And the curve sets everything it claims to.
+      for (const key of profile.derives) {
+        expect(profile.at(0.5)[key], `${id}.${key} is not set at 0.5`).toBeDefined();
+      }
+    }
+  });
+
+  it("stays inside every parameter's declared range across the whole knob", () => {
+    // A profile that runs past a range is not clipped by the panel — it is
+    // clamped on the way into the chain, so the knob would silently stop
+    // meaning anything past that point.
+    for (const [id, profile] of Object.entries(HF_AUDIO_FX_PROFILES)) {
+      const def = getAudioFxDef(id);
+      for (let s = 0; s <= 1.0001; s += 0.05) {
+        const derived = profile.at(s);
+        for (const param of def?.params ?? []) {
+          const value = derived[param.key];
+          if (value === undefined || param.kind !== "number") continue;
+          expect(value, `${id}.${param.key} at ${s.toFixed(2)}`).toBeGreaterThanOrEqual(param.min);
+          expect(value, `${id}.${param.key} at ${s.toFixed(2)}`).toBeLessThanOrEqual(param.max);
+        }
+      }
+    }
+  });
+
+  it("moves every derived parameter monotonically", () => {
+    // The whole promise of one knob: everything under it moves together and in
+    // one direction. A parameter that turns around mid-sweep means the knob
+    // makes the effect stronger and then weaker, which is unusable and is the
+    // failure a hand-tuned table invites.
+    for (const [id, profile] of Object.entries(HF_AUDIO_FX_PROFILES)) {
+      for (const key of profile.derives) {
+        const series: number[] = [];
+        for (let s = 0; s <= 1.0001; s += 0.05) {
+          const value = profile.at(s)[key];
+          if (typeof value === "number") series.push(value);
+        }
+        const up = series.every((v, i) => i === 0 || v >= (series[i - 1] ?? v));
+        const down = series.every((v, i) => i === 0 || v <= (series[i - 1] ?? v));
+        expect(up || down, `${id}.${key} turns around mid-sweep`).toBe(true);
+      }
+    }
+  });
+
+  it("keeps what the author set under Details", () => {
+    // A profile names only the parameters it derives. A compressor's knee and a
+    // saturation's curve type are the author's, and the knob must not reach in
+    // and reset them on the way past.
+    const params = { ...defaultAudioFxParams("compressor"), knee: 6, mix: 0.5 };
+    const next = applyAudioFxProfile("compressor", 0.8, params);
+    expect(next.knee).toBe(6);
+    expect(next.mix).toBe(0.5);
+    expect(next.ratio).not.toBe(params.ratio);
+  });
+
+  it("reads a strength back out of the values a chain stores", () => {
+    // A chain stores mechanism, not the knob — the mechanism is what renders,
+    // so it has to be authoritative. Reopening a project has to put the knob
+    // back where it was.
+    for (const [id, profile] of Object.entries(HF_AUDIO_FX_PROFILES)) {
+      for (const s of [0, 0.25, 0.5, 0.75, 1]) {
+        const params = applyAudioFxProfile(id, s, defaultAudioFxParams(id));
+        expect(audioFxProfileStrength(id, params), `${id} at ${s}`).toBeCloseTo(s, 1);
+      }
+      void profile;
+    }
+  });
+
+  it("passes through the figures the design proposed", () => {
+    // The curves replaced a three-point table, and these are the points it
+    // named. Continuous beats three settings, but not at the price of landing
+    // somewhere else than the design said.
+    expect(getAudioFxProfile("compressor")?.at(0).threshold).toBe(-12);
+    expect(getAudioFxProfile("compressor")?.at(0.5).ratio).toBe(4);
+    expect(getAudioFxProfile("compressor")?.at(1).release).toBe(90);
+    expect(getAudioFxProfile("gate")?.at(0).threshold).toBe(-55);
+    expect(getAudioFxProfile("saturate")?.at(1).threshold).toBe(-18);
+    expect(getAudioFxProfile("reverb")?.at(0).size).toBe(0.25);
+    expect(getAudioFxProfile("reverb")?.at(0.5).size).toBe(0.55);
+    expect(getAudioFxProfile("reverb")?.at(1).size).toBe(0.9);
+    expect(getAudioFxProfile("bitcrush")?.at(1).bits).toBe(6);
+  });
+
+  it("takes a value that is not a number as the middle", () => {
+    // The knob has to land somewhere, and silence is the one answer that is
+    // never right.
+    expect(getAudioFxProfile("reverb")?.at(Number.NaN).size).toBe(
+      getAudioFxProfile("reverb")?.at(0.5).size,
+    );
+    expect(audioFxProfileStrength("reverb", {})).toBe(0.5);
+    expect(audioFxProfileStrength("not-an-effect", {})).toBe(0.5);
+  });
+});
@@ -0,0 +1,209 @@
+/**
+ * One knob over several, for the five effects that cannot honestly have one
+ * real parameter nominated as the control that matters.
+ *
+ * A compressor has seven controls and an author wants one. The rest of the rack
+ * opens on a single real parameter — a filter's frequency, a delay's mix — but
+ * these five have no such parameter: threshold means nothing without ratio,
+ * ratio means nothing without make-up gain, and picking any one of them as the
+ * face of the module would be a knob that lies about what it sets.
+ *
+ * So they get a derived one, exactly as the carve already does: `carveProfile`
+ * turns a single 0..1 into six numbers, and these do the same for the rest of
+ * the rack. `EFFECT_COPY[id].primary` is `"strength"` for precisely these five,
+ * which is what says a module wants this treatment.
+ *
+ * Continuous rather than the three-point tables the design proposed. A table
+ * makes gentle/middle/strong three settings an author picks between, and the
+ * thing being modelled is not three settings — it is one axis, and the carve's
+ * knob has proved that reads. The proposal's figures survive as the anchors:
+ * each curve passes through them at 0, 0.5 and 1.
+ *
+ * Every number below is expressed in the parameter's own registry unit and then
+ * clamped by `normalizeAudioFxParams` on the way into the chain, so a profile
+ * cannot ship a value the effect would refuse.
+ */
+
+import { normalizeAudioFxParams, type HfAudioFxParamValues } from "./audioFx.js";
+
+/** 0..1, whatever arrives. NaN reads as the middle rather than as silence. */
+function clamp01(strength: number): number {
+  return Number.isFinite(strength) ? Math.min(1, Math.max(0, strength)) : 0.5;
+}
+
+/** Two decimal places, so a derived value reads as a setting and not as float noise. */
+function to2(value: number): number {
+  return Number(value.toFixed(2));
+}
+
+export interface HfAudioFxProfile {
+  /** What the one knob is called. Never the DSP name of anything it drives. */
+  label: string;
+  /** What the two ends sound like — the question an author actually has. */
+  ends: { low: string; high: string };
+  /** The parameters it sets. Everything else keeps the effect's own default. */
+  derives: readonly string[];
+  /** The mechanism values at a given strength. */
+  at(strength: number): HfAudioFxParamValues;
+}
+
+export const HF_AUDIO_FX_PROFILES: Record<string, HfAudioFxProfile> = {
+  compressor: {
+    label: "Evenness",
+    ends: { low: "Barely touched", high: "Very even, quite squashed" },
+    derives: ["threshold", "ratio", "attack", "release", "makeup"],
+    at(strength) {
+      const s = clamp01(strength);
+      return {
+        // Lower threshold and higher ratio together: more of the signal is
+        // caught, and what is caught is held harder. Moving one without the
+        // other is the pair of knobs this exists to stop an author meeting.
+        threshold: to2(-12 - s * 18),
+        ratio: to2(2 + s * 4),
+        // Faster as it gets firmer, because a firm compressor that lets peaks
+        // through is doing the audible half of its job and not the useful half.
+        attack: to2(25 - s * 20),
+        release: to2(300 - s * 210),
+        // Compression makes things quieter; this is the level put back, and it
+        // has to rise with the amount taken off or the knob reads as a volume
+        // control that goes the wrong way.
+        //
+        // Solved from measurement rather than proposed, and it is not linear:
+        // gain reduction accelerates as the threshold drops and the ratio rises
+        // together, so a straight line is too loud in the middle and too quiet
+        // at the top. The design's 1/3/7 dB left the track +0.9 dB at rest,
+        // +1.3 dB at the middle and −2.5 dB at full. Numbers in
+        // `~/audio-fx-profiles-ab/README.md`.
+        makeup: to2(s * s * 9.5),
+      };
+    },
+  },
+
+  gate: {
+    label: "Tightness",
+    ends: { low: "Only true silence", high: "Cuts quiet words too" },
+    derives: ["threshold", "range", "release"],
+    at(strength) {
+      const s = clamp01(strength);
+      return {
+        threshold: to2(-55 + s * 23),
+        // How far the gaps are ducked, never to silence: a room that stops dead
+        // between sentences sounds broken rather than clean.
+        range: to2(-10 - s * 20),
+        // Release has to come along, which the design did not have — and it
+        // dominates: swept against a fixed threshold and range, the gaps move
+        // 0.2 dB at 140 ms and 13.4 dB at 10 ms. Left at the effect's 100 ms
+        // default the gate was very nearly inaudible whatever else it was told.
+        //
+        // Measured on narration, speech level is unmoved (−24.0 dB) at every
+        // release down to 10 ms, so the usual reason to stay slow — clipping
+        // word endings — does not bite on this material at these thresholds.
+        release: to2(120 - s * 105),
+      };
+    },
+  },
+
+  saturate: {
+    label: "Warmth",
+    ends: { low: "Just a sheen", high: "Openly distorted" },
+    derives: ["threshold", "output"],
+    at(strength) {
+      const s = clamp01(strength);
+      return {
+        // Drive: the lower the threshold, the more of the signal meets the
+        // curve.
+        threshold: to2(-3 - s * 15),
+        // Up, not down — which reverses the design's figure, on the measurement
+        // that motivated taking one. A soft clipper at -18 dB threshold IS a
+        // limiter at -18 dB: peak fell to 0.089 from 0.496 and RMS almost
+        // halved, so the proposed trim of −3 dB made "warmer" mean "much
+        // quieter" and an author would have heard the level, not the warmth.
+        // Accelerating for the same reason as the compressor's make-up.
+        output: to2(s * s * 2.8),
+      };
+    },
+  },
+
+  reverb: {
+    label: "Space",
+    ends: { low: "A small tight room", high: "A big open hall" },
+    derives: ["size", "wet", "dry"],
+    at(strength) {
+      const s = clamp01(strength);
+      return {
+        // Anchored at the design's three figures — 0.25 / 0.55 / 0.90 — which a
+        // single linear run cannot hit, because 0.55 is not their midpoint.
+        size: to2(s <= 0.5 ? 0.25 + s * 0.6 : 0.55 + (s - 0.5) * 0.7),
+        wet: to2(0.15 + s * 0.3),
+        // Dry comes down as wet goes up, but not by the same amount: the two
+        // legs sum, and matching them exactly makes a big room quieter than a
+        // small one instead of further away.
+        dry: to2(0.92 - s * 0.2),
+      };
+    },
+  },
+
+  bitcrush: {
+    label: "Crush",
+    ends: { low: "Slightly gritty", high: "Destroyed" },
+    derives: ["bits", "samples", "mix"],
+    at(strength) {
+      const s = clamp01(strength);
+      return {
+        // Fewer steps and longer holds. `bits` runs DOWN as the knob runs up,
+        // which is why it cannot be the module's face on its own.
+        bits: to2(14 - s * 8),
+        samples: Math.max(1, Math.round(1 + s * 3)),
+        mix: to2(0.25 + s * 0.75),
+      };
+    },
+  },
+};
+
+export function getAudioFxProfile(type: string): HfAudioFxProfile | undefined {
+  return HF_AUDIO_FX_PROFILES[type];
+}
+
+/**
+ * The parameters a profile sets at this strength, merged over what is there.
+ *
+ * Merged rather than replacing: a profile names only the parameters it derives,
+ * and the rest — a compressor's knee, a saturation's curve type — are the
+ * author's to set under Details and must survive the knob moving.
+ */
+export function applyAudioFxProfile(
+  type: string,
+  strength: number,
+  params: HfAudioFxParamValues,
+): HfAudioFxParamValues {
+  const profile = getAudioFxProfile(type);
+  if (!profile) return params;
+  return normalizeAudioFxParams(type, { ...params, ...profile.at(strength) });
+}
+
+/**
+ * The strength a set of parameters reads as, by inverting the profile's own
+ * curve on its most characteristic parameter.
+ *
+ * A chain stores mechanism values, not the knob — the same contract
+ * `normalizeCarveSettings` has, and for the same reason: the mechanism is what
+ * renders, so it is what must be authoritative. Reading the knob back means one
+ * parameter has to be nominated as the one that says most about intent.
+ *
+ * A hand-edited chain therefore lands the knob at the nearest strength that
+ * would have produced its most telling value, which is the honest answer — the
+ * alternative is a knob parked at a default while the effect is set to
+ * something else entirely.
+ */
+export function audioFxProfileStrength(type: string, params: HfAudioFxParamValues): number {
+  const profile = getAudioFxProfile(type);
+  if (!profile) return 0.5;
+  const key = profile.derives[0];
+  if (key === undefined) return 0.5;
+  const value = params[key];
+  if (typeof value !== "number") return 0.5;
+  const low = profile.at(0)[key];
+  const high = profile.at(1)[key];
+  if (typeof low !== "number" || typeof high !== "number" || low === high) return 0.5;
+  return to2(Math.min(1, Math.max(0, (value - low) / (high - low))));
+}