Metadata-Version: 2.4
Name: nocturne-fieldrecordist
Version: 0.1.0
Summary: Combined BirdNET + Nocturne bioacoustic classification for wildlife field-recordist libraries: scan a directory, get a species-tagged SQLite catalog. Includes a Reaper action for in-DAW markers.
Author: Stratus Labs
License: Apache-2.0
Project-URL: Homepage, https://nocturne.runstratus.com
Project-URL: Source, https://github.com/stratus-labs/nocturne-fieldrecordist
Keywords: bioacoustics,field-recording,birdnet,nocturne,wildlife,reaper,species-classification
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: nocturne-client>=1.0
Requires-Dist: birdnetlib>=0.18
Requires-Dist: tensorflow>=2.15
Requires-Dist: librosa>=0.10

# nocturne-fieldrecordist

Combined **BirdNET + Nocturne** bioacoustic classification for wildlife field-recordist libraries.

- **BirdNET** ≈ 3,000 bird species (runs locally via `birdnetlib`)
- **Nocturne** ≈ 2,182 non-bird species — insects, amphibians, non-bird mammals, reptiles (Stratus Labs hosted API at `nocturne.runstratus.com`)
- Scan a directory → get a species-tagged **SQLite catalog** searchable by species, model, confidence
- Ships with a **Reaper action** that adds species markers to a selected media item

Built by [Stratus Labs](https://nocturne.runstratus.com). Nocturne itself is Apache-2.0; BirdNET is licensed separately (see the [BirdNET-Analyzer](https://github.com/kahst/BirdNET-Analyzer) repo).

## Install

```bash
pip install nocturne-fieldrecordist
```

This pulls in `nocturne-client`, `birdnetlib`, and `tensorflow` (BirdNET's runtime). Total install ~2 GB. First run of BirdNET downloads the model (~50 MB, cached).

## Scan a library

```bash
nocturne-fr scan ~/recordings --db library.sqlite
```

Recurses into subdirectories; audio extensions: `.wav .flac .mp3 .m4a .ogg .aif .aiff`. Skips files already in the DB unless you pass `--reprocess`. Progress prints to stderr; a JSON summary lands on stdout.

## Classify a single clip

```bash
nocturne-fr classify path/to/clip.wav
```

Prints a JSON list of detections from both models.

## Query the catalog

```bash
# All Nocturne detections above 0.3 confidence, limit 50
nocturne-fr query --db library.sqlite --model nocturne --min-conf 0.3 --limit 50

# Everything matching "wren" (either BirdNET or Nocturne, any confidence)
nocturne-fr query --db library.sqlite --species wren
```

## Python API

```python
from nocturne_fieldrecordist import DualClassifier, scan_path

dc = DualClassifier(birdnet_min_conf=0.5, nocturne_min_conf=0.2, nocturne_top_k=5)
for det in dc.classify("recording.wav"):
    print(det.source_model, det.species, det.confidence, det.start_time_s)

# Or scan a whole tree:
summary = scan_path("~/recordings", db_path="library.sqlite", dc=dc)
```

## Reaper integration

Install the action from `nocturne_fieldrecordist/reaper/nocturne_reaper.py`:

1. Set Reaper's ReaScript Python interpreter to the same env where you `pip install`ed this package (Preferences → Plug-ins → ReaScript).
2. Actions → Load ReaScript → select `nocturne_reaper.py`.
3. Optional: bind a keyboard shortcut.

Select a media item, trigger the action, and get one Reaper marker per detection: `[bir] Passer domesticus (0.87)` or `[noc] Neoconocephalus triops (0.42)`. BirdNET markers get one color, Nocturne another.

## Tunables

- `--birdnet-min-conf` (default 0.5) — BirdNET's author recommends ≥0.5.
- `--nocturne-min-conf` (default 0.15) — Nocturne v1's per-class-calibrated thresholds sit around 0.15-0.30 across the vocab.
- `--top-k` (default 3) — how many Nocturne predictions to keep per file.

## Nocturne API auth

Anonymous is fine (rate-limited to 10 req/min per IP). For batch libraries pass a paid-tier key:

```bash
export NOCTURNE_KEY=ck_...
nocturne-fr scan ~/recordings --db library.sqlite --nocturne-key $NOCTURNE_KEY
```

Sign up at [nocturne.runstratus.com/pricing](https://nocturne.runstratus.com/pricing).

## SQLite schema

Two tables: `recordings` (one row per audio file) and `detections` (one row per model prediction). See `schema.sql` for indexes + full columns. The catalog file is portable — copy it, ship it to a Flask app, load it in DB Browser, whatever fits your workflow.
