@waveform-playlist/playout 9.0.3 → 9.1.0

package/dist/index.js

@@ -20,6 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  MidiToneTrack: () => MidiToneTrack,
+  SoundFontCache: () => SoundFontCache,
+  SoundFontToneTrack: () => SoundFontToneTrack,
   TonePlayout: () => TonePlayout,
   ToneTrack: () => ToneTrack,
   applyFadeIn: () => applyFadeIn,
@@ -39,7 +42,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/TonePlayout.ts
-var import_tone2 = require("tone");
+var import_tone4 = require("tone");
 
 // src/ToneTrack.ts
 var import_tone = require("tone");
@@ -449,6 +452,561 @@ var ToneTrack = class {
   }
 };
 
+// src/MidiToneTrack.ts
+var import_tone2 = require("tone");
+function getDrumCategory(midiNote) {
+  if (midiNote === 35 || midiNote === 36) return "kick";
+  if (midiNote >= 37 && midiNote <= 40) return "snare";
+  if (midiNote === 41 || midiNote === 43 || midiNote === 45 || midiNote === 47 || midiNote === 48 || midiNote === 50)
+    return "tom";
+  return "cymbal";
+}
+var MidiToneTrack = class {
+  constructor(options) {
+    this.track = options.track;
+    this.volumeNode = new import_tone2.Volume(this.gainToDb(options.track.gain));
+    this.panNode = new import_tone2.Panner(options.track.stereoPan);
+    this.muteGain = new import_tone2.Gain(options.track.muted ? 0 : 1);
+    this.volumeNode.chain(this.panNode, this.muteGain);
+    this.synth = new import_tone2.PolySynth(import_tone2.Synth, options.synthOptions);
+    this.synth.connect(this.volumeNode);
+    this.kickSynth = new import_tone2.PolySynth(import_tone2.MembraneSynth, {
+      voice: import_tone2.MembraneSynth,
+      options: {
+        pitchDecay: 0.05,
+        octaves: 6,
+        envelope: { attack: 1e-3, decay: 0.4, sustain: 0, release: 0.1 }
+      }
+    });
+    this.snareSynth = new import_tone2.NoiseSynth({
+      noise: { type: "white" },
+      envelope: { attack: 1e-3, decay: 0.15, sustain: 0, release: 0.05 }
+    });
+    this.cymbalSynth = new import_tone2.PolySynth(import_tone2.MetalSynth, {
+      voice: import_tone2.MetalSynth,
+      options: {
+        envelope: { attack: 1e-3, decay: 0.3, release: 0.1 },
+        harmonicity: 5.1,
+        modulationIndex: 32,
+        resonance: 4e3,
+        octaves: 1.5
+      }
+    });
+    this.tomSynth = new import_tone2.PolySynth(import_tone2.MembraneSynth, {
+      voice: import_tone2.MembraneSynth,
+      options: {
+        pitchDecay: 0.08,
+        octaves: 4,
+        envelope: { attack: 1e-3, decay: 0.3, sustain: 0, release: 0.1 }
+      }
+    });
+    this.kickSynth.connect(this.volumeNode);
+    this.snareSynth.connect(this.volumeNode);
+    this.cymbalSynth.connect(this.volumeNode);
+    this.tomSynth.connect(this.volumeNode);
+    const destination = options.destination || (0, import_tone2.getDestination)();
+    if (options.effects) {
+      const cleanup = options.effects(this.muteGain, destination, false);
+      if (cleanup) {
+        this.effectsCleanup = cleanup;
+      }
+    } else {
+      this.muteGain.connect(destination);
+    }
+    this.scheduledClips = options.clips.map((clipInfo) => {
+      const visibleNotes = clipInfo.notes.filter((note) => {
+        const noteEnd = note.time + note.duration;
+        return note.time < clipInfo.offset + clipInfo.duration && noteEnd > clipInfo.offset;
+      });
+      const absClipStart = this.track.startTime + clipInfo.startTime;
+      const partEvents = visibleNotes.map((note) => {
+        const adjustedTime = note.time - clipInfo.offset;
+        const clampedStart = Math.max(0, adjustedTime);
+        const clampedDuration = Math.min(
+          note.duration - Math.max(0, clipInfo.offset - note.time),
+          clipInfo.duration - clampedStart
+        );
+        return {
+          time: absClipStart + clampedStart,
+          note: note.name,
+          midi: note.midi,
+          duration: Math.max(0, clampedDuration),
+          velocity: note.velocity,
+          channel: note.channel
+        };
+      });
+      const part = new import_tone2.Part((time, event) => {
+        if (event.duration > 0) {
+          this.triggerNote(
+            event.midi,
+            event.note,
+            event.duration,
+            time,
+            event.velocity,
+            event.channel
+          );
+        }
+      }, partEvents);
+      part.start(0);
+      return { clipInfo, part };
+    });
+  }
+  /**
+   * Trigger a note using the appropriate synth.
+   * Routes per-note: channel 9 → percussion synths, others → melodic PolySynth.
+   */
+  triggerNote(midiNote, noteName, duration, time, velocity, channel) {
+    if (channel === 9) {
+      const category = getDrumCategory(midiNote);
+      switch (category) {
+        case "kick":
+          this.kickSynth.triggerAttackRelease("C1", duration, time, velocity);
+          break;
+        case "snare":
+          try {
+            this.snareSynth.triggerAttackRelease(duration, time, velocity);
+          } catch (err) {
+            console.warn(
+              "[waveform-playlist] Snare overlap \u2014 previous hit still decaying, skipped:",
+              err
+            );
+          }
+          break;
+        case "tom": {
+          const tomPitches = {
+            41: "G1",
+            43: "A1",
+            45: "C2",
+            47: "D2",
+            48: "E2",
+            50: "G2"
+          };
+          this.tomSynth.triggerAttackRelease(
+            tomPitches[midiNote] || "C2",
+            duration,
+            time,
+            velocity
+          );
+          break;
+        }
+        case "cymbal":
+          this.cymbalSynth.triggerAttackRelease("C4", duration, time, velocity);
+          break;
+      }
+    } else {
+      this.synth.triggerAttackRelease(noteName, duration, time, velocity);
+    }
+  }
+  gainToDb(gain) {
+    return 20 * Math.log10(gain);
+  }
+  /**
+   * No-op for MIDI — schedule guard is for AudioBufferSourceNode ghost tick prevention.
+   * Tone.Part handles its own scheduling relative to Transport.
+   */
+  setScheduleGuardOffset(_offset) {
+  }
+  /**
+   * For MIDI, mid-clip sources are notes that should already be sounding.
+   * We trigger them with their remaining duration.
+   */
+  startMidClipSources(transportOffset, audioContextTime) {
+    for (const { clipInfo } of this.scheduledClips) {
+      const absClipStart = this.track.startTime + clipInfo.startTime;
+      const absClipEnd = absClipStart + clipInfo.duration;
+      if (absClipStart < transportOffset && absClipEnd > transportOffset) {
+        for (const note of clipInfo.notes) {
+          const adjustedTime = note.time - clipInfo.offset;
+          const noteAbsStart = absClipStart + Math.max(0, adjustedTime);
+          const noteAbsEnd = noteAbsStart + note.duration;
+          if (noteAbsStart < transportOffset && noteAbsEnd > transportOffset) {
+            const remainingDuration = noteAbsEnd - transportOffset;
+            try {
+              this.triggerNote(
+                note.midi,
+                note.name,
+                remainingDuration,
+                audioContextTime,
+                note.velocity,
+                note.channel
+              );
+            } catch (err) {
+              console.warn(
+                `[waveform-playlist] Failed to start mid-clip MIDI note "${note.name}" on track "${this.id}":`,
+                err
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Stop all sounding notes and cancel scheduled Part events.
+   */
+  stopAllSources() {
+    const now3 = (0, import_tone2.getContext)().rawContext.currentTime;
+    try {
+      this.synth.releaseAll(now3);
+      this.kickSynth.releaseAll(now3);
+      this.cymbalSynth.releaseAll(now3);
+      this.tomSynth.releaseAll(now3);
+    } catch (err) {
+      console.warn(`[waveform-playlist] Error releasing synth on track "${this.id}":`, err);
+    }
+  }
+  /**
+   * No-op for MIDI — MIDI uses note velocity, not gain fades.
+   */
+  prepareFades(_when, _offset) {
+  }
+  /**
+   * No-op for MIDI — no fade automation to cancel.
+   */
+  cancelFades() {
+  }
+  setVolume(gain) {
+    this.track.gain = gain;
+    this.volumeNode.volume.value = this.gainToDb(gain);
+  }
+  setPan(pan) {
+    this.track.stereoPan = pan;
+    this.panNode.pan.value = pan;
+  }
+  setMute(muted) {
+    this.track.muted = muted;
+    const value = muted ? 0 : 1;
+    const audioParam = getUnderlyingAudioParam(this.muteGain.gain);
+    audioParam?.setValueAtTime(value, 0);
+    this.muteGain.gain.value = value;
+  }
+  setSolo(soloed) {
+    this.track.soloed = soloed;
+  }
+  dispose() {
+    if (this.effectsCleanup) {
+      try {
+        this.effectsCleanup();
+      } catch (err) {
+        console.warn(
+          `[waveform-playlist] Error during MIDI track "${this.id}" effects cleanup:`,
+          err
+        );
+      }
+    }
+    this.stopAllSources();
+    this.scheduledClips.forEach(({ part }, index) => {
+      try {
+        part.dispose();
+      } catch (err) {
+        console.warn(
+          `[waveform-playlist] Error disposing Part ${index} on MIDI track "${this.id}":`,
+          err
+        );
+      }
+    });
+    const synthsToDispose = [
+      this.synth,
+      this.kickSynth,
+      this.snareSynth,
+      this.cymbalSynth,
+      this.tomSynth
+    ];
+    for (const s of synthsToDispose) {
+      try {
+        s?.dispose();
+      } catch (err) {
+        console.warn(`[waveform-playlist] Error disposing synth on MIDI track "${this.id}":`, err);
+      }
+    }
+    try {
+      this.volumeNode.dispose();
+    } catch (err) {
+      console.warn(
+        `[waveform-playlist] Error disposing volumeNode on MIDI track "${this.id}":`,
+        err
+      );
+    }
+    try {
+      this.panNode.dispose();
+    } catch (err) {
+      console.warn(`[waveform-playlist] Error disposing panNode on MIDI track "${this.id}":`, err);
+    }
+    try {
+      this.muteGain.dispose();
+    } catch (err) {
+      console.warn(`[waveform-playlist] Error disposing muteGain on MIDI track "${this.id}":`, err);
+    }
+  }
+  get id() {
+    return this.track.id;
+  }
+  get duration() {
+    if (this.scheduledClips.length === 0) return 0;
+    const lastClip = this.scheduledClips[this.scheduledClips.length - 1];
+    return lastClip.clipInfo.startTime + lastClip.clipInfo.duration;
+  }
+  get muted() {
+    return this.track.muted;
+  }
+  get startTime() {
+    return this.track.startTime;
+  }
+};
+
+// src/SoundFontToneTrack.ts
+var import_tone3 = require("tone");
+var _SoundFontToneTrack = class _SoundFontToneTrack {
+  constructor(options) {
+    this.activeSources = /* @__PURE__ */ new Set();
+    this.track = options.track;
+    this.soundFontCache = options.soundFontCache;
+    this.programNumber = options.programNumber ?? 0;
+    this.bankNumber = options.isPercussion ? 128 : 0;
+    this.volumeNode = new import_tone3.Volume(this.gainToDb(options.track.gain));
+    this.panNode = new import_tone3.Panner(options.track.stereoPan);
+    this.muteGain = new import_tone3.Gain(options.track.muted ? 0 : 1);
+    this.volumeNode.chain(this.panNode, this.muteGain);
+    const destination = options.destination || (0, import_tone3.getDestination)();
+    if (options.effects) {
+      const cleanup = options.effects(this.muteGain, destination, false);
+      if (cleanup) {
+        this.effectsCleanup = cleanup;
+      }
+    } else {
+      this.muteGain.connect(destination);
+    }
+    this.scheduledClips = options.clips.map((clipInfo) => {
+      const visibleNotes = clipInfo.notes.filter((note) => {
+        const noteEnd = note.time + note.duration;
+        return note.time < clipInfo.offset + clipInfo.duration && noteEnd > clipInfo.offset;
+      });
+      const absClipStart = this.track.startTime + clipInfo.startTime;
+      const partEvents = visibleNotes.map((note) => {
+        const adjustedTime = note.time - clipInfo.offset;
+        const clampedStart = Math.max(0, adjustedTime);
+        const clampedDuration = Math.min(
+          note.duration - Math.max(0, clipInfo.offset - note.time),
+          clipInfo.duration - clampedStart
+        );
+        return {
+          time: absClipStart + clampedStart,
+          note: note.name,
+          midi: note.midi,
+          duration: Math.max(0, clampedDuration),
+          velocity: note.velocity,
+          channel: note.channel
+        };
+      });
+      const part = new import_tone3.Part((time, event) => {
+        if (event.duration > 0) {
+          this.triggerNote(event.midi, event.duration, time, event.velocity, event.channel);
+        }
+      }, partEvents);
+      part.start(0);
+      return { clipInfo, part };
+    });
+  }
+  /**
+   * Trigger a note by creating a native AudioBufferSourceNode from the SoundFont cache.
+   *
+   * Per-note routing: channel 9 → bank 128 (drums), others → bank 0 with programNumber.
+   */
+  triggerNote(midiNote, duration, time, velocity, channel) {
+    const bank = channel === 9 ? 128 : this.bankNumber;
+    const preset = channel === 9 ? 0 : this.programNumber;
+    const sfSample = this.soundFontCache.getAudioBuffer(midiNote, bank, preset);
+    if (!sfSample) {
+      if (!_SoundFontToneTrack._missingSampleWarned) {
+        console.warn(
+          `[waveform-playlist] SoundFont sample not found for MIDI note ${midiNote} (bank ${bank}, preset ${preset}). Subsequent missing samples will be silent.`
+        );
+        _SoundFontToneTrack._missingSampleWarned = true;
+      }
+      return;
+    }
+    const rawContext = (0, import_tone3.getContext)().rawContext;
+    const source = rawContext.createBufferSource();
+    source.buffer = sfSample.buffer;
+    source.playbackRate.value = sfSample.playbackRate;
+    if (sfSample.loopMode === 1 || sfSample.loopMode === 3) {
+      source.loop = true;
+      source.loopStart = sfSample.loopStart;
+      source.loopEnd = sfSample.loopEnd;
+    }
+    const sampleDuration = sfSample.buffer.duration / sfSample.playbackRate;
+    const effectiveDuration = sfSample.loopMode === 0 ? Math.max(duration, sampleDuration) : duration;
+    const peakGain = velocity * velocity;
+    const gainNode = rawContext.createGain();
+    const { attackVolEnv, holdVolEnv, decayVolEnv, sustainVolEnv, releaseVolEnv } = sfSample;
+    const sustainGain = peakGain * sustainVolEnv;
+    gainNode.gain.setValueAtTime(0, time);
+    gainNode.gain.linearRampToValueAtTime(peakGain, time + attackVolEnv);
+    if (holdVolEnv > 1e-3) {
+      gainNode.gain.setValueAtTime(peakGain, time + attackVolEnv + holdVolEnv);
+    }
+    const decayStart = time + attackVolEnv + holdVolEnv;
+    gainNode.gain.linearRampToValueAtTime(sustainGain, decayStart + decayVolEnv);
+    gainNode.gain.setValueAtTime(sustainGain, time + effectiveDuration);
+    gainNode.gain.linearRampToValueAtTime(0, time + effectiveDuration + releaseVolEnv);
+    source.connect(gainNode);
+    gainNode.connect(this.volumeNode.input.input);
+    this.activeSources.add(source);
+    source.onended = () => {
+      this.activeSources.delete(source);
+      try {
+        gainNode.disconnect();
+      } catch (err) {
+        console.warn("[waveform-playlist] GainNode already disconnected:", err);
+      }
+    };
+    source.start(time);
+    source.stop(time + effectiveDuration + releaseVolEnv);
+  }
+  gainToDb(gain) {
+    return 20 * Math.log10(gain);
+  }
+  /**
+   * No-op — Tone.Part handles scheduling internally, no ghost tick guard needed.
+   */
+  setScheduleGuardOffset(_offset) {
+  }
+  /**
+   * Start notes that should already be sounding at the current transport offset.
+   */
+  startMidClipSources(transportOffset, audioContextTime) {
+    for (const { clipInfo } of this.scheduledClips) {
+      const absClipStart = this.track.startTime + clipInfo.startTime;
+      const absClipEnd = absClipStart + clipInfo.duration;
+      if (absClipStart < transportOffset && absClipEnd > transportOffset) {
+        for (const note of clipInfo.notes) {
+          const adjustedTime = note.time - clipInfo.offset;
+          const noteAbsStart = absClipStart + Math.max(0, adjustedTime);
+          const noteAbsEnd = noteAbsStart + note.duration;
+          if (noteAbsStart < transportOffset && noteAbsEnd > transportOffset) {
+            const remainingDuration = noteAbsEnd - transportOffset;
+            try {
+              this.triggerNote(
+                note.midi,
+                remainingDuration,
+                audioContextTime,
+                note.velocity,
+                note.channel
+              );
+            } catch (err) {
+              console.warn(
+                `[waveform-playlist] Failed to start mid-clip SoundFont note on track "${this.id}":`,
+                err
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Stop all active AudioBufferSourceNodes.
+   */
+  stopAllSources() {
+    for (const source of this.activeSources) {
+      try {
+        source.stop();
+      } catch (err) {
+        console.warn("[waveform-playlist] Error stopping AudioBufferSourceNode:", err);
+      }
+    }
+    this.activeSources.clear();
+  }
+  /** No-op for MIDI — MIDI uses note velocity, not gain fades. */
+  prepareFades(_when, _offset) {
+  }
+  /** No-op for MIDI — no fade automation to cancel. */
+  cancelFades() {
+  }
+  setVolume(gain) {
+    this.track.gain = gain;
+    this.volumeNode.volume.value = this.gainToDb(gain);
+  }
+  setPan(pan) {
+    this.track.stereoPan = pan;
+    this.panNode.pan.value = pan;
+  }
+  setMute(muted) {
+    this.track.muted = muted;
+    const value = muted ? 0 : 1;
+    const audioParam = getUnderlyingAudioParam(this.muteGain.gain);
+    audioParam?.setValueAtTime(value, 0);
+    this.muteGain.gain.value = value;
+  }
+  setSolo(soloed) {
+    this.track.soloed = soloed;
+  }
+  dispose() {
+    if (this.effectsCleanup) {
+      try {
+        this.effectsCleanup();
+      } catch (err) {
+        console.warn(
+          `[waveform-playlist] Error during SoundFont track "${this.id}" effects cleanup:`,
+          err
+        );
+      }
+    }
+    this.stopAllSources();
+    this.scheduledClips.forEach(({ part }, index) => {
+      try {
+        part.dispose();
+      } catch (err) {
+        console.warn(
+          `[waveform-playlist] Error disposing Part ${index} on SoundFont track "${this.id}":`,
+          err
+        );
+      }
+    });
+    try {
+      this.volumeNode.dispose();
+    } catch (err) {
+      console.warn(
+        `[waveform-playlist] Error disposing volumeNode on SoundFont track "${this.id}":`,
+        err
+      );
+    }
+    try {
+      this.panNode.dispose();
+    } catch (err) {
+      console.warn(
+        `[waveform-playlist] Error disposing panNode on SoundFont track "${this.id}":`,
+        err
+      );
+    }
+    try {
+      this.muteGain.dispose();
+    } catch (err) {
+      console.warn(
+        `[waveform-playlist] Error disposing muteGain on SoundFont track "${this.id}":`,
+        err
+      );
+    }
+  }
+  get id() {
+    return this.track.id;
+  }
+  get duration() {
+    if (this.scheduledClips.length === 0) return 0;
+    const lastClip = this.scheduledClips[this.scheduledClips.length - 1];
+    return lastClip.clipInfo.startTime + lastClip.clipInfo.duration;
+  }
+  get muted() {
+    return this.track.muted;
+  }
+  get startTime() {
+    return this.track.startTime;
+  }
+};
+/** Rate-limit missing sample warnings — one per class lifetime */
+_SoundFontToneTrack._missingSampleWarned = false;
+var SoundFontToneTrack = _SoundFontToneTrack;
+
 // src/TonePlayout.ts
 var TonePlayout = class {
   constructor(options = {}) {
@@ -461,9 +1019,9 @@ var TonePlayout = class {
     this._loopEnabled = false;
     this._loopStart = 0;
     this._loopEnd = 0;
-    this.masterVolume = new import_tone2.Volume(this.gainToDb(options.masterGain ?? 1));
+    this.masterVolume = new import_tone4.Volume(this.gainToDb(options.masterGain ?? 1));
     if (options.effects) {
-      const cleanup = options.effects(this.masterVolume, (0, import_tone2.getDestination)(), false);
+      const cleanup = options.effects(this.masterVolume, (0, import_tone4.getDestination)(), false);
       if (cleanup) {
         this.effectsCleanup = cleanup;
       }
@@ -483,7 +1041,7 @@ var TonePlayout = class {
   clearCompletionEvent() {
     if (this._completionEventId !== null) {
       try {
-        (0, import_tone2.getTransport)().clear(this._completionEventId);
+        (0, import_tone4.getTransport)().clear(this._completionEventId);
       } catch (err) {
         console.warn("[waveform-playlist] Error clearing Transport completion event:", err);
       }
@@ -492,7 +1050,7 @@ var TonePlayout = class {
   }
   async init() {
     if (this.isInitialized) return;
-    await (0, import_tone2.start)();
+    await (0, import_tone4.start)();
     this.isInitialized = true;
   }
   addTrack(trackOptions) {
@@ -508,6 +1066,32 @@ var TonePlayout = class {
     }
     return toneTrack;
   }
+  addMidiTrack(trackOptions) {
+    const optionsWithDestination = {
+      ...trackOptions,
+      destination: this.masterVolume
+    };
+    const midiTrack = new MidiToneTrack(optionsWithDestination);
+    this.tracks.set(midiTrack.id, midiTrack);
+    this.manualMuteState.set(midiTrack.id, trackOptions.track.muted ?? false);
+    if (trackOptions.track.soloed) {
+      this.soloedTracks.add(midiTrack.id);
+    }
+    return midiTrack;
+  }
+  addSoundFontTrack(trackOptions) {
+    const optionsWithDestination = {
+      ...trackOptions,
+      destination: this.masterVolume
+    };
+    const sfTrack = new SoundFontToneTrack(optionsWithDestination);
+    this.tracks.set(sfTrack.id, sfTrack);
+    this.manualMuteState.set(sfTrack.id, trackOptions.track.muted ?? false);
+    if (trackOptions.track.soloed) {
+      this.soloedTracks.add(sfTrack.id);
+    }
+    return sfTrack;
+  }
   /**
    * Apply solo muting after all tracks have been added.
    * Call this after adding all tracks to ensure solo logic is applied correctly.
@@ -531,8 +1115,8 @@ var TonePlayout = class {
     if (!this.isInitialized) {
       throw new Error("[waveform-playlist] TonePlayout not initialized. Call init() first.");
     }
-    const startTime = when ?? (0, import_tone2.now)();
-    const transport = (0, import_tone2.getTransport)();
+    const startTime = when ?? (0, import_tone4.now)();
+    const transport = (0, import_tone4.getTransport)();
     this.clearCompletionEvent();
     const transportOffset = offset ?? 0;
     this.tracks.forEach((track) => {
@@ -578,7 +1162,7 @@ var TonePlayout = class {
     }
   }
   pause() {
-    const transport = (0, import_tone2.getTransport)();
+    const transport = (0, import_tone4.getTransport)();
     try {
       transport.pause();
     } catch (err) {
@@ -589,7 +1173,7 @@ var TonePlayout = class {
     this.clearCompletionEvent();
   }
   stop() {
-    const transport = (0, import_tone2.getTransport)();
+    const transport = (0, import_tone4.getTransport)();
     try {
       transport.stop();
     } catch (err) {
@@ -649,7 +1233,7 @@ var TonePlayout = class {
     this._loopEnabled = enabled;
     this._loopStart = loopStart;
     this._loopEnd = loopEnd;
-    const transport = (0, import_tone2.getTransport)();
+    const transport = (0, import_tone4.getTransport)();
     try {
       transport.loopStart = loopStart;
       transport.loopEnd = loopEnd;
@@ -660,7 +1244,7 @@ var TonePlayout = class {
     }
     if (enabled && !this._loopHandler) {
       this._loopHandler = () => {
-        const currentTime = (0, import_tone2.now)();
+        const currentTime = (0, import_tone4.now)();
         this.tracks.forEach((track) => {
           try {
             track.stopAllSources();
@@ -683,16 +1267,16 @@ var TonePlayout = class {
     }
   }
   getCurrentTime() {
-    return (0, import_tone2.getTransport)().seconds;
+    return (0, import_tone4.getTransport)().seconds;
   }
   seekTo(time) {
-    (0, import_tone2.getTransport)().seconds = time;
+    (0, import_tone4.getTransport)().seconds = time;
   }
   dispose() {
     this.clearCompletionEvent();
     if (this._loopHandler) {
       try {
-        (0, import_tone2.getTransport)().off("loop", this._loopHandler);
+        (0, import_tone4.getTransport)().off("loop", this._loopHandler);
       } catch (err) {
         console.warn("[waveform-playlist] Error removing Transport loop handler:", err);
       }
@@ -720,23 +1304,187 @@ var TonePlayout = class {
     }
   }
   get context() {
-    return (0, import_tone2.getContext)();
+    return (0, import_tone4.getContext)();
   }
   get sampleRate() {
-    return (0, import_tone2.getContext)().sampleRate;
+    return (0, import_tone4.getContext)().sampleRate;
   }
   setOnPlaybackComplete(callback) {
     this.onPlaybackCompleteCallback = callback;
   }
 };
 
+// src/SoundFontCache.ts
+var import_soundfont2 = require("soundfont2");
+function timecentsToSeconds(tc) {
+  return Math.pow(2, tc / 1200);
+}
+var MAX_RELEASE_SECONDS = 5;
+function getGeneratorValue(generators, type) {
+  return generators[type]?.value;
+}
+var SoundFontCache = class {
+  /**
+   * @param context Optional AudioContext for createBuffer(). If omitted, uses
+   *   an OfflineAudioContext which doesn't require user gesture — safe to
+   *   construct before user interaction (avoids Firefox autoplay warnings).
+   */
+  constructor(context) {
+    this.sf2 = null;
+    this.audioBufferCache = /* @__PURE__ */ new Map();
+    this.context = context ?? new OfflineAudioContext(1, 1, 44100);
+  }
+  /**
+   * Load and parse an SF2 file from a URL.
+   */
+  async load(url, signal) {
+    const response = await fetch(url, { signal });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch SoundFont ${url}: ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    try {
+      this.sf2 = new import_soundfont2.SoundFont2(new Uint8Array(arrayBuffer));
+    } catch (err) {
+      throw new Error(
+        `Failed to parse SoundFont ${url}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  /**
+   * Load from an already-fetched ArrayBuffer.
+   */
+  loadFromBuffer(data) {
+    try {
+      this.sf2 = new import_soundfont2.SoundFont2(new Uint8Array(data));
+    } catch (err) {
+      throw new Error(
+        `Failed to parse SoundFont from buffer: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  get isLoaded() {
+    return this.sf2 !== null;
+  }
+  /**
+   * Look up a MIDI note and return the AudioBuffer + playbackRate.
+   *
+   * @param midiNote - MIDI note number (0-127)
+   * @param bankNumber - Bank number (0 for melodic, 128 for percussion/drums)
+   * @param presetNumber - GM program number (0-127)
+   * @returns SoundFontSample or null if no sample found for this note
+   */
+  getAudioBuffer(midiNote, bankNumber = 0, presetNumber = 0) {
+    if (!this.sf2) return null;
+    const keyData = this.sf2.getKeyData(midiNote, bankNumber, presetNumber);
+    if (!keyData) return null;
+    const sample = keyData.sample;
+    const sampleIndex = this.sf2.samples.indexOf(sample);
+    let buffer = this.audioBufferCache.get(sampleIndex);
+    if (!buffer) {
+      buffer = this.int16ToAudioBuffer(sample.data, sample.header.sampleRate);
+      this.audioBufferCache.set(sampleIndex, buffer);
+    }
+    const playbackRate = this.calculatePlaybackRate(midiNote, keyData);
+    const loopAndEnvelope = this.extractLoopAndEnvelope(keyData);
+    return { buffer, playbackRate, ...loopAndEnvelope };
+  }
+  /**
+   * Extract loop points and volume envelope data from per-zone generators.
+   *
+   * Loop points are stored as absolute indices into the SF2 sample pool.
+   * We convert to AudioBuffer-relative seconds by subtracting header.start
+   * and dividing by sampleRate.
+   *
+   * Volume envelope times are in SF2 timecents; sustain is centibels attenuation.
+   */
+  extractLoopAndEnvelope(keyData) {
+    const { generators } = keyData;
+    const header = keyData.sample.header;
+    const loopMode = getGeneratorValue(generators, import_soundfont2.GeneratorType.SampleModes) ?? 0;
+    const rawLoopStart = header.startLoop + (getGeneratorValue(generators, import_soundfont2.GeneratorType.StartLoopAddrsOffset) ?? 0) + (getGeneratorValue(generators, import_soundfont2.GeneratorType.StartLoopAddrsCoarseOffset) ?? 0) * 32768;
+    const rawLoopEnd = header.endLoop + (getGeneratorValue(generators, import_soundfont2.GeneratorType.EndLoopAddrsOffset) ?? 0) + (getGeneratorValue(generators, import_soundfont2.GeneratorType.EndLoopAddrsCoarseOffset) ?? 0) * 32768;
+    const loopStart = rawLoopStart / header.sampleRate;
+    const loopEnd = rawLoopEnd / header.sampleRate;
+    const attackVolEnv = timecentsToSeconds(
+      getGeneratorValue(generators, import_soundfont2.GeneratorType.AttackVolEnv) ?? -12e3
+    );
+    const holdVolEnv = timecentsToSeconds(
+      getGeneratorValue(generators, import_soundfont2.GeneratorType.HoldVolEnv) ?? -12e3
+    );
+    const decayVolEnv = timecentsToSeconds(
+      getGeneratorValue(generators, import_soundfont2.GeneratorType.DecayVolEnv) ?? -12e3
+    );
+    const releaseVolEnv = Math.min(
+      timecentsToSeconds(getGeneratorValue(generators, import_soundfont2.GeneratorType.ReleaseVolEnv) ?? -12e3),
+      MAX_RELEASE_SECONDS
+    );
+    const sustainCb = getGeneratorValue(generators, import_soundfont2.GeneratorType.SustainVolEnv) ?? 0;
+    const sustainVolEnv = Math.pow(10, -sustainCb / 200);
+    return {
+      loopMode,
+      loopStart,
+      loopEnd,
+      attackVolEnv,
+      holdVolEnv,
+      decayVolEnv,
+      sustainVolEnv,
+      releaseVolEnv
+    };
+  }
+  /**
+   * Calculate playback rate for a MIDI note using the SF2 generator chain.
+   *
+   * SF2 root key resolution priority:
+   *   1. OverridingRootKey generator (per-zone, most specific)
+   *   2. sample.header.originalPitch (sample header)
+   *   3. MIDI note 60 (middle C fallback)
+   *
+   * Tuning adjustments:
+   *   - CoarseTune generator (semitones, additive)
+   *   - FineTune generator (cents, additive)
+   *   - sample.header.pitchCorrection (cents, additive)
+   */
+  calculatePlaybackRate(midiNote, keyData) {
+    const sample = keyData.sample;
+    const generators = keyData.generators;
+    const overrideRootKey = getGeneratorValue(generators, import_soundfont2.GeneratorType.OverridingRootKey);
+    const originalPitch = sample.header.originalPitch;
+    const rootKey = overrideRootKey !== void 0 ? overrideRootKey : originalPitch !== 255 ? originalPitch : 60;
+    const coarseTune = getGeneratorValue(generators, import_soundfont2.GeneratorType.CoarseTune) ?? 0;
+    const fineTune = getGeneratorValue(generators, import_soundfont2.GeneratorType.FineTune) ?? 0;
+    const pitchCorrection = sample.header.pitchCorrection ?? 0;
+    const totalSemitones = midiNote - rootKey + coarseTune + (fineTune + pitchCorrection) / 100;
+    return Math.pow(2, totalSemitones / 12);
+  }
+  /**
+   * Convert Int16Array sample data to an AudioBuffer.
+   * SF2 samples are 16-bit signed integers; Web Audio needs Float32 [-1, 1].
+   */
+  int16ToAudioBuffer(data, sampleRate) {
+    const buffer = this.context.createBuffer(1, data.length, sampleRate);
+    const channel = buffer.getChannelData(0);
+    for (let i = 0; i < data.length; i++) {
+      channel[i] = data[i] / 32768;
+    }
+    return buffer;
+  }
+  /**
+   * Clear all cached AudioBuffers and release the parsed SF2.
+   */
+  dispose() {
+    this.audioBufferCache.clear();
+    this.sf2 = null;
+  }
+};
+
 // src/audioContext.ts
-var import_tone3 = require("tone");
+var import_tone5 = require("tone");
 var globalToneContext = null;
 function getGlobalContext() {
   if (!globalToneContext) {
-    globalToneContext = new import_tone3.Context();
-    (0, import_tone3.setContext)(globalToneContext);
+    globalToneContext = new import_tone5.Context();
+    (0, import_tone5.setContext)(globalToneContext);
   }
   return globalToneContext;
 }
@@ -763,14 +1511,14 @@ async function closeGlobalAudioContext() {
 }
 
 // src/mediaStreamSourceManager.ts
-var import_tone4 = require("tone");
+var import_tone6 = require("tone");
 var streamSources = /* @__PURE__ */ new Map();
 var streamCleanupHandlers = /* @__PURE__ */ new Map();
 function getMediaStreamSource(stream) {
   if (streamSources.has(stream)) {
     return streamSources.get(stream);
   }
-  const context = (0, import_tone4.getContext)();
+  const context = (0, import_tone6.getContext)();
   const source = context.createMediaStreamSource(stream);
   streamSources.set(stream, source);
   const cleanup = () => {
@@ -797,7 +1545,7 @@ function hasMediaStreamSource(stream) {
 
 // src/TonePlayoutAdapter.ts
 var import_core = require("@waveform-playlist/core");
-var import_tone5 = require("tone");
+var import_tone7 = require("tone");
 function createToneAdapter(options) {
   let playout = null;
   let _isPlaying = false;
@@ -830,34 +1578,82 @@ function createToneAdapter(options) {
       });
     }
     for (const track of tracks) {
-      const playableClips = track.clips.filter((c) => c.audioBuffer);
-      if (playableClips.length === 0) continue;
-      const startTime = Math.min(...playableClips.map(import_core.clipStartTime));
-      const endTime = Math.max(...playableClips.map(import_core.clipEndTime));
-      const trackObj = {
-        id: track.id,
-        name: track.name,
-        gain: track.volume,
-        muted: track.muted,
-        soloed: track.soloed,
-        stereoPan: track.pan,
-        startTime,
-        endTime
-      };
-      const clipInfos = playableClips.map((clip) => ({
-        buffer: clip.audioBuffer,
-        startTime: (0, import_core.clipStartTime)(clip) - startTime,
-        duration: (0, import_core.clipDurationTime)(clip),
-        offset: (0, import_core.clipOffsetTime)(clip),
-        fadeIn: clip.fadeIn,
-        fadeOut: clip.fadeOut,
-        gain: clip.gain
-      }));
-      playout.addTrack({
-        clips: clipInfos,
-        track: trackObj,
-        effects: track.effects
-      });
+      const audioClips = track.clips.filter((c) => c.audioBuffer && !c.midiNotes);
+      const midiClips = track.clips.filter((c) => c.midiNotes && c.midiNotes.length > 0);
+      if (audioClips.length > 0) {
+        const startTime = Math.min(...audioClips.map(import_core.clipStartTime));
+        const endTime = Math.max(...audioClips.map(import_core.clipEndTime));
+        const trackObj = {
+          id: track.id,
+          name: track.name,
+          gain: track.volume,
+          muted: track.muted,
+          soloed: track.soloed,
+          stereoPan: track.pan,
+          startTime,
+          endTime
+        };
+        const clipInfos = audioClips.map((clip) => ({
+          buffer: clip.audioBuffer,
+          startTime: (0, import_core.clipStartTime)(clip) - startTime,
+          duration: (0, import_core.clipDurationTime)(clip),
+          offset: (0, import_core.clipOffsetTime)(clip),
+          fadeIn: clip.fadeIn,
+          fadeOut: clip.fadeOut,
+          gain: clip.gain
+        }));
+        playout.addTrack({
+          clips: clipInfos,
+          track: trackObj,
+          effects: track.effects
+        });
+      }
+      if (midiClips.length > 0) {
+        const startTime = Math.min(...midiClips.map(import_core.clipStartTime));
+        const endTime = Math.max(...midiClips.map(import_core.clipEndTime));
+        const trackId = audioClips.length > 0 ? `${track.id}:midi` : track.id;
+        const trackObj = {
+          id: trackId,
+          name: track.name,
+          gain: track.volume,
+          muted: track.muted,
+          soloed: track.soloed,
+          stereoPan: track.pan,
+          startTime,
+          endTime
+        };
+        const midiClipInfos = midiClips.map((clip) => ({
+          notes: clip.midiNotes,
+          startTime: (0, import_core.clipStartTime)(clip) - startTime,
+          duration: (0, import_core.clipDurationTime)(clip),
+          offset: (0, import_core.clipOffsetTime)(clip)
+        }));
+        if (options?.soundFontCache?.isLoaded) {
+          const firstClip = midiClips[0];
+          const midiChannel = firstClip.midiChannel;
+          const isPercussion = midiChannel === 9;
+          const programNumber = firstClip.midiProgram ?? 0;
+          playout.addSoundFontTrack({
+            clips: midiClipInfos,
+            track: trackObj,
+            soundFontCache: options.soundFontCache,
+            programNumber,
+            isPercussion,
+            effects: track.effects
+          });
+        } else {
+          if (options?.soundFontCache) {
+            console.warn(
+              `[waveform-playlist] SoundFont not loaded for track "${track.name}" \u2014 falling back to PolySynth.`
+            );
+          }
+          playout.addMidiTrack({
+            clips: midiClipInfos,
+            track: trackObj,
+            effects: track.effects
+          });
+        }
+      }
     }
     playout.applyInitialSoloState();
     playout.setLoop(_loopEnabled, _loopStart, _loopEnd);
@@ -885,7 +1681,7 @@ function createToneAdapter(options) {
         return;
       }
       const duration = endTime !== void 0 ? endTime - startTime : void 0;
-      playout.play((0, import_tone5.now)(), startTime, duration);
+      playout.play((0, import_tone7.now)(), startTime, duration);
       _isPlaying = true;
     },
     pause() {
@@ -939,6 +1735,9 @@ function createToneAdapter(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MidiToneTrack,
+  SoundFontCache,
+  SoundFontToneTrack,
   TonePlayout,
   ToneTrack,
   applyFadeIn,