@waveform-playlist/media-element-playout 12.0.0 → 12.2.0

package/README.md

@@ -56,7 +56,7 @@ playout.play(0);           // Play from beginning
 playout.setPlaybackRate(0.75);  // Slow down to 75% speed (pitch preserved)
 playout.pause();
 playout.seekTo(30);        // Seek to 30 seconds
-playout.play();            // Resume
+playout.resume();          // Resume from the current position (does NOT reset to 0)
 
 // Clean up
 playout.dispose();
@@ -79,16 +79,22 @@ class MediaElementPlayout {
 
   // Track management
   addTrack(options: MediaElementTrackOptions): MediaElementTrack;
+  setSource(options: MediaElementTrackOptions): MediaElementTrack;  // silent in-place replace
   removeTrack(trackId: string): void;
   getTrack(trackId: string): MediaElementTrack | undefined;
 
   // Playback
   play(when?: number, offset?: number, duration?: number): void;
+  resume(): void;            // resume from current position (no reset to 0)
   pause(): void;
   stop(): void;
   seekTo(time: number): void;
   getCurrentTime(): number;
 
+  // Lifecycle events (typed via MediaElementTrackEvents)
+  on<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+  off<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+
   // Volume & Rate
   setMasterVolume(volume: number): void;
   setPlaybackRate(rate: number): void;  // 0.5 to 2.0, pitch preserved
@@ -105,7 +111,7 @@ class MediaElementPlayout {
 ```typescript
 interface MediaElementTrackOptions {
   source: string | HTMLAudioElement;  // URL or audio element
-  peaks: WaveformDataObject;          // Pre-computed peaks
+  peaks?: WaveformDataObject;         // Pre-computed peaks (optional — omit for scrubber-only / headless players)
   id?: string;
   name?: string;
   volume?: number;
@@ -113,6 +119,31 @@ interface MediaElementTrackOptions {
 }
 ```
 
+## Player Mode
+
+Beyond the timeline/editor API, three affordances make this engine pleasant to
+reuse as a single-track **player** (podcast/audiobook players, `<daw-player>`):
+
+```typescript
+// Resume from the current position (play() with no offset resets to 0)
+playout.resume();
+
+// Swap to the next source in place — no "Only one track is supported" warning,
+// and any Web Audio routing/effects are preserved across the swap
+playout.setSource({ source: '/audio/episode-2.mp3', name: 'Episode 2' });
+
+// Observe media lifecycle without reaching into the audio element
+playout.on('loadedmetadata', () => console.log('duration:', playout.duration));
+playout.on('play', () => updateTransportUI('playing'));
+playout.on('pause', () => updateTransportUI('paused'));
+playout.on('error', (err) => surfaceError(err));
+playout.off('play', handler); // unsubscribe
+```
+
+`on()` listeners are retained across `setSource()` swaps — register them once.
+The same `on()/off()` and `resume()`/`load()` methods exist on `MediaElementTrack`
+for power users. Event names and payloads are typed via `MediaElementTrackEvents`.
+
 ## Generating Peaks
 
 Use [audiowaveform](https://github.com/bbc/audiowaveform) or [waveform-data.js](https://github.com/bbc/waveform-data.js) to pre-compute peaks:

package/dist/index.d.mts

@@ -4,8 +4,9 @@ export { FadeConfig } from '@waveform-playlist/core';
 interface MediaElementTrackOptions {
     /** The audio source - can be a URL, Blob URL, or HTMLAudioElement */
     source: string | HTMLAudioElement;
-    /** Pre-computed waveform data for visualization (required - no AudioBuffer decoding) */
-    peaks: WaveformDataObject;
+    /** Pre-computed waveform data for visualization. Optional — omit for
+     *  scrubber-only / headless players that don't render a waveform. */
+    peaks?: WaveformDataObject;
     /** Track ID */
     id?: string;
     /** Track name for display */
@@ -33,6 +34,25 @@ interface MediaElementTrackOptions {
     /** Fade out configuration (requires audioContext) */
     fadeOut?: FadeConfig;
 }
+/**
+ * Typed event map for MediaElementTrack's emitter. Mirrors the on()/off()
+ * pattern used by @waveform-playlist/engine's PlaylistEngine so consumers and
+ * the dawcore web-components layer can wire events uniformly across engines.
+ */
+interface MediaElementTrackEvents {
+    /** Fired when the element's metadata (duration, dimensions) has loaded. */
+    loadedmetadata: () => void;
+    /** Fired when native playback starts/resumes. */
+    play: () => void;
+    /** Fired when native playback pauses (including at end-of-media). */
+    pause: () => void;
+    /** Fired on a media error; carries the element's MediaError (or null). */
+    error: (err: MediaError | null) => void;
+    /** Fired when playback reaches the end of the media. */
+    ended: () => void;
+    /** Fired on each native timeupdate; carries the current time in seconds. */
+    timeupdate: (time: number) => void;
+}
 /**
  * Single-track playback using HTMLAudioElement.
  *
@@ -56,6 +76,7 @@ declare class MediaElementTrack {
     private _volume;
     private onStopCallback?;
     private onTimeUpdateCallback?;
+    private _listeners;
     private _audioContext;
     private _sourceNode;
     private _fadeGain;
@@ -65,6 +86,10 @@ declare class MediaElementTrack {
     constructor(options: MediaElementTrackOptions);
     private handleEnded;
     private handleTimeUpdate;
+    private handleLoadedMetadata;
+    private handlePlay;
+    private handlePause;
+    private handleError;
     /**
      * Schedule fade automation on the fade GainNode.
      * Called at the start of each play() — fades are relative to the playback offset.
@@ -80,6 +105,29 @@ declare class MediaElementTrack {
      * (fades depend on audioContext.currentTime being non-zero).
      */
     play(offset?: number): void;
+    /**
+     * Resume playback from the current position without resetting currentTime.
+     * Reuses play()'s fade re-scheduling and AudioContext-resume machinery —
+     * passing the current position as the offset is a no-op seek that leaves
+     * playback where it was.
+     */
+    resume(): void;
+    /**
+     * Swap the audio source in place, reusing the existing <audio> element.
+     * Because the MediaElementAudioSourceNode is once-per-element, reusing the
+     * element preserves any Web Audio routing/effects across the swap.
+     *
+     * Only supported when this track owns its element (constructed from a URL
+     * string). A borrowed element (constructed from an HTMLAudioElement) warns
+     * and no-ops — swapping a consumer-owned element's src is out of contract.
+     *
+     * Peaks are coupled to the specific audio, so they are replaced (defaulting
+     * to null when omitted). Name is a label, so it updates only when provided.
+     */
+    load(source: string, opts?: {
+        peaks?: WaveformDataObject;
+        name?: string;
+    }): void;
     /**
      * Pause playback
      */
@@ -131,13 +179,23 @@ declare class MediaElementTrack {
      * Disconnect the output and reconnect to the default AudioContext destination.
      */
     disconnectOutput(): void;
+    /**
+     * Subscribe to a track lifecycle event. Multiple listeners per event are
+     * supported. Mirrors PlaylistEngine's on()/off() emitter.
+     */
+    on<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+    /**
+     * Unsubscribe a previously registered listener.
+     */
+    off<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+    private _emit;
     /**
      * Clean up resources
      */
     dispose(): void;
     get id(): string;
     get name(): string;
-    get peaks(): WaveformDataObject;
+    get peaks(): WaveformDataObject | null;
     get currentTime(): number;
     get duration(): number;
     get isPlaying(): boolean;
@@ -188,6 +246,8 @@ declare class MediaElementPlayout {
     private _preservesPitch;
     private _isPlaying;
     private onPlaybackCompleteCallback?;
+    /** Consumer event listeners, retained so they re-attach across track swaps. */
+    private _eventListeners;
     constructor(options?: MediaElementPlayoutOptions);
     /**
      * Initialize the playout engine.
@@ -201,6 +261,16 @@ declare class MediaElementPlayout {
      * Note: Only one track is supported. Adding a second track will dispose the first.
      */
     addTrack(options: MediaElementTrackOptions): MediaElementTrack;
+    /**
+     * Replace the playout's source (player-mode affordance). The documented
+     * single-track replace path — does NOT warn like addTrack().
+     *
+     * For URL (string) sources with an existing track, swaps in place via
+     * track.load(), reusing the element and preserving Web Audio routing. For a
+     * provided HTMLAudioElement source, or when there is no track yet, (re)creates
+     * the track. Returns the active track.
+     */
+    setSource(options: MediaElementTrackOptions): MediaElementTrack;
     /**
      * Remove a track by ID.
      */
@@ -216,6 +286,13 @@ declare class MediaElementPlayout {
      * @param duration - Duration to play in seconds (optional)
      */
     play(_when?: number, offset?: number, duration?: number): void;
+    /**
+     * Resume playback from the current position (player-mode affordance).
+     * Unlike play() with no offset (which resets to 0), this keeps currentTime.
+     * Delegates to play() with the current position as the offset, so all of
+     * play()'s machinery (AudioContext resume, fades, _isPlaying) is reused.
+     */
+    resume(): void;
     /**
      * Pause playback.
      */
@@ -253,6 +330,23 @@ declare class MediaElementPlayout {
      * Set callback for when playback completes.
      */
     setOnPlaybackComplete(callback: () => void): void;
+    /**
+     * Subscribe to a lifecycle event (loadedmetadata / play / pause / error /
+     * ended / timeupdate) without reaching into track.element. Listeners are
+     * retained and re-attached automatically when the source is swapped.
+     */
+    on<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+    /**
+     * Unsubscribe a previously registered lifecycle listener.
+     */
+    off<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+    /**
+     * Attach every registered listener to the current track. Called after a new
+     * track is created so subscriptions survive source swaps. The cast is safe:
+     * the event→listener correlation was enforced by the typed on() that filled
+     * the registry; TS cannot track it through this loop.
+     */
+    private _attachListenersToTrack;
     /**
      * Clean up resources.
      */
@@ -306,4 +400,4 @@ interface PlaybackRateEngine extends PlayoutEngine {
  */
 declare function supportsPlaybackRate(engine: PlayoutEngine): engine is PlaybackRateEngine;
 
-export { MediaElementPlayout, type MediaElementPlayoutOptions, MediaElementTrack, type MediaElementTrackOptions, type PlaybackRateEngine, type PlayoutEngine, supportsPlaybackRate };
+export { MediaElementPlayout, type MediaElementPlayoutOptions, MediaElementTrack, type MediaElementTrackEvents, type MediaElementTrackOptions, type PlaybackRateEngine, type PlayoutEngine, supportsPlaybackRate };

package/dist/index.d.ts

@@ -4,8 +4,9 @@ export { FadeConfig } from '@waveform-playlist/core';
 interface MediaElementTrackOptions {
     /** The audio source - can be a URL, Blob URL, or HTMLAudioElement */
     source: string | HTMLAudioElement;
-    /** Pre-computed waveform data for visualization (required - no AudioBuffer decoding) */
-    peaks: WaveformDataObject;
+    /** Pre-computed waveform data for visualization. Optional — omit for
+     *  scrubber-only / headless players that don't render a waveform. */
+    peaks?: WaveformDataObject;
     /** Track ID */
     id?: string;
     /** Track name for display */
@@ -33,6 +34,25 @@ interface MediaElementTrackOptions {
     /** Fade out configuration (requires audioContext) */
     fadeOut?: FadeConfig;
 }
+/**
+ * Typed event map for MediaElementTrack's emitter. Mirrors the on()/off()
+ * pattern used by @waveform-playlist/engine's PlaylistEngine so consumers and
+ * the dawcore web-components layer can wire events uniformly across engines.
+ */
+interface MediaElementTrackEvents {
+    /** Fired when the element's metadata (duration, dimensions) has loaded. */
+    loadedmetadata: () => void;
+    /** Fired when native playback starts/resumes. */
+    play: () => void;
+    /** Fired when native playback pauses (including at end-of-media). */
+    pause: () => void;
+    /** Fired on a media error; carries the element's MediaError (or null). */
+    error: (err: MediaError | null) => void;
+    /** Fired when playback reaches the end of the media. */
+    ended: () => void;
+    /** Fired on each native timeupdate; carries the current time in seconds. */
+    timeupdate: (time: number) => void;
+}
 /**
  * Single-track playback using HTMLAudioElement.
  *
@@ -56,6 +76,7 @@ declare class MediaElementTrack {
     private _volume;
     private onStopCallback?;
     private onTimeUpdateCallback?;
+    private _listeners;
     private _audioContext;
     private _sourceNode;
     private _fadeGain;
@@ -65,6 +86,10 @@ declare class MediaElementTrack {
     constructor(options: MediaElementTrackOptions);
     private handleEnded;
     private handleTimeUpdate;
+    private handleLoadedMetadata;
+    private handlePlay;
+    private handlePause;
+    private handleError;
     /**
      * Schedule fade automation on the fade GainNode.
      * Called at the start of each play() — fades are relative to the playback offset.
@@ -80,6 +105,29 @@ declare class MediaElementTrack {
      * (fades depend on audioContext.currentTime being non-zero).
      */
     play(offset?: number): void;
+    /**
+     * Resume playback from the current position without resetting currentTime.
+     * Reuses play()'s fade re-scheduling and AudioContext-resume machinery —
+     * passing the current position as the offset is a no-op seek that leaves
+     * playback where it was.
+     */
+    resume(): void;
+    /**
+     * Swap the audio source in place, reusing the existing <audio> element.
+     * Because the MediaElementAudioSourceNode is once-per-element, reusing the
+     * element preserves any Web Audio routing/effects across the swap.
+     *
+     * Only supported when this track owns its element (constructed from a URL
+     * string). A borrowed element (constructed from an HTMLAudioElement) warns
+     * and no-ops — swapping a consumer-owned element's src is out of contract.
+     *
+     * Peaks are coupled to the specific audio, so they are replaced (defaulting
+     * to null when omitted). Name is a label, so it updates only when provided.
+     */
+    load(source: string, opts?: {
+        peaks?: WaveformDataObject;
+        name?: string;
+    }): void;
     /**
      * Pause playback
      */
@@ -131,13 +179,23 @@ declare class MediaElementTrack {
      * Disconnect the output and reconnect to the default AudioContext destination.
      */
     disconnectOutput(): void;
+    /**
+     * Subscribe to a track lifecycle event. Multiple listeners per event are
+     * supported. Mirrors PlaylistEngine's on()/off() emitter.
+     */
+    on<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+    /**
+     * Unsubscribe a previously registered listener.
+     */
+    off<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+    private _emit;
     /**
      * Clean up resources
      */
     dispose(): void;
     get id(): string;
     get name(): string;
-    get peaks(): WaveformDataObject;
+    get peaks(): WaveformDataObject | null;
     get currentTime(): number;
     get duration(): number;
     get isPlaying(): boolean;
@@ -188,6 +246,8 @@ declare class MediaElementPlayout {
     private _preservesPitch;
     private _isPlaying;
     private onPlaybackCompleteCallback?;
+    /** Consumer event listeners, retained so they re-attach across track swaps. */
+    private _eventListeners;
     constructor(options?: MediaElementPlayoutOptions);
     /**
      * Initialize the playout engine.
@@ -201,6 +261,16 @@ declare class MediaElementPlayout {
      * Note: Only one track is supported. Adding a second track will dispose the first.
      */
     addTrack(options: MediaElementTrackOptions): MediaElementTrack;
+    /**
+     * Replace the playout's source (player-mode affordance). The documented
+     * single-track replace path — does NOT warn like addTrack().
+     *
+     * For URL (string) sources with an existing track, swaps in place via
+     * track.load(), reusing the element and preserving Web Audio routing. For a
+     * provided HTMLAudioElement source, or when there is no track yet, (re)creates
+     * the track. Returns the active track.
+     */
+    setSource(options: MediaElementTrackOptions): MediaElementTrack;
     /**
      * Remove a track by ID.
      */
@@ -216,6 +286,13 @@ declare class MediaElementPlayout {
      * @param duration - Duration to play in seconds (optional)
      */
     play(_when?: number, offset?: number, duration?: number): void;
+    /**
+     * Resume playback from the current position (player-mode affordance).
+     * Unlike play() with no offset (which resets to 0), this keeps currentTime.
+     * Delegates to play() with the current position as the offset, so all of
+     * play()'s machinery (AudioContext resume, fades, _isPlaying) is reused.
+     */
+    resume(): void;
     /**
      * Pause playback.
      */
@@ -253,6 +330,23 @@ declare class MediaElementPlayout {
      * Set callback for when playback completes.
      */
     setOnPlaybackComplete(callback: () => void): void;
+    /**
+     * Subscribe to a lifecycle event (loadedmetadata / play / pause / error /
+     * ended / timeupdate) without reaching into track.element. Listeners are
+     * retained and re-attached automatically when the source is swapped.
+     */
+    on<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+    /**
+     * Unsubscribe a previously registered lifecycle listener.
+     */
+    off<K extends keyof MediaElementTrackEvents>(event: K, listener: MediaElementTrackEvents[K]): void;
+    /**
+     * Attach every registered listener to the current track. Called after a new
+     * track is created so subscriptions survive source swaps. The cast is safe:
+     * the event→listener correlation was enforced by the typed on() that filled
+     * the registry; TS cannot track it through this loop.
+     */
+    private _attachListenersToTrack;
     /**
      * Clean up resources.
      */
@@ -306,4 +400,4 @@ interface PlaybackRateEngine extends PlayoutEngine {
  */
 declare function supportsPlaybackRate(engine: PlayoutEngine): engine is PlaybackRateEngine;
 
-export { MediaElementPlayout, type MediaElementPlayoutOptions, MediaElementTrack, type MediaElementTrackOptions, type PlaybackRateEngine, type PlayoutEngine, supportsPlaybackRate };
+export { MediaElementPlayout, type MediaElementPlayoutOptions, MediaElementTrack, type MediaElementTrackEvents, type MediaElementTrackOptions, type PlaybackRateEngine, type PlayoutEngine, supportsPlaybackRate };

package/dist/index.js

@@ -31,6 +31,7 @@ var import_core = require("@waveform-playlist/core");
 var MediaElementTrack = class {
   constructor(options) {
     this._playbackRate = 1;
+    this._listeners = /* @__PURE__ */ new Map();
     // Web Audio nodes (only when audioContext is provided)
     this._audioContext = null;
     this._sourceNode = null;
@@ -41,13 +42,27 @@ var MediaElementTrack = class {
       if (this.onStopCallback) {
         this.onStopCallback();
       }
+      this._emit("ended");
     };
     this.handleTimeUpdate = () => {
       if (this.onTimeUpdateCallback) {
         this.onTimeUpdateCallback(this.audioElement.currentTime);
       }
+      this._emit("timeupdate", this.audioElement.currentTime);
     };
-    this._peaks = options.peaks;
+    this.handleLoadedMetadata = () => {
+      this._emit("loadedmetadata");
+    };
+    this.handlePlay = () => {
+      this._emit("play");
+    };
+    this.handlePause = () => {
+      this._emit("pause");
+    };
+    this.handleError = () => {
+      this._emit("error", this.audioElement.error);
+    };
+    this._peaks = options.peaks ?? null;
     this._id = options.id ?? `track-${Date.now()}`;
     this._name = options.name ?? "Track";
     this._playbackRate = options.playbackRate ?? 1;
@@ -93,6 +108,10 @@ var MediaElementTrack = class {
     }
     this.audioElement.addEventListener("ended", this.handleEnded);
     this.audioElement.addEventListener("timeupdate", this.handleTimeUpdate);
+    this.audioElement.addEventListener("loadedmetadata", this.handleLoadedMetadata);
+    this.audioElement.addEventListener("play", this.handlePlay);
+    this.audioElement.addEventListener("pause", this.handlePause);
+    this.audioElement.addEventListener("error", this.handleError);
   }
   /**
    * Schedule fade automation on the fade GainNode.
@@ -179,6 +198,45 @@ var MediaElementTrack = class {
       startPlayback();
     }
   }
+  /**
+   * Resume playback from the current position without resetting currentTime.
+   * Reuses play()'s fade re-scheduling and AudioContext-resume machinery —
+   * passing the current position as the offset is a no-op seek that leaves
+   * playback where it was.
+   */
+  resume() {
+    this.play(this.currentTime);
+  }
+  /**
+   * Swap the audio source in place, reusing the existing <audio> element.
+   * Because the MediaElementAudioSourceNode is once-per-element, reusing the
+   * element preserves any Web Audio routing/effects across the swap.
+   *
+   * Only supported when this track owns its element (constructed from a URL
+   * string). A borrowed element (constructed from an HTMLAudioElement) warns
+   * and no-ops — swapping a consumer-owned element's src is out of contract.
+   *
+   * Peaks are coupled to the specific audio, so they are replaced (defaulting
+   * to null when omitted). Name is a label, so it updates only when provided.
+   */
+  load(source, opts = {}) {
+    if (!this.ownsElement) {
+      console.warn(
+        "[waveform-playlist] MediaElementTrack: load() is only supported for tracks that own their audio element (constructed from a URL string). A track constructed from an existing HTMLAudioElement cannot swap its source in place."
+      );
+      return;
+    }
+    this._cancelFades();
+    this.audioElement.pause();
+    this.audioElement.src = source;
+    this.audioElement.load();
+    this.audioElement.currentTime = 0;
+    this._peaks = opts.peaks ?? null;
+    if (opts.name !== void 0) {
+      this._name = opts.name;
+    }
+    this.audioElement.playbackRate = this._playbackRate;
+  }
   /**
    * Pause playback
    */
@@ -285,12 +343,47 @@ var MediaElementTrack = class {
     }
     this._volumeGain.connect(this._audioContext.destination);
   }
+  /**
+   * Subscribe to a track lifecycle event. Multiple listeners per event are
+   * supported. Mirrors PlaylistEngine's on()/off() emitter.
+   */
+  on(event, listener) {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this._listeners.get(event).add(listener);
+  }
+  /**
+   * Unsubscribe a previously registered listener.
+   */
+  off(event, listener) {
+    this._listeners.get(event)?.delete(listener);
+  }
+  _emit(event, ...args) {
+    const listeners = this._listeners.get(event);
+    if (listeners) {
+      for (const listener of listeners) {
+        try {
+          listener(...args);
+        } catch (error) {
+          console.warn(
+            "[waveform-playlist] MediaElementTrack: error in event listener: " + String(error)
+          );
+        }
+      }
+    }
+  }
   /**
    * Clean up resources
    */
   dispose() {
     this.audioElement.removeEventListener("ended", this.handleEnded);
     this.audioElement.removeEventListener("timeupdate", this.handleTimeUpdate);
+    this.audioElement.removeEventListener("loadedmetadata", this.handleLoadedMetadata);
+    this.audioElement.removeEventListener("play", this.handlePlay);
+    this.audioElement.removeEventListener("pause", this.handlePause);
+    this.audioElement.removeEventListener("error", this.handleError);
+    this._listeners.clear();
     this._cancelFades();
     this.audioElement.pause();
     if (this._sourceNode) {
@@ -339,7 +432,7 @@ var MediaElementTrack = class {
     return this.audioElement.currentTime;
   }
   get duration() {
-    return this.audioElement.duration || this._peaks.duration;
+    return this.audioElement.duration || this._peaks?.duration || 0;
   }
   get isPlaying() {
     return !this.audioElement.paused && !this.audioElement.ended;
@@ -373,6 +466,8 @@ var MediaElementPlayout = class {
   constructor(options = {}) {
     this.track = null;
     this._isPlaying = false;
+    /** Consumer event listeners, retained so they re-attach across track swaps. */
+    this._eventListeners = /* @__PURE__ */ new Map();
     this._masterVolume = options.masterVolume ?? 1;
     this._playbackRate = options.playbackRate ?? 1;
     this._preservesPitch = options.preservesPitch ?? true;
@@ -408,8 +503,30 @@ var MediaElementPlayout = class {
         this.onPlaybackCompleteCallback();
       }
     });
+    this._attachListenersToTrack();
     return this.track;
   }
+  /**
+   * Replace the playout's source (player-mode affordance). The documented
+   * single-track replace path — does NOT warn like addTrack().
+   *
+   * For URL (string) sources with an existing track, swaps in place via
+   * track.load(), reusing the element and preserving Web Audio routing. For a
+   * provided HTMLAudioElement source, or when there is no track yet, (re)creates
+   * the track. Returns the active track.
+   */
+  setSource(options) {
+    this._isPlaying = false;
+    if (this.track && typeof options.source === "string") {
+      this.track.load(options.source, { peaks: options.peaks, name: options.name });
+      return this.track;
+    }
+    if (this.track) {
+      this.track.dispose();
+      this.track = null;
+    }
+    return this.addTrack(options);
+  }
   /**
    * Remove a track by ID.
    */
@@ -454,6 +571,15 @@ var MediaElementPlayout = class {
       }, adjustedDuration * 1e3);
     }
   }
+  /**
+   * Resume playback from the current position (player-mode affordance).
+   * Unlike play() with no offset (which resets to 0), this keeps currentTime.
+   * Delegates to play() with the current position as the offset, so all of
+   * play()'s machinery (AudioContext resume, fades, _isPlaying) is reused.
+   */
+  resume() {
+    this.play(void 0, this.getCurrentTime());
+  }
   /**
    * Pause playback.
    */
@@ -529,6 +655,43 @@ var MediaElementPlayout = class {
   setOnPlaybackComplete(callback) {
     this.onPlaybackCompleteCallback = callback;
   }
+  /**
+   * Subscribe to a lifecycle event (loadedmetadata / play / pause / error /
+   * ended / timeupdate) without reaching into track.element. Listeners are
+   * retained and re-attached automatically when the source is swapped.
+   */
+  on(event, listener) {
+    if (!this._eventListeners.has(event)) {
+      this._eventListeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this._eventListeners.get(event).add(listener);
+    this.track?.on(event, listener);
+  }
+  /**
+   * Unsubscribe a previously registered lifecycle listener.
+   */
+  off(event, listener) {
+    this._eventListeners.get(event)?.delete(listener);
+    this.track?.off(event, listener);
+  }
+  /**
+   * Attach every registered listener to the current track. Called after a new
+   * track is created so subscriptions survive source swaps. The cast is safe:
+   * the event→listener correlation was enforced by the typed on() that filled
+   * the registry; TS cannot track it through this loop.
+   */
+  _attachListenersToTrack() {
+    const track = this.track;
+    if (!track) return;
+    for (const [event, listeners] of this._eventListeners) {
+      for (const listener of listeners) {
+        track.on(
+          event,
+          listener
+        );
+      }
+    }
+  }
   /**
    * Clean up resources.
    */
@@ -537,6 +700,7 @@ var MediaElementPlayout = class {
       this.track.dispose();
       this.track = null;
     }
+    this._eventListeners.clear();
   }
   // Getters
   get isPlaying() {
@@ -552,7 +716,7 @@ var MediaElementPlayout = class {
     return this.track?.duration ?? 0;
   }
   get sampleRate() {
-    return this.track?.peaks.sample_rate ?? 44100;
+    return this.track?.peaks?.sample_rate ?? 44100;
   }
   /**
    * Get the volume GainNode output for connecting external effects chains.