Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Installation

Authors
Affiliations
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley

There are three ways to install, depending on how you work:

  1. pixi (recommended) — a reproducible, cross-platform environment. Best choice if you’re comfortable with a terminal.

  2. pip — if you already manage your own Python / JupyterLab environment.

  3. Desktop app — a no-code, no-terminal download for the small set of users who don’t work in Python tooling at all.

1. pixi (recommended)

pixi builds an isolated, lock-fileable environment and pulls both conda-forge packages (Python, JupyterLab) and PyPI packages (jupyter-bioacoustic) in one step.

Quick start (new project)

pixi init my-annotations
cd my-annotations
pixi add jupyterlab "python>=3.11"          # conda-forge
pixi add --pypi jupyter-bioacoustic          # PyPI
pixi run jupyter lab

Or declare it in pixi.toml / pyproject.toml

[tool.pixi.dependencies]
python = ">=3.11"
jupyterlab = ">=4.0,<5"

[tool.pixi.pypi-dependencies]
jupyter-bioacoustic = ">=0.9,<1.0"

Then pixi install and pixi run jupyter lab.

2. pip

If you already have a Python ≥ 3.9 environment with JupyterLab:

pip install jupyter-bioacoustic

Or install a specific release wheel from GitHub Releases (no Node.js or build step needed):

pip install jupyter_bioacoustic-<version>-py3-none-any.whl

Some sources need packages that aren’t installed by default; see Requirements.

3. Desktop app (no-code)

A double-click desktop app (no terminal, no pip, no pixi) that runs the annotator in your browser via a menu-bar / system-tray icon. Download it from GitHub Releases (since v0.9.3):

Command-line tools (optional)

The app is self-contained, so its jba CLI (jba lab, jba validate, …) isn’t on your PATH. If you do want it in a terminal, add a small shell function pointing at the app’s bundled environment:

# macOS (zsh)
cat >> ~/.zshrc <<'EOF'
jba() {
  local d="$HOME/Library/Application Support/JupyterBioacoustic/env/.pixi/envs/default/bin"
  PATH="$d:$PATH" "$d/jba" "$@"
}
EOF
source ~/.zshrc
# Windows (PowerShell) — open a new terminal afterward
Add-Content $PROFILE @'
function jba {
  $e = "$env:LOCALAPPDATA\JupyterBioacoustic\env\.pixi\envs\default"
  $env:PATH = "$e;$e\Scripts;$e\Library\bin;$env:PATH"
  & "$e\Scripts\jba.exe" @args
}
'@

(if you’ve never used a PowerShell profile, you may first need Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.)

Uninstalling

From the app: tray icon → Uninstall… — it asks for confirmation, then removes the app and its downloaded environment.

From a terminal (quit the app first, via tray → Quit):

# macOS
rm -rf ~/Library/Application\ Support/JupyterBioacoustic
rm -rf /Applications/JupyterBioacoustic.app ~/Applications/JupyterBioacoustic.app
rm -f  ~/Applications/"Set JupyterBioacoustic Folder.command" \
       /Applications/"Set JupyterBioacoustic Folder.command"
# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\JupyterBioacoustic"
Remove-Item -Force "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Jupyter Bioacoustic.lnk"

Troubleshooting: blank or crashed browser tab

If the browser opens to a blank or crashed (grey) page, the app itself is fine — the menu-bar / system-tray icon is still running, and the problem is your browser’s renderer (this commonly happens right after the browser auto-updates in the background). Fix it:

  1. Fully quit your browser (Cmd-Q on macOS — not just the window) and reopen it, then click the tray icon → Open in Browser again. A clean relaunch loads the updated browser properly.

  2. If it persists, clear the browser’s GPU cache (Chrome: quit, then remove ~/Library/Application Support/Google/Chrome/*/GPUCache), or open the app in a different browser.

The tray menu’s “Page blank or crashed? — Help” item shows these same steps.

Requirements

Remote FLAC and WAV audio is read by byte range (only the clip being played is downloaded); other formats are downloaded and cached in full. No ffmpeg is needed.

The extension auto-registers on install — just launch JupyterLab and go.

See the Development guide on the wiki for building from source.