Guide — Tuning segmentation
When detect_units over- or under-segments, work through these knobs in order.
1. Verify the bandpass
The detector estimates the noise floor from the input itself. If the input contains broadband out-of-band energy (low-frequency mooring rumble, high-frequency electronics noise), the noise floor estimate will be wrong. Always bandpass to the species' vocal range first.
2. Look at the envelope
The envelope and the threshold line are usually the fastest diagnostic. Plot them with the units you got, and the failure mode is usually obvious.
3. Choose the envelope method
| Method | When |
|---|---|
"hilbert" | Default. Broadband calls, short recordings, stable background. Runs at sample rate; chunked internally to bound memory. |
"rms" | Long recordings, drifting background, archival LP transfers. Median-smoothed RMS in dB. |
4. Choose the noise-floor estimator
| Method | When |
|---|---|
"global" | Default. Constant median across the entire envelope. |
"local" | Sliding-window low-percentile (interpolated back to frame resolution). Use when the background drifts on a timescale shorter than the recording. |
5. Adjust threshold and merge gap
- Too many tiny units (clicks within a click-train, or sub-syllables of a single call): increase
merge_gap_s. - Distinct calls fused into one: decrease
merge_gap_s. - Quiet calls missed: lower
threshold_db. - Noise becoming units: raise
threshold_db, or set a stricterabsolute_silence_dbfloor.
6. Plot the duration histogram
If the histogram has a tall spike at min_dur_s or a hard
cliff at max_dur_s, the duration filter is doing too much work
and the upstream parameters need attention.
