@waveform-playlist/playout 10.3.0 → 10.4.0

package/dist/index.d.mts

@@ -21,6 +21,12 @@ interface ToneTrackOptions {
     effects?: TrackEffectsFunction;
     destination?: ToneAudioNode;
 }
+/** Per-clip scheduling info and audio nodes */
+interface ScheduledClip {
+    clipInfo: ClipInfo;
+    fadeGainNode: GainNode;
+    scheduleId: number;
+}
 declare class ToneTrack {
     private scheduledClips;
     private activeSources;
@@ -51,6 +57,26 @@ declare class ToneTrack {
      * schedule callbacks at exact Transport position (e.g., loopStart).
      */
     startMidClipSources(transportOffset: number, audioContextTime: number): void;
+    /**
+     * Add a clip to this track at runtime. Creates a Transport.schedule event
+     * and fadeGainNode. If playing, starts the source mid-clip if needed.
+     */
+    addClip(clipInfo: ClipInfo): ScheduledClip;
+    /**
+     * Remove a scheduled clip by index. Clears the Transport event and
+     * disconnects the fadeGainNode.
+     */
+    removeScheduledClip(index: number): void;
+    /**
+     * Replace clips on this track. Diffs old vs new by buffer + timing —
+     * unchanged clips keep their active sources playing (no audible interruption).
+     * Changed/added/removed clips are rescheduled. Disconnecting a removed clip's
+     * fadeGainNode silences its source immediately (audio path broken) without
+     * needing to explicitly stop it.
+     */
+    replaceClips(newClips: ClipInfo[], newStartTime?: number): void;
+    /** Compare two clips by reference (buffer), timing, and fade properties */
+    private _clipsEqual;
     /**
      * Stop all active AudioBufferSourceNodes and clear the set.
      * Native AudioBufferSourceNodes ignore Transport state changes —
@@ -425,6 +451,18 @@ declare class TonePlayout {
     applyInitialSoloState(): void;
     removeTrack(trackId: string): void;
     getTrack(trackId: string): PlayableTrack | undefined;
+    getTrackIds(): string[];
+    /**
+     * Replace clips on a track, preserving the track's audio graph.
+     * Only works for ToneTrack (audio clips), not MidiToneTrack.
+     */
+    replaceTrackClips(trackId: string, newClips: ClipInfo[], newStartTime?: number): boolean;
+    /**
+     * Start mid-clip sources for a specific track at the current Transport position.
+     * Call after adding/updating a track during active playback so clips that span
+     * the current position produce audio immediately.
+     */
+    resumeTrackMidPlayback(trackId: string): void;
     play(when?: number, offset?: number, duration?: number): void;
     pause(): void;
     stop(): void;

package/dist/index.d.ts

@@ -21,6 +21,12 @@ interface ToneTrackOptions {
     effects?: TrackEffectsFunction;
     destination?: ToneAudioNode;
 }
+/** Per-clip scheduling info and audio nodes */
+interface ScheduledClip {
+    clipInfo: ClipInfo;
+    fadeGainNode: GainNode;
+    scheduleId: number;
+}
 declare class ToneTrack {
     private scheduledClips;
     private activeSources;
@@ -51,6 +57,26 @@ declare class ToneTrack {
      * schedule callbacks at exact Transport position (e.g., loopStart).
      */
     startMidClipSources(transportOffset: number, audioContextTime: number): void;
+    /**
+     * Add a clip to this track at runtime. Creates a Transport.schedule event
+     * and fadeGainNode. If playing, starts the source mid-clip if needed.
+     */
+    addClip(clipInfo: ClipInfo): ScheduledClip;
+    /**
+     * Remove a scheduled clip by index. Clears the Transport event and
+     * disconnects the fadeGainNode.
+     */
+    removeScheduledClip(index: number): void;
+    /**
+     * Replace clips on this track. Diffs old vs new by buffer + timing —
+     * unchanged clips keep their active sources playing (no audible interruption).
+     * Changed/added/removed clips are rescheduled. Disconnecting a removed clip's
+     * fadeGainNode silences its source immediately (audio path broken) without
+     * needing to explicitly stop it.
+     */
+    replaceClips(newClips: ClipInfo[], newStartTime?: number): void;
+    /** Compare two clips by reference (buffer), timing, and fade properties */
+    private _clipsEqual;
     /**
      * Stop all active AudioBufferSourceNodes and clear the set.
      * Native AudioBufferSourceNodes ignore Transport state changes —
@@ -425,6 +451,18 @@ declare class TonePlayout {
     applyInitialSoloState(): void;
     removeTrack(trackId: string): void;
     getTrack(trackId: string): PlayableTrack | undefined;
+    getTrackIds(): string[];
+    /**
+     * Replace clips on a track, preserving the track's audio graph.
+     * Only works for ToneTrack (audio clips), not MidiToneTrack.
+     */
+    replaceTrackClips(trackId: string, newClips: ClipInfo[], newStartTime?: number): boolean;
+    /**
+     * Start mid-clip sources for a specific track at the current Transport position.
+     * Call after adding/updating a track during active playback so clips that span
+     * the current position produce audio immediately.
+     */
+    resumeTrackMidPlayback(trackId: string): void;
     play(when?: number, offset?: number, duration?: number): void;
     pause(): void;
     stop(): void;

package/dist/index.js

@@ -179,6 +179,112 @@ var ToneTrack = class {
       }
     }
   }
+  /**
+   * Add a clip to this track at runtime. Creates a Transport.schedule event
+   * and fadeGainNode. If playing, starts the source mid-clip if needed.
+   */
+  addClip(clipInfo) {
+    const transport = (0, import_tone.getTransport)();
+    const rawContext = (0, import_tone.getContext)().rawContext;
+    const volumeNativeInput = this.volumeNode.input.input;
+    const fadeGainNode = rawContext.createGain();
+    fadeGainNode.gain.value = clipInfo.gain;
+    fadeGainNode.connect(volumeNativeInput);
+    const absTransportTime = this.track.startTime + clipInfo.startTime;
+    const scheduleId = transport.schedule((audioContextTime) => {
+      if (absTransportTime < this._scheduleGuardOffset) return;
+      this.startClipSource(clipInfo, fadeGainNode, audioContextTime);
+    }, absTransportTime);
+    const scheduled = { clipInfo, fadeGainNode, scheduleId };
+    this.scheduledClips.push(scheduled);
+    return scheduled;
+  }
+  /**
+   * Remove a scheduled clip by index. Clears the Transport event and
+   * disconnects the fadeGainNode.
+   */
+  removeScheduledClip(index) {
+    const scheduled = this.scheduledClips[index];
+    if (!scheduled) return;
+    const transport = (0, import_tone.getTransport)();
+    try {
+      transport.clear(scheduled.scheduleId);
+    } catch {
+    }
+    try {
+      scheduled.fadeGainNode.disconnect();
+    } catch {
+    }
+    this.scheduledClips.splice(index, 1);
+  }
+  /**
+   * Replace clips on this track. Diffs old vs new by buffer + timing —
+   * unchanged clips keep their active sources playing (no audible interruption).
+   * Changed/added/removed clips are rescheduled. Disconnecting a removed clip's
+   * fadeGainNode silences its source immediately (audio path broken) without
+   * needing to explicitly stop it.
+   */
+  replaceClips(newClips, newStartTime) {
+    if (newStartTime !== void 0) {
+      this.track.startTime = newStartTime;
+    }
+    const tp = (0, import_tone.getTransport)();
+    const kept = [];
+    const toAdd = [];
+    const matched = /* @__PURE__ */ new Set();
+    for (const clipInfo of newClips) {
+      const idx = this.scheduledClips.findIndex(
+        (s, i) => !matched.has(i) && this._clipsEqual(s.clipInfo, clipInfo)
+      );
+      if (idx !== -1) {
+        kept.push(this.scheduledClips[idx]);
+        matched.add(idx);
+      } else {
+        toAdd.push(clipInfo);
+      }
+    }
+    for (let i = 0; i < this.scheduledClips.length; i++) {
+      if (!matched.has(i)) {
+        const scheduled = this.scheduledClips[i];
+        try {
+          tp.clear(scheduled.scheduleId);
+        } catch {
+        }
+        try {
+          scheduled.fadeGainNode.disconnect();
+        } catch {
+        }
+      }
+    }
+    this.scheduledClips = kept;
+    const isPlaying = tp.state === "started";
+    for (const clipInfo of toAdd) {
+      const scheduled = this.addClip(clipInfo);
+      if (isPlaying) {
+        const context = (0, import_tone.getContext)();
+        const transportOffset = tp.seconds;
+        const audioContextTime = context.currentTime;
+        const lookAhead = context.lookAhead ?? 0;
+        const audibleOffset = Math.max(0, transportOffset - lookAhead);
+        const absClipStart = this.track.startTime + clipInfo.startTime;
+        const absClipEnd = absClipStart + clipInfo.duration;
+        if (absClipStart < transportOffset && absClipEnd > audibleOffset) {
+          const elapsed = audibleOffset - absClipStart;
+          this.startClipSource(
+            clipInfo,
+            scheduled.fadeGainNode,
+            audioContextTime,
+            clipInfo.offset + Math.max(0, elapsed),
+            clipInfo.duration - Math.max(0, elapsed)
+          );
+        }
+      }
+    }
+  }
+  /** Compare two clips by reference (buffer), timing, and fade properties */
+  _clipsEqual(a, b) {
+    return a.buffer === b.buffer && a.startTime === b.startTime && a.duration === b.duration && a.offset === b.offset && a.gain === b.gain && a.fadeIn?.duration === b.fadeIn?.duration && a.fadeIn?.type === b.fadeIn?.type && a.fadeOut?.duration === b.fadeOut?.duration && a.fadeOut?.type === b.fadeOut?.type;
+  }
   /**
    * Stop all active AudioBufferSourceNodes and clear the set.
    * Native AudioBufferSourceNodes ignore Transport state changes —
@@ -1031,6 +1137,34 @@ var TonePlayout = class {
   getTrack(trackId) {
     return this.tracks.get(trackId);
   }
+  getTrackIds() {
+    return [...this.tracks.keys()];
+  }
+  /**
+   * Replace clips on a track, preserving the track's audio graph.
+   * Only works for ToneTrack (audio clips), not MidiToneTrack.
+   */
+  replaceTrackClips(trackId, newClips, newStartTime) {
+    const track = this.tracks.get(trackId);
+    if (!track || !("replaceClips" in track)) return false;
+    track.replaceClips(newClips, newStartTime);
+    return true;
+  }
+  /**
+   * Start mid-clip sources for a specific track at the current Transport position.
+   * Call after adding/updating a track during active playback so clips that span
+   * the current position produce audio immediately.
+   */
+  resumeTrackMidPlayback(trackId) {
+    const track = this.tracks.get(trackId);
+    if (!track) return;
+    const transport = (0, import_tone4.getTransport)();
+    if (transport.state !== "started") return;
+    const context = (0, import_tone4.getContext)();
+    const lookAhead = context.lookAhead ?? 0;
+    const audibleOffset = Math.max(0, transport.seconds - lookAhead);
+    track.startMidClipSources(audibleOffset, context.currentTime);
+  }
   play(when, offset, duration) {
     if (!this.isInitialized) {
       throw new Error("[waveform-playlist] TonePlayout not initialized. Call init() first.");
@@ -1468,6 +1602,7 @@ function createToneAdapter(options) {
   let _loopStart = 0;
   let _loopEnd = 0;
   let _audioInitialized = false;
+  let _pendingInit = null;
   function addTrackToPlayout(p, track) {
     const audioClips = track.clips.filter((c) => c.audioBuffer && !c.midiNotes);
     const midiClips = track.clips.filter((c) => c.midiNotes && c.midiNotes.length > 0);
@@ -1551,7 +1686,7 @@ function createToneAdapter(options) {
       try {
         playout.dispose();
       } catch (err) {
-        console.warn("[waveform-playlist] Error disposing previous playout during rebuild:", err);
+        console.warn("[waveform-playlist] Error disposing previous playout:", err);
       }
       playout = null;
     }
@@ -1561,9 +1696,9 @@ function createToneAdapter(options) {
       effects: options?.effects
     });
     if (_audioInitialized) {
-      playout.init().catch((err) => {
+      _pendingInit = playout.init().catch((err) => {
         console.warn(
-          "[waveform-playlist] Failed to re-initialize playout after rebuild. Audio playback will require another user gesture.",
+          "[waveform-playlist] Failed to initialize playout. Audio playback will require another user gesture.",
           err
         );
         _audioInitialized = false;
@@ -1582,13 +1717,80 @@ function createToneAdapter(options) {
   }
   return {
     async init() {
+      if (_pendingInit) {
+        await _pendingInit;
+        _pendingInit = null;
+        return;
+      }
       if (playout) {
         await playout.init();
         _audioInitialized = true;
       }
     },
     setTracks(tracks) {
-      buildPlayout(tracks);
+      if (!playout) {
+        buildPlayout(tracks);
+        return;
+      }
+      const newTrackIds = new Set(tracks.map((t) => t.id));
+      const oldTrackIds = new Set(playout.getTrackIds());
+      for (const id of oldTrackIds) {
+        if (!newTrackIds.has(id)) {
+          playout.removeTrack(id);
+        }
+      }
+      for (const track of tracks) {
+        if (oldTrackIds.has(track.id)) {
+          playout.removeTrack(track.id);
+          playout.removeTrack(track.id + ":midi");
+        }
+        addTrackToPlayout(playout, track);
+      }
+      playout.applyInitialSoloState();
+      if (_isPlaying) {
+        for (const track of tracks) {
+          playout.resumeTrackMidPlayback(track.id);
+          playout.resumeTrackMidPlayback(track.id + ":midi");
+        }
+      }
+    },
+    updateTrack(trackId, track) {
+      if (!playout) return;
+      const audioClips = track.clips.filter((c) => c.audioBuffer && !c.midiNotes);
+      if (audioClips.length > 0) {
+        const startTime = Math.min(...audioClips.map(import_core2.clipStartTime));
+        const clipInfos = audioClips.map((clip) => ({
+          buffer: clip.audioBuffer,
+          startTime: (0, import_core2.clipStartTime)(clip) - startTime,
+          duration: (0, import_core2.clipDurationTime)(clip),
+          offset: (0, import_core2.clipOffsetTime)(clip),
+          fadeIn: clip.fadeIn,
+          fadeOut: clip.fadeOut,
+          gain: clip.gain
+        }));
+        const audioUpdated = playout.replaceTrackClips(trackId, clipInfos, startTime);
+        const midiClips = track.clips.filter((c) => c.midiNotes && c.midiNotes.length > 0);
+        if (midiClips.length > 0) {
+          const midiTrackId = trackId + ":midi";
+          playout.removeTrack(midiTrackId);
+          addTrackToPlayout(playout, track);
+          if (_isPlaying) {
+            playout.resumeTrackMidPlayback(midiTrackId);
+          }
+        }
+        if (audioUpdated) {
+          playout.applyInitialSoloState();
+          return;
+        }
+      }
+      playout.removeTrack(trackId);
+      playout.removeTrack(trackId + ":midi");
+      addTrackToPlayout(playout, track);
+      playout.applyInitialSoloState();
+      if (_isPlaying) {
+        playout.resumeTrackMidPlayback(trackId);
+        playout.resumeTrackMidPlayback(trackId + ":midi");
+      }
     },
     addTrack(track) {
       if (!playout) {