1.4.1 CPU Installation

On macOS or Linux:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install "batbot[cpu]"
.venv/bin/batbot --help

On Windows, use PowerShell without changing its activation policy:

py -3 -m venv .venv
./.venv/Scripts/python.exe -m pip install --upgrade pip
./.venv/Scripts/python.exe -m pip install "batbot[cpu]"
./.venv/Scripts/batbot.exe --help

Or install from source in the chosen environment:

git clone https://github.com/Kitware/batbot
cd batbot
git lfs pull
python -m pip install -e ".[cpu,test]"

The base batbot distribution contains spectrogram tools. Classification requires one runtime extra. The CPU and GPU ONNX distributions share the same Python import and belong in separate environments. Existing base installations can add CPU inference with pip install "batbot[cpu]".

Binary wheels supply audio/image dependencies on supported desktops. Minimal Debian/Ubuntu systems may also need libgomp1, libsndfile1, and zlib1g (already included in the Docker images). Windows requires the Microsoft Visual C++ x64 runtime described in the ONNX Runtime installation guide.

1.4.2 NVIDIA GPU Installation

In a separate virtual environment, install the GPU extra:

python -m pip install "batbot[gpu]"
python -m pip check
batbot classify recording.jpg --provider cuda

This extra selects the ONNX Runtime 1.31 series and matching CUDA/cuDNN runtime libraries. BatBot preloads them before creating its session. A compatible NVIDIA driver is required; a separate CUDA toolkit installation is unnecessary. To change an existing CPU environment, uninstall onnxruntime first.

The GPU extra uses the CUDA 13 build. For an existing PyTorch environment or another CUDA version, install core batbot with the runtime specified in the upstream CUDA compatibility guide. --provider cuda requires CUDA initialization; automatic selection warns when CUDA initialization fails and CPU fallback is used.

1.4.3 Apple CoreML

The standard macOS runtime can also expose the Apple CoreML backend:

batbot classify recording.jpg --provider coreml

CoreML can use the Apple CPU, GPU, and Neural Engine, depending on supported model operators. It requires macOS 12 or newer and uses MLProgram with a fixed one-window inference batch to support this model’s dynamic batch axis. Multiple inference workers are still supported. CPU remains the default on macOS. Explicit CoreML selection fails if the provider is unavailable; see the CoreML documentation.

1.4.4 Paths and Caches

Python APIs accept pathlib.Path and native path strings, including spaces, Unicode names, Windows drive paths, and UNC shares. Home and environment variables are expanded before access. Folder discovery recognizes extension case consistently, including .WAV, .JPG, and .JPEG. Preprocessing preserves directory structure; flattening rejects colliding filenames. Inputs from separate Windows drives get distinct output namespaces.

Models use Pooch’s native per-user cache. Set BATBOT_CACHE_DIR to place the versioned model cache elsewhere, such as a writable container volume. Images use Python file access rather than OpenCV filename handling.

1.5.1 Species Classification

BatBot includes a 35-class MobileNet ONNX model for classifying spectrograms. The model is used from the package when available and can also be downloaded from its Kitware Data mirror with pooch:

batbot fetch
batbot fetch --pull

Classify an existing spectrogram, classify a WAV through BatBot’s built-in spectrogram step, or recursively process a large directory:

batbot classify recording.jpg
batbot classify-wav recording.wav --output recording.json
batbot classify-bulk ./recordings --input-type wav \
    --preprocess-workers 4 --num-workers 2 --output results.json
batbot classify-wav ./recordings --provider cuda --output results.json

Bulk JSON includes every per-file prediction plus label_counts, species_counts (which excludes NOISE), the noise count, failures, and mean confidence. Generated WAV spectrograms are temporary by default; pass --spectrogram-dir ./spectrograms to retain them. --num-workers runs multiple spectrogram inference jobs concurrently while sharing one validated ONNX Runtime session; results retain input order. --preprocess-workers runs WAV spectrogram generation in separate processes, then feeds generated images from multiple recordings into batch inference. Work is staged in bounded batches, temporary images are removed after each batch, and failed inputs are retained in the JSON report. The legacy batch command uses this same pipeline and accepts directories.

Batch commands display separate preprocessing and classification progress bars on stderr by default, leaving stdout available for JSON. Use --no-progress to disable them. --provider auto prefers CUDA when available; --provider cuda requires NVIDIA CUDA, --provider coreml selects Apple CoreML, and --provider cpu explicitly selects CPU inference.

The corresponding Python API follows the Scoutbot WIC pre / predict / post pattern. A convenience call is usually sufficient:

from batbot import classifier

if __name__ == '__main__':
    result = classifier.classify('recording.jpg')[0]
    wav_result = classifier.classify_wav('recording.wav')
    folder = classifier.classify_bulk(
        ['./recordings'], input_type='wav', num_workers=2,
        preprocess_workers=4, progress=True,
    )

When using multiple preprocessing processes from a standalone Python script, put the call inside if __name__ == '__main__': so spawned workers can import the script safely. The CLI handles this entry point automatically.

To evaluate a labeled dataset arranged as LABEL/*.wav, install scikit-learn and run the included performance example:

pip install "batbot[cpu,performance]"
python examples/plot_classifier_performance.py ./validation \
    --cache predictions.json --output performance.png

The plot includes count, true-normalized, and prediction-normalized confusion matrices, top-k accuracy, Matthews correlation, and NOISE precision-recall and ROC diagnostics when that label is present. Species codes are reordered by genus before plotting so the shaded error regions remain contiguous.