wavesurfer.js 6.5.0 → 7.0.0-alpha.0

package/examples/webaudio.js

@@ -0,0 +1,14 @@
+import WaveSurfer from '/dist/index.js'
+
+const audio = new Audio()
+audio.controls = true
+audio.src = '/examples/audio.ogg'
+document.body.appendChild(audio)
+
+const wavesurfer = WaveSurfer.create({
+  container: document.body,
+  waveColor: 'rgb(200, 0, 200)',
+  progressColor: 'rgb(100, 0, 100)',
+  backend: 'WebAudio',
+  media: audio,
+})

package/package.json

@@ -1,106 +1,26 @@
 {
   "name": "wavesurfer.js",
-  "version": "6.5.0",
-  "description": "Interactive navigable audio visualization using Web Audio and Canvas",
-  "main": "dist/wavesurfer.js",
-  "directories": {
-    "example": "example"
-  },
-  "files": [
-    "dist/",
-    "src/"
-  ],
+  "version": "7.0.0-alpha.0",
+  "description": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "scripts": {
-    "start": "npm run build:plugins && npm run build:htmlinit && webpack serve --config ./build-config/webpack.dev.main.js",
-    "start:htmlinit": "npm run build:main && npm run build:plugins && webpack serve --config ./build-config/webpack.dev.htmlinit.js",
-    "start:plugins": "npm run build:main && npm run build:htmlinit && webpack serve --config ./build-config/webpack.dev.plugins.js",
-    "build": "npm run build:normal && npm run build:minified",
-    "build:main": "webpack --config ./build-config/webpack.prod.main.js",
-    "build:main:min": "webpack --config ./build-config/webpack.prod.main.min.js",
-    "build:plugins": "webpack --config ./build-config/webpack.prod.plugins.js",
-    "build:plugins:min": "webpack --config ./build-config/webpack.prod.plugins.min.js",
-    "build:htmlinit": "webpack --config ./build-config/webpack.prod.htmlinit.js",
-    "build:htmlinit:min": "webpack --config ./build-config/webpack.prod.htmlinit.min.js",
-    "build:normal": "npm run build:main && npm run build:plugins && npm run build:htmlinit",
-    "build:minified": "npm run build:main:min && npm run build:plugins:min && npm run build:htmlinit:min",
-    "lint": "npm run lint:js && npm run lint:html",
-    "lint:js": "eslint src example spec",
-    "lint:html": "htmlhint example",
-    "lint-js-html": "lint-staged",
-    "doc": "esdoc",
-    "test": "karma start karma.conf.js",
-    "test:chrome": "karma start karma.conf.js --browsers=Chrome --single-run=false",
-    "prepublishOnly": "not-in-install && npm run build || in-install",
-    "prepare": "npm run build"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git@github.com:wavesurfer-js/wavesurfer.js.git"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org"
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "lint": "eslint --ext .ts src --fix",
+    "prettier": "prettier -w src",
+    "docs": "npx typedoc src/index.ts"
   },
-  "author": "",
-  "license": "BSD-3-Clause",
-  "bugs": {
-    "url": "https://github.com/wavesurfer-js/wavesurfer.js/issues"
-  },
-  "keywords": [
-    "waveform",
-    "audio",
-    "music",
-    "player",
-    "webaudio",
-    "microphone",
-    "visualization"
-  ],
+  "author": "katspaugh <katspaugh@gmail.com>",
+  "license": "ISC",
   "devDependencies": {
-    "@babel/core": "^7.20.12",
-    "@babel/eslint-parser": "^7.19.1",
-    "@babel/plugin-proposal-class-properties": "^7.18.6",
-    "@babel/preset-env": "^7.20.2",
-    "@babel/register": "^7.18.9",
-    "@chiragrupani/karma-chromium-edge-launcher": "^2.2.2",
-    "babel-loader": "^9.1.2",
-    "babel-plugin-add-module-exports": "^1.0.4",
-    "babel-plugin-istanbul": "^6.1.1",
-    "date-fns": "^2.29.3",
-    "debounce": "^1.2.1",
-    "esdoc": "^1.1.0",
-    "esdoc-accessor-plugin": "^1.0.0",
-    "esdoc-brand-plugin": "^1.0.1",
-    "esdoc-coverage-plugin": "^1.1.0",
-    "esdoc-ecmascript-proposal-plugin": "^1.0.0",
-    "esdoc-integrate-test-plugin": "^1.0.0",
-    "esdoc-standard-plugin": "^1.0.0",
-    "eslint": "^8.26.0",
-    "htmlhint": "^1.1.4",
-    "in-publish": "^2.0.1",
-    "jasmine-core": "^4.5.0",
-    "karma": "^6.4.1",
-    "karma-chrome-launcher": "3.1.1",
-    "karma-coverage": "^2.2.0",
-    "karma-firefox-launcher": "^2.1.2",
-    "karma-jasmine": "5.1.0",
-    "karma-jasmine-matchers": "5.0.0",
-    "karma-verbose-reporter": "0.0.8",
-    "karma-webpack": "^5.0.0",
-    "lint-staged": "^13.1.0",
-    "load-script": "^2.0.0",
-    "pre-commit": "^1.2.2",
-    "webpack": "^5.75.0",
-    "webpack-cli": "^5.0.1",
-    "webpack-dev-server": "^4.11.1",
-    "webpack-merge": "^5.8.0"
-  },
-  "homepage": "https://wavesurfer-js.org",
-  "pre-commit": "lint-js-html",
-  "lint-staged": {
-    "*.js": [
-      "eslint"
-    ],
-    "*.html": [
-      "htmlhint"
-    ]
+    "@typescript-eslint/eslint-plugin": "^5.54.0",
+    "@typescript-eslint/parser": "^5.54.0",
+    "eslint": "^8.35.0",
+    "eslint-config-prettier": "^8.7.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "prettier": "^2.8.4",
+    "typedoc": "^0.23.26",
+    "typescript": "^4.9.5"
   }
 }

