wavesurfer.js 7.0.0-alpha.4 → 7.0.0-alpha.41

package/README.md

@@ -1,43 +1,90 @@
 # <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.
+A rewrite of [wavesufer.js](https://github.com/wavesurfer-js/wavesurfer.js) in TypeScript with better performance.
 
 <img alt="screenshot" src="https://user-images.githubusercontent.com/381895/225539680-fc724acd-8657-458e-a558-ff1c6758ba30.png" width="800" />
 
-## Goals
+Try it out:
+```
+npm install --save wavesurfer.js@alpha
+```
+
+Import like this:
+
+```
+import WaveSurfer from 'wavesurfer.js'
+```
+
+To import a plugin, e.g. the Timeline plugin:
+```
+import Timeline from 'wavesurfer.js/dist/plugins/timeline'
+```
+
+TypeScript types are included in the package, so there's no need to install `@types/wavesurfer.js`.
 
- * TypeScript API
- * Better architecture
- * Minimize the available options and provide sensible defaults
- * Improve the decoding and rendering performance
+## Why upgrade to wavesurfer.ts?
 
-## Non-goals
+wavesurfer.js v7 (aka wavesurfer.ts) brings several improvements:
 
-Keeping backwards compatibility with earlier versions of wavesurfer.js.
+ * Typed API for better development experience
+ * Enhanced decoding and rendering performance
+ * New and improved plugins
 
-## Architecture
+## Plugins
+The "official" plugins have been completely rewritten and enhanced:
 
-Principles:
- * Modular and event-driven
- * Flexible (e.g. allow custom media elements and user-defined Web Audio graphs)
- * Extensible with plugins
+ * [Regions](https://wavesurfer-ts.pages.dev/tutorial/#/examples/regions.js) – now also replaces the old Markers plugin
+ * [Timeline](https://wavesurfer-ts.pages.dev/tutorial/#/examples/timeline.js) – displays notches and time labels below the waveform
+ * [Minimap](https://wavesurfer-ts.pages.dev/tutorial/#/examples/minimap.js) – a small waveform that serves as a scrollbar for the main waveform
+ * [Envelope](https://wavesurfer-ts.pages.dev/tutorial/#/examples/envelope.js) – a graphical interface to add fade-in and -out effects and control volume
+ * [Record](https://wavesurfer-ts.pages.dev/tutorial/#/examples/record.js) – records audio from the microphone and renders a waveform
+
+## Documentation
+See the documentation on wavesurfer.js [methods](https://wavesurfer-ts.pages.dev/docs/classes/wavesurfer.WaveSurfer), [options](https://wavesurfer-ts.pages.dev/docs/types/wavesurfer.WaveSurferOptions) and [events](https://wavesurfer-ts.pages.dev/docs/types/wavesurfer.WaveSurferEvents) on our website.
+
+## Migrating from v6 and lower
+
+Most options, events, and methods are similar to those in previous versions.
+
+### Notable differences
+ * The `backend` option is removed – HTML5 audio (or video) is the only playback mechanism. However, you can still connect wavesurfer to Web Audio via `MediaElementSourceNode`. See this [example](https://wavesurfer-ts.pages.dev/tutorial/#/examples/webaudio.js).
+ * The Markers plugin is removed – use the Regions plugin with `startTime` equal to `endTime`.
+ * No Microphone plugn – superseded by the new Record plugin with more features.
+ * No Spectrogram, Cursor and Playhead plugins yet – to be done.
+
+### Removed methods
+ * `getFilters`, `setFilter` – as there's no Web Audio "backend"
+ * `cancelAjax` – ajax is replaced by `fetch`
+ * `loadBlob` – use `URL.createObjectURL()` to convert a blob to a URL and call `load(url)` instead
+ * `skipForward`, `skipBackward`, `setPlayEnd` – can be implemented using `setTime(time)`
+ * `exportPCM` is renamed to `getDecodedData` and doesn't take any params
+ * `toggleMute` is now called `setMuted(true | false)`
+ * `setHeight`, `setWaveColor`, `setCursorColor`, etc. – use `setOptions` with the corresponding params instead. E.g., `wavesurfer.setOptions({ height: 300, waveColor: '#abc' })`
+
+See the complete [documentation of the new API](https://wavesurfer-ts.pages.dev/docs/classes/wavesurfer.WaveSurfer).
 
 ## Development
 
-Install dev dependencies:
+To get started with development, follow these steps:
+
+ 1. Install dev dependencies:
 
 ```
 yarn
 ```
 
-Start the TypeScript compiler in watch mode and an HTTP server:
+ 2. Start the TypeScript compiler in watch mode and launch an HTTP server:
 
 ```
 yarn start
 ```
 
-This will open http://localhost:9090/tutorial in your browser with live reload.
+This command will open http://localhost:9090/tutorial in your browser with live reload, allowing you to see the changes as you develop.
 
 ## Feedback
 
-Your feedback is very welcome here: https://github.com/wavesurfer-js/wavesurfer.js/discussions/2684
+We appreciate your feedback and contributions! Join the conversation and share your thoughts here: https://github.com/wavesurfer-js/wavesurfer.js/discussions/2684
+
+If you encounter any issues or have suggestions for improvements, please don't hesitate to open an issue or submit a pull request on the GitHub repository.
+
+We hope you enjoy using wavesurfer.ts and look forward to hearing about your experiences with the library!

package/dist/base-plugin.d.ts

@@ -1,10 +1,19 @@
 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> {
-    protected wavesurfer: WaveSurfer;
-    protected container: HTMLElement;
+import type WaveSurfer from './wavesurfer.js';
+export type GenericPlugin = BasePlugin<GeneralEventTypes, unknown>;
+export type WaveSurferPluginParams = {
+    wavesurfer: WaveSurfer;
+    container: HTMLElement;
+    wrapper: HTMLElement;
+};
+export declare class BasePlugin<EventTypes extends GeneralEventTypes, Options> extends EventEmitter<EventTypes> {
+    protected wavesurfer?: WaveSurfer;
+    protected container?: HTMLElement;
+    protected wrapper?: HTMLElement;
     protected subscriptions: (() => void)[];
-    constructor(params: WaveSurferPluginParams);
+    protected options: Options;
+    constructor(options: Options);
+    init(params: WaveSurferPluginParams): void;
     destroy(): void;
 }
 export default BasePlugin;

package/dist/base-plugin.js

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

package/dist/decoder.d.ts

@@ -1,11 +1,9 @@
-declare class Decoder {
-    audioCtx: AudioContext | null;
-    private initAudioContext;
-    constructor();
-    decode(audioData: ArrayBuffer): Promise<{
-        duration: number;
-        channelData: Float32Array[];
-    }>;
-    destroy(): void;
-}
+/** Decode an array buffer into an audio buffer */
+declare function decode(audioData: ArrayBuffer): Promise<AudioBuffer>;
+/** Create an audio buffer from pre-decoded audio data */
+declare function createBuffer(channelData: Float32Array[] | Array<number[]>, duration: number): AudioBuffer;
+declare const Decoder: {
+    decode: typeof decode;
+    createBuffer: typeof createBuffer;
+};
 export default Decoder;

package/dist/decoder.js

@@ -1,51 +1,44 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-class Decoder {
-    initAudioContext(sampleRate) {
-        this.audioCtx = new AudioContext({
-            latencyHint: 'playback',
-            sampleRate,
+/** Decode an array buffer into an audio buffer */
+async function decode(audioData) {
+    const DEFAULT_SAMPLE_RATE = 8000; // All user agents are required to support a range of 8000Hz to 96000Hz
+    const MIN_SAMPLE_RATE = 3000; // Chrome, Safari can do 3kHz
+    let audioCtx;
+    try {
+        audioCtx = new AudioContext({
+            sampleRate: MIN_SAMPLE_RATE,
         });
     }
-    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,
-            };
+    catch (_) {
+        audioCtx = new AudioContext({
+            sampleRate: DEFAULT_SAMPLE_RATE,
         });
     }
-    destroy() {
-        var _a;
-        (_a = this.audioCtx) === null || _a === void 0 ? void 0 : _a.close();
-        this.audioCtx = null;
+    const decode = audioCtx.decodeAudioData(audioData);
+    decode.finally(() => audioCtx.close());
+    return decode;
+}
+/** Create an audio buffer from pre-decoded audio data */
+function createBuffer(channelData, duration) {
+    // If a single array of numbers is passed, make it an array of arrays
+    if (typeof channelData[0] === 'number')
+        channelData = [channelData];
+    // Normalize to -1..1
+    if (channelData[0].some((n) => n > 1 || n < -1)) {
+        const max = Math.max(...channelData[0]);
+        channelData = channelData.map((channel) => channel.map((n) => n / max));
     }
+    return {
+        length: channelData[0].length,
+        duration,
+        numberOfChannels: channelData.length,
+        sampleRate: channelData[0].length / duration,
+        getChannelData: (i) => channelData?.[i],
+        copyFromChannel: AudioBuffer.prototype.copyFromChannel,
+        copyToChannel: AudioBuffer.prototype.copyToChannel,
+    };
 }
+const Decoder = {
+    decode,
+    createBuffer,
+};
 export default Decoder;

package/dist/event-emitter.d.ts

@@ -1,13 +1,19 @@
-export interface GeneralEventTypes {
-    [eventType: string]: unknown;
-}
+export type GeneralEventTypes = {
+    [EventName: string]: any[];
+};
+type EventListener<EventTypes extends GeneralEventTypes, EventName extends keyof EventTypes> = (...args: EventTypes[EventName]) => void;
+/** A simple event emitter that can be used to listen to and emit events. */
 declare class EventEmitter<EventTypes extends GeneralEventTypes> {
-    private eventTarget;
-    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, 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;
+    private listeners;
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<EventName extends keyof EventTypes>(eventName: EventName, listener: EventListener<EventTypes, EventName>): () => void;
+    /** Subscribe to an event only once */
+    once<EventName extends keyof EventTypes>(eventName: EventName, listener: EventListener<EventTypes, EventName>): () => void;
+    /** Unsubscribe from an event */
+    un<EventName extends keyof EventTypes>(eventName: EventName, listener: EventListener<EventTypes, EventName>): void;
+    /** Clear all events */
+    unAll(): void;
+    /** Emit an event */
+    protected emit<EventName extends keyof EventTypes>(eventName: EventName, ...args: EventTypes[EventName]): void;
 }
 export default EventEmitter;

package/dist/event-emitter.js

@@ -1,25 +1,47 @@
+/** A simple event emitter that can be used to listen to and emit events. */
 class EventEmitter {
     constructor() {
-        this.eventTarget = new EventTarget();
+        this.listeners = {};
     }
-    emit(eventType, detail) {
-        const e = new CustomEvent(String(eventType), { detail });
-        this.eventTarget.dispatchEvent(e);
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on(eventName, listener) {
+        if (!this.listeners[eventName]) {
+            this.listeners[eventName] = new Set();
+        }
+        this.listeners[eventName].add(listener);
+        return () => this.un(eventName, listener);
     }
-    /** Subscribe to an event and return a function to unsubscribe */
-    on(eventType, callback, once) {
-        const handler = (e) => {
-            if (e instanceof CustomEvent) {
-                callback(e.detail);
+    /** Subscribe to an event only once */
+    once(eventName, listener) {
+        // The actual subscription
+        const unsubscribe = this.on(eventName, listener);
+        // Another subscription that will unsubscribe the actual subscription and itself after the first event
+        const unsubscribeOnce = this.on(eventName, () => {
+            unsubscribe();
+            unsubscribeOnce();
+        });
+        return unsubscribe;
+    }
+    /** Unsubscribe from an event */
+    un(eventName, listener) {
+        if (this.listeners[eventName]) {
+            if (listener) {
+                this.listeners[eventName].delete(listener);
+            }
+            else {
+                delete this.listeners[eventName];
             }
-        };
-        const eventName = String(eventType);
-        this.eventTarget.addEventListener(eventName, handler, { once });
-        return () => this.eventTarget.removeEventListener(eventName, handler);
+        }
+    }
+    /** Clear all events */
+    unAll() {
+        this.listeners = {};
     }
-    /** Subscribe to an event once and return a function to unsubscribe */
-    once(eventType, callback) {
-        return this.on(eventType, callback, true);
+    /** Emit an event */
+    emit(eventName, ...args) {
+        if (this.listeners[eventName]) {
+            this.listeners[eventName].forEach((listener) => listener(...args));
+        }
     }
 }
 export default EventEmitter;

package/dist/fetcher.js

@@ -1,17 +1,6 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 class Fetcher {
-    load(url) {
-        return __awaiter(this, void 0, void 0, function* () {
-            return fetch(url).then((response) => response.arrayBuffer());
-        });
+    async load(url) {
+        return fetch(url).then((response) => response.arrayBuffer());
     }
 }
 export default Fetcher;

package/dist/legacy-adapter.d.ts

@@ -0,0 +1,7 @@
+import type WaveSurfer from "./wavesurfer";
+type LegacyWavesurferMethodsType = Partial<WaveSurfer> & {
+    skip(offset: number): void;
+    stop(): void;
+};
+declare const LegacyWavesurferMethods: LegacyWavesurferMethodsType;
+export default LegacyWavesurferMethods;

package/dist/legacy-adapter.js

@@ -0,0 +1,15 @@
+const LegacyWavesurferMethods = {
+    /** Skip a number of seconds from the current position (use a negative value to go backwards) */
+    skip(seconds) {
+        console.warn('Deprecated, please use `wavesurfer.setTime(wavesurfer.getCurrentTime() + seconds)` instead');
+        const time = this.getCurrentTime() + seconds;
+        this.setTime(time);
+    },
+    /** Stop the audio and go to the beginning */
+    stop() {
+        console.warn('Deprecated, please use `wavesurfer.pause(); wavesurfer.setTime(0)` instead');
+        this.pause();
+        this.setTime(0);
+    }
+};
+export default LegacyWavesurferMethods;

package/dist/player.d.ts

@@ -1,24 +1,45 @@
-declare class Player {
+import EventEmitter, { type GeneralEventTypes } from './event-emitter.js';
+type PlayerOptions = {
+    media?: HTMLMediaElement;
+    autoplay?: boolean;
+    playbackRate?: number;
+};
+declare class Player<T extends GeneralEventTypes> extends EventEmitter<T> {
     protected media: HTMLMediaElement;
+    protected subscriptions: Array<() => void>;
     private isExternalMedia;
-    private hasPlayedOnce;
-    constructor({ media, autoplay }: {
-        media?: HTMLMediaElement;
-        autoplay?: boolean;
-    });
-    on(event: keyof HTMLMediaElementEventMap, callback: () => void): () => void;
+    constructor(options: PlayerOptions);
+    protected onMediaEvent(event: keyof HTMLMediaElementEventMap, callback: () => void, options?: AddEventListenerOptions): () => void;
+    protected onceMediaEvent(event: keyof HTMLMediaElementEventMap, callback: () => void): () => void;
+    protected loadUrl(src: string): void;
     destroy(): void;
-    loadUrl(src: string): void;
-    getCurrentTime(): number;
-    play(): void;
+    /** Start playing the audio */
+    play(): Promise<void>;
+    /** Pause the audio */
     pause(): void;
+    /** Check if the audio is playing */
     isPlaying(): boolean;
-    seekTo(time: number): void;
+    /** Jumpt to a specific time in the audio (in seconds) */
+    setTime(time: number): void;
+    /** Get the duration of the audio in seconds */
+    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 the playback speed */
     getPlaybackRate(): number;
+    /** Set the playback speed, pass an optional false to NOT preserve the pitch */
     setPlaybackRate(rate: number, preservePitch?: boolean): void;
+    /** Get the HTML media element */
+    getMediaElement(): HTMLMediaElement;
+    /** Set a sink id to change the audio output device */
+    setSinkId(sinkId: string): Promise<void>;
 }
 export default Player;

package/dist/player.js

@@ -1,81 +1,87 @@
-class Player {
-    constructor({ media, autoplay }) {
+import EventEmitter from './event-emitter.js';
+class Player extends EventEmitter {
+    constructor(options) {
+        super();
+        this.subscriptions = [];
         this.isExternalMedia = false;
-        this.hasPlayedOnce = false;
-        if (media) {
-            this.media = media;
+        if (options.media) {
+            this.media = options.media;
             this.isExternalMedia = true;
         }
         else {
             this.media = document.createElement('audio');
         }
-        // Track the first play() call
-        const unsubscribe = this.on('play', () => {
-            this.hasPlayedOnce = true;
-            unsubscribe();
-        });
         // Autoplay
-        if (autoplay) {
+        if (options.autoplay) {
             this.media.autoplay = true;
         }
+        // Speed
+        if (options.playbackRate != null) {
+            this.media.playbackRate = options.playbackRate;
+        }
     }
-    on(event, callback) {
-        var _a;
-        (_a = this.media) === null || _a === void 0 ? void 0 : _a.addEventListener(event, callback);
-        return () => { var _a; return (_a = this.media) === null || _a === void 0 ? void 0 : _a.removeEventListener(event, callback); };
+    onMediaEvent(event, callback, options) {
+        this.media.addEventListener(event, callback, options);
+        return () => this.media.removeEventListener(event, callback);
     }
-    destroy() {
-        var _a, _b;
-        (_a = this.media) === null || _a === void 0 ? void 0 : _a.pause();
-        if (!this.isExternalMedia) {
-            (_b = this.media) === null || _b === void 0 ? void 0 : _b.remove();
-        }
+    onceMediaEvent(event, callback) {
+        return this.onMediaEvent(event, callback, { once: true });
     }
     loadUrl(src) {
-        if (this.media) {
-            this.media.src = src;
-        }
+        this.media.src = src;
     }
-    getCurrentTime() {
-        return this.media.currentTime;
+    destroy() {
+        this.media.pause();
+        this.subscriptions.forEach((unsubscribe) => unsubscribe());
+        if (!this.isExternalMedia) {
+            this.media.remove();
+        }
     }
+    /** Start playing the audio */
     play() {
-        this.media.play();
+        return this.media.play();
     }
+    /** Pause the audio */
     pause() {
         this.media.pause();
     }
+    /** Check if the audio is playing */
     isPlaying() {
         return this.media.currentTime > 0 && !this.media.paused && !this.media.ended;
     }
-    seekTo(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();
-            }
-        }
+    /** Jumpt to a specific time in the audio (in seconds) */
+    setTime(time) {
+        this.media.currentTime = time;
     }
+    /** Get the duration of the audio in seconds */
+    getDuration() {
+        return this.media.duration;
+    }
+    /** Get the current audio position in seconds */
+    getCurrentTime() {
+        return this.media.currentTime;
+    }
+    /** Get the audio volume */
     getVolume() {
         return this.media.volume;
     }
+    /** Set the audio volume */
     setVolume(volume) {
         this.media.volume = volume;
     }
+    /** Get the audio muted state */
     getMuted() {
         return this.media.muted;
     }
+    /** Mute or unmute the audio */
     setMuted(muted) {
         this.media.muted = muted;
     }
+    /** Get the playback speed */
     getPlaybackRate() {
         return this.media.playbackRate;
     }
+    /** Set the playback speed, pass an optional false to NOT preserve the pitch */
     setPlaybackRate(rate, preservePitch) {
         // preservePitch is true by default in most browsers
         if (preservePitch != null) {
@@ -83,5 +89,15 @@ class Player {
         }
         this.media.playbackRate = rate;
     }
+    /** Get the HTML media element */
+    getMediaElement() {
+        return this.media;
+    }
+    /** Set a sink id to change the audio output device */
+    setSinkId(sinkId) {
+        // See https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/setSinkId
+        const media = this.media;
+        return media.setSinkId(sinkId);
+    }
 }
 export default Player;