@hraness/dawg 0.6.0 → 0.7.0

package/core/fx.ts

@@ -12,10 +12,13 @@
  * under `track.fx.<name>` with every parameter stored once enabled.
  */
 
-import { MODAL_LANE_PARAMS } from "./resonators.ts";
+import { MODAL_LANE_PARAMS, WIND_LANE_PARAMS } from "./resonators.ts";
+import { VOCODER_LANE_PARAMS } from "./vocoder.ts";
 import { SYNTH_LANE_PARAMS } from "./synth.ts";
 import { STRING_LANE_PARAMS } from "./strings.ts";
 import { KEYS_LANE_PARAMS } from "./keys.ts";
+import { GRANULAR_LANE_PARAMS } from "./granular.ts";
+import { SING_LANE_PARAMS } from "./sing.ts";
 import {
   FxValidationError,
   normalizeParam,
@@ -48,6 +51,8 @@ export const FX_CHAIN = Object.freeze([
   "filter",
   "djf",
   "autofilter",
+  // 0.7 formant shift at constant pitch (src/audio/effects/formant.ts).
+  "formant",
   "vowel",
   "crush",
   "distort",
@@ -55,9 +60,16 @@ export const FX_CHAIN = Object.freeze([
   "stomp",
   "head",
   "cab",
+  // 0.6.1 shoegaze (src/audio/effects/gaze.ts): a held tremolo arm, the
+  // dominant note's feedback bloom, a volume swell; double (mono in, stereo
+  // out) runs where the chain turns stereo.
+  "wobble",
+  "bloom",
+  "swell",
   "tremolo",
   "compressor",
   "pan",
+  "double",
   "phaser",
   "chorus",
   "leslie",
@@ -102,7 +114,7 @@ const sync = (fallback: number, strudel?: readonly string[]): NumberParam => ({
   default: fallback,
   step: 0.25,
   unit: "beats",
-  doc: "LFO cycle length in beats (tempo-synced); 0 uses rate in Hz",
+  doc: "LFO period in beats (tempo-synced); 0 uses rate in Hz",
   ...(strudel ? { strudel } : {}),
 });
 const mix = (fallback: number, strudel?: readonly string[]): NumberParam => ({
@@ -116,6 +128,25 @@ const mix = (fallback: number, strudel?: readonly string[]): NumberParam => ({
   ...(strudel ? { strudel } : {}),
 });
 
+/** Vowels of the `vowel` effect (src/audio/dsp/formant.ts tables). */
+export const VOWEL_VALUES = Object.freeze([
+  "a",
+  "e",
+  "i",
+  "o",
+  "u",
+  "ae",
+  "aa",
+  "oe",
+  "ue",
+  "y",
+  "uh",
+  "un",
+  "en",
+  "an",
+  "on",
+] as const);
+
 /**
  * Effects stored under `track.fx`. Every number is bounded; enabling an
  * effect stores all of its parameters so a document says exactly what plays.
@@ -123,7 +154,7 @@ const mix = (fallback: number, strudel?: readonly string[]): NumberParam => ({
 export const FX_SPECS = Object.freeze({
   autofilter: {
     label: "auto filter",
-    doc: "filter whose cutoff an LFO sweeps around a centre, optionally opened by the input level",
+    doc: "filter whose cutoff an LFO sweeps around a center, optionally opened by the input level",
     simple: ["type", "cutoff", "depth", "sync", "shape"],
     strudel:
       "none built in (Strudel fakes it with lpf(sine.range(..)).seg(n)); names follow lpf/lpq",
@@ -143,7 +174,7 @@ export const FX_SPECS = Object.freeze({
         step: "log",
         unit: "Hz",
         automate: true,
-        doc: "centre cutoff",
+        doc: "center cutoff",
         strudel: ["lpf", "cutoff"],
       },
       resonance: {
@@ -164,7 +195,7 @@ export const FX_SPECS = Object.freeze({
         step: 0.25,
         unit: "oct",
         automate: true,
-        doc: "sweep width in octaves around the centre",
+        doc: "sweep width in octaves around the center",
       },
       sync: sync(4),
       rate: rate(0.5),
@@ -208,11 +239,30 @@ export const FX_SPECS = Object.freeze({
         default: 0.5,
         step: 0.02,
         automate: true,
-        doc: "0 dark … 0.5 open … 1 thin",
+        doc: "0 dark (20 Hz low-pass) … 0.5 open … 1 thin (10 kHz high-pass)",
         strudel: ["djf"],
       },
     },
   },
+  formant: {
+    label: "formant",
+    doc: "formant shift at constant pitch: moves the spectral envelope (throat or gender knob), any source",
+    simple: ["shift", "mix"],
+    strudel: "none (not a Strudel concept)",
+    params: {
+      shift: {
+        kind: "number",
+        min: -12,
+        max: 12,
+        default: 0,
+        step: 0.5,
+        unit: "st",
+        automate: true,
+        doc: "semitones the formants move (negative deeper, positive smaller); pitch stays",
+      },
+      mix: mix(1),
+    },
+  },
   vowel: {
     label: "vowel",
     doc: "formant filter bank: five band-passes per vowel",
@@ -221,28 +271,30 @@ export const FX_SPECS = Object.freeze({
     params: {
       vowel: {
         kind: "enum",
-        values: [
-          "a",
-          "e",
-          "i",
-          "o",
-          "u",
-          "ae",
-          "aa",
-          "oe",
-          "ue",
-          "y",
-          "uh",
-          "un",
-          "en",
-          "an",
-          "on",
-        ],
+        values: VOWEL_VALUES,
         default: "a",
         doc: "vowel formants (a e i o u plus the extended set)",
         strudel: ["vowel"],
       },
       mix: mix(1),
+      // 0.7: optional morph target; absent keeps the static bank exactly.
+      to: {
+        kind: "enum",
+        values: VOWEL_VALUES,
+        default: "a",
+        optional: true,
+        doc: "vowel to morph toward (absent: no morph)",
+      },
+      morph: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0,
+        step: 0.05,
+        optional: true,
+        automate: true,
+        doc: "position between vowel (0) and to (1), log-frequency formant morph",
+      },
     },
   },
   crush: {
@@ -459,7 +511,7 @@ export const FX_SPECS = Object.freeze({
         step: 1,
         unit: "dB",
         optional: true,
-        doc: "noise gate threshold before the amp (absent: no gate)",
+        doc: "noise gate threshold before the amp (absent: no gate; 0 dB gates all)",
       },
       level: {
         kind: "number",
@@ -490,11 +542,140 @@ export const FX_SPECS = Object.freeze({
         max: 1,
         default: 0.3,
         step: 0.05,
-        doc: "microphone position: 0 centre (bright) .. 1 edge (dark)",
+        doc: "microphone position: 0 center (bright) .. 1 edge (dark)",
       },
       mix: mix(1),
     },
   },
+  wobble: {
+    label: "wobble",
+    doc: "held tremolo arm: slow seeded pitch wow and flutter of the whole track",
+    simple: ["depth", "rate", "drift"],
+    strudel: "(no Strudel equivalent; dawg shoegaze)",
+    params: {
+      depth: {
+        kind: "number",
+        min: 0,
+        max: 100,
+        default: 20,
+        step: 1,
+        unit: "c",
+        automate: true,
+        doc: "peak pitch deviation in cents",
+      },
+      rate: {
+        kind: "number",
+        min: 0.05,
+        max: 8,
+        default: 0.5,
+        step: 0.05,
+        unit: "Hz",
+        doc: "wobble rate",
+      },
+      drift: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.3,
+        step: 0.05,
+        doc: "0 periodic .. 1 wandering (seeded, so every render matches)",
+      },
+    },
+  },
+  bloom: {
+    label: "bloom",
+    doc: "feedback bloom: the top held note grows a singing harmonic",
+    simple: ["amount", "harm", "delay"],
+    strudel: "(no Strudel equivalent; dawg shoegaze)",
+    params: {
+      amount: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.5,
+        step: 0.05,
+        doc: "level of the feedback partial",
+      },
+      harm: {
+        kind: "number",
+        min: 1,
+        max: 4,
+        default: 2,
+        step: 1,
+        doc: "harmonic that feeds back: 1 the note, 2 its octave, 3 the fifth above",
+      },
+      delay: {
+        kind: "number",
+        min: 0,
+        max: 4,
+        default: 0.6,
+        step: 0.05,
+        unit: "s",
+        doc: "how long a note is held before it starts to feed back",
+      },
+      time: {
+        kind: "number",
+        min: 0.05,
+        max: 4,
+        default: 1,
+        step: 0.05,
+        unit: "s",
+        doc: "how fast the feedback grows",
+      },
+    },
+  },
+  swell: {
+    label: "swell",
+    doc: "volume swell: each strum fades in, no pick attack",
+    simple: ["time", "mix"],
+    strudel: "(no Strudel equivalent; dawg shoegaze)",
+    params: {
+      time: {
+        kind: "number",
+        min: 0.01,
+        max: 4,
+        default: 0.4,
+        step: 0.01,
+        unit: "s",
+        doc: "rise time after each onset",
+      },
+      mix: mix(1),
+    },
+  },
+  double: {
+    label: "double",
+    doc: "automatic double tracking: a seeded second take, spread left and right",
+    simple: ["time", "drift", "width"],
+    strudel: "(no Strudel equivalent; dawg shoegaze)",
+    params: {
+      time: {
+        kind: "number",
+        min: 5,
+        max: 60,
+        default: 22,
+        step: 1,
+        unit: "ms",
+        doc: "how late the second take plays",
+      },
+      drift: {
+        kind: "number",
+        min: 0,
+        max: 10,
+        default: 3,
+        step: 0.5,
+        unit: "ms",
+        doc: "how far the second take's timing wanders",
+      },
+      width: {
+        kind: "number",
+        min: 0,
+        max: 1,
+        default: 0.6,
+        step: 0.05,
+        doc: "0 centered .. 1 the two takes hard left and right",
+      },
+    },
+  },
   tremolo: {
     label: "tremolo",
     doc: "volume modulation",
@@ -634,7 +815,7 @@ export const FX_SPECS = Object.freeze({
         default: 1000,
         step: "log",
         unit: "Hz",
-        doc: "sweep centre",
+        doc: "sweep center",
         strudel: ["phasercenter", "phc"],
       },
       sweep: {
@@ -818,7 +999,7 @@ export const TRACK_EFFECT_SPECS = Object.freeze({
         step: "log",
         unit: "Hz",
         automate: true,
-        doc: "cutoff (lpf/hpf) or centre (bpf) frequency",
+        doc: "cutoff (lpf/hpf) or center (bpf) frequency",
         strudel: [
           "lpf",
           "cutoff",
@@ -1006,6 +1187,14 @@ export const CORE_EFFECTS: readonly EffectName[] = Object.freeze([
   "reverb",
 ] as const);
 
+/** The 0.6.1 shoegaze stages (Effects > Shoegaze), in chain order. */
+export const SHOEGAZE_EFFECTS: readonly EffectName[] = Object.freeze([
+  "wobble",
+  "bloom",
+  "swell",
+  "double",
+] as const);
+
 export function isEffectName(value: unknown): value is EffectName {
   return (
     typeof value === "string" &&
@@ -1076,12 +1265,22 @@ export function normalizeFx(input: unknown): TrackFx | undefined {
 
 /** Automation lane name of an `fx` parameter, e.g. `distort-drive`. */
 export type FxLane =
-  `${FxName | "reverb" | "synth" | "string" | "keys" | "modal"}-${string}`;
+  `${FxName | "reverb" | "synth" | "string" | "keys" | "modal" | "grain" | "wind" | "sing" | "vocoder"}-${string}`;
 
 /** Every automatable `fx` parameter as `{ lane, effect, param, spec }`. */
 export const FX_LANES: readonly Readonly<{
   lane: FxLane;
-  effect: FxName | "reverb" | "synth" | "string" | "keys" | "modal";
+  effect:
+    | FxName
+    | "reverb"
+    | "synth"
+    | "string"
+    | "keys"
+    | "modal"
+    | "grain"
+    | "wind"
+    | "sing"
+    | "vocoder";
   param: string;
   spec: NumberParam;
 }>[] = Object.freeze([
@@ -1137,6 +1336,43 @@ export const FX_LANES: readonly Readonly<{
       spec,
     }),
   ),
+  // Granular parameters (core/granular.ts, 0.6.1), read every 32 frames;
+  // grain-scoped ones are latched at each grain's onset.
+  ...GRANULAR_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `grain-${param}` as FxLane,
+      effect: "grain" as const,
+      param,
+      spec,
+    }),
+  ),
+  // Wind parameters (core/winds.ts), read every 32-sample control tick.
+  ...WIND_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `wind-${param}` as FxLane,
+      effect: "wind" as const,
+      param,
+      spec,
+    }),
+  ),
+  // Sing parameters (core/sing.ts, 0.7), read every 32-sample control tick.
+  ...SING_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `sing-${param}` as FxLane,
+      effect: "sing" as const,
+      param,
+      spec,
+    }),
+  ),
+  // Vocoder (core/vocoder.ts, 0.7), read per 32-sample block on the song grid.
+  ...VOCODER_LANE_PARAMS.map(({ param, spec }) =>
+    Object.freeze({
+      lane: `vocoder-${param}` as FxLane,
+      effect: "vocoder" as const,
+      param,
+      spec,
+    }),
+  ),
 ]);
 
 /**
@@ -1183,6 +1419,12 @@ export const FX_PRESETS: Readonly<
       resonance: 0.6,
     },
   },
+  formant: {
+    deep: { shift: -4 },
+    giant: { shift: -8 },
+    bright: { shift: 3 },
+    tiny: { shift: 7 },
+  },
   vowel: { a: { vowel: "a" }, o: { vowel: "o" }, ee: { vowel: "i" } },
   crush: {
     "8-bit": { bits: 8, coarse: 1 },
@@ -1222,6 +1464,24 @@ export const FX_PRESETS: Readonly<
     "1x15": { type: "1x15" },
     di: { type: "di" },
   },
+  wobble: {
+    glide: { depth: 35, rate: 0.4, drift: 0.4 },
+    tape: { depth: 12, rate: 0.8, drift: 0.6 },
+    seasick: { depth: 60, rate: 0.25, drift: 0.2 },
+  },
+  bloom: {
+    octave: { amount: 0.5, harm: 2, delay: 0.6, time: 1 },
+    fifth: { amount: 0.4, harm: 3, delay: 0.8, time: 1.2 },
+    ebow: { amount: 0.8, harm: 1, delay: 0.1, time: 0.6 },
+  },
+  swell: {
+    slow: { time: 0.8 },
+    violin: { time: 0.3 },
+  },
+  double: {
+    tight: { time: 12, drift: 1.5, width: 0.5 },
+    wide: { time: 28, drift: 3, width: 0.7 },
+  },
   tremolo: {
     gentle: { sync: 1, depth: 0.3, shape: "sine" },
     "eighth-chop": { sync: 0.5, depth: 0.9, shape: "square" },
@@ -1390,14 +1650,70 @@ export const RIG_PRESETS: Readonly<
     head: { type: "chime", gain: 3, treble: 7 },
     cab: { type: "2x12", mic: 0.2 },
     compressor: { threshold: -20, ratio: 4, attack: 0.01, release: 0.15 },
+    // 0.6.1: the double-tracked jangle of a twelve-string record. A stored
+    // 0.6.0 jangle (no double) keeps rendering as it was; `rig jangle` again
+    // adds it. The SDK's rig("jangle") keeps its 0.6.0 stages (see
+    // RIG_ADDED), so the printer writes this double out explicitly.
+    double: { time: 12, drift: 1.5, width: 0.5 },
   },
   alt: {
     stomp: { type: "rat", gain: 6, tone: 0.4 },
     head: { type: "crunch", gain: 4 },
     cab: { type: "4x12" },
   },
+  // 0.6.1 shoegaze rigs (src/audio/effects/gaze.ts): fuzz into a held
+  // tremolo arm, a feedback bloom, doubled takes and a long wash.
+  shoegaze: {
+    stomp: { type: "fuzz", gain: 7, tone: 0.45 },
+    head: { type: "chime", gain: 4 },
+    cab: { type: "2x12" },
+    wobble: { depth: 25, rate: 0.4, drift: 0.4 },
+    bloom: { amount: 0.4, harm: 2, delay: 0.6, time: 1 },
+    double: { time: 18, drift: 2.5, width: 0.4 },
+    postgain: { gain: 0.86 },
+    reverb: { mix: 0.35, size: 0.9, fade: 4, predelay: 0.02, dim: 6000 },
+  },
+  glide: {
+    stomp: { type: "face", gain: 5, tone: 0.5 },
+    head: { type: "clean", gain: 4, treble: 5 },
+    cab: { type: "2x12" },
+    wobble: { depth: 35, rate: 0.4, drift: 0.4 },
+    postgain: { gain: 0.8 },
+    reverb: { mix: 0.35, size: 0.7, fade: 2.5, predelay: 0.01, dim: 6000 },
+  },
+  dreampop: {
+    head: { type: "clean", gain: 2, treble: 6 },
+    cab: { type: "1x12" },
+    chorus: { rate: 0.6, depth: 0.3, mix: 0.35 },
+    double: { time: 14, drift: 2, width: 0.4 },
+    postgain: { gain: 1.45 },
+    reverb: { mix: 0.4, size: 0.85, fade: 5, predelay: 0.03, dim: 7000 },
+  },
+  swell: {
+    head: { type: "clean", gain: 3, treble: 5 },
+    cab: { type: "1x12" },
+    swell: { time: 0.5 },
+    postgain: { gain: 1.25 },
+    reverb: { mix: 0.45, size: 0.8, fade: 4, predelay: 0.02, dim: 6500 },
+  },
+  ebow: {
+    stomp: { type: "od", gain: 3, tone: 0.5, level: 3 },
+    head: { type: "lead", gain: 5, mid: 6 },
+    cab: { type: "4x12" },
+    swell: { time: 0.25 },
+    bloom: { amount: 0.8, harm: 1, delay: 0.1, time: 0.6 },
+  },
 });
 
+/**
+ * Effects a rig preset gained after SDK `rig(name)` was fixed. `rig(name)`
+ * leaves them out, so an older song.ts spreading `...rig("jangle")` keeps
+ * its sound; the printer writes them next to the spread, and a stored
+ * track with or without them still reads as that rig.
+ */
+export const RIG_ADDED: Readonly<Record<string, readonly FxName[]>> =
+  Object.freeze({ jangle: Object.freeze(["double"] as FxName[]) });
+
 export function isRigPreset(name: string): boolean {
   return Object.prototype.hasOwnProperty.call(RIG_PRESETS, name);
 }
