wavesurfer.js 7.0.0-alpha.5 → 7.0.0-alpha.51

package/README.md

@@ -1,43 +1,118 @@
 # <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 from a CDN or a local file like this:
+
+```
+import WaveSurfer from 'https://unpkg.com/wavesurfer.js@alpha'
+```
+
+Or, as a script tag which exposes `WaveSurfer` as a global variable:
+```
+<script src="https://unpkg.com/wavesurfer.js@alpha"></script>
+```
+
+To import a plugin, e.g. the Timeline plugin:
+```
+import Timeline from 'https://unpkg.com/wavesurfer.js@alpha/dist/plugins/timeline.js'
+```
+
+TypeScript types are included in the package, so there's no need to install `@types/wavesurfer.js`.
+
+## Why upgrade to wavesurfer.ts?
+
+wavesurfer.js v7 (aka wavesurfer.ts) brings several improvements:
 
- * TypeScript API
- * Better architecture
- * Minimize the available options and provide sensible defaults
- * Improve the decoding and rendering performance
+ * Typed API for better development experience
+ * Enhanced decoding and rendering performance
+ * New and improved plugins
 
-## Non-goals
+## Plugins
+The "official" plugins have been completely rewritten and enhanced:
 
-Keeping backwards compatibility with earlier versions of wavesurfer.js.
+ * [Regions](https://wavesurfer.pages.dev/examples/#regions.js) – now also replaces the old Markers plugin
+ * [Timeline](https://wavesurfer.pages.dev/examples/#timeline.js) – displays notches and time labels below the waveform
+ * [Minimap](https://wavesurfer.pages.dev/examples/#minimap.js) – a small waveform that serves as a scrollbar for the main waveform
+ * [Envelope](https://wavesurfer.pages.dev/examples/#envelope.js) – a graphical interface to add fade-in and -out effects and control volume
+ * [Record](https://wavesurfer.pages.dev/examples/#record.js) – records audio from the microphone and renders a waveform
+ * [Spectrogram](https://wavesurfer.pages.dev/examples/#spectrogram.js) – visualization of an audio frequency spectrum
 
-## Architecture
+## CSS styling
 
-Principles:
- * Modular and event-driven
- * Flexible (e.g. allow custom media elements and user-defined Web Audio graphs)
- * Extensible with plugins
+wavesurfer.js v7 is rendered into a Shadow DOM tree. This isolates its CSS from the rest of the web page.
+However, it's still possible to style various wavesurfer.js elements via CSS using the `::part()` pseudo-selector.
+For example:
+
+```css
+#waveform ::part(cursor):before {
+  content: '🏄';
+}
+#waveform ::part(region) {
+  font-family: fantasy;
+}
+```
+
+You can see which elements you can style in the DOM inspector – they will have a `part` attribute.
+
+<img width="466" alt="DOM inspector screenshot" src="https://github.com/katspaugh/wavesurfer.ts/assets/381895/fcfb4e4d-9572-4931-811f-9615b7e3aa85">
+
+See [this example](https://wavesurfer.pages.dev/examples/#styling.js) for play around with styling.
+
+## 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.pages.dev/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 Cursor and Playhead plugins yet – to be done.
+
+### Removed methods
+ * `getFilters`, `setFilter` – as there's no Web Audio "backend"
+ * `drawBuffer` – to redraw the waveform, use `setOptions` instead and pass new rendering options
+ * `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/modules/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,13 @@
 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 declare class BasePlugin<EventTypes extends GeneralEventTypes, Options> extends EventEmitter<EventTypes> {
+    protected wavesurfer?: WaveSurfer;
     protected subscriptions: (() => void)[];
-    constructor(params: WaveSurferPluginParams);
+    protected options: Options;
+    constructor(options: Options);
+    onInit(): void;
+    init(wavesurfer: WaveSurfer): void;
     destroy(): void;
 }
 export default BasePlugin;

package/dist/base-plugin.js

@@ -1,10 +1,17 @@
 import EventEmitter from './event-emitter.js';
 export class BasePlugin extends EventEmitter {
-    constructor(params) {
+    constructor(options) {
         super();
         this.subscriptions = [];
-        this.wavesurfer = params.wavesurfer;
-        this.container = params.container;
+        this.options = options;
+    }
+    onInit() {
+        // Overridden in plugin definition
+        return;
+    }
+    init(wavesurfer) {
+        this.wavesurfer = wavesurfer;
+        this.onInit();
     }
     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, sampleRate: number): 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,32 @@
-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,
-        });
-    }
-    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,
-            };
-        });
-    }
-    destroy() {
-        var _a;
-        (_a = this.audioCtx) === null || _a === void 0 ? void 0 : _a.close();
-        this.audioCtx = null;
+/** Decode an array buffer into an audio buffer */
+async function decode(audioData, sampleRate) {
+    const audioCtx = new AudioContext({ sampleRate });
+    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.d.ts

@@ -1,4 +1,5 @@
-declare class Fetcher {
-    load(url: string): Promise<ArrayBuffer>;
-}
+declare function fetchArrayBuffer(url: string): Promise<ArrayBuffer>;
+declare const Fetcher: {
+    fetchArrayBuffer: typeof fetchArrayBuffer;
+};
 export default Fetcher;

package/dist/fetcher.js

@@ -1,17 +1,7 @@
-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 function fetchArrayBuffer(url) {
+    return fetch(url).then((response) => response.arrayBuffer());
 }
+const Fetcher = {
+    fetchArrayBuffer,
+};
 export default Fetcher;

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;
     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;
+    private revokeSrc;
+    protected setSrc(url: string, arrayBuffer?: ArrayBuffer): 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,95 @@
-class Player {
-    constructor({ media, autoplay }) {
+import EventEmitter from './event-emitter.js';
+class Player extends EventEmitter {
+    constructor(options) {
+        super();
         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;
+    revokeSrc() {
+        if (this.media.src?.startsWith('blob:')) {
+            URL.revokeObjectURL(this.media.src);
         }
     }
-    getCurrentTime() {
-        return this.media.currentTime;
+    setSrc(url, arrayBuffer) {
+        if (this.media.src === url)
+            return;
+        this.revokeSrc();
+        const src = arrayBuffer ? URL.createObjectURL(new Blob([arrayBuffer], { type: 'audio/wav' })) : url;
+        this.media.src = src;
+    }
+    destroy() {
+        this.media.pause();
+        this.revokeSrc();
+        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 +97,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;