@waveform-playlist/media-element-playout 12.1.0 → 12.3.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
@@ -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

@@ -13,7 +13,7 @@ interface MediaElementTrackOptions {
     name?: string;
     /** Initial volume (0.0 to 1.0) */
     volume?: number;
-    /** Initial playback rate (0.5 to 2.0) */
+    /** Initial playback rate (0.25 to 4.0) */
     playbackRate?: number;
     /** Whether to preserve pitch when changing playback rate (default: true) */
     preservesPitch?: boolean;
@@ -34,11 +34,30 @@ 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.
  *
  * Benefits over AudioBuffer/Tone.js:
- * - Pitch-preserving playback rate (0.5x - 2.0x) via browser's built-in algorithm
+ * - Pitch-preserving playback rate (0.25x - 4.0x) via browser's built-in algorithm
  * - No AudioBuffer decoding required (uses pre-computed peaks for visualization)
  * - Simpler, lighter-weight for single-track use cases
  *
@@ -57,6 +76,7 @@ declare class MediaElementTrack {
     private _volume;
     private onStopCallback?;
     private onTimeUpdateCallback?;
+    private _listeners;
     private _audioContext;
     private _sourceNode;
     private _fadeGain;
@@ -66,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.
@@ -81,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
      */
@@ -98,7 +145,7 @@ declare class MediaElementTrack {
      */
     setVolume(volume: number): void;
     /**
-     * Set playback rate (0.5 to 2.0, pitch preserved)
+     * Set playback rate (0.25 to 4.0, pitch preserved)
      */
     setPlaybackRate(rate: number): void;
     /**
@@ -132,6 +179,16 @@ 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
      */
@@ -159,7 +216,7 @@ declare class MediaElementTrack {
 interface MediaElementPlayoutOptions {
     /** Initial master volume (0.0 to 1.0) */
     masterVolume?: number;
-    /** Initial playback rate (0.5 to 2.0) */
+    /** Initial playback rate (0.25 to 4.0) */
     playbackRate?: number;
     /** Whether to preserve pitch when changing playback rate (default: true).
      *  Set to false when using an external pitch processor like SoundTouch. */
@@ -172,7 +229,7 @@ interface MediaElementPlayoutOptions {
  * that need pitch-preserving playback rate control.
  *
  * Key features:
- * - Pitch-preserving playback rate (0.5x - 2.0x)
+ * - Pitch-preserving playback rate (0.25x - 4.0x)
  * - Uses pre-computed peaks (no AudioBuffer required)
  * - Simpler API for single-track playback
  *
@@ -189,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.
@@ -202,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.
      */
@@ -217,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.
      */
@@ -238,7 +314,7 @@ declare class MediaElementPlayout {
      */
     setMasterVolume(volume: number): void;
     /**
-     * Set playback rate (0.5 to 2.0, pitch preserved).
+     * Set playback rate (0.25 to 4.0, pitch preserved).
      */
     setPlaybackRate(rate: number): void;
     /**
@@ -254,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.
      */
@@ -307,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

@@ -13,7 +13,7 @@ interface MediaElementTrackOptions {
     name?: string;
     /** Initial volume (0.0 to 1.0) */
     volume?: number;
-    /** Initial playback rate (0.5 to 2.0) */
+    /** Initial playback rate (0.25 to 4.0) */
     playbackRate?: number;
     /** Whether to preserve pitch when changing playback rate (default: true) */
     preservesPitch?: boolean;
@@ -34,11 +34,30 @@ 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.
  *
  * Benefits over AudioBuffer/Tone.js:
- * - Pitch-preserving playback rate (0.5x - 2.0x) via browser's built-in algorithm
+ * - Pitch-preserving playback rate (0.25x - 4.0x) via browser's built-in algorithm
  * - No AudioBuffer decoding required (uses pre-computed peaks for visualization)
  * - Simpler, lighter-weight for single-track use cases
  *
@@ -57,6 +76,7 @@ declare class MediaElementTrack {
     private _volume;
     private onStopCallback?;
     private onTimeUpdateCallback?;
+    private _listeners;
     private _audioContext;
     private _sourceNode;
     private _fadeGain;
@@ -66,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.
@@ -81,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
      */
@@ -98,7 +145,7 @@ declare class MediaElementTrack {
      */
     setVolume(volume: number): void;
     /**
-     * Set playback rate (0.5 to 2.0, pitch preserved)
+     * Set playback rate (0.25 to 4.0, pitch preserved)
      */
     setPlaybackRate(rate: number): void;
     /**
@@ -132,6 +179,16 @@ 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
      */
@@ -159,7 +216,7 @@ declare class MediaElementTrack {
 interface MediaElementPlayoutOptions {
     /** Initial master volume (0.0 to 1.0) */
     masterVolume?: number;
-    /** Initial playback rate (0.5 to 2.0) */
+    /** Initial playback rate (0.25 to 4.0) */
     playbackRate?: number;
     /** Whether to preserve pitch when changing playback rate (default: true).
      *  Set to false when using an external pitch processor like SoundTouch. */
@@ -172,7 +229,7 @@ interface MediaElementPlayoutOptions {
  * that need pitch-preserving playback rate control.
  *
  * Key features:
- * - Pitch-preserving playback rate (0.5x - 2.0x)
+ * - Pitch-preserving playback rate (0.25x - 4.0x)
  * - Uses pre-computed peaks (no AudioBuffer required)
  * - Simpler API for single-track playback
  *
@@ -189,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.
@@ -202,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.
      */
@@ -217,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.
      */
@@ -238,7 +314,7 @@ declare class MediaElementPlayout {
      */
     setMasterVolume(volume: number): void;
     /**
-     * Set playback rate (0.5 to 2.0, pitch preserved).
+     * Set playback rate (0.25 to 4.0, pitch preserved).
      */
     setPlaybackRate(rate: number): void;
     /**
@@ -254,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.
      */
@@ -307,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 };