package/src/base-plugin.ts

@@ -0,0 +1,20 @@
+import EventEmitter, { type GeneralEventTypes } from './event-emitter.js'
+import type { WaveSurfer, WaveSurferPluginParams } from './index.js'
+
+export class BasePlugin<EventTypes extends GeneralEventTypes> extends EventEmitter<EventTypes> {
+  protected wavesurfer: WaveSurfer
+  protected renderer: WaveSurfer['renderer']
+  protected subscriptions: (() => void)[] = []
+
+  constructor(params: WaveSurferPluginParams) {
+    super()
+    this.wavesurfer = params.wavesurfer
+    this.renderer = params.renderer
+  }
+
+  destroy() {
+    this.subscriptions.forEach((unsubscribe) => unsubscribe())
+  }
+}
+
+export default BasePlugin

package/src/decoder.ts

@@ -0,0 +1,41 @@
+// Web Audio decodeAudioData with a minimum allowed sample rate
+const SAMPLE_RATE = 3000
+
+class Decoder {
+  audioCtx: AudioContext | null = null
+
+  constructor() {
+    this.audioCtx = new (window.AudioContext ||
+      (window as unknown as { webkitAudioContext: AudioContext }).webkitAudioContext)({
+      latencyHint: 'playback',
+      sampleRate: SAMPLE_RATE,
+    })
+  }
+
+  public async decode(audioData: ArrayBuffer): Promise<{
+    duration: number
+    channelData: Float32Array[]
+  }> {
+    if (!this.audioCtx) {
+      throw new Error('AudioContext is not initialized')
+    }
+
+    const buffer = await this.audioCtx.decodeAudioData(audioData)
+    const channelData = [buffer.getChannelData(0)]
+    if (buffer.numberOfChannels > 1) {
+      channelData.push(buffer.getChannelData(1))
+    }
+
+    return {
+      duration: buffer.duration,
+      channelData,
+    }
+  }
+
+  destroy() {
+    this.audioCtx?.close()
+    this.audioCtx = null
+  }
+}
+
+export default Decoder

package/src/event-emitter.ts

