@hraness/dawg 0.6.1 → 0.8.0

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>",
+]);

package/src/tui/menu-clips.ts

@@ -0,0 +1,297 @@
+/**
+ * Voice › Clips and Lyrics, and Voice › voice presets >
+ * Vocal (0.7 clips lane). Every row runs a prompt command (`/clip`,
+ * `/lyrics`, `/vocal`), so the menu, the prompt and undo stay one path.
+ */
+import { basename } from "node:path";
+import {
+  CLIP_GAIN_MAX_DB,
+  CLIP_GAIN_MIN_DB,
+  clipGainDb,
+  lyricText,
+} from "../../core/clips.ts";
+import { SCORE_LIMITS, type AudioClip } from "../../core/score.ts";
+import { userBarLabel, VOCAL_SETUPS } from "../commands/clips.ts";
+import type { MenuContext, MenuNode } from "./menu.ts";
+
+const round = (value: number, places = 2) => {
+  const scale = 10 ** places;
+  return Math.round(value * scale) / scale;
+};
+const dbText = (db: number) =>
+  Number.isFinite(db) ? `${db > 0 ? "+" : ""}${round(db, 1)} dB` : "-inf dB";
+
+function clipDetail(context: MenuContext, clip: AudioClip): string {
+  return [
+    `bar ${userBarLabel(context.score, clip.startTick)}`,
+    clip.gain !== undefined ? dbText(clipGainDb(clip.gain)) : "",
+    clip.rev ? "rev" : "",
+    clip.mute ? "muted" : "",
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+/** The rows for one clip: gain, fades, place, rev, mute, repeat, remove. */
+function clipRows(context: MenuContext, id: string): MenuNode[] {
+  const track = context.score.tracks.find((t) => t.id === context.trackId);
+  const clip = track?.clips?.find((c) => c.id === id);
+  if (!clip) return [{ kind: "info", label: "clip", value: "removed" }];
+  const fadeIn = clip.fadeInTime ?? 0.005;
+  const fadeOut = clip.fadeTime ?? 0.005;
+  const fadeMax = SCORE_LIMITS.maxClipFadeSeconds;
+  const fadeStep = (value: number, direction: 1 | -1) =>
+    Math.max(
+      0,
+      Math.min(
+        fadeMax,
+        round(
+          value < 0.05 ? value + 0.005 * direction : value + 0.05 * direction,
+          3,
+        ),
+      ),
+    );
+  return [
+    {
+      kind: "number",
+      label: "gain",
+      help: "clip gain in dB before the track's effects",
+      value: round(clipGainDb(clip.gain ?? 1), 1),
+      min: CLIP_GAIN_MIN_DB,
+      max: CLIP_GAIN_MAX_DB,
+      step: (value, direction) =>
+        Math.max(
+          CLIP_GAIN_MIN_DB,
+          Math.min(CLIP_GAIN_MAX_DB, round(value + direction, 1)),
+        ),
+      format: dbText,
+      command: (value) => `/clip ${id} gain ${value}`,
+      reset: `/clip ${id} gain 0`,
+    },
+    {
+      kind: "number",
+      label: "fade in",
+      help: "equal-power fade-in, seconds",
+      value: fadeIn,
+      min: 0,
+      max: fadeMax,
+      step: fadeStep,
+      format: (value) => `${round(value, 3)} s`,
+      command: (value) => `/clip ${id} fade in ${value}`,
+      reset: `/clip ${id} fade in default`,
+    },
+    {
+      kind: "number",
+      label: "fade out",
+      help: "equal-power fade-out, seconds",
+      value: fadeOut,
+      min: 0,
+      max: fadeMax,
+      step: fadeStep,
+      format: (value) => `${round(value, 3)} s`,
+      command: (value) => `/clip ${id} fade out ${value}`,
+      reset: `/clip ${id} fade out default`,
+    },
+    {
+      kind: "number",
+      label: "start in file",
+      help: "seconds into the file where the clip starts playing",
+      value: clip.offset ?? 0,
+      min: 0,
+      max: SCORE_LIMITS.maxClipSeconds,
+      step: (value, direction) =>
+        Math.max(0, round(value + 0.1 * direction, 3)),
+      format: (value) => `${round(value, 3)} s`,
+      command: (value) => `/clip ${id} trim offset ${value}`,
+      reset: `/clip ${id} trim offset 0`,
+    },
+    {
+      kind: "entry",
+      label: "length",
+      value: clip.dur === undefined ? "to file end" : `${round(clip.dur, 3)} s`,
+      help: "seconds of the file to play; `end` plays to the file's end",
+      placeholder: "seconds, e.g. 4.5, or end",
+      command: (text) => {
+        const value = text.trim().toLowerCase().replace(/s$/, "");
+        if (value === "end") return `/clip ${id} trim dur end`;
+        return Number(value) > 0 ? `/clip ${id} trim dur ${value}` : undefined;
+      },
+      example: `/clip ${id} trim dur 4.5`,
+    },
+    {
+      kind: "toggle",
+      label: "reverse",
+      help: "play the clip backwards",
+      value: clip.rev === true,
+      command: () => `/clip ${id} rev`,
+    },
+    {
+      kind: "toggle",
+      label: "mute",
+      help: "silence this clip only",
+      value: clip.mute === true,
+      command: () => `/clip ${id} mute`,
+    },
+    {
+      kind: "entry",
+      label: "move to bar",
+      value: userBarLabel(context.score, clip.startTick),
+      help: "1-based bar, or bar.beat",
+      placeholder: "bar, e.g. 9 or 5.3",
+      command: (text) =>
+        text.trim() ? `/clip ${id} move ${text.trim()}` : undefined,
+      example: `/clip ${id} move 9`,
+    },
+    {
+      kind: "entry",
+      label: "split at bar",
+      value: "",
+      help: "cut the clip in two at a bar (5 ms fades at the cut)",
+      placeholder: "bar, e.g. 7",
+      command: (text) =>
+        text.trim() ? `/clip ${id} split ${text.trim()}` : undefined,
+      example: `/clip ${id} split 7`,
+    },
+    {
+      kind: "entry",
+      label: "repeat",
+      value: "",
+      help: "copies every N bars up to a bar: type `2 to 32`",
+      placeholder: "every N to bar",
+      command: (text) => {
+        const match = text
+          .trim()
+          .match(/^(?:every\s+)?(\d+(?:\.\d+)?)\s+(?:to\s+)?(\d+)$/i);
+        return match
+          ? `/clip ${id} repeat every ${match[1]} to ${match[2]}`
+          : undefined;
+      },
+      example: `/clip ${id} repeat every 2 to 32`,
+    },
+    {
+      kind: "info",
+      label: "file",
+      value: basename(clip.src),
+      help: clip.src,
+    },
+    {
+      kind: "action",
+      label: "remove clip",
+      command: `/clip ${id} rm`,
+      help: "remove this clip (the file stays in the project; undo brings it back)",
+    },
+  ];
+}
+
+/** Voice rows from the clips lane: Clips and Lyrics. */
+export function clipMenuRows(context: MenuContext): MenuNode[] {
+  const track = context.score.tracks.find((t) => t.id === context.trackId);
+  if (!track) return [];
+  const clips = track.clips ?? [];
+  const notes = context.score.notes.filter((n) => n.trackId === track.id);
+  const sung = lyricText(notes);
+  return [
+    {
+      kind: "menu",
+      id: "voice:clips",
+      label: "clips",
+      detail: clips.length
+        ? `${clips.length} clip${clips.length === 1 ? "" : "s"}`
+        : "import a vocal",
+      help: "audio clips on this track: import a file or the vocals stem, then edit",
+      build: (inner) => {
+        const now =
+          inner.score.tracks.find((t) => t.id === inner.trackId)?.clips ?? [];
+        return [
+          ...now.map((clip): MenuNode => ({
+            kind: "menu",
+            id: `clip:${clip.id}`,
+            label: clip.id,
+            detail: clipDetail(inner, clip),
+            help: `${basename(clip.src)} · gain, fades, reverse, mute, move, split, repeat`,
+            build: (deeper) => clipRows(deeper, clip.id),
+          })),
+          {
+            kind: "entry",
+            label: "import a file",
+            value: "",
+            help: "copy an audio file into the track (48 kHz mono, peak -6 dBFS) at a bar",
+            placeholder: "<file> [bar]",
+            command: (text) =>
+              text.trim() ? `/vocal import ${text.trim()}` : undefined,
+            example: "/vocal import ~/take.wav 9",
+          },
+          {
+            kind: "entry",
+            label: "vocals stem",
+            value: "",
+            help: "place the vocals stem from the last split_stems at a bar",
+            placeholder: "bar (default 1)",
+            command: (text) => `/vocal stem ${text.trim() || "1"}`,
+            example: "/vocal stem 1",
+          },
+          {
+            kind: "choice",
+            label: "setup",
+            value: "",
+            options: VOCAL_SETUPS.filter(
+              (setup) => !setup.needs?.includes("say"),
+            ).map((setup) => setup.name),
+            help: "a vocal chain in one step (setups naming later tools say what is missing)",
+            command: (option) => `/vocal setups ${option}`,
+          },
+        ];
+      },
+    },
+    {
+      kind: "menu",
+      id: "voice:lyrics",
+      label: "lyrics",
+      detail: sung ? sung.slice(0, 32) : "none",
+      help: "words on this track's notes: - splits syllables, _ holds, ~ skips",
+      build: (inner) => {
+        const text = lyricText(
+          inner.score.notes.filter((n) => n.trackId === inner.trackId),
+        );
+        return [
+          {
+            kind: "entry",
+            label: "lyrics",
+            value: text,
+            help: "typed words are split into syllables onto the notes in order",
+            placeholder: "sun-lit morn-ing _ glow",
+            command: (typed) =>
+              typed.trim() ? `/lyrics ${typed.trim()}` : undefined,
+            example: "/lyrics sun-lit morn-ing",
+          },
+          {
+            kind: "entry",
+            label: "from bar",
+            value: "",
+            help: "lyrics starting at a bar: type `9 la la la`",
+            placeholder: "<bar> <words>",
+            command: (typed) =>
+              /^\d+(?:\.\d+)?\s+\S/.test(typed.trim())
+                ? `/lyrics ${typed.trim()}`
+                : undefined,
+            example: "/lyrics 9 la la la",
+          },
+          { kind: "action", label: "clear lyrics", command: "/lyrics clear" },
+        ];
+      },
+    },
+  ];
+}
+
+/** Voice › voice presets › vocal: the guide-note vocal track. */
+export function vocalBrowseRows(_context: MenuContext): MenuNode[] {
+  return [
+    {
+      kind: "action",
+      label:
+        "vocal  clips sound, notes are a silent guide · hpf 90, 3:1, plate",
+      command: "instrument vocal",
+      help: "a vocal track: import a take or stem in Voice › clips",
+    },
+  ];
+}

package/src/tui/menu-time.ts

@@ -1,6 +1,6 @@
 /**
- * Project › Tempo & meter: the song's tempo map, meter changes and
- * fermatas, and the focused track's rate, phase and cycle. Every row runs a
+ * Project › Tempo and meter: the song's tempo map, meter changes and
+ * fermatas, and the focused track's rate, phase and loop. Every row runs a
  * prompt command from `src/commands/time.ts`, so the menu and the prompt
  * stay one grammar.
  */
@@ -28,7 +28,7 @@ export function openingMeterCommand(score: TimeScore, value: number): string {
   return unit === 4 ? `meter ${beats}` : `meter ${beats}/${unit}`;
 }
 
-/** One-line summary for the Project row and the Tempo & meter row. */
+/** One-line summary for the Project row and the Tempo and meter row. */
 export function tempoDetail(score: TimeScore): string {
   const time = score.time;
   const parts: string[] = [];
@@ -55,19 +55,24 @@ export function tempoDetail(score: TimeScore): string {
   return parts.join(" · ");
 }
 
-/** The Tempo & meter submenu node for Project. */
+/** The Tempo and meter submenu node for Project. */
 export function tempoMenuNode(context: MenuContext): MenuNode {
   return {
     kind: "menu",
     id: "tempo",
-    label: "tempo & meter",
+    label: "tempo and meter",
     detail: tempoDetail(context.score),
     help: "tempo changes, rit. and accel., fermatas, meter changes, track rate and phase",
     build: tempoNodes,
   };
 }
 
-/** Rows of Project › Tempo & meter. */
+/** What x puts the song's tempo, meter and loop length back to. */
+export const START_TEMPO_BPM = 120;
+export const START_BEATS_PER_BAR = 4;
+export const START_BARS = 8;
+
+/** Rows of Project › Tempo and meter. */
 export function tempoNodes(context: MenuContext): MenuNode[] {
   const score = context.score;
   const tpb = score.ticksPerBeat;
@@ -78,6 +83,7 @@ export function tempoNodes(context: MenuContext): MenuNode[] {
       label: "start tempo",
       help: "beats per minute at the top of the song",
       value: score.tempoBpm,
+      start: START_TEMPO_BPM,
       min: TIME_LIMITS.minBpm,
       max: TIME_LIMITS.maxBpm,
       step: stepBy(1, TIME_LIMITS.minBpm, TIME_LIMITS.maxBpm),
@@ -182,6 +188,7 @@ export function tempoNodes(context: MenuContext): MenuNode[] {
       label: "beats per bar",
       help: "the song's opening meter; meter changes below override it later",
       value: score.beatsPerBar,
+      start: START_BEATS_PER_BAR,
       min: 1,
       max: TIME_LIMITS.maxBeatsPerBar,
       step: stepBy(1, 1, TIME_LIMITS.maxBeatsPerBar),
@@ -223,7 +230,7 @@ export function tempoNodes(context: MenuContext): MenuNode[] {
       id: "track-time",
       label: `${track.name ?? track.id} time`,
       detail: trackTimeDetail(context),
-      help: "the focused track's tempo ratio, phase and cycle (polytempo, polymeter, phasing)",
+      help: "the focused track's tempo ratio, phase and loop (polytempo, polymeter, phasing)",
       build: trackTimeNodes,
     });
   if (time?.tempo?.length)
@@ -278,7 +285,7 @@ function trackTimeDetail(context: MenuContext): string {
   const parts: string[] = [];
   if (time.rate !== undefined) parts.push(`rate ${fmt(time.rate, 4)}×`);
   if (time.phase !== undefined) parts.push(`phase ${fmt(time.phase / tpb)}`);
-  if (time.cycle !== undefined) parts.push(`cycle ${fmt(time.cycle / tpb)}`);
+  if (time.cycle !== undefined) parts.push(`loop ${fmt(time.cycle / tpb)}`);
   return parts.join(" · ");
 }
 
@@ -320,8 +327,8 @@ export function trackTimeNodes(context: MenuContext): MenuNode[] {
     },
     {
       kind: "number",
-      label: "cycle",
-      help: "beats before the track's pattern repeats (polymeter) · x follows the song loop",
+      label: "loop",
+      help: "beats before the track's own loop repeats (polymeter) · x follows the song loop",
       value: time?.cycle !== undefined ? time.cycle / tpb : undefined,
       off: "song loop",
       start: score.beatsPerBar,
@@ -329,8 +336,8 @@ export function trackTimeNodes(context: MenuContext): MenuNode[] {
       max: TIME_LIMITS.maxTick / tpb,
       step: stepBy(0.25, 0.25, TIME_LIMITS.maxTick / tpb),
       format: (value) => `${fmt(value)} beat${value === 1 ? "" : "s"}`,
-      command: (value) => `track cycle ${fmt(value, 4)}`,
-      reset: "track cycle off",
+      command: (value) => `track loop ${fmt(value, 4)}`,
+      reset: "track loop off",
     },
     entry(
       "phasing",
@@ -350,7 +357,7 @@ export function trackTimeNodes(context: MenuContext): MenuNode[] {
       kind: "action",
       label: "follow the song",
       command: "track time off",
-      help: "clear rate, phase and cycle",
+      help: "clear rate, phase and loop",
     },
   ];
 }