@hraness/dawg 0.7.0 → 0.8.0

package/src/tui/fader.ts

@@ -9,7 +9,8 @@
  * field, so repeated nudges replace one staged edit and Enter keeps them
  * all as one revision.
  */
-import type { DrawerField, DrawerView } from "../../tui/drawer.ts";
+import type { DrawerAside, DrawerField, DrawerView } from "../../tui/drawer.ts";
+import type { KnobIndex } from "../../tui/knobs.ts";
 import {
   KEY_BACKSPACE,
   KEY_BACKTAB,
@@ -488,6 +489,14 @@ export const FADER_HINT =
  * The hint for a field the loop cannot stage (tempo, meter, loop length):
  * each step is a new revision, so there is nothing to keep or revert.
  */
+/** The knob front page (design §8.6): the four knobs, then Tab for all. */
+export const KNOB_FADER_HINT =
+  "↑↓ knob · ←→ turn · tab all · enter keep · ⇧ coarse · x reset · esc revert";
+
+/** Every param behind Tab: Tab goes back to the four knobs. */
+export const ALL_FADER_HINT =
+  "←→ adjust · ↑↓ param · tab knobs · enter keep · ⇧ coarse · x reset · esc revert";
+
 export const FADER_HINT_AT_ONCE =
   "←→ adjust · applies at once · x reset · 0-9 type · ↑↓ param · ⇧←→ coarse · [ ] fine · esc back";
 
@@ -511,6 +520,8 @@ export function drawerView(
     hint?: string;
     /** The focused field applies at once (cannot stage on the loop). */
     atOnce?: boolean | undefined;
+    /** The drawer has a knob page: which side of Tab is up. */
+    knobs?: "knobs" | "all" | undefined;
   },
 ): DrawerView {
   const before = new Map(committed.map((field) => [field.label, field]));
@@ -528,6 +539,7 @@ export function drawerView(
       return {
         kind: "choice",
         label: field.label,
+        knob: knobOf(field),
         options: field.options,
         index,
         committedIndex:
@@ -550,6 +562,7 @@ export function drawerView(
     return {
       kind: "number",
       label: field.label,
+      knob: knobOf(field),
       text,
       committed: changed ? wasText : undefined,
       position:
@@ -576,10 +589,50 @@ export function drawerView(
     dirty: options.dirty,
     badge: options.dirty ? stagedBadge(staged) : undefined,
     status: options.status,
-    hint: options.hint ?? (options.atOnce ? FADER_HINT_AT_ONCE : FADER_HINT),
+    hint:
+      options.hint ??
+      (options.knobs
+        ? (options.knobs === "knobs" ? KNOB_FADER_HINT : ALL_FADER_HINT)
+            .replace(
+              "enter keep",
+              options.atOnce ? "applies at once" : "enter keep",
+            )
+            .replace("esc revert", options.atOnce ? "esc back" : "esc revert")
+        : options.atOnce
+          ? FADER_HINT_AT_ONCE
+          : FADER_HINT),
   };
 }
 
+/**
+ * The drawer's side list: every param on the page with its value, each one
+ * a knob also drives wearing that knob (matched by label).
+ */
+export function drawerAside(
+  page: readonly FaderSpec[],
+  knobs: readonly FaderSpec[],
+): DrawerAside[] {
+  const knobByLabel = new Map(
+    knobs.map((field) => [field.label, knobOf(field)] as const),
+  );
+  return page.map((field) => ({
+    label: field.label,
+    text:
+      field.kind === "choice"
+        ? field.value
+        : field.value === undefined
+          ? (field.off ?? "off")
+          : field.format(field.value),
+    knob: knobByLabel.get(field.label),
+  }));
+}
+
+/** A knob field's knob (0 blue … 3 orange); plain rows have none. */
+function knobOf(field: FaderSpec): KnobIndex | undefined {
+  const knob = (field as FaderSpec & { knob?: KnobIndex }).knob;
+  return knob;
+}
+
 /** `A/B: 1 change staged · enter keep · esc revert`. */
 export function stagedBadge(count: number): string {
   const n = Math.max(1, count);

package/src/tui/knob-fields.ts

@@ -0,0 +1,107 @@
+/**
+ * The four knobs of a page as fader fields: each path of a KNOB_MAPS row
+ * (src/tui/knob-map.ts) resolved in the live Ctrl-K tree, so a knob turns
+ * exactly what that menu row turns and runs the same typed command.
+ */
+import type { KnobIndex } from "../../tui/knobs.ts";
+import type { FaderSpec } from "./fader.ts";
+import { knobMap, type KnobMap } from "./knob-map.ts";
+import {
+  faderSpecs,
+  rootNodes,
+  type MenuContext,
+  type MenuNode,
+} from "./menu.ts";
+
+export type KnobField = FaderSpec & { knob: KnobIndex };
+
+const norm = (text: string) => text.trim().toLowerCase();
+
+function matches(node: MenuNode, segment: string): boolean {
+  const want = norm(segment);
+  if (want.endsWith("*"))
+    return node.kind === "menu" && norm(node.id).startsWith(want.slice(0, -1));
+  if (node.kind === "menu" && norm(node.id) === want) return true;
+  return norm(node.label) === want;
+}
+
+/** The row a knob path reaches from the root, or undefined. */
+export function resolveKnobPath(
+  context: MenuContext,
+  path: string,
+): MenuNode | undefined {
+  let nodes: readonly MenuNode[] = rootNodes(context);
+  let found: MenuNode | undefined;
+  for (const segment of path.split("/")) {
+    found = nodes.find((node) => matches(node, segment));
+    if (!found) {
+      // Effects beyond the first few live under "more effects".
+      const more = nodes.find(
+        (node) => node.kind === "menu" && node.id === "more effects",
+      );
+      if (more?.kind === "menu")
+        found = more.build(context).find((node) => matches(node, segment));
+    }
+    if (!found) return undefined;
+    nodes = found.kind === "menu" ? found.build(context) : [];
+  }
+  return found;
+}
+
+/**
+ * The knob label: the row's own label, or `reverb mix` when the row lives in
+ * another effect than the page's (the mixer's reverb send).
+ */
+function knobLabel(page: string, path: string, label: string): string {
+  const segments = path.split("/");
+  if (segments[0] === "effects" && segments.length >= 3) {
+    const effect = segments[1]!;
+    if (page !== `fx:${effect}`) return `${effect} ${label}`;
+  }
+  return label;
+}
+
+/**
+ * The four slots of `page` for `context`: a field per slot whose path
+ * resolves to a number or choice row, else undefined (drawn `·`, skipped).
+ * A page without a row (an effect not in the table) derives one from
+ * `fallback`: its first three number rows, and `mix` on orange.
+ */
+export function knobSlots(
+  context: MenuContext,
+  page: string,
+  fallback: readonly FaderSpec[] = [],
+): (KnobField | undefined)[] {
+  const map: KnobMap | undefined = knobMap(page);
+  if (!map) {
+    const numbers = fallback.filter(
+      (field) => field.kind === "number" && field.label !== "mix",
+    );
+    const mix = fallback.find((field) => field.label === "mix");
+    return [numbers[0], numbers[1], numbers[2], mix].map((field, index) =>
+      field ? { ...field, knob: index as KnobIndex } : undefined,
+    );
+  }
+  return map.map((path, index) => {
+    if (!path || path.startsWith("@") || !path.includes("/")) return undefined;
+    const node = resolveKnobPath(context, path);
+    const spec = node ? faderSpecs([node])[0] : undefined;
+    if (!spec) return undefined;
+    return {
+      ...spec,
+      label: knobLabel(page, path, spec.label),
+      knob: index as KnobIndex,
+    } as KnobField;
+  });
+}
+
+/** The present knobs of `page`, in knob order: the drawer's front page. */
+export function knobFields(
+  context: MenuContext,
+  page: string,
+  fallback: readonly FaderSpec[] = [],
+): KnobField[] {
+  return knobSlots(context, page, fallback).filter(
+    (field): field is KnobField => field !== undefined,
+  );
+}

package/src/tui/knob-map.ts

@@ -0,0 +1,198 @@
+/**
+ * Which value each of the four knobs turns, per page (design §7.3): one
+ * table, read by the fader drawer's front page, the mixer page and euclid.
+ * A row is four menu paths from the Ctrl-K root (`sound/attack`,
+ * `effects/reverb/mix`, `mix/volume`): segments match a submenu's id or a
+ * row's label, and `more effects` is searched on the way. An undefined slot
+ * shows as `·` and ↑↓ skips it.
+ *
+ * The rule (tui/knobs.ts): blue moves, green sizes, white shapes, orange
+ * level. Pages not in the table (an effect without a row) derive one: their
+ * first three number rows on blue, green and white, and `mix` on orange.
+ *
+ * Data, not code, so the patcher can map a patch's macros onto the same
+ * four knobs by adding rows (`patch:<id>`), and a test checks every path
+ * resolves for every instrument family. A `*` at the end of a segment
+ * matches the first submenu whose id starts with it (`sample:*`).
+ */
+import { isWavetableInstrument, type Track } from "../../core/score.ts";
+import { isDrumInstrument } from "../../core/drums.ts";
+import {
+  isElectricFamily,
+  isKeysFamily,
+  isOrganFamily,
+} from "../../core/keys.ts";
+import { isStringTrack } from "../../core/strings.ts";
+import { isGranularInstrument } from "../../core/granular.ts";
+
+export type KnobRef = string | undefined;
+export type KnobMap = readonly [KnobRef, KnobRef, KnobRef, KnobRef];
+
+/**
+ * Pages, by id. `sound:<family>` rows use each engine's own param names (the
+ * rows its Sound menu shows); orange is the track level on every sound page,
+ * so ◆ always means "how loud".
+ */
+export const KNOB_MAPS: Readonly<Record<string, KnobMap>> = Object.freeze({
+  "sound:synth": [
+    "sound/preset",
+    "sound/attack",
+    "sound/synth filter",
+    "mix/volume",
+  ],
+  "sound:wavetable": [
+    "sound/position (wt)",
+    "sound/attack",
+    "sound/synth filter",
+    "mix/volume",
+  ],
+  "sound:piano": [
+    "sound/preset",
+    "sound/decay",
+    "sound/hardness",
+    "mix/volume",
+  ],
+  "sound:electric": ["sound/preset", "sound/bell", "sound/tone", "mix/volume"],
+  "sound:organ": ["sound/preset", "sound/perc", "sound/drive", "mix/volume"],
+  "sound:string": [
+    "sound/preset",
+    "sound/ring s",
+    "sound/bright",
+    "mix/volume",
+  ],
+  "sound:wind": [
+    "sound/breath",
+    "sound/wind:advanced/vib",
+    "sound/bright",
+    "mix/volume",
+  ],
+  "sound:modal": [
+    "sound/position",
+    "sound/ring",
+    "sound/hardness",
+    "mix/volume",
+  ],
+  "sound:sing": ["sound/vowel", "sound/voices", "sound/bright", "mix/volume"],
+  "sound:granular": [
+    "sound/granular/position",
+    "sound/granular/grain (s)",
+    "sound/granular/spray (s)",
+    "mix/volume",
+  ],
+  // `sample:*` is the track's first sample voice.
+  "sound:sampler": [
+    "sound/sample:*/begin",
+    "sound/sample:*/len",
+    "sound/sample:*/speed",
+    "mix/volume",
+  ],
+  // A kit has no voice params: blue loosens the timing, green the room it
+  // plays in, white its tone.
+  "sound:kit": [
+    "sound/performance/humanize timing (ms)",
+    "effects/reverb/mix",
+    "effects/filter/cutoff",
+    "mix/volume",
+  ],
+  // The mixer page: this track's pan, reverb send, tone and level.
+  mix: ["mix/pan", "effects/reverb/mix", "effects/filter/cutoff", "mix/volume"],
+  master: [
+    "mix/master/master:eq/low",
+    "mix/master/master:eq/bell1",
+    "mix/master/master:eq/high",
+    "mix/master/target LUFS",
+  ],
+  tempo: [
+    "project/tempo",
+    "project/loop length",
+    "project/beats per bar",
+    undefined,
+  ],
+  // Effects: time or rate, feedback / size / depth, tone, mix.
+  "fx:filter": [
+    "effects/filter/type",
+    "effects/filter/resonance",
+    "effects/filter/cutoff",
+    undefined,
+  ],
+  "fx:delay": [
+    "effects/delay/beats",
+    "effects/delay/feedback",
+    undefined,
+    "effects/delay/mix",
+  ],
+  "fx:reverb": [
+    "effects/reverb/impulse (ir)",
+    "effects/reverb/size",
+    undefined,
+    "effects/reverb/mix",
+  ],
+  "fx:chorus": [
+    "effects/chorus/rate",
+    "effects/chorus/depth",
+    undefined,
+    "effects/chorus/mix",
+  ],
+  /**
+   * The Euclid editor (design §8.7): its row's own fields, not menu paths.
+   * Blue picks the drum row; ←→ on it moves between rows.
+   */
+  euclid: ["drum", "pulses", "rotate", "velocity"],
+  /**
+   * TAPE (design §7.3): its own values, not menu paths. Blue the playhead
+   * (a beat; ⇧ a bar), green the loop length, white the tempo of the
+   * segment under the playhead, orange the focused track's volume.
+   */
+  tape: ["playhead", "loop", "tempo", "volume"],
+  "fx:distort": [
+    undefined,
+    "effects/distort/drive",
+    "effects/distort/tone",
+    "effects/distort/mix",
+  ],
+});
+
+/** The sound page's family for a track: which engine its Sound menu shows. */
+export function soundFamily(track: Track): string {
+  if (isDrumInstrument(track.instrument)) return "kit";
+  if (track.sampler) return "sampler";
+  if (isGranularInstrument(track.instrument)) return "granular";
+  if (isOrganFamily(track.instrument) && track.keys) return "organ";
+  if (isKeysFamily(track.instrument) && track.keys)
+    return isElectricFamily(track.instrument) ? "electric" : "piano";
+  if (isStringTrack(track)) return "string";
+  if (track.instrument === "modal") return "modal";
+  if (track.instrument === "wind" && track.wind) return "wind";
+  if (track.instrument === "sing" && track.sing) return "sing";
+  if (isWavetableInstrument(track.instrument)) return "wavetable";
+  return "synth";
+}
+
+/** The page id for `knobs <page>`, or undefined when no page has that name. */
+export function knobPageId(
+  word: string | undefined,
+  track: Track | undefined,
+): string | undefined {
+  const name = (word ?? "sound").trim().toLowerCase().replace(/\s+/g, " ");
+  if (name === "sound" || name === "")
+    return `sound:${track ? soundFamily(track) : "synth"}`;
+  if (name === "mix" || name === "master" || name === "tempo") return name;
+  const fx = name.match(/^(?:fx|effect|effects)\s+(\S+)$/)?.[1];
+  if (fx) return `fx:${fx}`;
+  if (`sound:${name}` in KNOB_MAPS) return `sound:${name}`;
+  return undefined;
+}
+
+/** The page's row; an unmapped effect gets none (the menu derives one). */
+export function knobMap(page: string): KnobMap | undefined {
+  return KNOB_MAPS[page];
+}
+
+/** The pages `knobs` names, for help and completion. */
+export const KNOB_PAGE_WORDS = Object.freeze([
+  "sound",
+  "mix",
+  "master",
+  "tempo",
+  "fx <effect>",
+]);