@waveform-playlist/playout 12.2.0 → 12.4.0

package/dist/index.d.mts

@@ -317,6 +317,16 @@ declare class SoundFontCache {
      *   construct before user interaction (avoids Firefox autoplay warnings).
      */
     constructor(context?: BaseAudioContext);
+    /**
+     * Fetch and parse an SF2 file, resolving only once it's ready to play.
+     * Prefer this over `new SoundFontCache()` + `load()` — the returned cache
+     * is always loaded, so it can't hit the "unloaded cache → PolySynth
+     * fallback" path in createToneAdapter / setSoundFontCache.
+     */
+    static fromUrl(url: string, options?: {
+        context?: BaseAudioContext;
+        signal?: AbortSignal;
+    }): Promise<SoundFontCache>;
     /**
      * Load and parse an SF2 file from a URL.
      */
@@ -610,6 +620,20 @@ interface ToneAdapterOptions {
     /** Pulses per quarter note. Defaults to 192 (Tone.js native). */
     ppqn?: number;
 }
-declare function createToneAdapter(options?: ToneAdapterOptions): PlayoutAdapter;
+interface ToneAdapter extends PlayoutAdapter {
+    /**
+     * Provide or swap the SoundFont after creation. Rebuilds only the MIDI
+     * tracks whose routing changes; audio tracks keep playing untouched.
+     * Pass undefined to revert MIDI tracks to PolySynth synthesis.
+     */
+    setSoundFontCache(cache: SoundFontCache | undefined): void;
+}
+/**
+ * Capability check for Tone-specific adapter features. Structural, not
+ * instanceof — any adapter implementing setSoundFontCache passes. Narrows a
+ * generic PlayoutAdapter so soundfont calls typecheck without casts.
+ */
+declare function isToneAdapter(adapter: PlayoutAdapter | null | undefined): adapter is ToneAdapter;
+declare function createToneAdapter(options?: ToneAdapterOptions): ToneAdapter;
 
-export { type AudioContextOptions, type EffectsFunction, type LoopAndEnvelopeParams, type MidiClipInfo, MidiToneTrack, type MidiToneTrackOptions, type PlayableTrack, type PlaybackRateParams, SoundFontCache, type SoundFontSample, SoundFontToneTrack, type SoundFontToneTrackOptions, type ToneAdapterOptions, TonePlayout, type TonePlayoutOptions, ToneTrack, type ToneTrackOptions, type TrackEffectsFunction, calculatePlaybackRate, closeGlobalAudioContext, configureGlobalContext, createToneAdapter, extractLoopAndEnvelope, getGeneratorValue, getGlobalAudioContext, getGlobalAudioContextState, getGlobalContext, getGlobalToneContext, getMediaStreamSource, getUnderlyingAudioParam, hasMediaStreamSource, int16ToFloat32, releaseMediaStreamSource, resumeGlobalAudioContext, timecentsToSeconds };
+export { type AudioContextOptions, type EffectsFunction, type LoopAndEnvelopeParams, type MidiClipInfo, MidiToneTrack, type MidiToneTrackOptions, type PlayableTrack, type PlaybackRateParams, SoundFontCache, type SoundFontSample, SoundFontToneTrack, type SoundFontToneTrackOptions, type ToneAdapter, type ToneAdapterOptions, TonePlayout, type TonePlayoutOptions, ToneTrack, type ToneTrackOptions, type TrackEffectsFunction, calculatePlaybackRate, closeGlobalAudioContext, configureGlobalContext, createToneAdapter, extractLoopAndEnvelope, getGeneratorValue, getGlobalAudioContext, getGlobalAudioContextState, getGlobalContext, getGlobalToneContext, getMediaStreamSource, getUnderlyingAudioParam, hasMediaStreamSource, int16ToFloat32, isToneAdapter, releaseMediaStreamSource, resumeGlobalAudioContext, timecentsToSeconds };

package/dist/index.d.ts

@@ -317,6 +317,16 @@ declare class SoundFontCache {
      *   construct before user interaction (avoids Firefox autoplay warnings).
      */
     constructor(context?: BaseAudioContext);
+    /**
+     * Fetch and parse an SF2 file, resolving only once it's ready to play.
+     * Prefer this over `new SoundFontCache()` + `load()` — the returned cache
+     * is always loaded, so it can't hit the "unloaded cache → PolySynth
+     * fallback" path in createToneAdapter / setSoundFontCache.
+     */
+    static fromUrl(url: string, options?: {
+        context?: BaseAudioContext;
+        signal?: AbortSignal;
+    }): Promise<SoundFontCache>;
     /**
      * Load and parse an SF2 file from a URL.
      */
@@ -610,6 +620,20 @@ interface ToneAdapterOptions {
     /** Pulses per quarter note. Defaults to 192 (Tone.js native). */
     ppqn?: number;
 }
-declare function createToneAdapter(options?: ToneAdapterOptions): PlayoutAdapter;
+interface ToneAdapter extends PlayoutAdapter {
+    /**
+     * Provide or swap the SoundFont after creation. Rebuilds only the MIDI
+     * tracks whose routing changes; audio tracks keep playing untouched.
+     * Pass undefined to revert MIDI tracks to PolySynth synthesis.
+     */
+    setSoundFontCache(cache: SoundFontCache | undefined): void;
+}
+/**
+ * Capability check for Tone-specific adapter features. Structural, not
+ * instanceof — any adapter implementing setSoundFontCache passes. Narrows a
+ * generic PlayoutAdapter so soundfont calls typecheck without casts.
+ */
+declare function isToneAdapter(adapter: PlayoutAdapter | null | undefined): adapter is ToneAdapter;
+declare function createToneAdapter(options?: ToneAdapterOptions): ToneAdapter;
 
-export { type AudioContextOptions, type EffectsFunction, type LoopAndEnvelopeParams, type MidiClipInfo, MidiToneTrack, type MidiToneTrackOptions, type PlayableTrack, type PlaybackRateParams, SoundFontCache, type SoundFontSample, SoundFontToneTrack, type SoundFontToneTrackOptions, type ToneAdapterOptions, TonePlayout, type TonePlayoutOptions, ToneTrack, type ToneTrackOptions, type TrackEffectsFunction, calculatePlaybackRate, closeGlobalAudioContext, configureGlobalContext, createToneAdapter, extractLoopAndEnvelope, getGeneratorValue, getGlobalAudioContext, getGlobalAudioContextState, getGlobalContext, getGlobalToneContext, getMediaStreamSource, getUnderlyingAudioParam, hasMediaStreamSource, int16ToFloat32, releaseMediaStreamSource, resumeGlobalAudioContext, timecentsToSeconds };
+export { type AudioContextOptions, type EffectsFunction, type LoopAndEnvelopeParams, type MidiClipInfo, MidiToneTrack, type MidiToneTrackOptions, type PlayableTrack, type PlaybackRateParams, SoundFontCache, type SoundFontSample, SoundFontToneTrack, type SoundFontToneTrackOptions, type ToneAdapter, type ToneAdapterOptions, TonePlayout, type TonePlayoutOptions, ToneTrack, type ToneTrackOptions, type TrackEffectsFunction, calculatePlaybackRate, closeGlobalAudioContext, configureGlobalContext, createToneAdapter, extractLoopAndEnvelope, getGeneratorValue, getGlobalAudioContext, getGlobalAudioContextState, getGlobalContext, getGlobalToneContext, getMediaStreamSource, getUnderlyingAudioParam, hasMediaStreamSource, int16ToFloat32, isToneAdapter, releaseMediaStreamSource, resumeGlobalAudioContext, timecentsToSeconds };

package/dist/index.js

@@ -39,6 +39,7 @@ __export(index_exports, {
   getUnderlyingAudioParam: () => getUnderlyingAudioParam,
   hasMediaStreamSource: () => hasMediaStreamSource,
   int16ToFloat32: () => int16ToFloat32,
+  isToneAdapter: () => isToneAdapter,
   releaseMediaStreamSource: () => releaseMediaStreamSource,
   resumeGlobalAudioContext: () => resumeGlobalAudioContext,
   timecentsToSeconds: () => timecentsToSeconds
@@ -1455,7 +1456,7 @@ function extractLoopAndEnvelope(params) {
     releaseVolEnv
   };
 }
-var SoundFontCache = class {
+var SoundFontCache = class _SoundFontCache {
   /**
    * @param context Optional AudioContext for createBuffer(). If omitted, uses
    *   an OfflineAudioContext which doesn't require user gesture — safe to
@@ -1466,6 +1467,17 @@ var SoundFontCache = class {
     this.audioBufferCache = /* @__PURE__ */ new Map();
     this.context = context ?? new OfflineAudioContext(1, 1, 44100);
   }
+  /**
+   * Fetch and parse an SF2 file, resolving only once it's ready to play.
+   * Prefer this over `new SoundFontCache()` + `load()` — the returned cache
+   * is always loaded, so it can't hit the "unloaded cache → PolySynth
+   * fallback" path in createToneAdapter / setSoundFontCache.
+   */
+  static async fromUrl(url, options) {
+    const cache = new _SoundFontCache(options?.context);
+    await cache.load(url, options?.signal);
+    return cache;
+  }
   /**
    * Load and parse an SF2 file from a URL.
    */
@@ -1638,6 +1650,9 @@ function hasMediaStreamSource(stream) {
 // src/TonePlayoutAdapter.ts
 var import_core6 = require("@waveform-playlist/core");
 var import_tone7 = require("tone");
+function isToneAdapter(adapter) {
+  return typeof adapter?.setSoundFontCache === "function";
+}
 function createToneAdapter(options) {
   getGlobalContext();
   let _playoutGeneration = 1;
@@ -1655,85 +1670,98 @@ function createToneAdapter(options) {
   let _pendingInit = null;
   const _ppqn = options?.ppqn ?? 192;
   let _bpm = 120;
-  function addTrackToPlayout(p, track) {
+  let _soundFontCache = options?.soundFontCache;
+  const _currentTracks = /* @__PURE__ */ new Map();
+  const _midiTrackBuild = /* @__PURE__ */ new Map();
+  function midiPlayoutTrackId(track) {
+    const hasAudio = track.clips.some((c) => c.audioBuffer && !c.midiNotes);
+    return hasAudio ? `${track.id}:midi` : track.id;
+  }
+  function addAudioTrackToPlayout(p, track) {
     const audioClips = track.clips.filter((c) => c.audioBuffer && !c.midiNotes);
+    if (audioClips.length === 0) return;
+    const startTime = Math.min(...audioClips.map(import_core6.clipStartTime));
+    const endTime = Math.max(...audioClips.map(import_core6.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_core6.clipStartTime)(clip) - startTime,
+      duration: (0, import_core6.clipDurationTime)(clip),
+      offset: (0, import_core6.clipOffsetTime)(clip),
+      fadeIn: clip.fadeIn,
+      fadeOut: clip.fadeOut,
+      gain: clip.gain
+    }));
+    p.addTrack({
+      clips: clipInfos,
+      track: trackObj,
+      effects: track.effects,
+      channelCount: (0, import_core6.trackChannelCount)(track)
+    });
+  }
+  function addMidiTrackToPlayout(p, track) {
     const midiClips = track.clips.filter((c) => c.midiNotes && c.midiNotes.length > 0);
-    if (audioClips.length > 0) {
-      const startTime = Math.min(...audioClips.map(import_core6.clipStartTime));
-      const endTime = Math.max(...audioClips.map(import_core6.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_core6.clipStartTime)(clip) - startTime,
-        duration: (0, import_core6.clipDurationTime)(clip),
-        offset: (0, import_core6.clipOffsetTime)(clip),
-        fadeIn: clip.fadeIn,
-        fadeOut: clip.fadeOut,
-        gain: clip.gain
-      }));
-      p.addTrack({
-        clips: clipInfos,
+    if (midiClips.length === 0) return;
+    const startTime = Math.min(...midiClips.map(import_core6.clipStartTime));
+    const endTime = Math.max(...midiClips.map(import_core6.clipEndTime));
+    const trackId = midiPlayoutTrackId(track);
+    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_core6.clipStartTime)(clip) - startTime,
+      duration: (0, import_core6.clipDurationTime)(clip),
+      offset: (0, import_core6.clipOffsetTime)(clip)
+    }));
+    if (_soundFontCache?.isLoaded) {
+      const firstClip = midiClips[0];
+      const midiChannel = firstClip.midiChannel;
+      const isPercussion = midiChannel === 9;
+      const programNumber = firstClip.midiProgram ?? 0;
+      p.addSoundFontTrack({
+        clips: midiClipInfos,
         track: trackObj,
-        effects: track.effects,
-        channelCount: (0, import_core6.trackChannelCount)(track)
+        soundFontCache: _soundFontCache,
+        programNumber,
+        isPercussion,
+        effects: track.effects
       });
-    }
-    if (midiClips.length > 0) {
-      const startTime = Math.min(...midiClips.map(import_core6.clipStartTime));
-      const endTime = Math.max(...midiClips.map(import_core6.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_core6.clipStartTime)(clip) - startTime,
-        duration: (0, import_core6.clipDurationTime)(clip),
-        offset: (0, import_core6.clipOffsetTime)(clip)
-      }));
-      if (options?.soundFontCache?.isLoaded) {
-        const firstClip = midiClips[0];
-        const midiChannel = firstClip.midiChannel;
-        const isPercussion = midiChannel === 9;
-        const programNumber = firstClip.midiProgram ?? 0;
-        p.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.`
-          );
-        }
-        p.addMidiTrack({
-          clips: midiClipInfos,
-          track: trackObj,
-          effects: track.effects
-        });
+      _midiTrackBuild.set(trackId, _soundFontCache);
+    } else {
+      if (_soundFontCache) {
+        console.warn(
+          `[waveform-playlist] SoundFont not loaded for track "${track.name}" \u2014 falling back to PolySynth.`
+        );
       }
+      p.addMidiTrack({
+        clips: midiClipInfos,
+        track: trackObj,
+        effects: track.effects
+      });
+      _midiTrackBuild.set(trackId, null);
     }
   }
+  function addTrackToPlayout(p, track) {
+    addAudioTrackToPlayout(p, track);
+    addMidiTrackToPlayout(p, track);
+  }
   function buildPlayout(tracks) {
     if (playout) {
       try {
@@ -1781,6 +1809,11 @@ function createToneAdapter(options) {
       }
     },
     setTracks(tracks) {
+      _currentTracks.clear();
+      _midiTrackBuild.clear();
+      for (const track of tracks) {
+        _currentTracks.set(track.id, track);
+      }
       if (!playout) {
         buildPlayout(tracks);
         return;
@@ -1808,6 +1841,7 @@ function createToneAdapter(options) {
       }
     },
     updateTrack(trackId, track) {
+      _currentTracks.set(trackId, track);
       if (!playout) return;
       const audioClips = track.clips.filter((c) => c.audioBuffer && !c.midiNotes);
       if (audioClips.length > 0) {
@@ -1826,7 +1860,7 @@ function createToneAdapter(options) {
         if (midiClips.length > 0) {
           const midiTrackId = trackId + ":midi";
           playout.removeTrack(midiTrackId);
-          addTrackToPlayout(playout, track);
+          addMidiTrackToPlayout(playout, track);
           if (_isPlaying) {
             playout.resumeTrackMidPlayback(midiTrackId);
           }
@@ -1838,6 +1872,8 @@ function createToneAdapter(options) {
       }
       playout.removeTrack(trackId);
       playout.removeTrack(trackId + ":midi");
+      _midiTrackBuild.delete(trackId);
+      _midiTrackBuild.delete(trackId + ":midi");
       addTrackToPlayout(playout, track);
       playout.applyInitialSoloState();
       if (_isPlaying) {
@@ -1846,6 +1882,7 @@ function createToneAdapter(options) {
       }
     },
     addTrack(track) {
+      _currentTracks.set(track.id, track);
       if (!playout) {
         console.warn(
           "[waveform-playlist] adapter.addTrack() called but playout is not available (adapter may have been disposed)."
@@ -1856,8 +1893,12 @@ function createToneAdapter(options) {
       playout.applyInitialSoloState();
     },
     removeTrack(trackId) {
+      _currentTracks.delete(trackId);
+      _midiTrackBuild.delete(trackId);
+      _midiTrackBuild.delete(trackId + ":midi");
       if (!playout) return;
       playout.removeTrack(trackId);
+      playout.removeTrack(trackId + ":midi");
       playout.applyInitialSoloState();
     },
     play(startTime, endTime) {
@@ -1892,15 +1933,23 @@ function createToneAdapter(options) {
       playout?.setMasterGain(volume);
     },
     setTrackVolume(trackId, volume) {
+      const existing = _currentTracks.get(trackId);
+      if (existing) _currentTracks.set(trackId, { ...existing, volume });
       playout?.getTrack(trackId)?.setVolume(volume);
     },
     setTrackMute(trackId, muted) {
+      const existing = _currentTracks.get(trackId);
+      if (existing) _currentTracks.set(trackId, { ...existing, muted });
       playout?.setMute(trackId, muted);
     },
     setTrackSolo(trackId, soloed) {
+      const existing = _currentTracks.get(trackId);
+      if (existing) _currentTracks.set(trackId, { ...existing, soloed });
       playout?.setSolo(trackId, soloed);
     },
     setTrackPan(trackId, pan) {
+      const existing = _currentTracks.get(trackId);
+      if (existing) _currentTracks.set(trackId, { ...existing, pan });
       playout?.getTrack(trackId)?.setPan(pan);
     },
     setLoop(enabled, start2, end) {
@@ -1912,6 +1961,9 @@ function createToneAdapter(options) {
     get audioContext() {
       return getGlobalAudioContext();
     },
+    get lookAhead() {
+      return getGlobalContext().lookAhead ?? 0;
+    },
     get ppqn() {
       return _ppqn;
     },
@@ -1956,6 +2008,38 @@ function createToneAdapter(options) {
       }
       return playout.masterOutputNode;
     },
+    setSoundFontCache(cache) {
+      _soundFontCache = cache;
+      if (cache && !cache.isLoaded) {
+        console.warn(
+          "[waveform-playlist] setSoundFontCache called with a SoundFontCache that is not loaded \u2014 MIDI tracks remain on PolySynth. Await cache.load() and call again."
+        );
+      }
+      if (!playout) return;
+      const effective = cache?.isLoaded ? cache : null;
+      let changed = false;
+      for (const track of _currentTracks.values()) {
+        const hasMidi = track.clips.some((c) => c.midiNotes && c.midiNotes.length > 0);
+        if (!hasMidi) continue;
+        const midiTrackId = midiPlayoutTrackId(track);
+        if (_midiTrackBuild.get(midiTrackId) === effective) continue;
+        try {
+          playout.removeTrack(midiTrackId);
+          addMidiTrackToPlayout(playout, track);
+          if (_isPlaying) {
+            playout.resumeTrackMidPlayback(midiTrackId);
+          }
+          changed = true;
+        } catch (err) {
+          console.warn(
+            `[waveform-playlist] SoundFont swap failed for track "${track.name}": ` + String(err)
+          );
+        }
+      }
+      if (changed) {
+        playout.applyInitialSoloState();
+      }
+    },
     dispose() {
       try {
         playout?.dispose();
@@ -1964,6 +2048,8 @@ function createToneAdapter(options) {
       }
       playout = null;
       _isPlaying = false;
+      _currentTracks.clear();
+      _midiTrackBuild.clear();
     }
   };
 }
@@ -1988,6 +2074,7 @@ function createToneAdapter(options) {
   getUnderlyingAudioParam,
   hasMediaStreamSource,
   int16ToFloat32,
+  isToneAdapter,
   releaseMediaStreamSource,
   resumeGlobalAudioContext,
   timecentsToSeconds