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> ...
| Command | Description |
|---|---|
whalu scan mbari |
Run detection over MBARI Pacific Sound (S3, no auth required) |
whalu scan orcasound |
Run detection over Orcasound labeled samples (S3, no auth required) |
whalu analyze |
Summarize and visualize stored detections |
whalu info [source] |
Show sensor/dataset metadata for a source |
whalu scan mbari
| Flag | Default | Description |
|---|---|---|
--start YYYY-MM |
required | First year-month to process |
--end YYYY-MM |
same as --start |
Last year-month (inclusive) |
--max-files N |
all | Stop after N files |
--limit-hours N |
full file | Only process first N hours per file |
--output-dir PATH |
data/detections/mbari |
Where to write Parquet files |
whalu scan orcasound
| Flag | Default | Description |
|---|---|---|
--key S3_KEY |
labeled killer whale sample | Specific S3 key to process |
--output-dir PATH |
data/detections/orcasound |
Where to write Parquet files |
whalu analyze
| Flag | Default | Description |
|---|---|---|
--input-dir PATH |
required | Directory of detection Parquet files |
--top-n N |
5 |
Number of top species shown in heatmap |
whalu info
| Flag | Default | Description |
|---|---|---|
source |
(all) | Source ID to inspect (mbari, orcasound) |
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
| Source | Location | Coverage | Format |
|---|---|---|---|
| MBARI Pacific Sound | Monterey Canyon, CA | 2015-present | 16 kHz 24-bit WAV, 1 file/day (4.1 GB) |
| Orcasound | Puget Sound, WA | 2017-present | 20 kHz 16-bit WAV |
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).
Metadata
Release files for whalu 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| whalu-0.1.1.tar.gz | 305.1 kB | Without provenance | Details for whalu-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| whalu-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for whalu-0.1.1-py3-none-any.whl |
Total release size: 332.0 kB
Release files / whalu-0.1.1.tar.gz
| Download URL | whalu-0.1.1.tar.gz |
|---|---|
| Size | 305.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dddd52d5a48da295fb6116a2489504a5b2d69769303dca706e4d7cbfb4c417aa
|
|
BLAKE2b-256 checksum How to use checksums |
4dd867eef33f492169e3d9587ab4284891e85efd7631e169a53087fe1bf84056
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / whalu-0.1.1-py3-none-any.whl
| Download URL | whalu-0.1.1-py3-none-any.whl |
|---|---|
| Size | 26.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0a5248efc06759c6e06541a23cf8b9273ebe0fe9a98cbd0a35e6a4bb214511ef
|
|
BLAKE2b-256 checksum How to use checksums |
b64ffdccaf751ea6a4eab1c3418cc2f82febf881048bed4a77ac7cffa4e678ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for whalu 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.