@@ -1476,8 +1792,11 @@ export function rigReverb(name: string): FxValues | undefined {
 export function rigPresetOf(fx: TrackFx | undefined): string | undefined {
   if (!fx || !RIG_STAGES.some((stage) => fx[stage])) return undefined;
   for (const name of Object.keys(RIG_PRESETS)) {
-    const want = applyRigPreset(undefined, name) ?? {};
-    const keys = new Set([...RIG_STAGES, ...Object.keys(want)]);
+    const want: Partial<Record<FxName, FxValues>> = {
+      ...(applyRigPreset(undefined, name) ?? {}),
+    };
+    for (const added of RIG_ADDED[name] ?? []) delete want[added];
+    const keys = new Set<string>([...RIG_STAGES, ...Object.keys(want)]);
     if (
       [...keys].every(
         (key) =>
@@ -1492,7 +1811,10 @@ export function rigPresetOf(fx: TrackFx | undefined): string | undefined {
 
 /** The effects of `fx` a printed `...rig(name)` stands for. */
 export function rigPresetKeys(name: string): readonly FxName[] {
-  return Object.keys(RIG_PRESETS[name] ?? {}).filter(isFxName);
+  const added = RIG_ADDED[name] ?? [];
+  return Object.keys(RIG_PRESETS[name] ?? {}).filter(
+    (key): key is FxName => isFxName(key) && !added.includes(key),
+  );
 }
 
 export function effectPresetNames(effect: EffectName): readonly string[] {

package/core/granular.ts

@@ -77,6 +77,14 @@ export type TrackGranular = Readonly<{
   release?: number;
   veltone?: number;
   gain?: number;
+  /** Optional (0.6.1): grain rate as a note value on the tempo map. */
+  sync?: GrainSync;
+  /** Optional (0.6.1): snap grain pitches to the scale or chord. */
+  quant?: GrainQuant;
+  /** Optional (0.6.1): one voice; legato notes retarget it. */
+  mono?: boolean;
+  /** Optional (0.6.1): the sustain pedal freezes the head. */
+  pedal?: boolean;
   /**
    * The instrument `grain off` returns to (set when granular turns on;
    * absent: a sampler, a wavetable, or the source's synth).
@@ -102,6 +110,30 @@ const n = (
     ...extra,
   });
 
+export const GRAIN_SYNC_VALUES = Object.freeze([
+  "off",
+  "1/64",
+  "1/32",
+  "1/16t",
+  "1/16",
+  "1/16d",
+  "1/8t",
+  "1/8",
+  "1/8d",
+  "1/4t",
+  "1/4",
+  "1/4d",
+  "1/2",
+  "1/1",
+] as const);
+export type GrainSync = (typeof GRAIN_SYNC_VALUES)[number];
+export const GRAIN_QUANT_VALUES = Object.freeze([
+  "off",
+  "scale",
+  "chord",
+] as const);
+export type GrainQuant = (typeof GRAIN_QUANT_VALUES)[number];
+
 /**
  * The granular parameter table: one row per stored number, enum or flag,
  * in stored key order. It drives validation, the printer, the menu, the
@@ -223,8 +255,63 @@ export const GRANULAR_PARAMS: Readonly<Record<string, ParamSpec>> =
     }),
     veltone: n(0, 1, 0, 0.05, "soft notes are darker"),
     gain: n(0, 4, 1, 0.05, "voice level"),
+    // 0.6.1 grainplay (appended; absent keeps 0.6.0 behaviour).
+    sync: Object.freeze({
+      kind: "enum",
+      values: GRAIN_SYNC_VALUES,
+      default: "off",
+      doc: "grain rate as a note value on the tempo map (off: grain/overlap)",
+    }),
+    quant: Object.freeze({
+      kind: "enum",
+      values: GRAIN_QUANT_VALUES,
+      default: "off",
+      doc: "snap grain pitches to the song scale or the sounding chord",
+    }),
+    mono: Object.freeze({
+      kind: "boolean",
+      default: false,
+      doc: "one voice: legato notes retarget its pitch, the cloud keeps going",
+    }),
+    pedal: Object.freeze({
+      kind: "boolean",
+      default: false,
+      doc: "the sustain pedal freezes the head while it is down",
+    }),
   });
 
+/** Lanes `grain-<param>` (0.6.1): every number row marked `automate`. */
+export const GRANULAR_LANE_PARAMS: readonly Readonly<{
+  param: string;
+  spec: Extract<ParamSpec, { kind: "number" }>;
+}>[] = Object.freeze(
+  Object.entries(GRANULAR_PARAMS)
+    .filter(
+      (entry): entry is [string, Extract<ParamSpec, { kind: "number" }>] =>
+        entry[1].kind === "number" && entry[1].automate === true,
+    )
+    .map(([param, spec]) => Object.freeze({ param, spec })),
+);
+
+/** Note values `sync` takes, with their length in beats. */
+export const GRAIN_SYNC_BEATS: Readonly<Record<string, number>> = Object.freeze(
+  {
+    "1/64": 1 / 16,
+    "1/32": 1 / 8,
+    "1/16t": 1 / 6,
+    "1/16": 1 / 4,
+    "1/16d": 3 / 8,
+    "1/8t": 1 / 3,
+    "1/8": 1 / 2,
+    "1/8d": 3 / 4,
+    "1/4t": 2 / 3,
+    "1/4": 1,
+    "1/4d": 3 / 2,
+    "1/2": 2,
+    "1/1": 4,
+  },
+);
+
 export type GranularParamName = keyof typeof GRANULAR_PARAMS & string;
 
 /** Resolved settings the voice reads (presets and defaults applied). */
@@ -256,6 +343,10 @@ export type GranularSettings = Readonly<{
   release: number;
   veltone: number;
   gain: number;
+  sync: GrainSync;
+  quant: GrainQuant;
+  mono: boolean;
+  pedal: boolean;
 }>;
 
 /**