⚠️ Early development — Unstable

This project is in active early development. APIs, features, and build artifacts may change or break without notice. You're encouraged to try it and provide feedback, but do not expect a stable release or backward compatibility yet. If you require stability, pin to a specific commit or wait for an official release. Contributions and bug reports are welcome.

audio-workbench

💡 Try it — Demo Interactive demo and a full labeling app (BirdNET detection & annotation). Try them in your browser:

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

Table of contents

• audio-workbench
  • Table of contents
  • Features
  • Install
  • Quickstart
  • Player Options
  • Usage Examples
    • ESM (Vite / Vanilla)
    • Load from URL
    • File Input
    • React
    • Vue
    • Svelte
    • CDN / IIFE
    • Streamlit (Python)
    • Jupyter Notebook
  • Demos
  • Python wrapper
  • Contributing
  • License

✨ Highlights

• Customizable spectrogram rendering — adjust scale, contrast, gain, color mapping, and more
• Synced waveform + spectrogram with zoom and scroll
• Label annotation — draw, drag, resize, undo, redo
• BirdNET suggestions — accept or discard detections in one click
• Xeno-canto integration — search, import, and enrich recordings
• Bandpass playback — listen to specific frequency regions
• Fast frequency zoom — wheel, slider, and drag controls

Install

npm i audio-workbench

Note: audio-workbench expects wavesurfer.js as a peer dependency (v7). Install it with:

npm i wavesurfer.js@^7

Or include wavesurfer.js from a CDN in the browser:

<script src="https://unpkg.com/wavesurfer.js@7"></script>

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

npm ci
npm run typecheck
npm test
npm run build
npm run build:css
# Inspect what would be published
npm pack --dry-run

Publishing via CI:

• The CI workflow runs on push and for tags; it publishes when a tag matching v* is pushed.
• To enable automatic publishing to npm, add an NPM_TOKEN secret in GitHub repository settings (Settings → Secrets → Actions → NPM_TOKEN).
• Create and push a semver tag to trigger a release:

git tag -a v0.3.1 -m "release v0.3.1"
git push origin v0.3.1

The release job will build artifacts, publish to npm and PyPI, and create a GitHub Release including built files.

How to create tokens & add GitHub secrets

• NPM (automation token): create an automation token on https://www.npmjs.com/settings//tokens (Create New Token → Automation). Copy the token and add it to your repository secrets as NPM_TOKEN (Settings → Secrets → Actions → New repository secret). You can also set it via the GitHub CLI:

gh secret set NPM_TOKEN --body 'PASTE_TOKEN_HERE' -R owner/repo

• PyPI: create an API token on https://pypi.org/manage/account/#api-tokens and add it as PYPI_API_TOKEN in repository secrets. The CI uses this secret when uploading the Python package.

Packaging notes:

• The package includes model files under models/ (e.g., models/birdnet-v2.4/) — verify with npm pack --dry-run.

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