@hraness/dawg 0.4.0 → 0.5.0

package/src/tui/performance-menu.ts

@@ -0,0 +1,235 @@
+/**
+ * Sound › Performance: how the focused track plays its notes. Every row
+ * runs the same prompt command a user could type (src/commands/expression.ts),
+ * so the menu, the prompt and the agent share one grammar.
+ */
+import {
+  ARTICULATIONS,
+  DEFAULT_FIXED_VELOCITY,
+  DEFAULT_GLIDE_SECONDS,
+  EXPRESSION_LIMITS,
+  GLIDE_MODES,
+  VELOCITY_CURVES,
+} from "../../core/expression.ts";
+import type { Note, Track } from "../../core/score.ts";
+import {
+  BEND_SHAPES,
+  DEFAULT_HUMANIZE,
+  describeHumanize,
+  parseExpressionCommand,
+} from "../commands/expression.ts";
+import type { MenuContext, MenuNode } from "./menu.ts";
+
+const round = (value: number, places = 3) =>
+  Math.round(value * 10 ** places) / 10 ** places;
+
+/** One value every note shares, `mixed`, or `fallback` when none set it. */
+function shared(
+  notes: readonly Note[],
+  read: (note: Note) => string | undefined,
+  fallback: string,
+): string {
+  const values = new Set(notes.map((note) => read(note) ?? fallback));
+  if (values.size === 0) return fallback;
+  return values.size === 1 ? [...values][0]! : "mixed";
+}
+
+function bendName(note: Note): string | undefined {
+  if (!note.bend) return undefined;
+  const text = JSON.stringify(note.bend);
+  return (
+    Object.entries(BEND_SHAPES).find(
+      ([, points]) => JSON.stringify(points) === text,
+    )?.[0] ?? "custom"
+  );
+}
+
+/** The menu's one-line summary of a track's performance, for its row. */
+export function performanceDetail(track: Track | undefined): string {
+  if (!track) return "—";
+  const parts = [
+    track.glide ? `glide ${track.glide.mode}` : "",
+    track.pedal?.length ? "pedal" : "",
+    track.velocityCurve ? `vel ${track.velocityCurve.curve}` : "",
+    track.humanize ? "humanized" : "",
+  ].filter(Boolean);
+  return parts.length ? parts.join(" · ") : "as written";
+}
+
+export function performanceNodes(context: MenuContext): MenuNode[] {
+  const track = context.score.tracks.find(
+    (item) => item.id === context.trackId,
+  );
+  if (!track) return [];
+  const notes = context.score.notes.filter((note) => note.trackId === track.id);
+  const glide = track.glide;
+  const curve = track.velocityCurve;
+  const humanize = track.humanize;
+  const humanizeCommand = (timing: number, velocity: number, length: number) =>
+    `humanize ${round(timing)} ${round(velocity)} ${round(length)}`;
+  const timing = humanize?.timing ?? 0;
+  const velocity = humanize?.velocity ?? 0;
+  const length = humanize?.length ?? 0;
+  const pedalLabel = track.pedal?.length
+    ? `${track.pedal.length} events`
+    : "off";
+  const nodes: MenuNode[] = [
+    {
+      kind: "choice",
+      label: "articulation",
+      value: shared(notes, (note) => note.articulation, "none"),
+      options: ["none", ...ARTICULATIONS],
+      command: (option) => `art ${option === "none" ? "off" : option}`,
+      help: "every note on the track: staccato halves the length, ghost plays quiet",
+    },
+    {
+      kind: "number",
+      label: "glide (ms)",
+      value: glide?.time,
+      min: 0,
+      max: EXPRESSION_LIMITS.maxGlideSeconds,
+      step: (value, direction) =>
+        Math.min(
+          EXPRESSION_LIMITS.maxGlideSeconds,
+          Math.max(0, round(value + 0.01 * direction, 2)),
+        ),
+      format: (value) => `${Math.round(value * 1000)} ms`,
+      command: (value) => `glide ${Math.round(value * 1000)}ms`,
+      off: "off",
+      start: DEFAULT_GLIDE_SECONDS,
+      reset: "glide off",
+      help: "portamento into each note from the one before",
+    },
+    {
+      kind: "choice",
+      label: "glide mode",
+      value: glide?.mode ?? "off",
+      options: ["off", ...GLIDE_MODES],
+      command: (option) => (option === "off" ? "glide off" : `glide ${option}`),
+      help: "legato: slide only into overlapping notes (TB-303); mono: always; poly: every voice",
+    },
+    {
+      kind: "choice",
+      label: "bend",
+      value: shared(notes, bendName, "none"),
+      options: ["none", ...Object.keys(BEND_SHAPES)],
+      command: (option) => `bend ${option === "none" ? "off" : option}`,
+      help: "a pitch curve over every note; `bend` in the prompt takes points",
+    },
+    {
+      kind: "entry",
+      label: "vibrato",
+      value: shared(
+        notes,
+        (note) =>
+          note.vibrato
+            ? `${note.vibrato.rate} Hz ${note.vibrato.depth}¢`
+            : undefined,
+        "none",
+      ),
+      placeholder: "rate Hz, depth cents, delay s: 5.5 25 0.2",
+      command: (text) => {
+        const command = text.trim() ? `vibrato ${text.trim()}` : "vibrato off";
+        return parseExpressionCommand(command) ? command : undefined;
+      },
+      example: "vibrato 5.5 25 0.2",
+      help: "replaces the synth's vib on every note on the track",
+    },
+    {
+      kind: "choice",
+      label: "sustain pedal",
+      value: pedalLabel,
+      options: ["off", ...(pedalLabel === "off" ? [] : [pedalLabel]), "bars"],
+      command: (option) =>
+        option === "bars"
+          ? "pedal bars"
+          : option === "off"
+            ? "pedal off"
+            : "pedal",
+      help: "bars replaces the lane with a re-pedal on each downbeat; in play mode press Tab (latch) or hold Shift while recording",
+    },
+    {
+      kind: "choice",
+      label: "velocity curve",
+      value: curve?.curve ?? "linear",
+      options: VELOCITY_CURVES,
+      command: (option) => `velcurve ${option}`,
+      help: "soft lifts quiet notes, hard deepens them, fixed plays every note the same",
+    },
+  ];
+  if (curve?.curve === "fixed")
+    nodes.push({
+      kind: "number",
+      label: "fixed velocity",
+      value: curve.fixed ?? DEFAULT_FIXED_VELOCITY,
+      min: 0,
+      max: 1,
+      step: (value, direction) =>
+        Math.min(1, Math.max(0, round(value + 0.05 * direction, 2))),
+      format: (value) => String(round(value, 2)),
+      command: (value) => `velcurve fixed ${round(value, 2)}`,
+      reset: `velcurve fixed ${DEFAULT_FIXED_VELOCITY}`,
+    });
+  nodes.push(
+    {
+      kind: "number",
+      label: "humanize timing (ms)",
+      value: humanize ? timing : undefined,
+      min: 0,
+      max: EXPRESSION_LIMITS.maxHumanizeTimingMs,
+      step: (value, direction) =>
+        Math.min(
+          EXPRESSION_LIMITS.maxHumanizeTimingMs,
+          Math.max(0, value + direction),
+        ),
+      format: (value) => `±${round(value)} ms`,
+      command: (value) => humanizeCommand(value, velocity, length),
+      off: "off",
+      start: DEFAULT_HUMANIZE.timing,
+      reset: "humanize off",
+      help: `seeded drift applied at render; the score stays clean (${describeHumanize(humanize)})`,
+    },
+    {
+      kind: "number",
+      label: "humanize velocity (%)",
+      value: humanize ? velocity : undefined,
+      min: 0,
+      max: EXPRESSION_LIMITS.maxHumanizePercent,
+      step: (value, direction) =>
+        Math.min(
+          EXPRESSION_LIMITS.maxHumanizePercent,
+          Math.max(0, value + direction),
+        ),
+      format: (value) => `±${round(value)}%`,
+      command: (value) => humanizeCommand(timing, value, length),
+      off: "off",
+      start: DEFAULT_HUMANIZE.velocity,
+      reset: "humanize off",
+    },
+    {
+      kind: "number",
+      label: "humanize length (%)",
+      value: humanize ? length : undefined,
+      min: 0,
+      max: EXPRESSION_LIMITS.maxHumanizePercent,
+      step: (value, direction) =>
+        Math.min(
+          EXPRESSION_LIMITS.maxHumanizePercent,
+          Math.max(0, value + direction),
+        ),
+      format: (value) => `±${round(value)}%`,
+      command: (value) => humanizeCommand(timing, velocity, value),
+      off: "off",
+      start: 5,
+      reset: "humanize off",
+    },
+  );
+  if (humanize)
+    nodes.push({
+      kind: "action",
+      label: `new take (seed ${humanize.seed})`,
+      command: "humanize reseed",
+      help: "the same amounts with a different seeded performance",
+    });
+  return nodes;
+}

