WAVStream: drain queued I2S audio by wall-clock instead of a fixed ibuf sleep - #282

Problem

On ESP32, WAVStream.play() sleeps a fixed ibuf / bytes_per_second after the last I2S write before firing on_complete. But the blocking write loop already paces against DMA drain (measured: writes complete in almost exactly the clip duration), so nearly nothing is left queued when the loop exits — and the fixed estimate overshoots by the full ibuf duration, worst at low byte rates:

(Measured on a Waveshare ESP32-S3-Touch-LCD-3.5 through an ES8311 "Speaker" output, player start → on_complete; the residual ~200 ms is player-thread startup + codec on_open, not drain error.)

Every clip appears to run long, and anything sequencing off on_complete (playlists, repeat chaining, sound-then-action flows) inherits the same dead gap between clips.

Fix

Track the duration of the audio actually queued (_progress_samples over the original rate — correct for ADPCM and for upsampled playback, since upsampling scales data and rate by the same factor) and the wall-clock time spent queueing it, then sleep only the difference: compute_drain_ms(played_ms, elapsed_ms). If playback ran long (stalls), the drain is clamped to zero rather than sleeping a negative/absurd amount.

This also self-adapts if the underlying machine.I2S buffering behavior ever changes: the drain is derived from observed pacing, not from a driver-internal constant.

Verification

• Raw machine.I2S consumption rates were measured first on hardware to rule out clock/slot-config bugs: mono and stereo at 22050 Hz and mono at 8000 Hz all drain within ~1% of nominal, deterministically. The wall-clock discrepancies were entirely the drain sleep.
• Fix verified end-to-end on the ESP32-S3 device by loading the patched module (numbers above), including a repeat run through the real AudioManager → output on_open/on_close path.
• New unit tests for compute_drain_ms; full tests/test_stream_wav.py and tests/test_audiomanager.py pass on the desktop build.
• ruff clean.

Merge checklist

• tests/test_stream_wav.py passes
• tests/test_audiomanager.py passes
• CHANGELOG entry under "Future release"
• Verified on ESP32 hardware (Waveshare ESP32-S3-Touch-LCD-3.5, ES8311)

🤖 Generated with Claude Code