New skill: environmental-audio-dsp — measurement-first DSP for field recordings

Why a skill

When working on DSP for environmental / field audio (birdsong, soundscapes, bioacoustics), the agent should apply a rigorous measurement-first methodology instead of guessing filter parameters. A working session on a 6 h alpine recording demonstrated a repeatable expert workflow — isolate the target call, measure its band, characterize the noise sources, derive HPF cutoff + roll-off, source a noise profile from signal-free gaps, set NR strength, and validate by classifier confidence. That workflow was improvised; a skill makes it reliable and reusable across any field recording.

A skill (not static CLAUDE.md docs) is the right vehicle because it's an on-demand, multi-step procedure with decision rules and bundled analysis scripts, loaded only when the task is field-audio DSP — so it can be detailed without bloating always-on context.

What the skill encodes

1. Measure, never assume. Before recommending any filter/NR, characterize signal and noise spectra from the actual recording:

• Welch PSD, spectrogram, per-octave-band energy, cumulative-energy percentiles.
• Isolate the target signal from background via excess-over-background (loudest frame minus a quiet frame) so the call's true band is separated from wind/water.

2. Noise-source taxonomy & signatures

• Wind: sub-150–300 Hz rumble, low-tilted, non-stationary (gusts) -> high-pass filter.
• Water/stream: broadband, fairly stationary, intrudes into mid-frequency call bands -> spectral NR (HPF cannot touch it).
• Plus rain (broadband bursts), insects (narrow high-frequency bands), anthropogenic (aircraft/vehicle: low broadband + engine harmonics).

3. Filter decision rules

• HPF cutoff = below the lowest target-signal energy, with margin, derived from the measured signal/noise gap.
• Roll-off: 4th-order Butterworth (24 dB/oct), zero-phase (sosfiltfilt doubles the effective magnitude slope to ~48 dB/oct with no phase smear). Steeper when noise sits just below the cutoff; gentler to avoid pre-ringing on transients (e.g. woodpecker drums).
• HPF removes only sub-cutoff energy; in-band noise is NR's job.

4. Spectral-NR methodology

• Needs a noise profile. In signal-dense recordings (dawn chorus) there is no clean segment inside the clip — source the profile from signal-free segments elsewhere in the same recording (use detection timestamps / silence detection), and verify the floor is stationary across the borrow gap.
• Gentle prop_decrease for tonal/narrowband calls; aggressive NR causes musical noise and erodes tonal calls. Tonal-signal-over-broadband-noise is the favorable case.

5. Validate empirically. Re-score with the detector (is target-species confidence preserved?) and measure noise-floor reduction; sweep parameters rather than eyeballing.

6. Reporting hygiene. Report SNR, in-band vs out-of-band noise levels, and label timestamps with the recording's local timezone (not UTC) when building a timeline.

Bundled scripts (ship with the skill)

• measure_spectrum.py — PSD + per-band energy + cumulative-energy percentiles for a segment.
• isolate_signal.py — excess-over-background to recover a target call's true band.
• hpf_safety.py — fraction of target-signal energy removed by candidate HPF cutoffs.
• find_noise_profile.py — locate signal-free gaps from a detection JSON and report noise-floor stability across them.

Acceptance

• Invoking the skill on a field recording + a target signal produces a measurement-grounded filter/NR recommendation (HPF cutoff + roll-off, NR strength, noise-profile source) with the supporting numbers and an explicit validation step.
• The methodology section makes the agent default to measuring before filtering, and to sourcing noise profiles from signal-free segments when the clip is dense.

Provenance

Distilled from a field-validation session on the AudioClassifier project (TimZander/AudioClassifier). Concrete measurements and rationale live in that repo's PR #1 thread and issues #32/#33/#34. Out of scope (decided): elevation/habitat-aware species filtering (can't be done accurately).

Use the skill specification as the entry point, then review the four named scripts: measure_spectrum.py, isolate_signal.py, hpf_safety.py, and find_noise_profile.py. Confirm the skill measures before filtering, uses signal-free segments for noise profiles, and validates recommendations with supporting measurements and detector results as described in Acceptance.