fix(bsp): audio tasks wait for a whole block instead of padding with silence (all 10 BSPs)

[finger563]

Problem

Every BSP with audio output drains its TX stream buffer the same way (the code was copied from esp-box): each time the audio task wakes it takes whatever is queued, up to one block, zero-fills the rest, and writes a full block to I2S. The block is sized from the default sample rate (sample_rate × channels × 2 / 60), so at the rates emulators and games actually run at (26.6 kHz for a Genesis, for instance) one block is 30 ms of audio. Producers push one video frame of audio (~16.7 ms) at a time with frame-to-frame jitter, so any moment the stream momentarily holds less than one block becomes up to a block of injected silence — audible as stutter whenever the producer's cadence is uneven.

Measured on an ESP32-S3-BOX-3 running esp-box-emu (Sonic 3's special stages, emulator at a locked 60 fps): ~1000 padded blocks per play session with the current code, zero with this change, and the audio is clean by ear.

The comments in several boards argue the opposite — that writing only the available bytes "interleaves whole frames of silence into bursty streams". That observation was correct for the other naive option (write available immediately); this change keeps the DMA fed with whole blocks at a constant cadence while audio is flowing. The difference is when a partial block is allowed: only after a bounded wait, i.e. when the producer is idle or genuinely slower than real time, never merely because the producer's next frame hadn't arrived yet.

Change (all ten BSPs: esp-box, esp32-p4-eth, esp32-p4-function-ev-board, esp32-p4-module-dev-kit, esp32-p4-nano, esp32-p4-wifi6-dev-kit, m5stack-cardputer, m5stack-tab5, smartpanlee-sc01-plus, t-deck)

• Create the TX stream buffer with a trigger level of one block (capacity unchanged), so the task's receive waits for a whole block while audio is flowing; the stream's capacity is what absorbs the producer's jitter.
• Receive with a bounded timeout (40 ms, longer than one block at every rate these boards use). After a timeout, write what was received as is (the I2S driver concatenates partial writes without gaps), or a block of silence when there is nothing — which keeps the DMA fed exactly as before when a producer is idle (menu, pause).
• Per-board behaviour is preserved: the 16-bit sample alignment (& ~1) on the boards that use it and whole stereo frames (% 4) on the others; the 100 ms write timeouts and short-write logging on the P4 kits; on esp32-p4-module-dev-kit / esp32-p4-wifi6-dev-kit the wait happens before audio_tx_mutex_ is taken so a sample-rate change is never held off by it; cardputer / sc01-plus / t-deck apply their software volume and mute to the bytes actually received.

Hardware-verified on esp-box (ESP32-S3-BOX-3). The other nine are the same mechanism applied to the same construct; please review them with that in mind — I could not run them.

Related

esp-cpp/esp-box-emu#129 (the consumer side was verified there with a local edit of the managed component; that PR also moves the application's audio task above its emulator tasks so it is never starved — the second half of the fix, which is an application-side Task::BaseConfig decision).

Review follow-up

• The TX block (and therefore the stream buffer's trigger level) is trimmed to a whole number of frames at init on every board, using the board's own channel/byte constants, so a receive can never split a frame.
• The callback no longer silently discards a trailing partial frame; it writes what it received and logs a rate-limited warning if the byte count is ever misaligned.
• The receive timeout is a named constant (AUDIO_TX_RECEIVE_TIMEOUT_MS) with its rationale.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AWhoGwibqcKDhcG17mjVT1

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

2 open findings

• got -= got % 4 trims bytes after they have already been removed from the stream buffer, which… · New
• The 40 ms timeout is a hard-coded magic number that is closely tied to block sizing and expected… · New

What changed in this PR

Adjust ESP-BOX audio consumption to reduce audible stutter by waiting for full audio blocks instead of padding underfilled blocks with silence, while still keeping I2S fed during idle periods.

Changes:

• Set the FreeRTOS stream buffer trigger level to one block so the consumer typically waits for a full block.
• Switch the audio task to bounded receive (40 ms) and write only what was received (or silence on timeout/no data).
• Enforce whole 16-bit stereo frame alignment when writing to I2S.

File	Description
components/​esp-box/​src/​audio.cpp	Updates stream buffer configuration and audio task receive/write logic to avoid padding-induced silence and stutter.

🧠 Review effort: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.