package/src/tui/play-chords.ts

@@ -22,9 +22,15 @@
  *
  * Pure: the session asks for a chord per note key and owns sound and time.
  */
+import { resolveTuning, snapToTuning } from "../../core/tuning.ts";
 import {
   BASS_MODES,
   CHORD_PATTERNS,
+  DEFAULT_ARP_RATE,
+  DEFAULT_STRUM,
+  generateProgression,
+  presetChords,
+  renderProgression,
   CHORD_TYPES,
   EXTENSIONS,
   MAX_VOICING_STEP,
@@ -56,7 +62,12 @@ import {
   type ProgressionStyle,
   type Spread,
 } from "../../core/chords.ts";
-import { isSamplerInstrument, type Track } from "../../core/score.ts";
+import {
+  isSamplerInstrument,
+  type NoteInput,
+  type Track,
+  type TrackScore,
+} from "../../core/score.ts";
 
 export const CHORD_MODES = ["auto", "manual", "off"] as const;
 export type ChordMode = (typeof CHORD_MODES)[number];
@@ -536,3 +547,86 @@ export function chordsSummary(settings: ChordSettings): string {
     `style ${s.style}`,
   ].join(" · ");
 }
+
+/** Chords in the chord settings screen's audition phrase. */
+const PHRASE_CHORDS = 4;
+
+/**
+ * What the chord settings sound like, for the audition loop: the chosen
+ * progression (the preset, or four chords of the style's seeded walk) in the
+ * song key, voiced and performed with `settings` (voicing, spread, sevenths,
+ * perform mode, pattern, arp rate and octaves, bass mode), one chord per bar
+ * or two per bar in a one-bar loop. With chords `off` it plays each chord's
+ * root alone, as play mode would. Deterministic: the same settings and key
+ * always give the same notes.
+ */
+export function chordPhrase(
+  settings: ChordSettings,
+  score: TrackScore,
+  track: Track,
+  bars: number,
+): NoteInput[] {
+  const key = parseKey(score.key) ?? { tonic: 0, mode: "major" as const };
+  const preset =
+    settings.preset === "none" ? undefined : findPreset(settings.preset);
+  const progression = preset
+    ? presetChords(key, preset)
+    : generateProgression({
+        key,
+        length: PHRASE_CHORDS,
+        style: settings.style,
+        seed: 1,
+        sevenths: settings.sevenths,
+      });
+  const tpb = score.ticksPerBeat;
+  const totalBeats = Math.max(1, bars) * score.beatsPerBar;
+  const count = Math.max(2, Math.max(1, bars));
+  const span = totalBeats / count;
+  const chords = Array.from(
+    { length: count },
+    (_, index) => progression[index % progression.length]!,
+  );
+  const mode = settings.perform;
+  const rendered = renderProgression({
+    key,
+    chords,
+    beatsPerChord: span,
+    inversion: settings.inversion,
+    spread: settings.spread,
+    bassMode: settings.mode === "off" ? "solo" : settings.bass,
+    perform: {
+      mode,
+      rate:
+        settings.rate === "grid" ? DEFAULT_ARP_RATE : RATE_BEATS[settings.rate],
+      octaves: settings.octaves,
+      strum: mode === "harp" ? DEFAULT_STRUM * 2 : DEFAULT_STRUM,
+      seed: 1,
+      velocity: 0.8,
+      ...(mode === "pattern" ? { pattern: settings.pattern } : {}),
+    },
+  });
+  // With chords off a key plays one note: the root, in the chord's octave.
+  const performed =
+    settings.mode === "off"
+      ? rendered.bass.map((note) => ({ ...note, pitch: note.pitch + 24 }))
+      : [...rendered.notes, ...rendered.bass];
+  const end = totalBeats * tpb;
+  const table = resolveTuning(score.tuning, track.tuning, score.key);
+  const notes: NoteInput[] = [];
+  for (const note of performed) {
+    const startTick = Math.round(note.start * tpb);
+    if (startTick >= end) continue;
+    notes.push({
+      id: `chords-${notes.length + 1}`,
+      trackId: track.id,
+      startTick,
+      durationTicks: Math.max(
+        1,
+        Math.min(Math.round(note.length * tpb), end - startTick),
+      ),
+      pitch: snapToTuning(note.pitch, table),
+      velocity: note.velocity,
+    });
+  }
+  return notes;
+}

