birdnet-onnx

A Rust library for running inference on BirdNET and Perch ONNX models with CUDA GPU support.

Features

• Support for BirdNET v2.4, v3.0, and Perch v2 models
• Automatic model type detection from ONNX tensor shapes
• Thread-safe classifier with builder pattern
• Top-K predictions with configurable confidence threshold
• Batch inference for GPU efficiency
• CLI tool for WAV file analysis

Supported Models

Installation

Add to your Cargo.toml:

[dependencies]
birdnet-onnx = { git = "https://github.com/tphakala/rust-birdnet-onnx" }

Library Usage

use birdnet_onnx::{Classifier, Result};

fn main() -> Result<()> {
    // Build classifier
    let classifier = Classifier::builder()
        .model_path("birdnet_v24.onnx")
        .labels_path("labels.txt")
        .top_k(5)
        .min_confidence(0.1)
        .build()?;

    // Prepare audio segment (48kHz, 3.0s = 144,000 samples for v2.4)
    let audio: Vec<f32> = load_audio_segment();

    // Run inference
    let result = classifier.predict(&audio)?;

    for pred in &result.predictions {
        println!("{}: {:.1}%", pred.species, pred.confidence * 100.0);
    }

    Ok(())
}

With CUDA GPU

use birdnet_onnx::{Classifier, execution_providers::CUDAExecutionProvider};

let classifier = Classifier::builder()
    .model_path("model.onnx")
    .labels_path("labels.txt")
    .execution_provider(CUDAExecutionProvider::default())
    .build()?;

Batch Inference

let segments: Vec<Vec<f32>> = chunk_audio_file();
let refs: Vec<&[f32]> = segments.iter().map(|s| s.as_slice()).collect();

let results = classifier.predict_batch(&refs)?;

CLI Usage

A basic CLI tool is included for quick testing of the library. It is not intended for production analysis tasks.

Build:

cargo build --release --bin birdnet-analyze

Analyze a WAV file:

birdnet-analyze recording.wav -m birdnet_v24.onnx -l labels.txt

With options:

birdnet-analyze recording.wav \
    -m birdnet_v24.onnx \
    -l labels.txt \
    -o 1.5 \          # 1.5s overlap between segments
    -k 5 \            # Top 5 predictions
    --min-confidence 0.2

Example output:

Analyzing: recording.wav (3m 21s, 48000 Hz)
Model: BirdNET v2.4 (3.0s segments, 1.5s overlap)

00:00.0  Eurasian Pygmy-Owl (92.4%)
00:01.5  Eurasian Pygmy-Owl (97.8%)
00:03.0  Eurasian Pygmy-Owl (98.5%)
...

134 segments analyzed in 1.2s

Development

Requires Task runner:

task --list        # Show available tasks
task build         # Build in debug mode
task build:release # Build in release mode
task test          # Run unit tests
task lint          # Run clippy
task ci            # Run all CI checks

License

MIT