@jxgame2020/dsh-token-quota 0.1.26 → 0.1.28

package/lib/types/client/music.js

@@ -1,57 +1,71 @@
 /**
- * Live-composed ambient soundtrack driven by host actions (turns, steps,
- * tool calls, etc.). Three layers:
+ * 古风 live-composed soundtrack driven by host actions.
  *
- *  - **Pad**: a sustained three-note chord (triangle waves) that fades in when
- *    a request starts and crossfades to the next chord on every step.
- *  - **Bass**: one long root note per beat (lower octave), keeps the pulse.
- *  - **Melody**: an eighth-note scale line that dances inside the current
- *    chord — always in key, never a wrong note.
+ * Design: when a request starts the engine composes a *piece* — a guzheng-like
+ * plucked-string voice (Web Audio synthesis; the MIDI output is switched to
+ * the Koto program so hardware synths match). The piece plays phrase after
+ * phrase so it stays alive while the model thinks or streams; incoming events
+ * steer the piece instead of interrupting it: a step change rotates the mode
+ * centre and inserts a fast 过门 (fill); tool calls get a high plink; the
+ * ending gets a dizi-like breath note and a descending glissando.
  *
- * Outputs through Web Audio (built-in synthesis) by default, and also sends
- * MIDI NoteOn/NoteOff to the first available MIDI output when one is detected
- * (both play simultaneously when MIDI is present — use the panel volume for
- * overall level, the MIDI output has its own gain on the receiver).
+ * **No sustained tones by design.** Every voice is a decaying pluck (≤1.6s)
+ * or a fixed-duration breath note — there is no drone/pad oscillator that
+ * depends on a later stop event. A lost SSE event can at worst leave the
+ * phrase chain running, and the stream watchdog below stops that too, so a
+ * hanging "呜呜" hum is physically impossible.
+ *
+ * Anti-runaway guards:
+ *  - the host sends an SSE heartbeat every 5s; if it stops arriving the whole
+ *    engine stops (a dead stream means no stop event will ever come),
+ *  - every MIDI NoteOn is registered and swept; stops also send
+ *    All Notes Off (CC 123),
+ *  - every Web Audio oscillator is explicitly stopped at envelope end.
  *
  * @module @jxgame2020/dsh-token-quota/music
  */
-/** Scale degrees in semitones from the root. */
+/** Scale degrees in semitones from the (current) tonic. */
 const SCALES = {
     major: [0, 2, 4, 5, 7, 9, 11],
     minor: [0, 2, 3, 5, 7, 8, 10],
-    pentatonic: [0, 2, 4, 7, 9],
+    pentatonic: [0, 2, 4, 7, 9], // 宫商角徵羽
 };
 /**
- * Chord progression roots in semitones from the key centre. Loops — every
- * step advance moves one position forward.
+ * Tonic offsets for the progression — the piece rotates its mode centre on
+ * every step advance. For pentatonic this is 宫 → 羽 → 徵 → 商 (mode
+ * rotation on one scale), which is the classic gufeng colour.
  */
