@hraness/dawg 0.4.0 → 0.5.0

package/src/tui/play-session.ts

@@ -20,8 +20,33 @@ import {
   type ScoreOperation,
   type TrackScore,
 } from "../../core/score.ts";
+import {
+  EXPRESSION_LIMITS,
+  ExpressionValidationError,
+  normalizePedal,
+  pedalStateAt,
+  type PedalEvent,
+  type PedalState,
+} from "../../core/expression.ts";
 import type { ClickBus } from "../audio/engine.ts";
-import { DEFAULT_CLICK_VOLUME, parseClickArgument } from "../audio/click.ts";
+import {
+  DEFAULT_CLICK_VOLUME,
+  countInClicks,
+  meterClickGrid,
+  parseClickArgument,
+} from "../audio/click.ts";
+import {
+  barAt,
+  barStartTick,
+  bpmAtTick,
+  clickTicksOf,
+  hasMeterChanges,
+  hasTempoMap,
+  loopTickAt,
+  loopTicksOf,
+  transportBar,
+  transportBarStart,
+} from "../../core/tempo.ts";
 import {
   LiveSynth,
   MAX_LIVE_NOTE_SECONDS,
@@ -43,10 +68,12 @@ import {
   type PlayedChord,
 } from "./play-chords.ts";
 import type { PlayHeaderView, PlayStripKey } from "../../tui/play-strip.ts";
+import { resolveTuning, type Tuning } from "../../core/tuning.ts";
 import {
   NOTE_KEYS,
   PlayKeyboard,
   REPEAT_DELAY_MS,
+  degreeLayout,
   playLayoutFor,
   stripCells,
   type PlayAction,
@@ -75,6 +102,11 @@ export interface PlayHost {
   playing(): boolean;
   /** Transport beat (unwrapped) at monotonic `ms`. */
   beatAt(ms: number): number;
+  /**
+   * The score beat transport `beat` plays: inside a looped section, or the
+   * matching bar of the form pass. Absent means the transport is the score.
+   */
+  scoreBeat?(beat: number): number;
   engine(): LiveEngine | undefined;
   samples?(): SampleBank | undefined;
   commit(
@@ -122,6 +154,12 @@ type Pending = {
   /** Unwrapped transport beat of the press. */
   beat: number;
   releaseAtMs: number;
+  /**
+   * When the key itself let go. Differs from `releaseAtMs` only while the
+   * sustain pedal holds the note: the recorded length is the key's, and the
+   * recorded pedal events do the sustaining (as a MIDI CC64 recording does).
+   */
+  keyUpMs: number;
   /** Set when the key played a chord: laid out with `perform` on flush. */
   chord?: RecordedChord;
 };
@@ -157,7 +195,16 @@ const LIVE_PLAN_BEATS = 64;
 /** Live chord voices use ids far above the keyboard's. */
 const VOICE_ID_BASE = 1_000_000_000;
 
-type CountIn = { startMs: number; beats: number; startBeat: number };
+type CountIn = {
+  startMs: number;
+  beats: number;
+  startBeat: number;
+  /** Count-in tempo: the tempo where recording starts. */
+  bpm: number;
+  /** Beats per counted bar and per click (meter-aware). */
+  barBeats: number;
+  clickBeats: number;
+};
 
 export type PlayKeyResult =
   | { type: "handled" }
@@ -174,13 +221,22 @@ export class PlaySession {
   public countInBars = 1;
   public grid = DEFAULT_GRID;
   public status: string | undefined;
+  /** Scale-degree layout on (`i`); follows key and tuning changes. */
+  public degreesOn = false;
+  private degreeKey: string | undefined;
   private active = false;
   private synth: LiveSynth | undefined;
   private readonly pending = new Map<number, Pending>();
+  /** Sustain changes while recording (Tab latch or Shift), as pedal events. */
+  private pendingPedal: { beat: number; state: PedalState }[] = [];
+  /** The pedal state last recorded this pass. */
+  private pedalDown = false;
   /** Played note id → recorded score note id, for this pass. */
   private readonly recordedIds = new Set<string>();
   /** In-loop bars the playhead finished while replacing. */
   private readonly replaceBars = new Set<number>();
+  /** Live pedal state as the playhead entered each loop bar (replace). */
+  private readonly barPedal = new Map<number, PedalState>();
   private lastBar: number | undefined;
   private countIn: CountIn | undefined;
   private flushing: Promise<void> = Promise.resolve();
@@ -212,8 +268,15 @@ export class PlaySession {
     this.layout = playLayoutFor(track);
     const settings = options.chords ?? defaultChordSettings();
     // Auto chords by default on chord-capable tracks, until chosen by hand.
+    // Diatonic triads assume 12-TET and a polyphonic part: a track in
+    // another tuning, or a mono/legato glide line, plays single notes.
     if (!settings.explicit)
-      settings.mode = chordCapable(track) ? "auto" : "manual";
+      settings.mode =
+        chordCapable(track) &&
+        twelveTet(this.host.score(), track) &&
+        (track?.glide === undefined || track.glide.mode === "poly")
+          ? "auto"
+          : "manual";
     this.chords = new ChordPad(settings, () => this.host.score().key);
     this.keyboard = new PlayKeyboard({ base: this.layout.base });
     this.clickOn = options.clickOn ?? false;
@@ -236,7 +299,17 @@ export class PlaySession {
 
   /** Gate for a single press: one grid step at the current tempo. */
   public gateMs(): number {
-    return (this.gridStep * 60_000) / this.host.score().tempoBpm;
+    return (this.gridStep * 60_000) / this.currentBpm();
+  }
+
+  /** Tempo at the playhead (the song tempo without a tempo map). */
+  private currentBpm(): number {
+    const score = this.host.score();
+    if (!hasTempoMap(score)) return score.tempoBpm;
+    return bpmAtTick(
+      score,
+      loopTickAt(score, this.host.beatAt(this.host.now())),
+    );
   }
 
   public async enter(): Promise<void> {
@@ -265,11 +338,27 @@ export class PlaySession {
   /** The click bus the engine mixes: count-in, then the transport. */
   public clickBus(): ClickBus {
     const score = this.host.score();
+    const count = this.countIn;
+    // Without meter changes the fixed beatsPerBar grid clicks as in 0.4.
+    let grid: ClickBus["grid"];
+    if (count && hasMeterChanges(score))
+      grid = (from, to) =>
+        countInClicks(
+          count.startBeat,
+          count.beats / count.barBeats,
+          count.barBeats,
+          count.clickBeats,
+          from,
+          to,
+        );
+    else if (!count && hasMeterChanges(score))
+      grid = meterClickGrid(() => this.host.score());
     return {
       volume: this.clickVolume,
       beatsPerBar: score.beatsPerBar,
       subdivision: 1,
       beatAt: (ms) => this.clickBeatAt(ms),
+      ...(grid ? { grid } : {}),
     };
   }
 
@@ -277,7 +366,7 @@ export class PlaySession {
   public clickBeatAt(ms: number): number | undefined {
     const count = this.countIn;
     if (count) {
-      const beatMs = 60_000 / this.host.score().tempoBpm;
+      const beatMs = 60_000 / count.bpm;
       return count.startBeat - count.beats + (ms - count.startMs) / beatMs;
     }
     if (!this.clickOn || !this.host.playing()) return undefined;
@@ -320,6 +409,7 @@ export class PlaySession {
   /** Handle one decoded key; mode commands return to the caller. */
   public press(value: string): PlayKeyResult {
     const now = this.host.now();
+    this.syncDegrees();
     let key = value;
     if (this.chords.on && value === "n") {
       // Route the suggestion through the note key of its root, so holding
@@ -340,16 +430,21 @@ export class PlaySession {
       }
     }
     const action = this.keyboard.press(key, now, this.gateMs());
-    return this.apply(action, now);
+    const result = this.apply(action, now);
+    this.recordPedal(now);
+    return result;
   }
 
   /** The suggested next chord and the lowest note key on its root. */
   private nextRoute(): { key: string; chord: PlayedChord["chord"] } {
     const chord = this.chords.next();
-    const keys = Object.entries(NOTE_KEYS).sort((a, b) => a[1] - b[1]);
-    const found = keys.find(
-      ([, offset]) => (this.keyboard.base + offset - chord.root) % 12 === 0,
-    );
+    const keys = Object.keys(NOTE_KEYS)
+      .map((key) => [key, this.keyboard.pitchFor(key)] as const)
+      .filter(
+        (entry): entry is readonly [string, number] => entry[1] !== undefined,
+      )
+      .sort((a, b) => a[1] - b[1]);
+    const found = keys.find(([, pitch]) => (pitch - chord.root) % 12 === 0);
     return { key: found?.[0] ?? "a", chord };
   }
 
@@ -402,7 +497,15 @@ export class PlaySession {
           this.stopChord(action.absorbed);
           this.pending.delete(action.absorbed);
         }
-        if (pending) pending.releaseAtMs = action.releaseAtMs;
+        if (pending) {
+          pending.releaseAtMs = action.releaseAtMs;
+          pending.keyUpMs = Math.max(
+            pending.keyUpMs,
+            pending.chord || Number.isFinite(action.releaseAtMs)
+              ? action.releaseAtMs
+              : now + this.gateMs(),
+          );
+        }
         const live = this.liveChords.get(action.id);
         if (live) {
           live.releaseAtMs = action.releaseAtMs;
@@ -442,9 +545,47 @@ export class PlaySession {
       this.status = this.clickCommand("toggle");
       return { type: "handled" };
     }
+    if (command === "degrees") {
+      this.status = this.toggleDegrees();
+      return { type: "handled" };
+    }
     return { type: "command", command };
   }
 
+  /**
+   * `i`: the home row plays scale degrees (the song key's scale, or every
+   * step of a non-12 tuning) instead of chromatic keys. Drum kits and
+   * sampler slots keep their pads.
+   */
+  public toggleDegrees(on = !this.degreesOn): string {
+    if (on && this.layout.labels.size > 0)
+      return "scale degrees need a melodic track";
+    this.degreesOn = on;
+    this.degreeKey = undefined;
+    this.syncDegrees();
+    return on
+      ? `scale degrees · ${this.keyboard.degrees!.name} · ${this.keyboard.range}`
+      : `chromatic · ${this.keyboard.range}`;
+  }
+
+  /** Follows the song key and tuning while degree mode is on. */
+  private syncDegrees(): void {
+    if (!this.degreesOn) {
+      this.keyboard.degrees = undefined;
+      return;
+    }
+    const score = this.host.score();
+    const track = this.trackData();
+    const signature = JSON.stringify([score.key, score.tuning, track?.tuning]);
+    if (signature === this.degreeKey && this.keyboard.degrees) return;
+    this.degreeKey = signature;
+    const table =
+      score.tuning || track?.tuning
+        ? resolveTuning(score.tuning, track?.tuning, score.key)
+        : undefined;
+    this.keyboard.degrees = degreeLayout(score.key, table);
+  }
+
   /** Render the note through the track's own voice and start it. */
   private sound(id: number, note: PlayedNote): void {
     const engine = this.host.engine();
@@ -455,13 +596,17 @@ export class PlaySession {
     const samples = this.host.samples?.();
     if (this.synth?.rate !== engine.sampleRate)
       this.synth = new LiveSynth(engine.sampleRate);
+    const score = this.host.score();
     const pcm = this.synth.render({
-      score: this.host.score(),
+      score,
       trackId: this.trackId,
       pitch: note.pitch,
       velocity: note.velocity / 127,
       seconds,
       ...(samples ? { samples } : {}),
+      ...(score.time?.tempo
+        ? { tick: loopTickAt(score, this.host.beatAt(note.atMs)) }
+        : {}),
     });
     if (!pcm) return;
     const scheduled = engine.noteOn(id, pcm);
@@ -475,7 +620,10 @@ export class PlaySession {
       const live = this.liveChords.get(id);
       if (live) live.releaseAtMs = Math.min(live.releaseAtMs, atMs);
       const pending = this.pending.get(id);
-      if (pending) pending.releaseAtMs = atMs;
+      if (pending) {
+        pending.releaseAtMs = atMs;
+        pending.keyUpMs = Math.min(pending.keyUpMs, atMs);
+      }
     }
   }
 
@@ -492,10 +640,38 @@ export class PlaySession {
       atMs: note.atMs,
       beat: this.host.beatAt(note.atMs),
       releaseAtMs: note.releaseAtMs,
+      // A chord press lays its voices out over the held length (arps keep
+      // stepping while the pedal holds), so it keeps that length.
+      keyUpMs:
+        chord || Number.isFinite(note.releaseAtMs)
+          ? note.releaseAtMs
+          : note.atMs + this.gateMs(),
       ...(chord ? { chord } : {}),
     });
   }
 
+  /**
+   * Record a sustain change (Tab latch, or Shift held on note keys) as a
+   * pedal event at the playhead, like Logic's Musical Typing records its Tab
+   * sustain key as CC64.
+   */
+  private recordPedal(now: number): void {
+    // Chord presses record the held length on their voices instead.
+    const down =
+      this.keyboard.sustain &&
+      ![...this.pending.values()].some((pending) => pending.chord);
+    if (!this.recording) {
+      if (!down) this.pedalDown = false;
+      return;
+    }
+    if (down === this.pedalDown) return;
+    this.pedalDown = down;
+    this.pendingPedal.push({
+      beat: this.host.beatAt(now),
+      state: down ? "down" : "up",
+    });
+  }
+
   private recordedChord(
     played: PlayedChord,
     seed: number,
@@ -560,7 +736,7 @@ export class PlaySession {
   }
 
   private beatMs(): number {
-    return 60_000 / this.host.score().tempoBpm;
+    return 60_000 / this.currentBpm();
   }
 
   /** Start due voices, end finished ones, drop released chords. */
@@ -639,17 +815,25 @@ export class PlaySession {
   public startWithCountIn(): boolean {
     if (!this.armed || this.host.playing() || this.countIn) return false;
     const score = this.host.score();
-    const startBeat =
-      Math.floor(this.host.beatAt(this.host.now()) / score.beatsPerBar) *
-      score.beatsPerBar;
+    const startBeat = transportBarStart(
+      score,
+      transportBar(score, this.host.beatAt(this.host.now())),
+    );
     if (this.countInBars === 0) {
       void this.host.startTransport(startBeat);
       return true;
     }
+    // Count in the meter and tempo of the bar recording starts in.
+    const at = barAt(score, loopTickAt(score, startBeat));
+    const tpb = score.ticksPerBeat;
+    const barBeats = at.barTicks / tpb;
     this.countIn = {
       startMs: this.host.now(),
-      beats: this.countInBars * score.beatsPerBar,
+      beats: this.countInBars * barBeats,
       startBeat,
+      bpm: bpmAtTick(score, at.tick),
+      barBeats,
+      clickBeats: clickTicksOf(at, tpb) / tpb,
     };
     this.applyClick();
     return true;
@@ -662,7 +846,7 @@ export class PlaySession {
     this.pumpChords(now);
     const count = this.countIn;
     if (count) {
-      const beatMs = 60_000 / this.host.score().tempoBpm;
+      const beatMs = 60_000 / count.bpm;
       if (now - count.startMs >= count.beats * beatMs) {
         this.countIn = undefined;
         this.applyClick();
@@ -677,14 +861,28 @@ export class PlaySession {
       return;
     }
     const score = this.host.score();
-    const bar = Math.floor(this.host.beatAt(now) / score.beatsPerBar);
+    const bar = transportBar(score, this.host.beatAt(now));
+    if (bar !== this.lastBar)
+      this.barPedal.set(this.loopBar(bar), this.pedalDown ? "down" : "up");
     if (this.lastBar !== undefined && bar !== this.lastBar) {
-      if (this.replace) this.replaceBars.add(this.loopBar(this.lastBar));
+      if (this.replace)
+        this.replaceBars.add(
+          this.loopBar(
+            Math.floor(
+              this.toScoreBeat(this.lastBar * score.beatsPerBar) /
+                score.beatsPerBar,
+            ),
+          ),
+        );
       this.queueFlush(bar, now, false);
     }
     this.lastBar = bar;
   }
 
+  private toScoreBeat(beat: number): number {
+    return this.host.scoreBeat ? this.host.scoreBeat(beat) : beat;
+  }
+
   private loopBar(bar: number): number {
     const bars = this.host.score().bars;
     return ((bar % bars) + bars) % bars;
@@ -693,6 +891,10 @@ export class PlaySession {
   /** Commit what record armed collected; called when recording ends. */
   public async stopRecording(): Promise<void> {
     const now = this.host.now();
+    // A pedal still down when recording stops lifts here.
+    if (this.pedalDown && this.host.playing())
+      this.pendingPedal.push({ beat: this.host.beatAt(now), state: "up" });
+    this.pedalDown = false;
     this.queueFlush(Number.POSITIVE_INFINITY, now, true);
     await this.flushing;
     this.recordedIds.clear();
@@ -722,24 +924,52 @@ export class PlaySession {
     const score = this.host.score();
     const ready: Pending[] = [];
     for (const pending of this.pending.values()) {
-      const bar = Math.floor(pending.beat / score.beatsPerBar);
-      const released = pending.releaseAtMs <= now;
+      const bar = transportBar(score, pending.beat);
+      const released = pending.keyUpMs <= now;
       if (all || (bar < currentBar && released)) ready.push(pending);
     }
     const erase = [...this.replaceBars];
     this.replaceBars.clear();
-    if (ready.length === 0 && erase.length === 0) return;
-    for (const pending of ready) this.pending.delete(pending.id);
+    const pedal = this.pendingPedal.filter(
+      (event) => all || transportBar(score, event.beat) < currentBar,
+    );
+    this.pendingPedal = this.pendingPedal.filter(
+      (event) => !pedal.includes(event),
+    );
+    if (ready.length === 0 && erase.length === 0 && pedal.length === 0) return;
+    const eraseStates = new Map(
+      erase.map((bar) => [bar, this.barPedal.get(bar) ?? "up"] as const),
+    );
+    try {
+      await this.commitTake(score, ready, erase, eraseStates, pedal, now);
+    } catch (error) {
+      // Nothing was committed: keep the take so the next flush retries it.
+      for (const pending of ready) this.pending.set(pending.id, pending);
+      for (const bar of erase) this.replaceBars.add(bar);
+      this.pendingPedal = [...pedal, ...this.pendingPedal];
+      throw error;
+    }
+  }
+
+  private async commitTake(
+    score: TrackScore,
+    ready: readonly Pending[],
+    erase: readonly number[],
+    eraseStates: ReadonlyMap<number, PedalState>,
+    pedal: readonly { beat: number; state: PedalState }[],
+    now: number,
+  ): Promise<void> {
     const operations = recordOperations(score, {
       trackId: this.trackId,
       notes: ready.flatMap((pending) => {
-        const beats =
-          ((Math.min(pending.releaseAtMs, now) - pending.atMs) *
-            score.tempoBpm) /
-          60_000;
+        const beats = hasTempoMap(score)
+          ? this.host.beatAt(Math.min(pending.keyUpMs, now)) -
+            this.host.beatAt(pending.atMs)
+          : ((Math.min(pending.keyUpMs, now) - pending.atMs) * score.tempoBpm) /
+            60_000;
         return pending.chord
           ? chordNotes(pending.chord, {
-              beat: pending.beat,
+              beat: this.toScoreBeat(pending.beat),
               beats,
               velocity: pending.velocity,
               grid: this.gridStep,
@@ -748,7 +978,7 @@ export class PlaySession {
               {
                 pitch: pending.pitch,
                 velocity: pending.velocity,
-                beat: pending.beat,
+                beat: this.toScoreBeat(pending.beat),
                 beats,
               },
             ];
@@ -758,22 +988,37 @@ export class PlaySession {
       keep: this.recordedIds,
       newId: () => this.host.newNoteId(),
     });
+    // A pedal lane that cannot take more events never costs the notes.
+    let pedalNote = "";
+    try {
+      const pedalOperation = recordPedalOperation(score, {
+        trackId: this.trackId,
+        events: pedal,
+        eraseBars: erase,
+        eraseStates,
+      });
+      if (pedalOperation) operations.push(pedalOperation);
+    } catch (error) {
+      if (!(error instanceof ExpressionValidationError)) throw error;
+      pedalNote = ` · pedal not recorded (${error.message})`;
+    }
     if (operations.length === 0) return;
     let next = score;
     for (const operation of operations)
       next = applyScoreOperation(next, operation);
-    for (const operation of operations)
-      if (operation.type === "addNote") this.recordedIds.add(operation.note.id);
     const added = operations.filter((op) => op.type === "addNote").length;
-    const removed = operations.length - added;
+    const removed = operations.filter((op) => op.type === "removeNote").length;
     await this.host.commit(next, "score.record", {
       trackId: this.trackId,
       operations,
       replace: this.replace,
     });
+    for (const pending of ready) this.pending.delete(pending.id);
+    for (const operation of operations)
+      if (operation.type === "addNote") this.recordedIds.add(operation.note.id);
     this.host.card(
-      `recorded ${added} note${added === 1 ? "" : "s"}${removed ? ` · replaced ${removed}` : ""} · ${this.trackId}`,
-      "success",
+      `recorded ${added} note${added === 1 ? "" : "s"}${pedal.length && !pedalNote ? ` · ${pedal.length} pedal` : ""}${removed ? ` · replaced ${removed}` : ""} · ${this.trackId}${pedalNote}`,
+      pedalNote ? "warning" : "success",
     );
   }
 
@@ -783,13 +1028,13 @@ export class PlaySession {
     const count = this.countIn;
     let beat: PlayHeaderView["beat"];
     let countIn: string | undefined;
-    const beatMs = 60_000 / score.tempoBpm;
+    const beatMs = 60_000 / (count?.bpm ?? score.tempoBpm);
     const at = count
       ? count.startBeat - count.beats + (now - count.startMs) / beatMs
       : this.host.playing()
         ? this.host.beatAt(now)
         : undefined;
-    if (at !== undefined) {
+    if (at !== undefined && (count || !hasMeterChanges(score))) {
       const whole = Math.floor(at);
       const inBar =
         ((whole % score.beatsPerBar) + score.beatsPerBar) % score.beatsPerBar;
@@ -798,7 +1043,37 @@ export class PlaySession {
         of: score.beatsPerBar,
         flash: (at - whole) * beatMs < FLASH_MS,
       };
-      if (count) countIn = `count-in ${Math.ceil(count.startBeat - at)}`;
+      if (count) {
+        const clicks = Math.round(count.barBeats / count.clickBeats);
+        const step = Math.floor(
+          (at - (count.startBeat - count.beats)) / count.clickBeats,
+        );
+        beat = {
+          index: (((step % clicks) + clicks) % clicks) + 1,
+          of: clicks,
+          flash:
+            ((at - (count.startBeat - count.beats)) % count.clickBeats) *
+              beatMs <
+            FLASH_MS,
+        };
+        countIn = `count-in ${Math.ceil((count.startBeat - at) / count.clickBeats)}`;
+      }
+    } else if (at !== undefined) {
+      // Meter changes: count the clicks of the bar the playhead is in.
+      const tpb = score.ticksPerBeat;
+      const position = barAt(score, loopTickAt(score, at));
+      const click = clickTicksOf(position, tpb);
+      const inBar = position.offset / click;
+      const whole = Math.floor(inBar);
+      beat = {
+        index: whole + 1,
+        of: Math.round(position.barTicks / click),
+        flash:
+          ((inBar - whole) * click * 60_000) /
+            tpb /
+            bpmAtTick(score, position.tick + whole * click) <
+          FLASH_MS,
+      };
     }
     return {
       range: this.keyboard.range,
@@ -828,6 +1103,7 @@ export class PlaySession {
   }
 
   public strip(now = this.host.now()): PlayStripKey[] {
+    this.syncDegrees();
     return stripCells(
       this.keyboard,
       this.keyboard.litKeys(now),
@@ -929,14 +1205,16 @@ export function recordOperations(
   }>,
 ): ScoreOperation[] {
   const operations: ScoreOperation[] = [];
-  const loopBeats = score.bars * score.beatsPerBar;
   const tpb = score.ticksPerBeat;
+  const loopBeats = loopTicksOf(score) / tpb;
   const erase = new Set(options.eraseBars ?? []);
   if (erase.size > 0)
     for (const note of score.notes) {
       if (note.trackId !== options.trackId) continue;
       if (options.keep?.has(note.id)) continue;
-      const bar = Math.floor(note.startTick / tpb / score.beatsPerBar);
+      const bar = hasMeterChanges(score)
+        ? barAt(score, note.startTick).bar
+        : Math.floor(note.startTick / tpb / score.beatsPerBar);
       if (erase.has(bar))
         operations.push({ type: "removeNote", noteId: note.id });
     }
@@ -982,3 +1260,98 @@ export function recordOperations(
   }
   return operations;
 }
+
+/**
+ * The `updateTrack` that merges recorded pedal events into the track,
+ * wrapped into the loop (unquantized: pedalling is about the release), after
+ * dropping existing events in `eraseBars` (replace). Undefined when nothing
+ * changes.
+ */
+export function recordPedalOperation(
+  score: TrackScore,
+  options: Readonly<{
+    trackId: string;
+    events: readonly { beat: number; state: PedalState }[];
+    eraseBars?: readonly number[];
+    /** The pedal as the take entered each erased bar (default `up`). */
+    eraseStates?: ReadonlyMap<number, PedalState>;
+  }>,
+): ScoreOperation | undefined {
+  const track = score.tracks.find((item) => item.id === options.trackId);
+  if (!track) return undefined;
+  const tpb = score.ticksPerBeat;
+  // Bars follow the meter map; without meter changes this is the 0.4 grid.
+  const maxTick = loopTicksOf(score);
+  const original = track.pedal ?? [];
+  const erase = new Set(options.eraseBars ?? []);
+  const kept = original.filter(
+    (event) => !erase.has(barAt(score, event.tick).bar),
+  );
+  if (options.events.length === 0 && erase.size === 0) return undefined;
+  const byTick = new Map<number, PedalEvent>(
+    kept.map((event) => [event.tick, event]),
+  );
+  // Replace: an erased bar starts in the state the take had there, and the
+  // old pedal resumes after it, so no stale press is left without its lift.
+  for (const bar of erase) {
+    const start = barStartTick(score, bar);
+    const end = barStartTick(score, bar + 1);
+    byTick.set(start, {
+      tick: start,
+      state: options.eraseStates?.get(bar) ?? "up",
+    });
+    if (end < maxTick && !erase.has(bar + 1) && !byTick.has(end))
+      byTick.set(end, { tick: end, state: pedalStateAt(original, end - 1) });
+  }
+  for (const event of options.events) {
+    let tick = Math.round(event.beat * tpb) % maxTick;
+    if (tick < 0) tick += maxTick;
+    byTick.set(tick, { tick, state: event.state });
+  }
+  const sorted = [...byTick.values()].sort((a, b) => a.tick - b.tick);
+  // A pedal held across the loop seam is down again from tick 0.
+  const seam = sorted[sorted.length - 1]?.state ?? "up";
+  if (options.events.length > 0 && seam !== "up" && sorted[0]?.tick !== 0)
+    sorted.unshift({ tick: 0, state: seam });
+  // Drop events that do not change the state (the lane has a size limit).
+  const compact: PedalEvent[] = [];
+  for (const event of sorted) {
+    const before = compact[compact.length - 1]?.state ?? "up";
+    if (event.state !== before) compact.push(event);
+  }
+  if (compact.length > EXPRESSION_LIMITS.maxPedalEvents)
+    throw new ExpressionValidationError(
+      `the pedal lane is full (${EXPRESSION_LIMITS.maxPedalEvents} events)`,
+    );
+  const pedal = normalizePedal(compact, maxTick);
+  const same =
+    (pedal?.length ?? 0) === original.length &&
+    (pedal ?? []).every(
+      (event, index) =>
+        event.tick === original[index]!.tick &&
+        event.state === original[index]!.state,
+    );
+  if (same) return undefined;
+  return {
+    type: "updateTrack",
+    trackId: options.trackId,
+    patch: { pedal: pedal && pedal.length > 0 ? pedal : null },
+  };
+}
+
+/** Whether `track` sounds in plain 12-TET (no tuning, or one equal to it). */
+function twelveTet(
+  score: Readonly<{ tuning?: Tuning; key?: string | null }>,
+  track: Readonly<{ tuning?: Tuning }> | undefined,
+): boolean {
+  if (!score.tuning && !track?.tuning) return true;
+  const table = resolveTuning(score.tuning, track?.tuning, score.key);
+  if (!table) return true;
+  if (table.size !== 12 || Math.abs(table.period - 1200) > 0.01) return false;
+  for (let key = 1; key < 128; key += 1) {
+    const [low, high] = [table.hz[key - 1]!, table.hz[key]!];
+    if (low <= 0 || high <= 0) return false;
+    if (Math.abs(1200 * Math.log2(high / low) - 100) > 0.5) return false;
+  }
+  return true;
+}