@waveform-playlist/media-element-playout 5.0.0-alpha.14

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Naomi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# @waveform-playlist/media-element-playout
+
+A lightweight, HTMLMediaElement-based playout engine for waveform-playlist with **pitch-preserving playback rate control**.
+
+## Features
+
+- **Pitch-preserving playback rate** (0.5x - 2.0x) - uses browser's built-in time-stretching
+- **Pre-computed peaks** - no AudioBuffer decoding required, instant visualization
+- **Lightweight** - no Tone.js dependency
+- **Simple API** - designed for single-track playback use cases
+
+## When to Use
+
+Use `MediaElementPlayout` when you need:
+- Playback speed control for language learning, podcasts, etc.
+- Single-track playback with minimal overhead
+- Quick load times with pre-computed peaks
+
+Use `TonePlayout` from `@waveform-playlist/playout` when you need:
+- Multi-track mixing and editing
+- Clip-level effects and fades
+- Precise sample-accurate timing
+
+## Installation
+
+```bash
+npm install @waveform-playlist/media-element-playout
+```
+
+## Usage
+
+```typescript
+import { MediaElementPlayout } from '@waveform-playlist/media-element-playout';
+import WaveformData from 'waveform-data';
+
+// Load pre-computed peaks
+const response = await fetch('/audio/podcast.dat');
+const arrayBuffer = await response.arrayBuffer();
+const peaks = WaveformData.create(arrayBuffer);
+
+// Create playout
+const playout = new MediaElementPlayout({
+  masterVolume: 1.0,
+  playbackRate: 1.0,
+});
+
+// Add a track
+playout.addTrack({
+  source: '/audio/podcast.mp3',  // URL or Blob URL
+  peaks: peaks,
+  name: 'Podcast Episode 1',
+});
+
+// Control playback
+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
+
+// Clean up
+playout.dispose();
+```
+
+## API
+
+### MediaElementPlayout
+
+```typescript
+interface MediaElementPlayoutOptions {
+  masterVolume?: number;  // 0.0 to 1.0 (default: 1.0)
+  playbackRate?: number;  // 0.5 to 2.0 (default: 1.0)
+}
+
+class MediaElementPlayout {
+  // Lifecycle
+  init(): Promise<void>;  // No-op for media element
+  dispose(): void;
+
+  // Track management
+  addTrack(options: MediaElementTrackOptions): MediaElementTrack;
+  removeTrack(trackId: string): void;
+  getTrack(trackId: string): MediaElementTrack | undefined;
+
+  // Playback
+  play(when?: number, offset?: number, duration?: number): void;
+  pause(): void;
+  stop(): void;
+  seekTo(time: number): void;
+  getCurrentTime(): number;
+
+  // Volume & Rate
+  setMasterVolume(volume: number): void;
+  setPlaybackRate(rate: number): void;  // 0.5 to 2.0, pitch preserved
+
+  // State
+  readonly isPlaying: boolean;
+  readonly duration: number;
+  readonly playbackRate: number;
+}
+```
+
+### MediaElementTrack
+
+```typescript
+interface MediaElementTrackOptions {
+  source: string | HTMLAudioElement;  // URL or audio element
+  peaks: WaveformDataObject;          // Pre-computed peaks
+  id?: string;
+  name?: string;
+  volume?: number;
+  playbackRate?: number;
+}
+```
+
+## Generating Peaks
+
+Use [audiowaveform](https://github.com/bbc/audiowaveform) or [waveform-data.js](https://github.com/bbc/waveform-data.js) to pre-compute peaks:
+
+```bash
+# Generate peaks file with audiowaveform
+audiowaveform -i audio.mp3 -o peaks.dat -b 16
+```
+
+## Browser Support
+
+Pitch-preserving playback rate is supported in:
+- Chrome 77+
+- Firefox 20+
+- Safari 14.1+
+- Edge 79+
+
+Older browsers will still work but may change pitch with speed.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,235 @@
+import { WaveformDataObject } 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;
+    /** Track ID */
+    id?: string;
+    /** Track name for display */
+    name?: string;
+    /** Initial volume (0.0 to 1.0) */
+    volume?: number;
+    /** Initial playback rate (0.5 to 2.0, pitch preserved) */
+    playbackRate?: number;
+}
+/**
+ * Single-track playback using HTMLAudioElement.
+ *
+ * Benefits over AudioBuffer/Tone.js:
+ * - Pitch-preserving playback rate (0.5x - 2.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
+ *
+ * Limitations:
+ * - Single track only (no multi-track mixing)
+ * - No clip-level effects or fades (track-level volume only)
+ * - Relies on browser's time-stretching quality
+ */
+declare class MediaElementTrack {
+    private audioElement;
+    private ownsElement;
+    private _peaks;
+    private _id;
+    private _name;
+    private _playbackRate;
+    private onStopCallback?;
+    private onTimeUpdateCallback?;
+    constructor(options: MediaElementTrackOptions);
+    private handleEnded;
+    private handleTimeUpdate;
+    /**
+     * Start playback from a specific time
+     */
+    play(offset?: number): void;
+    /**
+     * Pause playback
+     */
+    pause(): void;
+    /**
+     * Stop playback and reset to beginning
+     */
+    stop(): void;
+    /**
+     * Seek to a specific time
+     */
+    seekTo(time: number): void;
+    /**
+     * Set volume (0.0 to 1.0)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Set playback rate (0.5 to 2.0, pitch preserved)
+     */
+    setPlaybackRate(rate: number): void;
+    /**
+     * Set muted state
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Set callback for when playback ends
+     */
+    setOnStopCallback(callback: () => void): void;
+    /**
+     * Set callback for time updates
+     */
+    setOnTimeUpdateCallback(callback: (time: number) => void): void;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+    get id(): string;
+    get name(): string;
+    get peaks(): WaveformDataObject;
+    get currentTime(): number;
+    get duration(): number;
+    get isPlaying(): boolean;
+    get volume(): number;
+    get playbackRate(): number;
+    get muted(): boolean;
+    /**
+     * Get the underlying audio element (for advanced use cases)
+     */
+    get element(): HTMLAudioElement;
+}
+
+interface MediaElementPlayoutOptions {
+    /** Initial master volume (0.0 to 1.0) */
+    masterVolume?: number;
+    /** Initial playback rate (0.5 to 2.0) */
+    playbackRate?: number;
+}
+/**
+ * Single-track playout engine using HTMLAudioElement.
+ *
+ * This is a lightweight alternative to TonePlayout for single-track use cases
+ * that need pitch-preserving playback rate control.
+ *
+ * Key features:
+ * - Pitch-preserving playback rate (0.5x - 2.0x)
+ * - Uses pre-computed peaks (no AudioBuffer required)
+ * - Simpler API for single-track playback
+ *
+ * Limitations:
+ * - Single track only - will warn if multiple tracks added
+ * - No clip-level effects or crossfades
+ * - No multi-track mixing
+ *
+ * For multi-track editing, use TonePlayout from @waveform-playlist/playout instead.
+ */
+declare class MediaElementPlayout {
+    private track;
+    private _masterVolume;
+    private _playbackRate;
+    private _isPlaying;
+    private onPlaybackCompleteCallback?;
+    constructor(options?: MediaElementPlayoutOptions);
+    /**
+     * Initialize the playout engine.
+     * For MediaElementPlayout this is a no-op (no AudioContext to start).
+     */
+    init(): Promise<void>;
+    /**
+     * Add a track to the playout.
+     * Note: Only one track is supported. Adding a second track will dispose the first.
+     */
+    addTrack(options: MediaElementTrackOptions): MediaElementTrack;
+    /**
+     * Remove a track by ID.
+     */
+    removeTrack(trackId: string): void;
+    /**
+     * Get a track by ID.
+     */
+    getTrack(trackId: string): MediaElementTrack | undefined;
+    /**
+     * Start playback.
+     * @param _when - Ignored (HTMLAudioElement doesn't support scheduled start)
+     * @param offset - Start position in seconds
+     * @param duration - Duration to play in seconds (optional)
+     */
+    play(_when?: number, offset?: number, duration?: number): void;
+    /**
+     * Pause playback.
+     */
+    pause(): void;
+    /**
+     * Stop playback and reset to start.
+     */
+    stop(): void;
+    /**
+     * Seek to a specific time.
+     */
+    seekTo(time: number): void;
+    /**
+     * Get current playback time.
+     */
+    getCurrentTime(): number;
+    /**
+     * Set master volume.
+     */
+    setMasterVolume(volume: number): void;
+    /**
+     * Set playback rate (0.5 to 2.0, pitch preserved).
+     */
+    setPlaybackRate(rate: number): void;
+    /**
+     * Set mute state for a track.
+     */
+    setMute(trackId: string, muted: boolean): void;
+    /**
+     * Set solo state for a track.
+     * Note: With single track, solo is effectively the same as unmute.
+     */
+    setSolo(_trackId: string, _soloed: boolean): void;
+    /**
+     * Set callback for when playback completes.
+     */
+    setOnPlaybackComplete(callback: () => void): void;
+    /**
+     * Clean up resources.
+     */
+    dispose(): void;
+    get isPlaying(): boolean;
+    get masterVolume(): number;
+    get playbackRate(): number;
+    get duration(): number;
+    get sampleRate(): number;
+}
+
+/**
+ * Common interface for playout engines.
+ *
+ * Both TonePlayout and MediaElementPlayout implement this interface,
+ * allowing the browser package to work with either engine.
+ */
+interface PlayoutEngine {
+    init(): Promise<void>;
+    dispose(): void;
+    play(when?: number, offset?: number, duration?: number): void;
+    pause(): void;
+    stop(): void;
+    seekTo(time: number): void;
+    getCurrentTime(): number;
+    setMasterVolume(volume: number): void;
+    setMute?(trackId: string, muted: boolean): void;
+    setSolo?(trackId: string, soloed: boolean): void;
+    setOnPlaybackComplete(callback: () => void): void;
+    readonly isPlaying: boolean;
+    readonly duration: number;
+    readonly sampleRate: number;
+}
+/**
+ * Extended interface for engines that support playback rate.
+ */
+interface PlaybackRateEngine extends PlayoutEngine {
+    setPlaybackRate(rate: number): void;
+    readonly playbackRate: number;
+}
+/**
+ * Type guard to check if an engine supports playback rate.
+ */
+declare function supportsPlaybackRate(engine: PlayoutEngine): engine is PlaybackRateEngine;
+
+export { MediaElementPlayout, type MediaElementPlayoutOptions, MediaElementTrack, type MediaElementTrackOptions, type PlaybackRateEngine, type PlayoutEngine, supportsPlaybackRate };

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+import { WaveformDataObject } 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;
+    /** Track ID */
+    id?: string;
+    /** Track name for display */
+    name?: string;
+    /** Initial volume (0.0 to 1.0) */
+    volume?: number;
+    /** Initial playback rate (0.5 to 2.0, pitch preserved) */
+    playbackRate?: number;
+}
+/**
+ * Single-track playback using HTMLAudioElement.
+ *
+ * Benefits over AudioBuffer/Tone.js:
+ * - Pitch-preserving playback rate (0.5x - 2.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
+ *
+ * Limitations:
+ * - Single track only (no multi-track mixing)
+ * - No clip-level effects or fades (track-level volume only)
+ * - Relies on browser's time-stretching quality
+ */
+declare class MediaElementTrack {
+    private audioElement;
+    private ownsElement;
+    private _peaks;
+    private _id;
+    private _name;
+    private _playbackRate;
+    private onStopCallback?;
+    private onTimeUpdateCallback?;
+    constructor(options: MediaElementTrackOptions);
+    private handleEnded;
+    private handleTimeUpdate;
+    /**
+     * Start playback from a specific time
+     */
+    play(offset?: number): void;
+    /**
+     * Pause playback
+     */
+    pause(): void;
+    /**
+     * Stop playback and reset to beginning
+     */
+    stop(): void;
+    /**
+     * Seek to a specific time
+     */
+    seekTo(time: number): void;
+    /**
+     * Set volume (0.0 to 1.0)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Set playback rate (0.5 to 2.0, pitch preserved)
+     */
+    setPlaybackRate(rate: number): void;
+    /**
+     * Set muted state
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Set callback for when playback ends
+     */
+    setOnStopCallback(callback: () => void): void;
+    /**
+     * Set callback for time updates
+     */
+    setOnTimeUpdateCallback(callback: (time: number) => void): void;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+    get id(): string;
+    get name(): string;
+    get peaks(): WaveformDataObject;
+    get currentTime(): number;
+    get duration(): number;
+    get isPlaying(): boolean;
+    get volume(): number;
+    get playbackRate(): number;
+    get muted(): boolean;
+    /**
+     * Get the underlying audio element (for advanced use cases)
+     */
+    get element(): HTMLAudioElement;
+}
+
+interface MediaElementPlayoutOptions {
+    /** Initial master volume (0.0 to 1.0) */
+    masterVolume?: number;
+    /** Initial playback rate (0.5 to 2.0) */
+    playbackRate?: number;
+}
+/**
+ * Single-track playout engine using HTMLAudioElement.
+ *
+ * This is a lightweight alternative to TonePlayout for single-track use cases
+ * that need pitch-preserving playback rate control.
+ *
+ * Key features:
+ * - Pitch-preserving playback rate (0.5x - 2.0x)
+ * - Uses pre-computed peaks (no AudioBuffer required)
+ * - Simpler API for single-track playback
+ *
+ * Limitations:
+ * - Single track only - will warn if multiple tracks added
+ * - No clip-level effects or crossfades
+ * - No multi-track mixing
+ *
+ * For multi-track editing, use TonePlayout from @waveform-playlist/playout instead.
+ */
+declare class MediaElementPlayout {
+    private track;
+    private _masterVolume;
+    private _playbackRate;
+    private _isPlaying;
+    private onPlaybackCompleteCallback?;
+    constructor(options?: MediaElementPlayoutOptions);
+    /**
+     * Initialize the playout engine.
+     * For MediaElementPlayout this is a no-op (no AudioContext to start).
+     */
+    init(): Promise<void>;
+    /**
+     * Add a track to the playout.
+     * Note: Only one track is supported. Adding a second track will dispose the first.
+     */
+    addTrack(options: MediaElementTrackOptions): MediaElementTrack;
+    /**
+     * Remove a track by ID.
+     */
+    removeTrack(trackId: string): void;
+    /**
+     * Get a track by ID.
+     */
+    getTrack(trackId: string): MediaElementTrack | undefined;
+    /**
+     * Start playback.
+     * @param _when - Ignored (HTMLAudioElement doesn't support scheduled start)
+     * @param offset - Start position in seconds
+     * @param duration - Duration to play in seconds (optional)
+     */
+    play(_when?: number, offset?: number, duration?: number): void;
+    /**
+     * Pause playback.
+     */
+    pause(): void;
+    /**
+     * Stop playback and reset to start.
+     */
+    stop(): void;
+    /**
+     * Seek to a specific time.
+     */
+    seekTo(time: number): void;
+    /**
+     * Get current playback time.
+     */
+    getCurrentTime(): number;
+    /**
+     * Set master volume.
+     */
+    setMasterVolume(volume: number): void;
+    /**
+     * Set playback rate (0.5 to 2.0, pitch preserved).
+     */
+    setPlaybackRate(rate: number): void;
+    /**
+     * Set mute state for a track.
+     */
+    setMute(trackId: string, muted: boolean): void;
+    /**
+     * Set solo state for a track.
+     * Note: With single track, solo is effectively the same as unmute.
+     */
+    setSolo(_trackId: string, _soloed: boolean): void;
+    /**
+     * Set callback for when playback completes.
+     */
+    setOnPlaybackComplete(callback: () => void): void;
+    /**
+     * Clean up resources.
+     */
+    dispose(): void;
+    get isPlaying(): boolean;
+    get masterVolume(): number;
+    get playbackRate(): number;
+    get duration(): number;
+    get sampleRate(): number;
+}
+
+/**
+ * Common interface for playout engines.
+ *
+ * Both TonePlayout and MediaElementPlayout implement this interface,
+ * allowing the browser package to work with either engine.
+ */
+interface PlayoutEngine {
+    init(): Promise<void>;
+    dispose(): void;
+    play(when?: number, offset?: number, duration?: number): void;
+    pause(): void;
+    stop(): void;
+    seekTo(time: number): void;
+    getCurrentTime(): number;
+    setMasterVolume(volume: number): void;
+    setMute?(trackId: string, muted: boolean): void;
+    setSolo?(trackId: string, soloed: boolean): void;
+    setOnPlaybackComplete(callback: () => void): void;
+    readonly isPlaying: boolean;
+    readonly duration: number;
+    readonly sampleRate: number;
+}
+/**
+ * Extended interface for engines that support playback rate.
+ */
+interface PlaybackRateEngine extends PlayoutEngine {
+    setPlaybackRate(rate: number): void;
+    readonly playbackRate: number;
+}
+/**
+ * Type guard to check if an engine supports playback rate.
+ */
+declare function supportsPlaybackRate(engine: PlayoutEngine): engine is PlaybackRateEngine;
+
+export { MediaElementPlayout, type MediaElementPlayoutOptions, MediaElementTrack, type MediaElementTrackOptions, type PlaybackRateEngine, type PlayoutEngine, supportsPlaybackRate };