audio-workbench

▶ Live demo — Open in browser (GitHub Pages)
🏷 Labeling App — BirdNET detection, annotation & Xeno-canto integration

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
• Vertical frequency zoom — Shift+Wheel, dedicated V-slider, draggable scrollbar, freq-axis drag
• Label annotations — draw, drag, resize time×frequency boxes on the spectrogram
• Label taxonomy — customizable species presets with colors and keyboard shortcuts
• Suggestion labels — BirdNET detections shown with distinct "construction-fence" styling; accept (✓) to promote to manual or discard (✕)
• Bandpass-filtered playback — isolate and play back a specific time×frequency region via Web Audio
• Xeno-canto integration — search, preview and import recordings; auto-enrich labels with XC metadata
• 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
• Properties panel — pin or hover to inspect label details; inline editing
• Crosshair overlay — real-time time + frequency readout
• Compact preview modes — hero transport, overlay mode, small embeds
• 196 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) — component storybook with configurable stories
• Labeling App — full-featured annotation tool with BirdNET detection, Xeno-canto integration, label management and spectrogram settings (demo/labeling-app.html)
• 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