audio-harness

Audio harness (observability + validation)

Pulp's agent-first way to turn "I can't hear it" / "does this sound right?" into inspectable, deterministic signal evidence — without a device, speakers, or a debugger. You are reading this skill because you need to prove, measure, debug, or regression-guard the audio a Pulp Processor emits.

Everything here is the test/tool layer, driven by pulp::format::HeadlessHost. Nothing in this skill runs on the realtime audio thread — measurements analyze buffers that have already left process(). The realtime probe path is a separate concern (see Roadmap).

It lives in two places, and the split is load-bearing:

• tools/audio/analysis/ — the pulp::audio-analysis lib (headers under <pulp/audio/analysis/…>). The pure buffer/file analysis: metrics, assertions, artifacts, and the FFT spectrum analyzers. It knows nothing about Processor, so the shipped pulp audio validate … CLI links it directly without pulling in any test/ library.
• test/support/ — the layers that need a Processor: signal generators, RenderScenario, contracts, and the scenario-driven Doctor wiring. Test-only; links the lib above.

The analysis target also owns the deterministic modal-extraction compiler (modal_extraction.hpp). It is offline-only: validate finite, sample-rate-qualified input, preserve recipe identity, and gate candidates with confidence/SNR/T60 evidence before emitting a ModalSpec; do not link it into realtime DSP or treat ranked candidates as host-facing parameter state.

Both use namespace pulp::test::audio, so the namespace does NOT tell you which target a symbol comes from — the include path does.

When to rope this skill in

• "There's no sound / it sounds wrong" — render the path offline and read the facts (peak/RMS/silence/frequency/NaN) instead of guessing.
• Building or changing a filter / oscillator / compressor / delay / sampler — state the contract and prove it (frequency response, delay time, decay, bypass-nulls).
• A regression hunt — "64 frames is fine but 128 is silent", "changing the sample rate chipmunked it", "the test tone toggle produces nothing".
• A DSP refactor — compare old vs new renders (exact / numeric / spectral).
• "How distorted is this?" — THD / THD+N and a harmonic breakdown.
• "What does this lowpass actually do at 8 kHz?" — a magnitude-response curve.
• "What's the group delay / latency of this filter?" — a phase + group-delay curve, in samples or seconds, per frequency.