wavesurfer.js 7.0.0-alpha.2 → 7.0.0-alpha.21

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:dev
-```
-
-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,12 @@
 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> {
+import WaveSurfer, { type WaveSurferPluginParams } from './index.js';
+export declare class BasePlugin<EventTypes extends GeneralEventTypes, Options> extends EventEmitter<EventTypes> {
     protected wavesurfer: WaveSurfer;
-    protected renderer: WaveSurfer['renderer'];
+    protected container: HTMLElement;
+    protected wrapper: 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

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

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

@@ -0,0 +1,31 @@
+class Decoder {
+    audioCtx = null;
+    initAudioContext(sampleRate) {
+        this.audioCtx = new AudioContext({
+            latencyHint: 'playback',
+            sampleRate,
+        });
+    }
+    constructor() {
+        // 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);
+        }
+    }
+    async decode(audioData) {
+        if (!this.audioCtx) {
+            throw new Error('AudioContext is not initialized');
+        }
+        return this.audioCtx.decodeAudioData(audioData);
+    }
+    destroy() {
+        this.audioCtx?.close();
+        this.audioCtx = null;
+    }
+}
+export default Decoder;

package/dist/event-emitter.d.ts

@@ -6,7 +6,7 @@ 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;
 }

package/dist/event-emitter.js

@@ -0,0 +1,26 @@
+class EventEmitter {
+    eventTarget;
+    constructor() {
+        this.eventTarget = new EventTarget();
+    }
+    emit(eventType, detail) {
+        const e = new CustomEvent(String(eventType), { detail });
+        this.eventTarget.dispatchEvent(e);
+    }
+    /** Subscribe to an event and return a function to unsubscribe */
+    on(eventType, callback, once) {
+        const handler = (e) => {
+            if (e instanceof CustomEvent) {
+                callback(e.detail);
+            }
+        };
+        const eventName = String(eventType);
+        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/fetcher.js

@@ -0,0 +1,6 @@
+class Fetcher {
+    async load(url) {
+        return fetch(url).then((response) => response.arrayBuffer());
+    }
+}
+export default Fetcher;

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,10 @@ export type WaveSurferOptions = {
     waveColor?: string;
     /** The color of the progress mask */
     progressColor?: string;
+    /** The color of the playpack cursor */
+    cursorColor?: string;
+    /** The cursor with */
+    cursorWidth?: number;
     /** If set, the waveform will be rendered in bars like so: ▁ ▂ ▇ ▃ ▅ ▂ */
     barWidth?: number;
     /** Spacing between bars in pixels */
@@ -21,37 +21,65 @@ 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;
+    /** Hide scrollbar **/
+    noScrollbar?: boolean;
+};
+declare const defaultOptions: {
+    height: number;
+    waveColor: string;
+    progressColor: string;
+    cursorWidth: number;
+    minPxPerSec: number;
+    fillParent: boolean;
+    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;
+    };
+    seekClick: {
         currentTime: number;
     };
-    seek: {
-        time: number;
+    zoom: {
+        minPxPerSec: number;
     };
+    destroy: void;
 };
 export type WaveSurferPluginParams = {
     wavesurfer: WaveSurfer;
-    renderer: WaveSurfer['renderer'];
+    container: HTMLElement;
+    wrapper: HTMLElement;
 };
-export declare class WaveSurfer extends EventEmitter<WaveSurferEvents> {
-    private options;
+declare class WaveSurfer extends EventEmitter<WaveSurferEvents> {
+    options: WaveSurferOptions & typeof defaultOptions;
     private fetcher;
     private decoder;
     private renderer;
@@ -59,8 +87,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 +95,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 +112,27 @@ 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, Options>, Options>(CustomPlugin: new (params: WaveSurferPluginParams, options: Options) => T, options: Options): T;
+    /** Get the decoded audio data */
+    getDecodedData(): AudioBuffer | null;
+    /** Get the raw media element */
+    getMediaElement(): HTMLMediaElement | null;
+    /** Toggle if the waveform should react to clicks */
+    toggleInteractive(isInteractive: boolean): void;
+    /** Unmount wavesurfer */
+    destroy(): void;
 }
 export default WaveSurfer;

package/dist/index.js

@@ -0,0 +1,238 @@
+import Fetcher from './fetcher.js';
+import Decoder from './decoder.js';
+import Renderer from './renderer.js';
+import Player from './player.js';
+import EventEmitter from './event-emitter.js';
+import Timer from './timer.js';
+const defaultOptions = {
+    height: 128,
+    waveColor: '#999',
+    progressColor: '#555',
+    cursorWidth: 1,
+    minPxPerSec: 0,
+    fillParent: true,
+    interactive: true,
+};
+class WaveSurfer extends EventEmitter {
+    options;
+    fetcher;
+    decoder;
+    renderer;
+    player;
+    timer;
+    plugins = [];
+    subscriptions = [];
+    decodedData = null;
+    /** Create a new WaveSurfer instance */
+    static create(options) {
+        return new WaveSurfer(options);
+    }
+    /** Create a new WaveSurfer instance */
+    constructor(options) {
+        super();
+        this.options = Object.assign({}, defaultOptions, options);
+        this.fetcher = new Fetcher();
+        this.decoder = new Decoder();
+        this.timer = new Timer();
+        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,
+            cursorWidth: this.options.cursorWidth,
+            minPxPerSec: this.options.minPxPerSec,
+            fillParent: this.options.fillParent,
+            barWidth: this.options.barWidth,
+            barGap: this.options.barGap,
+            barRadius: this.options.barRadius,
+            noScrollbar: this.options.noScrollbar,
+        });
+        this.initPlayerEvents();
+        this.initRendererEvents();
+        this.initTimerEvents();
+        this.initReadyEvent();
+        const url = this.options.url || this.options.media?.src;
+        if (url) {
+            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.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', { duration: this.getDuration() });
+        }), this.player.on('seeking', () => {
+            this.emit('seeking', { currentTime: this.getCurrentTime() });
+        }));
+    }
+    initRendererEvents() {
+        // Seek on click
+        this.subscriptions.push(this.renderer.on('click', ({ relativeX }) => {
+            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', () => {
+            const currentTime = this.getCurrentTime();
+            this.renderer.renderProgress(currentTime / this.getDuration(), true);
+            this.emit('timeupdate', { currentTime });
+        }));
+    }
+    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, with optional pre-decoded audio data */
+    async load(url, channelData, duration) {
+        this.player.loadUrl(url);
+        // Fetch and decode the audio of no pre-computed audio data is provided
+        if (channelData == null) {
+            const audio = await this.fetcher.load(url);
+            const data = await this.decoder.decode(audio);
+            this.decodedData = data;
+        }
+        else {
+            if (!duration) {
+                duration =
+                    (await 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.renderer.render(this.decodedData);
+        this.emit('decode', { duration: this.decodedData.duration });
+    }
+    /** Zoom in or out */
+    zoom(minPxPerSec) {
+        if (!this.decodedData) {
+            throw new Error('No audio loaded');
+        }
+        this.renderer.zoom(this.decodedData, minPxPerSec);
+        this.emit('zoom', { minPxPerSec });
+    }
+    /** Start playing the audio */
+    play() {
+        this.player.play();
+    }
+    /** Pause the audio */
+    pause() {
+        this.player.pause();
+    }
+    /** Skip to a time position in seconds */
+    seekTo(time) {
+        this.player.seekTo(time);
+    }
+    /** Check if the audio is playing */
+    isPlaying() {
+        return this.player.isPlaying();
+    }
+    /** Get the duration of the audio in seconds */
+    getDuration() {
+        return this.player.getDuration() || this.decodedData?.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, options) {
+        const plugin = new CustomPlugin({
+            wavesurfer: this,
+            container: this.renderer.getContainer(),
+            wrapper: this.renderer.getWrapper(),
+        }, options);
+        this.plugins.push(plugin);
+        plugin.once('destroy', () => {
+            this.plugins = this.plugins.filter((p) => p !== plugin);
+        });
+        return plugin;
+    }
+    /** Get the decoded audio data */
+    getDecodedData() {
+        return this.decodedData;
+    }
+    /** Get the raw media element */
+    getMediaElement() {
+        return this.player.getMediaElement();
+    }
+    /** Toggle if the waveform should react to clicks */
+    toggleInteractive(isInteractive) {
+        this.options.interactive = isInteractive;
+    }
+    /** 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.d.ts

@@ -1,10 +1,13 @@
 declare class Player {
     protected media: HTMLMediaElement;
     private isExternalMedia;
-    constructor({ media }: {
+    private hasPlayedOnce;
+    private subscriptions;
+    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 +15,13 @@ 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;
+    getMediaElement(): HTMLMediaElement;
 }
 export default Player;

package/dist/player.js

@@ -0,0 +1,90 @@
+class Player {
+    media;
+    isExternalMedia = false;
+    hasPlayedOnce = false;
+    subscriptions = [];
+    constructor({ media, autoplay }) {
+        if (media) {
+            this.media = media;
+            this.isExternalMedia = true;
+        }
+        else {
+            this.media = document.createElement('audio');
+        }
+        this.subscriptions.push(
+        // Track the first play() call
+        this.on('play', () => {
+            this.hasPlayedOnce = true;
+        }, { once: true }));
+        // Autoplay
+        if (autoplay) {
+            this.media.autoplay = true;
+        }
+    }
+    on(event, callback, options) {
+        this.media.addEventListener(event, callback, options);
+        return () => this.media.removeEventListener(event, callback);
+    }
+    destroy() {
+        this.subscriptions.forEach((unsubscribe) => {
+            unsubscribe();
+        });
+        this.media.pause();
+        if (!this.isExternalMedia) {
+            this.media.remove();
+        }
+    }
+    loadUrl(src) {
+        this.media.src = src;
+    }
+    getCurrentTime() {
+        return this.media.currentTime;
+    }
+    play() {
+        this.media.play();
+    }
+    pause() {
+        this.media.pause();
+    }
+    isPlaying() {
+        return this.media.currentTime > 0 && !this.media.paused && !this.media.ended;
+    }
+    seekTo(time) {
+        // iOS Safari requires a play() call before seeking
+        if (!this.hasPlayedOnce && navigator.userAgent.match(/(iPad|iPhone|iPod)/g)) {
+            this.media.play()?.then?.(() => {
+                setTimeout(() => this.media.pause(), 10);
+            });
+        }
+        this.media.currentTime = time;
+    }
+    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;
+    }
+    getMediaElement() {
+        return this.media;
+    }
+}
+export default Player;