audio-workbench

▶ Live demo — Open in browser (GitHub Pages)

DAW-like audio player (waveform + spectrogram + transport controls) as a standalone library — built for bioacoustic analysis, annotation, and embedding.

Table of contents

• Features
• Install
• Quickstart
• Player Options
• Usage Examples
• API
• Demos
• Python wrapper
• Contributing
• License

Features

• Dual spectrogram presets — Perch (mel + PCEN) and Classic (linear + dB)
• Waveform + spectrogram rendered side-by-side with synchronized scrolling and zoom
• Label annotations — draw, drag, resize time×frequency boxes on the spectrogram
• Label taxonomy — customizable species presets with colors and keyboard shortcuts
• Bandpass-filtered playback — isolate and play back a specific time×frequency region via Web Audio
• External spectrogram injection — supply pre-computed Float32 data or a rendered image
• Settings side-panel — FFT size, max frequency, color scheme, display gain, auto contrast, zoom
• Crosshair overlay — real-time time + frequency readout
• Compact preview modes — hero transport, overlay mode, small embeds
• 110+ tests — DSP, spectrogram utils, coordinate system, interaction state, transport state

Install

npm i audio-workbench

Or for Python:

pip install audio-workbench

See PyPI and the python-wrapper/README.md for full Python usage.

Quickstart

import { BirdNETPlayer } from 'audio-workbench'
import 'audio-workbench/style'

const player = new BirdNETPlayer(document.getElementById('player'))
await player.ready

Player Options

Option	Type	Default	Description
viewMode	string	'both'	'both', 'waveform', 'spectrogram' — visible analysis views
transportStyle	string	'default'	'default', 'hero' — transport button style
transportOverlay	boolean	false	Centered play overlay, no toolbar height
showFileOpen	boolean	true	Show Open button and file input
showTransport	boolean	true	Show transport controls (play/pause/stop)
showTime	boolean	true	Show time display
showVolume	boolean	true	Show volume controls
showViewToggles	boolean	true	Show Follow/Loop/Fit/Reset buttons
showZoom	boolean	true	Show zoom slider
showFFTControls	boolean	true	Show FFT size, max frequency, color scheme
showDisplayGain	boolean	true	Show floor/ceiling sliders, auto contrast
showStatusbar	boolean	true	Show bottom status bar
showOverview	boolean	true	Show overview navigator
showWaveformTimeline	boolean	true	Show bottom timeline in waveform view
compactToolbar	string	'auto'	'auto', 'on', 'off' — responsive toolbar compaction
labelTaxonomy	array	see docs	Custom label presets (name, color, shortcut)
...	...	...	...

See the API section for usage examples and more details.

Usage Examples

ESM (Vite / Vanilla)

import { BirdNETPlayer } from 'audio-workbench'
import 'audio-workbench/style'

const player = new BirdNETPlayer(document.getElementById('player'))
await player.ready

Load from URL

await player.loadUrl('/audio/birdsong.mp3')
player.play()

File Input

const input = document.querySelector('#audio')
input.addEventListener('change', async () => {
  const file = input.files?.[0]
  if (!file) return
  await player.loadFile(file)
})

React

import { useEffect, useRef } from 'react'
import { BirdNETPlayer } from 'audio-workbench'
import 'audio-workbench/style'

export default function Player() {
  const ref = useRef(null)
  useEffect(() => {
    if (!ref.current) return
    const p = new BirdNETPlayer(ref.current)
    return () => p.destroy()
  }, [])
  return <div ref={ref} />
}

Vue

import { onMounted, onBeforeUnmount, ref } from 'vue'
import { BirdNETPlayer } from 'audio-workbench'
import 'audio-workbench/style'

const root = ref(null)
let player

onMounted(() => { player = new BirdNETPlayer(root.value) })
onBeforeUnmount(() => player?.destroy())

Svelte

<script>
  import { onMount } from 'svelte'
  import { BirdNETPlayer } from 'audio-workbench'
  import 'audio-workbench/style'

  let el
  let player
  onMount(() => {
    player = new BirdNETPlayer(el)
    return () => player.destroy()
  })
</script>

<div bind:this={el}></div>

CDN / IIFE

<script src="https://unpkg.com/wavesurfer.js@7"></script>
<script src="https://unpkg.com/audio-workbench/dist/birdnet-player.iife.js"></script>
<link rel="stylesheet" href="https://unpkg.com/audio-workbench/dist/birdnet-player.css" />
<div id="player"></div>
<script>
  const player = new BirdNETPlayerModule.BirdNETPlayer(document.getElementById('player'))
</script>

Streamlit (Python)

from audio_workbench import render_daw_player
import streamlit.components.v1 as components

components.html(render_daw_player(audio_bytes), height=620, scrolling=False)

Jupyter Notebook

from IPython.display import HTML
from audio_workbench import render_daw_player

HTML(render_daw_player(audio_bytes))

Demos

• Live Demo (GitHub Pages)
• Google Colab Demo Notebook
• Streamlit:

  streamlit run python-wrapper/demo_streamlit.py

• Gradio:

  pip install gradio
  python python-wrapper/demo_gradio.py

Python wrapper

The Python wrapper allows embedding the player in Streamlit, Jupyter, and Gradio. See python-wrapper/README.md for full usage, options, and advanced features.

Install:

pip install audio-workbench

Docs & PyPI: https://pypi.org/project/audio-workbench

Contributing

See the repository on GitHub and open issues/PRs: https://github.com/LimitlessGreen/Audio-Workbench

License

GNU AGPL-3.0