wavesurfer.js 7.0.0-alpha.0 → 7.0.0-alpha.10

package/README.md

@@ -1,7 +1,14 @@
-# wavesurfer.ts
+# <img src="https://user-images.githubusercontent.com/381895/226091100-f5567a28-7736-4d37-8f84-e08f297b7e1a.png" alt="logo" height="60" valign="middle" /> wavesurfer.ts
 
 An experimental rewrite of [wavesufer.js](https://github.com/wavesurfer-js/wavesurfer.js) to play around with new ideas.
 
+<img alt="screenshot" src="https://user-images.githubusercontent.com/381895/225539680-fc724acd-8657-458e-a558-ff1c6758ba30.png" width="800" />
+
+Try it out:
+```
+npm install --save wavesurfer.js@alpha
+```
+
 ## Goals
 
  * TypeScript API
@@ -17,11 +24,9 @@ Keeping backwards compatibility with earlier versions of wavesurfer.js.
 
 Principles:
  * Modular and event-driven
- * Allow swapping the decoding, rendering and playback mechanisms
+ * Flexible (e.g. allow custom media elements and user-defined Web Audio graphs)
  * Extensible with plugins
 
-![diagram](https://user-images.githubusercontent.com/381895/222349436-38b550e5-24dc-4143-9cdb-efbe00540213.png)
-
 ## Development
 
 Install dev dependencies:
@@ -30,21 +35,14 @@ Install dev dependencies:
 yarn
 ```
 
-Start the TypeScript compiler in watch mode:
-
-```
-yarn build -w
-```
-
-Run an HTTP server to view the examples:
+Start the TypeScript compiler in watch mode and an HTTP server:
 
 ```
-python3 -m http.server --cgi 8080
+yarn start
 ```
 
-Open http://localhost:8080/examples/basic/ in your browser.
-There's no hot reload yet, so you'll need to reload the page manually on every change.
+This will open http://localhost:9090/tutorial in your browser with live reload.
 
 ## Feedback
 
-See https://github.com/wavesurfer-js/wavesurfer.js/discussions/2684
+Your feedback is very welcome here: https://github.com/wavesurfer-js/wavesurfer.js/discussions/2684

package/dist/base-plugin.d.ts

@@ -1,10 +1,11 @@
 import EventEmitter, { type GeneralEventTypes } from './event-emitter.js';
 import type { WaveSurfer, WaveSurferPluginParams } from './index.js';
-export declare class BasePlugin<EventTypes extends GeneralEventTypes> extends EventEmitter<EventTypes> {
+export declare class BasePlugin<EventTypes extends GeneralEventTypes, Options> extends EventEmitter<EventTypes> {
     protected wavesurfer: WaveSurfer;
-    protected renderer: WaveSurfer['renderer'];
+    protected container: HTMLElement;
     protected subscriptions: (() => void)[];
-    constructor(params: WaveSurferPluginParams);
+    protected options: Options;
+    constructor(params: WaveSurferPluginParams, options: Options);
     destroy(): void;
 }
 export default BasePlugin;

package/dist/base-plugin.js

@@ -1,10 +1,11 @@
 import EventEmitter from './event-emitter.js';
 export class BasePlugin extends EventEmitter {
-    constructor(params) {
+    constructor(params, options) {
         super();
         this.subscriptions = [];
         this.wavesurfer = params.wavesurfer;
-        this.renderer = params.renderer;
+        this.container = params.container;
+        this.options = options;
     }
     destroy() {
         this.subscriptions.forEach((unsubscribe) => unsubscribe());

package/dist/decoder.d.ts

@@ -1,10 +1,8 @@
 declare class Decoder {
     audioCtx: AudioContext | null;
+    private initAudioContext;
     constructor();
-    decode(audioData: ArrayBuffer): Promise<{
-        duration: number;
-        channelData: Float32Array[];
-    }>;
+    decode(audioData: ArrayBuffer): Promise<AudioBuffer>;
     destroy(): void;
 }
 export default Decoder;

package/dist/decoder.js

@@ -7,31 +7,31 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-// Web Audio decodeAudioData with a minimum allowed sample rate
-const SAMPLE_RATE = 3000;
 class Decoder {
-    constructor() {
-        this.audioCtx = null;
-        this.audioCtx = new (window.AudioContext ||
-            window.webkitAudioContext)({
+    initAudioContext(sampleRate) {
+        this.audioCtx = new AudioContext({
             latencyHint: 'playback',
-            sampleRate: SAMPLE_RATE,
+            sampleRate,
         });
     }
+    constructor() {
+        this.audioCtx = null;
+        // Minimum sample rate supported by Web Audio API
+        const DEFAULT_SAMPLE_RATE = 3000; // Chrome, Safari
+        const FALLBACK_SAMPLE_RATE = 8000; // Firefox
+        try {
+            this.initAudioContext(DEFAULT_SAMPLE_RATE);
+        }
+        catch (e) {
+            this.initAudioContext(FALLBACK_SAMPLE_RATE);
+        }
+    }
     decode(audioData) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.audioCtx) {
                 throw new Error('AudioContext is not initialized');
             }
-            const buffer = yield this.audioCtx.decodeAudioData(audioData);
-            const channelData = [buffer.getChannelData(0)];
-            if (buffer.numberOfChannels > 1) {
-                channelData.push(buffer.getChannelData(1));
-            }
-            return {
-                duration: buffer.duration,
-                channelData,
-            };
+            return this.audioCtx.decodeAudioData(audioData);
         });
     }
     destroy() {

package/dist/event-emitter.d.ts

@@ -6,6 +6,8 @@ declare class EventEmitter<EventTypes extends GeneralEventTypes> {
     constructor();
     protected emit<T extends keyof EventTypes>(eventType: T, detail?: EventTypes[T]): void;
     /** Subscribe to an event and return a function to unsubscribe */
-    on<T extends keyof EventTypes>(eventType: T, callback: (detail: EventTypes[T]) => void): () => void;
+    on<T extends keyof EventTypes>(eventType: T, callback: (detail: EventTypes[T]) => void, once?: boolean): () => void;
+    /** Subscribe to an event once and return a function to unsubscribe */
+    once<T extends keyof EventTypes>(eventType: T, callback: (detail: EventTypes[T]) => void): () => void;
 }
 export default EventEmitter;

package/dist/event-emitter.js

@@ -7,15 +7,19 @@ class EventEmitter {
         this.eventTarget.dispatchEvent(e);
     }
     /** Subscribe to an event and return a function to unsubscribe */
-    on(eventType, callback) {
+    on(eventType, callback, once) {
         const handler = (e) => {
             if (e instanceof CustomEvent) {
                 callback(e.detail);
             }
         };
         const eventName = String(eventType);
-        this.eventTarget.addEventListener(eventName, handler);
+        this.eventTarget.addEventListener(eventName, handler, { once });
         return () => this.eventTarget.removeEventListener(eventName, handler);
     }
+    /** Subscribe to an event once and return a function to unsubscribe */
+    once(eventType, callback) {
+        return this.on(eventType, callback, true);
+    }
 }
 export default EventEmitter;

package/dist/index.d.ts

@@ -1,9 +1,5 @@
 import EventEmitter, { type GeneralEventTypes } from './event-emitter.js';
 import BasePlugin from './base-plugin.js';
-export declare enum PlayerType {
-    WebAudio = "WebAudio",
-    MediaElement = "MediaElement"
-}
 export type WaveSurferOptions = {
     /** HTML element or CSS selector */
     container: HTMLElement | string | null;
@@ -13,6 +9,8 @@ export type WaveSurferOptions = {
     waveColor?: string;
     /** The color of the progress mask */
     progressColor?: string;
+    /** The color of the playpack cursort */
+    cursorColor?: string;
     /** If set, the waveform will be rendered in bars like so: ▁ ▂ ▇ ▃ ▅ ▂ */
     barWidth?: number;
     /** Spacing between bars in pixels */
@@ -21,34 +19,47 @@ export type WaveSurferOptions = {
     barRadius?: number;
     /** Minimum pixels per second of audio (zoom) */
     minPxPerSec?: number;
+    /** Stretch the waveform to fill the container, true by default */
+    fillParent?: boolean;
     /** Audio URL */
     url?: string;
     /** Pre-computed audio data */
-    channelData?: Float32Array[];
+    peaks?: Float32Array[];
     /** Pre-computed duration */
     duration?: number;
-    /** Player "backend", the default is MediaElement  */
-    backend?: PlayerType;
     /** Use an existing media element instead of creating one */
     media?: HTMLMediaElement;
+    /** Play the audio on load */
+    autoplay?: boolean;
+    /** Is the waveform clickable? */
+    interactive?: boolean;
 };
 export type WaveSurferEvents = {
+    decode: {
+        duration: number;
+    };
+    canplay: {
+        duration: number;
+    };
     ready: {
         duration: number;
     };
-    canplay: void;
     play: void;
     pause: void;
-    audioprocess: {
+    timeupdate: {
+        currentTime: number;
+    };
+    seeking: {
         currentTime: number;
     };
-    seek: {
-        time: number;
+    seekClick: {
+        currentTime: number;
     };
+    destroy: void;
 };
 export type WaveSurferPluginParams = {
     wavesurfer: WaveSurfer;
-    renderer: WaveSurfer['renderer'];
+    container: HTMLElement;
 };
 export declare class WaveSurfer extends EventEmitter<WaveSurferEvents> {
     private options;
@@ -59,8 +70,7 @@ export declare class WaveSurfer extends EventEmitter<WaveSurferEvents> {
     private timer;
     private plugins;
     private subscriptions;
-    private channelData;
-    private duration;
+    private decodedData;
     /** Create a new WaveSurfer instance */
     static create(options: WaveSurferOptions): WaveSurfer;
     /** Create a new WaveSurfer instance */
@@ -68,9 +78,8 @@ export declare class WaveSurfer extends EventEmitter<WaveSurferEvents> {
     private initPlayerEvents;
     private initRendererEvents;
     private initTimerEvents;
-    /** Unmount wavesurfer */
-    destroy(): void;
-    /** Load an audio file by URL */
+    private initReadyEvent;
+    /** Load an audio file by URL, with optional pre-decoded audio data */
     load(url: string, channelData?: Float32Array[], duration?: number): Promise<void>;
     /** Zoom in or out */
     zoom(minPxPerSec: number): void;
@@ -86,7 +95,23 @@ export declare class WaveSurfer extends EventEmitter<WaveSurferEvents> {
     getDuration(): number;
     /** Get the current audio position in seconds */
     getCurrentTime(): number;
+    /** Get the audio volume */
+    getVolume(): number;
+    /** Set the audio volume */
+    setVolume(volume: number): void;
+    /** Get the audio muted state */
+    getMuted(): boolean;
+    /** Mute or unmute the audio */
+    setMuted(muted: boolean): void;
+    /** Get playback rate */
+    getPlaybackRate(): number;
+    /** Set playback rate, with an optional parameter to NOT preserve the pitch if false */
+    setPlaybackRate(rate: number, preservePitch?: boolean): void;
     /** Register and initialize a plugin */
-    registerPlugin<T extends BasePlugin<GeneralEventTypes>>(CustomPlugin: new (params: WaveSurferPluginParams) => T): T;
+    registerPlugin<T extends BasePlugin<GeneralEventTypes, any>>(CustomPlugin: new (params: WaveSurferPluginParams, options: any) => T, options?: any): T;
+    /** Get the decoded audio data */
+    getDecodedData(): AudioBuffer | null;
+    /** Unmount wavesurfer */
+    destroy(): void;
 }
 export default WaveSurfer;

package/dist/index.js

@@ -11,20 +11,15 @@ import Fetcher from './fetcher.js';
 import Decoder from './decoder.js';
 import Renderer from './renderer.js';
 import Player from './player.js';
-import WebAudioPlayer from './player-webaudio.js';
 import EventEmitter from './event-emitter.js';
 import Timer from './timer.js';
-export var PlayerType;
-(function (PlayerType) {
-    PlayerType["WebAudio"] = "WebAudio";
-    PlayerType["MediaElement"] = "MediaElement";
-})(PlayerType || (PlayerType = {}));
 const defaultOptions = {
     height: 128,
     waveColor: '#999',
     progressColor: '#555',
     minPxPerSec: 0,
-    backend: 'MediaElement',
+    fillParent: true,
+    interactive: true,
 };
 export class WaveSurfer extends EventEmitter {
     /** Create a new WaveSurfer instance */
@@ -37,21 +32,23 @@ export class WaveSurfer extends EventEmitter {
         super();
         this.plugins = [];
         this.subscriptions = [];
-        this.channelData = null;
-        this.duration = 0;
+        this.decodedData = null;
         this.options = Object.assign({}, defaultOptions, options);
         this.fetcher = new Fetcher();
         this.decoder = new Decoder();
         this.timer = new Timer();
-        this.player = new (this.options.backend === PlayerType.WebAudio ? WebAudioPlayer : Player)({
+        this.player = new Player({
             media: this.options.media,
+            autoplay: this.options.autoplay,
         });
         this.renderer = new Renderer({
             container: this.options.container,
             height: this.options.height,
             waveColor: this.options.waveColor,
             progressColor: this.options.progressColor,
+            cursorColor: this.options.cursorColor,
             minPxPerSec: this.options.minPxPerSec,
+            fillParent: this.options.fillParent,
             barWidth: this.options.barWidth,
             barGap: this.options.barGap,
             barRadius: this.options.barRadius,
@@ -59,75 +56,100 @@ export class WaveSurfer extends EventEmitter {
         this.initPlayerEvents();
         this.initRendererEvents();
         this.initTimerEvents();
+        this.initReadyEvent();
         const url = this.options.url || ((_a = this.options.media) === null || _a === void 0 ? void 0 : _a.src);
         if (url) {
-            this.load(url, this.options.channelData, this.options.duration);
+            this.load(url, this.options.peaks, this.options.duration);
         }
     }
     initPlayerEvents() {
         this.subscriptions.push(this.player.on('timeupdate', () => {
             const currentTime = this.getCurrentTime();
-            this.renderer.renderProgress(currentTime / this.duration, this.isPlaying());
-            this.emit('audioprocess', { currentTime });
+            this.renderer.renderProgress(currentTime / this.getDuration(), this.isPlaying());
+            this.emit('timeupdate', { currentTime });
         }), this.player.on('play', () => {
             this.emit('play');
+            this.timer.start();
         }), this.player.on('pause', () => {
             this.emit('pause');
+            this.timer.stop();
         }), this.player.on('canplay', () => {
-            this.emit('canplay');
+            this.emit('canplay', { duration: this.getDuration() });
         }), this.player.on('seeking', () => {
-            this.emit('seek', { time: this.getCurrentTime() });
+            this.emit('seeking', { currentTime: this.getCurrentTime() });
         }));
     }
     initRendererEvents() {
         // Seek on click
         this.subscriptions.push(this.renderer.on('click', ({ relativeX }) => {
-            const time = this.getDuration() * relativeX;
-            this.seekTo(time);
+            if (this.options.interactive) {
+                const time = this.getDuration() * relativeX;
+                this.seekTo(time);
+                this.emit('seekClick', { currentTime: this.getCurrentTime() });
+            }
         }));
     }
     initTimerEvents() {
         // The timer fires every 16ms for a smooth progress animation
         this.subscriptions.push(this.timer.on('tick', () => {
-            if (this.isPlaying()) {
-                const currentTime = this.getCurrentTime();
-                this.renderer.renderProgress(currentTime / this.duration, true);
-                this.emit('audioprocess', { currentTime });
-            }
+            const currentTime = this.getCurrentTime();
+            this.renderer.renderProgress(currentTime / this.getDuration(), true);
+            this.emit('timeupdate', { currentTime });
         }));
     }
-    /** Unmount wavesurfer */
-    destroy() {
-        this.subscriptions.forEach((unsubscribe) => unsubscribe());
-        this.plugins.forEach((plugin) => plugin.destroy());
-        this.timer.destroy();
-        this.player.destroy();
-        this.decoder.destroy();
-        this.renderer.destroy();
+    initReadyEvent() {
+        let isDecoded = false;
+        let isPlayable = false;
+        const emitReady = () => {
+            if (isDecoded && isPlayable) {
+                this.emit('ready', { duration: this.getDuration() });
+            }
+        };
+        this.subscriptions.push(this.on('decode', () => {
+            isDecoded = true;
+            emitReady();
+        }), this.on('canplay', () => {
+            isPlayable = true;
+            emitReady();
+        }), this.player.on('waiting', () => {
+            isPlayable = false;
+            isDecoded = false;
+        }));
     }
-    /** Load an audio file by URL */
+    /** Load an audio file by URL, with optional pre-decoded audio data */
     load(url, channelData, duration) {
         return __awaiter(this, void 0, void 0, function* () {
             this.player.loadUrl(url);
             // Fetch and decode the audio of no pre-computed audio data is provided
-            if (channelData == null || duration == null) {
+            if (channelData == null) {
                 const audio = yield this.fetcher.load(url);
                 const data = yield this.decoder.decode(audio);
-                channelData = data.channelData;
-                duration = data.duration;
+                this.decodedData = data;
+            }
+            else {
+                if (!duration) {
+                    duration =
+                        (yield new Promise((resolve) => {
+                            this.player.on('canplay', () => resolve(this.getDuration()), { once: true });
+                        })) || 0;
+                }
+                this.decodedData = {
+                    duration,
+                    numberOfChannels: channelData.length,
+                    sampleRate: channelData[0].length / duration,
+                    getChannelData: (i) => channelData[i],
+                };
             }
-            this.channelData = channelData;
-            this.duration = duration;
-            this.renderer.render(this.channelData, this.duration);
-            this.emit('ready', { duration: this.duration });
+            this.renderer.render(this.decodedData);
+            this.emit('decode', { duration: this.decodedData.duration });
         });
     }
     /** Zoom in or out */
     zoom(minPxPerSec) {
-        if (this.channelData == null || this.duration == null) {
+        if (!this.decodedData) {
             throw new Error('No audio loaded');
         }
-        this.renderer.render(this.channelData, this.duration, minPxPerSec);
+        this.renderer.zoom(this.decodedData, minPxPerSec);
     }
     /** Start playing the audio */
     play() {
@@ -147,20 +169,59 @@ export class WaveSurfer extends EventEmitter {
     }
     /** Get the duration of the audio in seconds */
     getDuration() {
-        return this.duration;
+        var _a;
+        return this.player.getDuration() || ((_a = this.decodedData) === null || _a === void 0 ? void 0 : _a.duration) || 0;
     }
     /** Get the current audio position in seconds */
     getCurrentTime() {
         return this.player.getCurrentTime();
     }
+    /** Get the audio volume */
+    getVolume() {
+        return this.player.getVolume();
+    }
+    /** Set the audio volume */
+    setVolume(volume) {
+        this.player.setVolume(volume);
+    }
+    /** Get the audio muted state */
+    getMuted() {
+        return this.player.getMuted();
+    }
+    /** Mute or unmute the audio */
+    setMuted(muted) {
+        this.player.setMuted(muted);
+    }
+    /** Get playback rate */
+    getPlaybackRate() {
+        return this.player.getPlaybackRate();
+    }
+    /** Set playback rate, with an optional parameter to NOT preserve the pitch if false */
+    setPlaybackRate(rate, preservePitch) {
+        this.player.setPlaybackRate(rate, preservePitch);
+    }
     /** Register and initialize a plugin */
-    registerPlugin(CustomPlugin) {
+    registerPlugin(CustomPlugin, options) {
         const plugin = new CustomPlugin({
             wavesurfer: this,
-            renderer: this.renderer,
-        });
+            container: this.renderer.getContainer(),
+        }, options);
         this.plugins.push(plugin);
         return plugin;
     }
+    /** Get the decoded audio data */
+    getDecodedData() {
+        return this.decodedData;
+    }
+    /** Unmount wavesurfer */
+    destroy() {
+        this.emit('destroy');
+        this.subscriptions.forEach((unsubscribe) => unsubscribe());
+        this.plugins.forEach((plugin) => plugin.destroy());
+        this.timer.destroy();
+        this.player.destroy();
+        this.decoder.destroy();
+        this.renderer.destroy();
+    }
 }
 export default WaveSurfer;

package/dist/player-webaudio.js

@@ -16,16 +16,17 @@ class WebAudioPlayer extends Player {
     loadUrl(url) {
         super.loadUrl(url);
         if (!this.audioCtx) {
-            this.audioCtx = new (window.AudioContext ||
-                window.webkitAudioContext)({
+            this.audioCtx = new AudioContext({
                 latencyHint: 'playback',
             });
         }
         if (this.sourceNode) {
             this.sourceNode.disconnect();
         }
-        this.sourceNode = this.audioCtx.createMediaElementSource(this.media);
-        this.sourceNode.connect(this.audioCtx.destination);
+        if (this.media) {
+            this.sourceNode = this.audioCtx.createMediaElementSource(this.media);
+            this.sourceNode.connect(this.audioCtx.destination);
+        }
     }
 }
 export default WebAudioPlayer;

package/dist/player.d.ts

@@ -1,10 +1,12 @@
 declare class Player {
     protected media: HTMLMediaElement;
     private isExternalMedia;
-    constructor({ media }: {
+    private hasPlayedOnce;
+    constructor({ media, autoplay }: {
         media?: HTMLMediaElement;
+        autoplay?: boolean;
     });
-    on(event: keyof HTMLMediaElementEventMap, callback: () => void): () => void;
+    on(event: keyof HTMLMediaElementEventMap, callback: () => void, options?: AddEventListenerOptions): () => void;
     destroy(): void;
     loadUrl(src: string): void;
     getCurrentTime(): number;
@@ -12,5 +14,12 @@ declare class Player {
     pause(): void;
     isPlaying(): boolean;
     seekTo(time: number): void;
+    getDuration(): number;
+    getVolume(): number;
+    setVolume(volume: number): void;
+    getMuted(): boolean;
+    setMuted(muted: boolean): void;
+    getPlaybackRate(): number;
+    setPlaybackRate(rate: number, preservePitch?: boolean): void;
 }
 export default Player;

package/dist/player.js

@@ -1,6 +1,7 @@
 class Player {
-    constructor({ media }) {
+    constructor({ media, autoplay }) {
         this.isExternalMedia = false;
+        this.hasPlayedOnce = false;
         if (media) {
             this.media = media;
             this.isExternalMedia = true;
@@ -8,12 +9,22 @@ class Player {
         else {
             this.media = document.createElement('audio');
         }
+        // Track the first play() call
+        const unsubscribe = this.on('play', () => {
+            this.hasPlayedOnce = true;
+            unsubscribe();
+        });
+        // Autoplay
+        if (autoplay) {
+            this.media.autoplay = true;
+        }
     }
-    on(event, callback) {
-        this.media.addEventListener(event, callback);
+    on(event, callback, options) {
+        this.media.addEventListener(event, callback, options);
         return () => this.media.removeEventListener(event, callback);
     }
     destroy() {
+        this.media.pause();
         if (!this.isExternalMedia) {
             this.media.remove();
         }
@@ -34,7 +45,42 @@ class Player {
         return this.media.currentTime > 0 && !this.media.paused && !this.media.ended;
     }
     seekTo(time) {
-        this.media.currentTime = time;
+        if (this.media) {
+            // iOS Safari requires a play() call before seeking
+            const { hasPlayedOnce } = this;
+            if (!hasPlayedOnce) {
+                this.media.play();
+            }
+            this.media.currentTime = time;
+            if (!hasPlayedOnce) {
+                this.media.pause();
+            }
+        }
+    }
+    getDuration() {
+        return this.media.duration;
+    }
+    getVolume() {
+        return this.media.volume;
+    }
+    setVolume(volume) {
+        this.media.volume = volume;
+    }
+    getMuted() {
+        return this.media.muted;
+    }
+    setMuted(muted) {
+        this.media.muted = muted;
+    }
+    getPlaybackRate() {
+        return this.media.playbackRate;
+    }
+    setPlaybackRate(rate, preservePitch) {
+        // preservePitch is true by default in most browsers
+        if (preservePitch != null) {
+            this.media.preservesPitch = preservePitch;
+        }
+        this.media.playbackRate = rate;
     }
 }
 export default Player;