wavesurfer.js 6.5.1 → 7.0.0-alpha.0

package/.eslintrc.json

@@ -0,0 +1,24 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier",
+    "plugin:prettier/recommended"
+  ],
+  "overrides": [
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "rules": {
+  }
+}

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "tabWidth": 2,
+  "printWidth": 120,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "semi": false,
+  "endOfLine": "auto"
+}

package/README.md

@@ -1,141 +1,50 @@
-# [wavesurfer.js](https://wavesurfer-js.org)
+# wavesurfer.ts
 
-[![npm version](https://img.shields.io/npm/v/wavesurfer.js.svg?style=flat)](https://www.npmjs.com/package/wavesurfer.js)
-![npm](https://img.shields.io/npm/dm/wavesurfer.js.svg) [![Join the chat at https://gitter.im/wavesurfer-js/wavesurfer.js](https://badges.gitter.im/wavesurfer-js/wavesurfer.js.svg)](https://gitter.im/wavesurfer-js/wavesurfer.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/wavesurfer-js/wavesurfer.js/badge)](https://www.gitpoap.io/gh/wavesurfer-js/wavesurfer.js)
+An experimental rewrite of [wavesufer.js](https://github.com/wavesurfer-js/wavesurfer.js) to play around with new ideas.
 
-Interactive navigable audio visualization using Web Audio and Canvas.
+## Goals
 
-[![Screenshot](https://raw.githubusercontent.com/wavesurfer-js/wavesurfer.js/gh-pages/example/screenshot.png "Screenshot")](https://wavesurfer-js.org)
+ * TypeScript API
+ * Better architecture
+ * Minimize the available options and provide sensible defaults
+ * Improve the decoding and rendering performance
 
-See a [tutorial](https://wavesurfer-js.org/docs) and [examples](https://wavesurfer-js.org/examples) on [wavesurfer-js.org](https://wavesurfer-js.org).
+## Non-goals
 
-## Questions
-Have a question about integrating wavesurfer.js on your website? Feel free to ask in our forum: https://github.com/wavesurfer-js/wavesurfer.js/discussions/categories/q-a
+Keeping backwards compatibility with earlier versions of wavesurfer.js.
 
-## Quick start
-Install the package:
+## Architecture
 
-```
-npm install wavesurfer.js --save
-
-# or
-
-yarn add wavesurfer.js
-```
-
-And import it like so:
-```
-import WaveSurfer from 'wavesurfer.js'
-```
-
-If you're not using a package manager, simply insert the script from a CDN:
-```
-<script src="https://unpkg.com/wavesurfer.js"></script>
-```
-
-Create a container in your HTML:
-```html
-<div id="waveform"></div>
-```
-
-Create an instance of wavesufer.js, passing the container selector and a few [options](https://wavesurfer-js.org/docs/options.html):
-
-```javascript
-var wavesurfer = WaveSurfer.create({
-    container: '#waveform',
-    waveColor: 'violet',
-    progressColor: 'purple'
-});
-```
-
-Subscribe to some [events](https://wavesurfer-js.org/docs/events.html):
-
-```javascript
-wavesurfer.on('ready', function () {
-    wavesurfer.play();
-});
-```
-
-Load an audio file from a URL:
-
-```javascript
-wavesurfer.load('example/media/demo.wav');
-```
-
-## Documentation
+Principles:
+ * Modular and event-driven
+ * Allow swapping the decoding, rendering and playback mechanisms
+ * Extensible with plugins
 
-See the documentation on all available [methods](https://wavesurfer-js.org/docs/methods.html), [options](https://wavesurfer-js.org/docs/options.html) and [events](https://wavesurfer-js.org/docs/events.html) on the [homepage](https://wavesurfer-js.org/docs/).
+![diagram](https://user-images.githubusercontent.com/381895/222349436-38b550e5-24dc-4143-9cdb-efbe00540213.png)
 
-## Projects using wavesurfer.js
+## Development
 
-For the list of projects using wavesurfer.js, check out
-[the projects page](https://wavesurfer-js.org/projects/).
-
-## Contributing
-
-Have an idea and want to contribute to wavesurfer.js?
-Please first start a discussion in the [Ideas section of our forum](https://github.com/wavesurfer-js/wavesurfer.js/discussions/categories/ideas) to coordinate with the maintainers.
-
-### Development
-
-[![Build Status](https://github.com/wavesurfer-js/wavesurfer.js/workflows/wavesurfer.js/badge.svg?branch=master)](https://github.com/wavesurfer-js/wavesurfer.js/actions?workflow=wavesurfer.js)
-[![Coverage Status](https://coveralls.io/repos/github/wavesurfer-js/wavesurfer.js/badge.svg)](https://coveralls.io/github/wavesurfer-js/wavesurfer.js)
-![Size](https://img.shields.io/bundlephobia/minzip/wavesurfer.js.svg?style=flat)
-
-Install development dependencies:
-
-```
-npm install
-```
-Development tasks automatically rebuild certain parts of the library when files are changed (`start` – wavesurfer, `start:plugins` – plugins). Start a dev task and go to `localhost:8080/example/` to test the current build.
-
-Start development server for core library:
-
-```
-npm run start
-```
-
-Start development server for plugins:
+Install dev dependencies:
 
 ```
-npm run start:plugins
+yarn
 ```
 
-Build all the files. (generated files are placed in the `dist` directory.)
+Start the TypeScript compiler in watch mode:
 
 ```
-npm run build
+yarn build -w
 ```
 
-Running tests only:
-
-```
-npm run test
-```
+Run an HTTP server to view the examples:
 
-Build documentation with esdoc (generated files are placed in the `doc` directory.)
 ```
-npm run doc
+python3 -m http.server --cgi 8080
 ```
 
-If you want to use [the VS Code - Debugger for Chrome](https://github.com/Microsoft/vscode-chrome-debug), there is already a [launch.json](.vscode/launch.json) with a properly configured ``sourceMapPathOverrides`` for you.
-
-## Editing documentation
-The homepage and documentation files are maintained in the [`gh-pages` branch](https://github.com/wavesurfer-js/wavesurfer.js/tree/gh-pages). Contributions to the documentation are especially welcome.
-
-## Updating the NPM package
-When preparing a new release, update the version in the `package.json` and have it merged to master. The new version of the package will be published to NPM automatically via GitHub Actions.
-
-## Credits
-
-The main maintainer: <img src="https://avatars.githubusercontent.com/u/305679" width="16" height="16" /> [Thijs Triemstra](https://github.com/thijstriemstra)
-
-Many thanks to [all the awesome contributors](https://github.com/wavesurfer-js/wavesurfer.js/contributors)!
-
-## License
+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.
 
-[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+## Feedback
 
-This work is licensed under a
-[BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause).
+See https://github.com/wavesurfer-js/wavesurfer.js/discussions/2684

package/dist/base-plugin.d.ts

@@ -0,0 +1,10 @@
+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 renderer: WaveSurfer['renderer'];
+    protected subscriptions: (() => void)[];
+    constructor(params: WaveSurferPluginParams);
+    destroy(): void;
+}
+export default BasePlugin;

package/dist/base-plugin.js

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

package/dist/decoder.d.ts

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

package/dist/decoder.js

@@ -0,0 +1,43 @@
+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());
+    });
+};
+// 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)({
+            latencyHint: 'playback',
+            sampleRate: 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;
+    }
+}
+export default Decoder;

package/dist/event-emitter.d.ts

@@ -0,0 +1,11 @@
+export interface GeneralEventTypes {
+    [eventType: string]: unknown;
+}
+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): () => void;
+}
+export default EventEmitter;

package/dist/event-emitter.js

@@ -0,0 +1,21 @@
+class EventEmitter {
+    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) {
+        const handler = (e) => {
+            if (e instanceof CustomEvent) {
+                callback(e.detail);
+            }
+        };
+        const eventName = String(eventType);
+        this.eventTarget.addEventListener(eventName, handler);
+        return () => this.eventTarget.removeEventListener(eventName, handler);
+    }
+}
+export default EventEmitter;

package/dist/fetcher.d.ts

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

package/dist/fetcher.js

@@ -0,0 +1,17 @@
+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());
+        });
+    }
+}
+export default Fetcher;

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+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;
+    /** Height of the waveform in pixels */
+    height?: number;
+    /** The color of the waveform */
+    waveColor?: string;
+    /** The color of the progress mask */
+    progressColor?: string;
+    /** If set, the waveform will be rendered in bars like so: ▁ ▂ ▇ ▃ ▅ ▂ */
+    barWidth?: number;
+    /** Spacing between bars in pixels */
+    barGap?: number;
+    /** Rounded borders for bars */
+    barRadius?: number;
+    /** Minimum pixels per second of audio (zoom) */
+    minPxPerSec?: number;
+    /** Audio URL */
+    url?: string;
+    /** Pre-computed audio data */
+    channelData?: 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;
+};
+export type WaveSurferEvents = {
+    ready: {
+        duration: number;
+    };
+    canplay: void;
+    play: void;
+    pause: void;
+    audioprocess: {
+        currentTime: number;
+    };
+    seek: {
+        time: number;
+    };
+};
+export type WaveSurferPluginParams = {
+    wavesurfer: WaveSurfer;
+    renderer: WaveSurfer['renderer'];
+};
+export declare class WaveSurfer extends EventEmitter<WaveSurferEvents> {
+    private options;
+    private fetcher;
+    private decoder;
+    private renderer;
+    private player;
+    private timer;
+    private plugins;
+    private subscriptions;
+    private channelData;
+    private duration;
+    /** Create a new WaveSurfer instance */
+    static create(options: WaveSurferOptions): WaveSurfer;
+    /** Create a new WaveSurfer instance */
+    constructor(options: WaveSurferOptions);
+    private initPlayerEvents;
+    private initRendererEvents;
+    private initTimerEvents;
+    /** Unmount wavesurfer */
+    destroy(): void;
+    /** Load an audio file by URL */
+    load(url: string, channelData?: Float32Array[], duration?: number): Promise<void>;
+    /** Zoom in or out */
+    zoom(minPxPerSec: number): void;
+    /** Start playing the audio */
+    play(): void;
+    /** Pause the audio */
+    pause(): void;
+    /** Skip to a time position in seconds */
+    seekTo(time: number): void;
+    /** Check if the audio is playing */
+    isPlaying(): boolean;
+    /** Get the duration of the audio in seconds */
+    getDuration(): number;
+    /** Get the current audio position in seconds */
+    getCurrentTime(): number;
+    /** Register and initialize a plugin */
+    registerPlugin<T extends BasePlugin<GeneralEventTypes>>(CustomPlugin: new (params: WaveSurferPluginParams) => T): T;
+}
+export default WaveSurfer;

package/dist/index.js

@@ -0,0 +1,166 @@
+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());
+    });
+};
+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',
+};
+export class WaveSurfer extends EventEmitter {
+    /** Create a new WaveSurfer instance */
+    static create(options) {
+        return new WaveSurfer(options);
+    }
+    /** Create a new WaveSurfer instance */
+    constructor(options) {
+        var _a;
+        super();
+        this.plugins = [];
+        this.subscriptions = [];
+        this.channelData = null;
+        this.duration = 0;
+        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)({
+            media: this.options.media,
+        });
+        this.renderer = new Renderer({
+            container: this.options.container,
+            height: this.options.height,
+            waveColor: this.options.waveColor,
+            progressColor: this.options.progressColor,
+            minPxPerSec: this.options.minPxPerSec,
+            barWidth: this.options.barWidth,
+            barGap: this.options.barGap,
+            barRadius: this.options.barRadius,
+        });
+        this.initPlayerEvents();
+        this.initRendererEvents();
+        this.initTimerEvents();
+        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);
+        }
+    }
+    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.player.on('play', () => {
+            this.emit('play');
+        }), this.player.on('pause', () => {
+            this.emit('pause');
+        }), this.player.on('canplay', () => {
+            this.emit('canplay');
+        }), this.player.on('seeking', () => {
+            this.emit('seek', { time: this.getCurrentTime() });
+        }));
+    }
+    initRendererEvents() {
+        // Seek on click
+        this.subscriptions.push(this.renderer.on('click', ({ relativeX }) => {
+            const time = this.getDuration() * relativeX;
+            this.seekTo(time);
+        }));
+    }
+    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 });
+            }
+        }));
+    }
+    /** 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();
+    }
+    /** Load an audio file by URL */
+    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) {
+                const audio = yield this.fetcher.load(url);
+                const data = yield this.decoder.decode(audio);
+                channelData = data.channelData;
+                duration = data.duration;
+            }
+            this.channelData = channelData;
+            this.duration = duration;
+            this.renderer.render(this.channelData, this.duration);
+            this.emit('ready', { duration: this.duration });
+        });
+    }
+    /** Zoom in or out */
+    zoom(minPxPerSec) {
+        if (this.channelData == null || this.duration == null) {
+            throw new Error('No audio loaded');
+        }
+        this.renderer.render(this.channelData, this.duration, 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.duration;
+    }
+    /** Get the current audio position in seconds */
+    getCurrentTime() {
+        return this.player.getCurrentTime();
+    }
+    /** Register and initialize a plugin */
+    registerPlugin(CustomPlugin) {
+        const plugin = new CustomPlugin({
+            wavesurfer: this,
+            renderer: this.renderer,
+        });
+        this.plugins.push(plugin);
+        return plugin;
+    }
+}
+export default WaveSurfer;

