whalu 0.1.1

Marine bioacoustics detection pipeline. Slides a 5-second window over continuous hydrophone recordings, runs the Google Perch multispecies whale model, and stores detections as Parquet files for analysis.

Install

pip install whalu

Or with uv:

uv add whalu

CLI

whalu [-v] <command> ...

whalu scan mbari

whalu scan orcasound

whalu analyze

whalu info

Examples

# Single file, first hour only (quick test)
whalu scan mbari --start 2026-03 --max-files 1 --limit-hours 1

# Full month
whalu scan mbari --start 2026-03 --output-dir data/detections/mbari

# Multi-month date range (blue whale season)
whalu scan mbari --start 2023-07 --end 2023-10

# Orcasound validation sample
whalu scan orcasound

# Analyze stored detections
whalu analyze --input-dir data/detections/mbari

# Show source metadata
whalu info mbari
whalu info

Supported data sources

How it works

• Streams 4 GB daily files via S3 range requests in 1-hour chunks (~172 MB each), bounded RAM
• Applies sigmoid activation (correct for the multi-label whale model, not softmax)
• Emits detections only where confidence >= 0.5
• Stores one Parquet file per audio source, runs are resumable

Detection model

Google multispecies_whale via perch-hoplite. 12 classes: blue whale (Bm), fin whale (Bp), humpback (Mn), minke (Ba), Bryde's (Be), sei (Bs), right whale (Eg), orca (Oo), and call types (Upcall, Gunshot, Call, Echolocation, Whistle).