-const CHORD_PROGRESSIONS = {
-    major: [0, 9, 5, 7], // I - vi - IV - V
-    minor: [0, 9, 4, 11], // i - VI - III - VII
-    pentatonic: [0, 7, 2, 9], // open fifths feel — root + 5th
-};
-const CHORD_QUALITIES = {
-    major: ['major', 'minor', 'major', 'major'],
-    minor: ['minor', 'major', 'major', 'major'],
-    pentatonic: ['major', 'major', 'major', 'major'],
+const PROGRESSION = {
+    major: [0, 9, 5, 7],
+    minor: [0, 8, 3, 10],
+    pentatonic: [0, 9, 7, 5],
 };
+/**
+ * Phrase bank — pentatonic-degree melodies that also read fine on 7-note
+ * scales. Degrees index the current scale (values ≥ scale length wrap up an
+ * octave).
+ */
+const PHRASES = [
+    [{ deg: 0, beats: 2 }, { deg: 1, beats: 1 }, { deg: 2, beats: 1 }, { deg: 3, beats: 2 }, { deg: 2, beats: 1 }, { deg: 1, beats: 1 }, { deg: 0, beats: 3 }],
+    [{ deg: 5, beats: 1 }, { deg: 4, beats: 1 }, { deg: 3, beats: 2 }, { deg: 2, beats: 1 }, { deg: 1, beats: 2 }, { deg: 0, beats: 3 }],
+    [{ deg: 2, beats: 1 }, { deg: 3, beats: 1 }, { deg: 4, beats: 2 }, { deg: 5, beats: 1 }, { deg: 4, beats: 1 }, { deg: 3, beats: 2 }, { deg: 1, beats: 2 }, { deg: 0, beats: 2 }],
+    [{ deg: 4, beats: 2 }, { deg: 3, beats: 1 }, { deg: 2, beats: 1 }, { deg: 3, beats: 2 }, { deg: 1, beats: 1 }, { deg: 2, beats: 1 }, { deg: 0, beats: 4 }],
+];
+/** 过门 — a fast run played when a step (new phase) starts. */
+const FILL = [
+    { deg: 0, beats: 0.5 }, { deg: 1, beats: 0.5 }, { deg: 2, beats: 0.5 }, { deg: 3, beats: 0.5 },
+    { deg: 4, beats: 0.5 }, { deg: 5, beats: 0.5 }, { deg: 4, beats: 0.5 }, { deg: 3, beats: 0.5 },
+];
 /** Turn a MIDI note number into a frequency (equal temperament, A4 = 440). */
 function midiToFreq(midi) {
     return 440 * Math.pow(2, (midi - 69) / 12);
 }
-/** Interval in semitones from the root for each chord-tone. */
-function chordIntervals(quality) {
-    const third = quality === 'major' ? 4 : quality === 'minor' ? 3 : 3;
-    const fifth = quality === 'dim' ? 6 : 7;
-    return [0, third, fifth];
-}
+/** General-MIDI program closest to a guzheng: 108 Koto (0-indexed 106). */
+const GM_PROGRAM_KOTO = 106;
 /**
- * Live-composed music engine driven by host actions.
- *
- * The engine is idle until `ensureStarted()` is called from a user gesture
- * (the panel switch), and only produces sound while `enabled` is true AND a
- * request is in flight (pad + bass + melody are gated by `startPad` /
- * `stopPad`).
+ * Live-composed gufeng engine. Idle until `ensureStarted()` runs inside a
+ * user gesture; silent while `enabled` is false; the piece runs only between
+ * `request/header` (start) and `assistant/message` / `turn/end` (stop).
  */
 export class TokenQuotaMusic {
     audio = null;
@@ -59,36 +73,32 @@ export class TokenQuotaMusic {
     midiDetected = false;
     enabled = false;
     volume = 0.5;
-    style = 'major';
+    style = 'pentatonic';
     // Composition state
-    chordIndex = 0;
-    stepCount = 0;
-    toolCount = 0;
-    // Pad layer (sustained chord)
-    padOscs = [];
-    padGain = null;
-    padTarget = 0;
-    padActive = false;
-    // Bass + melody timing (shared beat clock)
-    beatTimer;
-    beatIndex = 0; // 0..3 inside a 4-beat bar
-    melodyDirection = 1;
-    melodyDegree = 0;
-    // Current chord (root midi + quality) for the melody and bass.
-    currentRoot = 60; // C4
-    currentQuality = 'major';
-    /** Base MIDI note of the key. C4 = middle C. */
+    playing = false;
+    tonicIndex = 0;
+    phraseIndex = 0;
+    /** True when the next piece start should play the full intro glissando. */
+    introPending = true;
+    phraseTimer;
+    // Watchdog: host heartbeat freshness (ms timestamp)
+    lastStreamActivity = 0;
+    watchdogTimer;
+    // MIDI note registry (anti hanging-note)
+    activeMidiNotes = new Set();
+    /** Base MIDI note of the tonic. C4 = middle C. */
     static BASE_MIDI = 60;
-    /** Beat length in ms — eighth note = beat / 2. */
-    static BEAT_MS = 640;
+    /** Beat length in ms — the phrase rhythm is measured in these. */
+    static BEAT_MS = 480;
+    /** Stop everything if the SSE stream goes silent this long. */
+    static STREAM_TIMEOUT_MS = 12_000;
     /** True once the audio context has been started (needs a user gesture). */
     get started() {
         return this.audio !== null;
     }
     /**
-     * Start the audio context and try to find a MIDI output.
-     * Must be called inside a user gesture (the panel switch click) so the
-     * AudioContext can resume. Safe to call multiple times.
+     * Start the audio context and probe for a MIDI output (once). Must be
+     * called inside a user gesture so the AudioContext can resume.
      */
     async ensureStarted() {
         if (this.audio !== null)
@@ -103,7 +113,9 @@ export class TokenQuotaMusic {
             this.audio = null;
             return false;
         }
-        // MIDI: try once; we don't re-probe (browser asks for permission only once).
+        // MIDI: probe once; switch the receiver to a plucked-string program so
+        // the timbre matches the gufeng idea (receivers that ignore program
+        // change just keep their own patch).
         if (!this.midiDetected && 'requestMIDIAccess' in navigator) {
             this.midiDetected = true;
             try {
@@ -112,12 +124,26 @@ export class TokenQuotaMusic {
                     this.midiOutput = output;
                     break;
                 }
+                try {
+                    this.midiOutput?.send([0xC0, GM_PROGRAM_KOTO]);
+                }
+                catch { /* optional */ }
             }
             catch {
-                // Permission denied or no MIDI hardware — stick to Web Audio.
                 this.midiOutput = null;
             }
         }
+        // Stream watchdog runs for the whole engine lifetime; it only acts while
+        // a piece is playing.
+        if (this.watchdogTimer === undefined) {
+            this.lastStreamActivity = Date.now();
+            this.watchdogTimer = setInterval(() => {
+                if (this.playing && Date.now() - this.lastStreamActivity > TokenQuotaMusic.STREAM_TIMEOUT_MS) {
+                    // Dead stream: no stop event will ever arrive — stop the piece.
+                    this.stopPiece(false);
+                }
+            }, 4_000);
+        }
         return true;
     }
     setEnabled(value) {
@@ -127,261 +153,294 @@ export class TokenQuotaMusic {
     }
     setVolume(value) {
         this.volume = Math.max(0, Math.min(1, value));
-        if (this.padGain !== null && this.audio !== null) {
-            this.padGain.gain.setValueAtTime(this.volume * this.padTarget, this.audio.currentTime);
-        }
     }
     setStyle(value) {
         this.style = value;
-        // Reset position so the new scale feels immediately.
-        this.melodyDegree = 0;
-        this.melodyDirection = 1;
     }
-    /** Handle one incoming host action and turn it into sound. */
+    /** Feed the engine one SSE activity timestamp (action or heartbeat). */
+    markStreamActivity() {
+        this.lastStreamActivity = Date.now();
+    }
+    /** Handle one incoming host action and steer the piece. */
     onAction(action) {
         if (!this.enabled || this.audio === null)
             return;
         const base = TokenQuotaMusic.BASE_MIDI;
         switch (action.type) {
             case 'turn/start':
-                this.stopAll();
-                this.chordIndex = 0;
-                this.stepCount = 0;
-                this.toolCount = 0;
-                this.currentRoot = base;
-                this.currentQuality = CHORD_QUALITIES[this.style][0] ?? 'major';
-                this.playChord(base, this.currentQuality, 1.6, 0.6);
+                this.stopPiece(false);
+                this.tonicIndex = 0;
+                this.phraseIndex = 0;
+                this.introPending = true;
                 break;
-            case 'step/start': {
-                this.chordIndex = (this.chordIndex + 1) % CHORD_PROGRESSIONS[this.style].length;
-                this.stepCount += 1;
-                const root = base + (CHORD_PROGRESSIONS[this.style][this.chordIndex] ?? 0);
-                const quality = CHORD_QUALITIES[this.style][this.chordIndex] ?? 'major';
-                this.currentRoot = root;
-                this.currentQuality = quality;
-                if (this.padActive)
-                    this.crossfadePad(root, quality);
+            case 'request/header': {
+                if (!this.playing)
+                    this.startPiece();
+                else
+                    this.pluck(base + 24, 0.3); // light accent on a subsequent request
                 break;
             }
-            case 'request/header': {
-                // Kick off the full three-layer ambient bed — the model is thinking
-                // and the user is waiting; this is where the soundtrack lives.
-                this.startPad(this.currentRoot, this.currentQuality);
-                this.startBeatClock();
-                // Small melodic flicker on top to mark the exact start.
-                const degree = (this.stepCount * 2 + this.toolCount) % SCALES[this.style].length;
-                const note = base + 12 + (SCALES[this.style][degree] ?? 0);
-                this.playNote(note, 0.25, 0.4);
+            case 'step/start': {
+                // New phase: rotate the mode centre and insert a 过门 fill.
+                const prog = PROGRESSION[this.style];
+                this.tonicIndex = (this.tonicIndex + 1) % prog.length;
+                if (this.playing) {
+                    const newRoot = base + (prog[this.tonicIndex] ?? 0);
+                    this.insertFill(newRoot);
+                }
                 break;
             }
             case 'tool/call':
-                this.toolCount += 1;
-                // High plink + low percussive tap — stays distinguishable over the pad.
-                this.playNote(base + 24 + (this.toolCount % 3) * 2, 0.12, 0.45);
-                this.playNote(base - 12, 0.08, 0.3);
+                // High plink + low tap — distinct from the plucked melody.
+                this.pluck(base + 26, 0.45, 0.5);
+                this.pluck(base - 12, 0.3, 0.35);
                 break;
             case 'tool/result': {
                 if (action.error) {
-                    // Dissonant downward glint (two half-steps).
-                    this.playNote(base + 13, 0.18, 0.4);
-                    setTimeout(() => this.playNote(base + 12, 0.25, 0.4), 90);
+                    this.pluck(base + 13, 0.4, 0.6);
+                    setTimeout(() => this.pluck(base + 12, 0.4, 0.9), 90);
                 }
                 else {
-                    // Upward resolution.
-                    this.playNote(base + 9, 0.14, 0.35);
-                    setTimeout(() => this.playNote(base + 11, 0.22, 0.35), 70);
+                    this.pluck(base + 9, 0.35, 0.6);
+                    setTimeout(() => this.pluck(base + 11, 0.35, 0.9), 70);
                 }
                 break;
             }
             case 'assistant/attempt':
-                // Failed attempt: wind down a moment and play a falling tension figure.
-                this.playNote(base + 8, 0.18, 0.4);
-                setTimeout(() => this.playNote(base + 7, 0.2, 0.4), 100);
-                setTimeout(() => this.playNote(base + 5, 0.3, 0.4), 200);
+                // Failed attempt: falling tension figure.
+                this.pluck(base + 8, 0.4, 0.8);
+                setTimeout(() => this.pluck(base + 7, 0.4, 0.8), 110);
+                setTimeout(() => this.pluck(base + 5, 0.4, 0.8), 220);
                 break;
             case 'assistant/message':
-                this.stopBeatClock();
-                this.stopPad();
-                if (action.interrupted) {
-                    this.playChord(base + 7, 'dim', 0.9, 0.55);
-                }
-                else {
-                    this.playChord(this.currentRoot, this.currentQuality, 1.1, 0.6);
-                }
+                // Sentence end: stop the phrase chain and breathe. The next
+                // request/header (next step or next turn) starts a fresh phrase.
+                this.stopMelody();
+                this.playing = false;
+                this.breath(action.interrupted ? base + 6 : base + 12, 1.6);
                 break;
             case 'turn/end':
-                this.stopAll();
-                // Final tonic chord, longer release.
-                this.playChord(base, this.style === 'minor' ? 'minor' : 'major', 2.4, 0.7);
-                this.chordIndex = 0;
+                this.stopPiece(true);
                 break;
         }
     }
-    // ── pad layer (sustained chord) ────────────────────────────────────────
-    /** Start the pad from silence, fading in to the target level. */
-    startPad(rootMidi, quality) {
-        if (!this.audio)
+    // ── piece lifecycle ───────────────────────────────────────────────────
+    /** Start a new piece: intro run, then the phrase chain. */
+    startPiece() {
+        if (!this.audio || this.playing)
             return;
-        if (this.padActive)
-            return;
-        const now = this.audio.currentTime;
-        const gain = this.audio.createGain();
-        gain.gain.setValueAtTime(0, now);
-        gain.connect(this.audio.destination);
-        const intervals = chordIntervals(quality);
-        const oscs = [];
-        for (const interval of intervals) {
-            const osc = this.audio.createOscillator();
-            osc.type = 'triangle';
-            osc.frequency.value = midiToFreq(rootMidi + interval);
-            osc.connect(gain);
-            osc.start(now);
-            oscs.push(osc);
+        this.playing = true;
+        const root = TokenQuotaMusic.BASE_MIDI + (PROGRESSION[this.style][this.tonicIndex] ?? 0);
+        const scale = SCALES[this.style];
+        if (this.introPending) {
+            // Full intro: the ascending guzheng glissando that announces the piece.
+            this.introPending = false;
+            let t = 0;
+            for (let i = 0; i < 8; i++) {
+                const note = root + 12 * Math.floor(i / scale.length) + (scale[i % scale.length] ?? 0);
+                setTimeout(() => {
+                    if (this.playing)
+                        this.pluck(note, 0.3);
+                }, t);
+                t += 150;
+            }
+            this.phraseTimer = setTimeout(() => this.playPhrase(), t + 100);
+        }
+        else {
+            // Restart within the same turn: a short three-note pickup, no glissando.
+            for (let i = 0; i < 3; i++) {
+                setTimeout(() => {
+                    if (this.playing)
+                        this.pluck(root + 12 + (scale[i] ?? 0), 0.3);
+                }, i * 140);
+            }
+            this.phraseTimer = setTimeout(() => this.playPhrase(), 480);
         }
-        this.padOscs = oscs;
-        this.padGain = gain;
-        this.padTarget = 0.18;
-        gain.gain.linearRampToValueAtTime(this.volume * this.padTarget, now + 0.6);
-        this.padActive = true;
     }
-    /** Smoothly morph the pad to a new root + quality. */
-    crossfadePad(rootMidi, quality) {
-        if (!this.audio || !this.padActive || this.padGain === null)
+    /** Play one phrase, then chain into the next after a one-beat rest. */
+    playPhrase() {
+        if (!this.playing || !this.audio)
             return;
-        const now = this.audio.currentTime;
-        const intervals = chordIntervals(quality);
-        this.padOscs.forEach((osc, i) => {
-            const interval = intervals[i] ?? 0;
-            osc.frequency.setValueAtTime(osc.frequency.value, now);
-            osc.frequency.exponentialRampToValueAtTime(midiToFreq(rootMidi + interval), now + 0.5);
-        });
+        const root = TokenQuotaMusic.BASE_MIDI + (PROGRESSION[this.style][this.tonicIndex] ?? 0);
+        const scale = SCALES[this.style];
+        // Soft low root pluck under each phrase — a foundation that decays away
+        // instead of a sustained drone (nothing here can hang).
+        this.pluck(root - 12, 0.28, 1.6);
+        const phrase = PHRASES[this.phraseIndex % PHRASES.length];
+        this.phraseIndex += 1;
+        let t = 0;
+        for (const step of phrase) {
+            const note = root + (scale[step.deg % scale.length] ?? 0) + 12 * Math.floor(step.deg / scale.length);
+            const delay = t;
+            setTimeout(() => {
+                if (this.playing)
+                    this.pluck(note, 0.34);
+            }, delay);
+            t += step.beats * TokenQuotaMusic.BEAT_MS;
+        }
+        this.phraseTimer = setTimeout(() => this.playPhrase(), t + TokenQuotaMusic.BEAT_MS);
     }
-    /** Fade the pad to silence, then stop the oscillators. */
-    stopPad() {
-        if (!this.audio || !this.padActive || this.padGain === null)
+    /** Insert a 过门 fill: pause the chain, play the run, resume after. */
+    insertFill(root) {
+        if (!this.audio)
             return;
-        const now = this.audio.currentTime;
-        const gain = this.padGain;
-        gain.gain.cancelScheduledValues(now);
-        gain.gain.setValueAtTime(gain.gain.value, now);
-        gain.gain.linearRampToValueAtTime(0, now + 0.8);
-        const oscs = this.padOscs;
-        setTimeout(() => {
-            for (const osc of oscs) {
-                try {
-                    osc.stop();
-                }
-                catch { /* ignore */ }
-                try {
-                    osc.disconnect();
-                }
-                catch { /* ignore */ }
-            }
-            try {
-                gain.disconnect();
-            }
-            catch { /* ignore */ }
-        }, 850);
-        this.padActive = false;
-        this.padOscs = [];
-        this.padGain = null;
+        this.stopMelody();
+        const scale = SCALES[this.style];
+        let t = 0;
+        for (const step of FILL) {
+            const note = root + (scale[step.deg % scale.length] ?? 0) + 12 * Math.floor(step.deg / scale.length);
+            const delay = t;
+            setTimeout(() => {
+                if (this.playing)
+                    this.pluck(note, 0.32, 0.7);
+            }, delay);
+            t += step.beats * TokenQuotaMusic.BEAT_MS;
+        }
+        this.phraseTimer = setTimeout(() => this.playPhrase(), t + 60);
     }
-    // ── beat clock (bass + melody) ────────────────────────────────────────
-    /** Start the per-beat clock that drives bass and melody. */
-    startBeatClock() {
-        if (this.beatTimer !== undefined)
-            return;
-        this.beatIndex = 0;
-        this.melodyDegree = 0;
-        this.melodyDirection = 1;
-        const tick = () => {
-            if (!this.audio || !this.enabled)
-                return;
-            // Bass note on beats 1 and 3 — root of the current chord, low octave.
-            if (this.beatIndex % 2 === 0) {
-                this.playNote(this.currentRoot - 12, 0.45, 0.3);
-            }
-            // Melody: eighth-note scale line inside the current chord.
+    /** Stop the phrase chain. */
+    stopMelody() {
+        if (this.phraseTimer !== undefined) {
+            clearTimeout(this.phraseTimer);
+            this.phraseTimer = undefined;
+        }
+    }
+    /** Stop the whole piece; `final` adds the closing cadence gestures. */
+    stopPiece(final) {
+        this.stopMelody();
+        this.playing = false;
+        if (final && this.audio) {
+            const base = TokenQuotaMusic.BASE_MIDI;
+            // Descending pentatonic glissando + tonic open-fifth pluck chord.
             const scale = SCALES[this.style];
-            const chordTones = new Set(chordIntervals(this.currentQuality));
-            // Walk up and down the scale, preferring chord tones on beats.
-            let degree = this.melodyDegree;
-            // Pick the next scale degree in the current direction.
-            let next = degree + this.melodyDirection;
-            if (next >= scale.length) {
-                this.melodyDirection = -1;
-                next = scale.length - 2;
-            }
-            else if (next < 0) {
-                this.melodyDirection = 1;
-                next = 0;
-            }
-            this.melodyDegree = next;
-            degree = next;
-            // Make sure we land on a chord tone on the downbeat.
-            if (this.beatIndex % 2 === 0) {
-                const rootRel = (scale[degree] ?? 0) % 12;
-                if (!chordTones.has(rootRel)) {
-                    // Shift one step toward the nearest chord tone.
-                    this.melodyDegree += this.melodyDirection;
-                    degree = this.melodyDegree;
-                }
+            let t = 0;
+            for (let i = 7; i >= 0; i--) {
+                const note = base + 12 * Math.floor(i / scale.length) + (scale[i % scale.length] ?? 0);
+                setTimeout(() => this.pluck(note, 0.3), t);
+                t += 120;
             }
-            const note = this.currentRoot + 12 + (scale[degree] ?? 0);
-            // Melody note — slightly shorter than a beat, staccato feel.
-            this.playNote(note, 0.22, 0.28);
-            this.beatIndex = (this.beatIndex + 1) % 4;
-        };
-        // First tick right away so the melody starts with the request.
-        tick();
-        this.beatTimer = setInterval(tick, TokenQuotaMusic.BEAT_MS);
-    }
-    stopBeatClock() {
-        if (this.beatTimer !== undefined) {
-            clearInterval(this.beatTimer);
-            this.beatTimer = undefined;
+            setTimeout(() => {
+                this.pluck(base, 0.5);
+                this.pluck(base + 7, 0.45);
+                this.pluck(base + 12, 0.4);
+                this.pluck(base - 12, 0.5);
+            }, t + 150);
         }
+        this.allMidiOff();
     }
-    // ── teardown ──────────────────────────────────────────────────────────
+    /** Hard stop everything (master switch off / teardown). */
     stopAll() {
-        this.stopBeatClock();
-        this.stopPad();
+        this.stopPiece(false);
+    }
+    // ── voices ────────────────────────────────────────────────────────────
+    /**
+     * Guzheng-like pluck: a triangle voice plus a soft octave partial through a
+     * sweeping lowpass, fast attack and a long exponential decay (notes
+     * overlap, which keeps the piece continuous instead of choppy).
+     */
+    pluck(midi, velocity, decaySec = 1.3) {
+        if (!this.audio)
+            return;
+        const peak = this.volume * velocity * 0.4;
+        if (peak <= 0)
+            return;
+        const now = this.audio.currentTime;
+        const freq = midiToFreq(midi);
+        const gain = this.audio.createGain();
+        const filter = this.audio.createBiquadFilter();
+        filter.type = 'lowpass';
+        filter.frequency.setValueAtTime(2400, now);
+        filter.frequency.exponentialRampToValueAtTime(420, now + decaySec);
+        filter.Q.value = 0.6;
+        gain.gain.setValueAtTime(0.0001, now);
+        gain.gain.exponentialRampToValueAtTime(peak, now + 0.006);
+        gain.gain.exponentialRampToValueAtTime(0.0001, now + decaySec);
+        filter.connect(gain);
+        gain.connect(this.audio.destination);
+        const osc1 = this.audio.createOscillator();
+        osc1.type = 'triangle';
+        osc1.frequency.value = freq;
+        const osc2 = this.audio.createOscillator();
+        osc2.type = 'sine';
+        osc2.frequency.value = freq * 2; // octave partial (no detune beating)
+        const octGain = this.audio.createGain();
+        octGain.gain.value = 0.25;
+        osc1.connect(filter);
+        osc2.connect(octGain);
+        octGain.connect(filter);
+        osc1.start(now);
+        osc1.stop(now + decaySec + 0.1);
+        osc2.start(now);
+        osc2.stop(now + decaySec + 0.1);
+        this.midiNote(midi, decaySec, velocity);
     }
-    // ── primitive note / chord playback (shared by all layers) ────────────
-    /** Play one note: Web Audio + MIDI simultaneously when available. */
-    playNote(midi, durationSec, velocity) {
+    /** Dizi-like breath note: sine with vibrato and a soft envelope. */
+    breath(midi, durationSec) {
         if (!this.audio)
             return;
-        const peak = this.volume * velocity * 0.5;
+        const peak = this.volume * 0.22;
         if (peak <= 0)
             return;
         const now = this.audio.currentTime;
         const osc = this.audio.createOscillator();
         osc.type = 'sine';
         osc.frequency.value = midiToFreq(midi);
+        const lfo = this.audio.createOscillator();
+        lfo.frequency.value = 5.2;
+        const lfoGain = this.audio.createGain();
+        lfoGain.gain.value = 4.5; // Hz of vibrato depth
+        lfo.connect(lfoGain);
+        lfoGain.connect(osc.frequency);
         const gain = this.audio.createGain();
         gain.gain.setValueAtTime(0, now);
-        gain.gain.linearRampToValueAtTime(peak, now + 0.008);
-        gain.gain.exponentialRampToValueAtTime(0.001, now + durationSec);
+        gain.gain.linearRampToValueAtTime(peak, now + 0.18);
+        gain.gain.setValueAtTime(peak, now + durationSec * 0.6);
+        gain.gain.linearRampToValueAtTime(0.0001, now + durationSec);
         osc.connect(gain);
         gain.connect(this.audio.destination);
         osc.start(now);
-        osc.stop(now + durationSec + 0.05);
-        if (this.midiOutput !== null) {
-            const vel = Math.max(1, Math.floor(velocity * 127));
-            this.midiOutput.send([0x90, midi & 0x7F, vel]);
-            setTimeout(() => {
-                this.midiOutput?.send([0x80, midi & 0x7F, 0]);
-            }, durationSec * 1000);
+        lfo.start(now);
+        osc.stop(now + durationSec + 0.1);
+        lfo.stop(now + durationSec + 0.1);
+        this.midiNote(midi, durationSec, 0.5);
+    }
+    // ── MIDI plumbing ─────────────────────────────────────────────────────
+    /** Send one MIDI note with a registered NoteOff (anti hanging note). */
+    midiNote(midi, durationSec, velocity) {
+        if (this.midiOutput === null)
+            return;
+        const note = midi & 0x7F;
+        const vel = Math.max(1, Math.min(127, Math.floor(velocity * 127)));
+        try {
+            this.midiOutput.send([0x90, note, vel]);
+        }
+        catch {
+            return;
         }
+        this.activeMidiNotes.add(note);
+        setTimeout(() => {
+            try {
+                this.midiOutput?.send([0x80, note, 0]);
+            }
+            catch { /* ignore */ }
+            this.activeMidiNotes.delete(note);
+        }, Math.max(80, durationSec * 1000));
     }
-    /** Play a three-note chord plus a bass octave below. */
-    playChord(rootMidi, quality, durationSec, velocity) {
-        const intervals = chordIntervals(quality);
-        for (const interval of intervals) {
-            this.playNote(rootMidi + interval, durationSec, velocity * 0.45);
+    /** Silence every registered note and send All Notes Off. */
+    allMidiOff() {
+        if (this.midiOutput === null)
+            return;
+        for (const note of this.activeMidiNotes) {
+            try {
+                this.midiOutput.send([0x80, note, 0]);
+            }
+            catch { /* ignore */ }
+        }
+        this.activeMidiNotes.clear();
+        try {
+            this.midiOutput.send([0xB0, 123, 0]);
         }
-        this.playNote(rootMidi - 12, durationSec * 1.1, velocity * 0.5);
+        catch { /* ignore */ }
     }
 }
 //# sourceMappingURL=music.js.map