package/src/tui/play-mode.ts

@@ -10,6 +10,8 @@
  *
  *   Z / X  octave down / up      C / V  velocity down / up (steps of 16)
  *   Shift  sustain while held    Tab    sustain latch     Esc  leave the mode
+ *   (while recording, sustain changes record as track pedal events)
+ *   I      scale degrees: the home row plays the key's scale (any tuning)
  *
  * Terminals report key-down only, so a held key is synthesized from the
  * keyboard's auto-repeat: a press sounds for the gate (one grid step by
@@ -21,12 +23,14 @@
  *
  * Everything here is pure: callers pass the monotonic time of each key.
  */
+import { keyName, parseKey, scaleSteps } from "../../core/chords.ts";
 import {
   SAMPLER_FIRST_SLOT,
   isSamplerInstrument,
   samplerVoiceSlots,
   type Track,
 } from "../../core/score.ts";
+import type { TuningTable } from "../../core/tuning.ts";
 import { pitchName } from "../../tui/highway.ts";
 
 /** Semitone offset from the base C for each note key. */
@@ -148,8 +152,86 @@ export function rangeLabel(base: number): string {
   return `${pitchName(base)}–${pitchName(base + LAYOUT_SPAN)}`;
 }
 
+/** The home row left to right: consecutive degrees in degree mode. */
+export const HOME_ROW: readonly string[] = Object.freeze(
+  Object.keys(WHITE_KEYS),
+);
+
+/**
+ * Scale-degree layout (Push's "In Key", Komplete Kontrol's Easy mode): the
+ * home row plays consecutive degrees from the tonic and the upper row is
+ * off, so every key is in the scale.
+ */
+export type DegreeLayout = Readonly<{
+  /** Key offsets of the degrees within one period, ascending from 0. */
+  steps: readonly number[];
+  /** Keys per period: 12, or a linear tuning's step count. */
+  period: number;
+  /** Key of degree 0 with the keyboard at its default base (C3). */
+  tonic: number;
+  /** `D dorian`, `19-edo`, `C major · 19-edo`. */
+  name: string;
+}>;
+
+/**
+ * The degrees the home row plays for a song key and the track's tuning. A
+ * twelve-key tuning (12-TET, just intonation, a maqam preset) plays the
+ * key's scale on the twelve keys, quarter tones on the key their preset
+ * retunes; a linear non-12 tuning (19-EDO, pelog) plays every step, or the
+ * nearest step to each scale note when a key is set. No key reads C major.
+ */
+export function degreeLayout(
+  keyText: string | null | undefined,
+  table: TuningTable | undefined,
+): DegreeLayout {
+  const key = parseKey(keyText ?? undefined);
+  if (table && table.linear && table.size !== 12) {
+    const period = table.size;
+    const pc = ((table.root % 12) + 12) % 12;
+    const tonic =
+      table.root + Math.round((DEFAULT_BASE + pc - table.root) / 12) * period;
+    const at = (offset: number) =>
+      table.hz[Math.max(0, Math.min(127, tonic + offset))]!;
+    const degreeCents = Array.from({ length: period }, (_, offset) =>
+      at(offset) > 0 && at(0) > 0 ? 1200 * Math.log2(at(offset) / at(0)) : NaN,
+    );
+    const steps = key
+      ? [
+          ...new Set(
+            scaleSteps(key).map((step) => {
+              let best = 0;
+              for (let offset = 1; offset < period; offset += 1)
+                if (
+                  Math.abs(degreeCents[offset]! - step * 100) <
+                  Math.abs(degreeCents[best]! - step * 100)
+                )
+                  best = offset;
+              return best;
+            }),
+          ),
+        ].sort((a, b) => a - b)
+      : degreeCents.map((_, offset) => offset);
+    return Object.freeze({
+      steps: Object.freeze(steps),
+      period,
+      tonic,
+      name: key ? `${keyName(key)} · ${table.name}` : table.name,
+    });
+  }
+  const chosen = key ?? { tonic: 0, mode: "major" as const };
+  const steps = [
+    ...new Set(scaleSteps(chosen).map((step) => Math.ceil(step) % 12)),
+  ].sort((a, b) => a - b);
+  return Object.freeze({
+    steps: Object.freeze(steps),
+    period: 12,
+    tonic: DEFAULT_BASE + chosen.tonic,
+    name: keyName(chosen),
+  });
+}
+
 export type PlayCommand =