package/dist/player-webaudio.d.ts

@@ -0,0 +1,8 @@
+import Player from './player.js';
+declare class WebAudioPlayer extends Player {
+    audioCtx: AudioContext | null;
+    sourceNode: MediaElementAudioSourceNode | null;
+    destroy(): void;
+    loadUrl(url: string): void;
+}
+export default WebAudioPlayer;

package/dist/player-webaudio.js

@@ -0,0 +1,31 @@
+import Player from './player.js';
+class WebAudioPlayer extends Player {
+    constructor() {
+        super(...arguments);
+        this.audioCtx = null;
+        this.sourceNode = null;
+    }
+    destroy() {
+        var _a, _b;
+        (_a = this.sourceNode) === null || _a === void 0 ? void 0 : _a.disconnect();
+        this.sourceNode = null;
+        (_b = this.audioCtx) === null || _b === void 0 ? void 0 : _b.close();
+        this.audioCtx = null;
+        super.destroy();
+    }
+    loadUrl(url) {
+        super.loadUrl(url);
+        if (!this.audioCtx) {
+            this.audioCtx = new (window.AudioContext ||
+                window.webkitAudioContext)({
+                latencyHint: 'playback',
+            });
+        }
+        if (this.sourceNode) {
+            this.sourceNode.disconnect();
+        }
+        this.sourceNode = this.audioCtx.createMediaElementSource(this.media);
+        this.sourceNode.connect(this.audioCtx.destination);
+    }
+}
+export default WebAudioPlayer;

package/dist/player.d.ts

@@ -0,0 +1,16 @@
+declare class Player {
+    protected media: HTMLMediaElement;
+    private isExternalMedia;
+    constructor({ media }: {
+        media?: HTMLMediaElement;
+    });
+    on(event: keyof HTMLMediaElementEventMap, callback: () => void): () => void;
+    destroy(): void;
+    loadUrl(src: string): void;
+    getCurrentTime(): number;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    seekTo(time: number): void;
+}
+export default Player;