@@ -0,0 +1,35 @@
+export interface GeneralEventTypes {
+  // the name of the event and the data it dispatches with
+  // e.g. 'entryCreated': { count: 1 }
+  [eventType: string]: unknown
+}
+
+class EventEmitter<EventTypes extends GeneralEventTypes> {
+  private eventTarget: EventTarget
+
+  constructor() {
+    this.eventTarget = new EventTarget()
+  }
+
+  protected emit<T extends keyof EventTypes>(eventType: T, detail?: EventTypes[T]): void {
+    const e = new CustomEvent(String(eventType), { detail })
+    this.eventTarget.dispatchEvent(e)
+  }
+
+  /** Subscribe to an event and return a function to unsubscribe */
+  on<T extends keyof EventTypes>(eventType: T, callback: (detail: EventTypes[T]) => void): () => void {
+    const handler = (e: Event) => {
+      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/src/fetcher.ts

@@ -0,0 +1,7 @@
+class Fetcher {
+  public async load(url: string): Promise<ArrayBuffer> {
+    return fetch(url).then((response) => response.arrayBuffer())
+  }
+}
+
+export default Fetcher

package/src/index.ts

@@ -0,0 +1,252 @@
+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, { type GeneralEventTypes } from './event-emitter.js'
+import Timer from './timer.js'
+import BasePlugin from './base-plugin.js'
+
+export 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
+}
+
+const defaultOptions = {
+  height: 128,
+  waveColor: '#999',
+  progressColor: '#555',
+  minPxPerSec: 0,
+  backend: 'MediaElement',
+}
+
+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 class WaveSurfer extends EventEmitter<WaveSurferEvents> {
+  private options: WaveSurferOptions & typeof defaultOptions
+
+  private fetcher: Fetcher
+  private decoder: Decoder
+  private renderer: Renderer
+  private player: Player
+  private timer: Timer
+
+  private plugins: BasePlugin<GeneralEventTypes>[] = []
+  private subscriptions: Array<() => void> = []
+  private channelData: Float32Array[] | null = null
+  private duration = 0
+
+  /** Create a new WaveSurfer instance */
+  public static create(options: WaveSurferOptions) {
+    return new WaveSurfer(options)
+  }
+
+  /** Create a new WaveSurfer instance */
+  constructor(options: WaveSurferOptions) {
+    super()
+
+    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 || this.options.media?.src
+    if (url) {
+      this.load(url, this.options.channelData, this.options.duration)
+    }
+  }
+
+  private 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() })
+      }),
+    )
+  }
+
+  private initRendererEvents() {
+    // Seek on click
+    this.subscriptions.push(
+      this.renderer.on('click', ({ relativeX }) => {
+        const time = this.getDuration() * relativeX
+        this.seekTo(time)
+      }),
+    )
+  }
+
+  private 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 */
+  public 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 */
+  public async load(url: string, channelData?: Float32Array[], duration?: number) {
+    this.player.loadUrl(url)
+
+    // Fetch and decode the audio of no pre-computed audio data is provided
+    if (channelData == null || duration == null) {
+      const audio = await this.fetcher.load(url)
+      const data = await 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 */
+  public zoom(minPxPerSec: number) {
+    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 */
+  public play() {
+    this.player.play()
+  }
+
+  /** Pause the audio */
+  public pause() {
+    this.player.pause()
+  }
+
+  /** Skip to a time position in seconds */
+  public seekTo(time: number) {
+    this.player.seekTo(time)
+  }
+
+  /** Check if the audio is playing */
+  public isPlaying(): boolean {
+    return this.player.isPlaying()
+  }
+
+  /** Get the duration of the audio in seconds */
+  public getDuration(): number {
+    return this.duration
+  }
+
+  /** Get the current audio position in seconds */
+  public getCurrentTime(): number {
+    return this.player.getCurrentTime()
+  }
+
+  /** Register and initialize a plugin */
+  public registerPlugin<T extends BasePlugin<GeneralEventTypes>>(
+    CustomPlugin: new (params: WaveSurferPluginParams) => T,
+  ): T {
+    const plugin = new CustomPlugin({
+      wavesurfer: this,
+      renderer: this.renderer,
+    })
+
+    this.plugins.push(plugin)
+
+    return plugin
+  }
+}
+
+export default WaveSurfer

package/src/player-webaudio.ts

@@ -0,0 +1,34 @@
+import Player from './player.js'
+
+class WebAudioPlayer extends Player {
+  audioCtx: AudioContext | null = null
+  sourceNode: MediaElementAudioSourceNode | null = null
+
+  destroy() {
+    this.sourceNode?.disconnect()
+    this.sourceNode = null
+    this.audioCtx?.close()
+    this.audioCtx = null
+
+    super.destroy()
+  }
+
+  loadUrl(url: string) {
+    super.loadUrl(url)
+
+    if (!this.audioCtx) {
+      this.audioCtx = new (window.AudioContext ||
+        (window as unknown as { webkitAudioContext: AudioContext }).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/src/player.ts

@@ -0,0 +1,50 @@
+class Player {
+  protected media: HTMLMediaElement
+  private isExternalMedia = false
+
+  constructor({ media }: { media?: HTMLMediaElement }) {
+    if (media) {
+      this.media = media
+      this.isExternalMedia = true
+    } else {
+      this.media = document.createElement('audio')
+    }
+  }
+
+  on(event: keyof HTMLMediaElementEventMap, callback: () => void): () => void {
+    this.media.addEventListener(event, callback)
+    return () => this.media.removeEventListener(event, callback)
+  }
+
+  destroy() {
+    if (!this.isExternalMedia) {
+      this.media.remove()
+    }
+  }
+
+  loadUrl(src: string) {
+    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: number) {
+    this.media.currentTime = time
+  }
+}
+
+export default Player