-  "exit" | "record" | "replace" | "click" | "transport" | "menu";
+  "exit" | "record" | "replace" | "click" | "transport" | "menu" | "degrees";
 
 /** Keys that drive the mode itself rather than notes. */
 const COMMAND_KEYS: Readonly<Record<string, PlayCommand>> = Object.freeze({
@@ -158,6 +240,7 @@ const COMMAND_KEYS: Readonly<Record<string, PlayCommand>> = Object.freeze({
   R: "replace",
   m: "click",
   M: "click",
+  i: "degrees",
   " ": "transport",
   "\u000b": "menu",
 });
@@ -225,6 +308,27 @@ export class PlayKeyboard {
   private nextId = 1;
   /** Shift was held on the last note key (BandLab's Sustain light). */
   public shiftHeld = false;
+  private layout: DegreeLayout | undefined;
+  /**
+   * Degrees the home row is shifted by when a period has more steps than
+   * the home row has keys (19- or 31-EDO): Z and X page by a row instead of
+   * a period, so every step stays reachable.
+   */
+  public degreeOffset = 0;
+
+  /** Scale-degree layout (`i` in play mode); undefined is chromatic. */
+  public get degrees(): DegreeLayout | undefined {
+    return this.layout;
+  }
+
+  public set degrees(layout: DegreeLayout | undefined) {
+    if (
+      layout?.steps.length !== this.layout?.steps.length ||
+      layout?.period !== this.layout?.period
+    )
+      this.degreeOffset = 0;
+    this.layout = layout;
+  }
 
   public constructor(options: PlayKeyboardOptions = {}) {
     this.base = clampBase(options.base ?? DEFAULT_BASE);
@@ -236,12 +340,30 @@ export class PlayKeyboard {
   }
 
   public get range(): string {
-    return rangeLabel(this.base);
+    if (!this.degrees) return rangeLabel(this.base);
+    const low = this.pitchFor(HOME_ROW[0]!);
+    const high = this.pitchFor(HOME_ROW[HOME_ROW.length - 1]!);
+    return low === undefined || high === undefined
+      ? "out of range"
+      : `${pitchName(low)}–${pitchName(high)}`;
   }
 
   /** Pitch a note key plays at the current octave, or undefined. */
   public pitchFor(key: string): number | undefined {
-    const offset = NOTE_KEYS[SHIFTED[key] ?? key.toLowerCase()];
+    const name = SHIFTED[key] ?? key.toLowerCase();
+    if (this.degrees) {
+      const index = HOME_ROW.indexOf(name);
+      if (index < 0) return undefined;
+      const { steps, period, tonic } = this.degrees;
+      const degree = this.degreeOffset + index;
+      const octave = Math.floor(degree / steps.length);
+      const pitch =
+        tonic +
+        ((this.base - DEFAULT_BASE) / 12 + octave) * period +
+        steps[degree - octave * steps.length]!;
+      return pitch >= MIN_PITCH && pitch <= MAX_PITCH ? pitch : undefined;
+    }
+    const offset = NOTE_KEYS[name];
     if (offset === undefined) return undefined;
     return this.base + offset;
   }
@@ -271,8 +393,25 @@ export class PlayKeyboard {
     if (command) return { type: "command", command };
     const lower = value.length === 1 ? value.toLowerCase() : value;
     if (lower === "z" || lower === "x") {
+      if (this.degrees && this.degrees.steps.length > HOME_ROW.length) {
+        // Page by a home row of degrees; stop before the row falls silent.
+        const previous = this.degreeOffset;
+        this.degreeOffset += lower === "z" ? -HOME_ROW.length : HOME_ROW.length;
+        const clamped = HOME_ROW.every(
+          (key) => this.pitchFor(key) === undefined,
+        );
+        if (clamped) this.degreeOffset = previous;
+        return { type: "octave", base: this.base, clamped };
+      }
       const wanted = this.base + (lower === "z" ? -12 : 12);
+      const previous = this.base;
       this.base = clampBase(wanted);
+      // Degree mode moves a period; stop before the home row falls silent.
+      if (
+        this.degrees &&
+        HOME_ROW.every((key) => this.pitchFor(key) === undefined)
+      )
+        this.base = previous;
       return { type: "octave", base: this.base, clamped: wanted !== this.base };
     }
     if (lower === "c" || lower === "v") {
@@ -428,10 +567,15 @@ export function stripCells(
   lit: ReadonlySet<string>,
   labels: ReadonlyMap<number, string> = new Map(),
 ): StripCell[] {
-  return STRIP_ORDER.map((key) => {
-    const pitch = keyboard.pitchFor(key)!;
+  const order = keyboard.degrees ? HOME_ROW : STRIP_ORDER;
+  return order.map((key) => {
+    const pitch = keyboard.pitchFor(key);
     const name =
-      labels.size > 0 ? (labels.get(pitch) ?? "·") : pitchName(pitch);
+      pitch === undefined
+        ? "·"
+        : labels.size > 0
+          ? (labels.get(pitch) ?? "·")
+          : pitchName(pitch);
     return {
       key,
       label: name,