WAVStream: opt-in warm output so back-to-back clips don't click (ES8311) - #301

CI note: the one red job is the macOS unit-test runner failing tests/test_graphical_simulate_long_press.py::test_short_click_does_not_fire_long_pressed (a timing-sensitive input test; the same test failed on main in run 35064389249). Both audio test modules touched by this PR pass on all three runners, and the PR changes nothing in input or LVGL timing. I can't re-run the job from a fork; a maintainer re-run should go green.

CI note: the one red job is the macOS unit-test runner failing tests/test_graphical_simulate_long_press.py::test_short_click_does_not_fire_long_pressed

Indeed, that test is flaky on the (slow?) CI macOS machine(s). I've committed a fix attempt.

Thanks — brought the branch up to date with main (merge commit beb688f; only CHANGELOG.md needed resolving, both sides kept) so it now carries your simulate_long_press deflake commits and CI reruns against them.

Since it adds complexity, I'm a bit hesitant to merge as-is.

As I understand it, it doesn't really solve the problem, as there will still be an audible click at the start of the first clip, as well as when the user waits more than 30 seconds to play the next clip.

Many of these audio DAC have a section in the datasheet with something like "click-free start" or "glitch-free startup" which describes how to start playing audio without clicks. I haven't studied the ES8311 but perhaps that could offer an even better solution?

BTW, I also fixed another test failure so feel free to re-sync this branch :-)

Fair pushback — you're right that it's a mitigation, not a cure: the first clip after boot and the first clip after the 30 s idle still get the transition. (Branch re-synced with main again; only CHANGELOG conflicted.)

On the datasheet route: I looked at what our driver actually does around a clip versus what the ES8311 documents as the pop-free sequence, and there's a real gap.

• Today on_open/on_close only toggle the REG31 soft-mute (bits 6:5), and the DAC stays powered (REG12 = 0x00) the whole time — including while WAVStream stops and restarts MCLK/BCLK/LRCK for every clip. Stopping the clocks with the DAC path powered is exactly the case the datasheet warns produces pops; the soft-mute only ramps the digital signal, it does nothing about the analog stage seeing its clocks vanish and reappear.
• The documented click-free sequence is: on stop → soft-mute → power the DAC/analog output down (REG12 DAC power-down, REG13/REG0D output + analog off) → then stop the clocks; on start → clocks first → power the DAC/analog up → un-mute with the DAC ramp (REG37 DAC_RAMPRATE bits[7:4], which we currently leave at 0 = no ramp; only EQ-bypass 0x08 is set). Espressif's esp_codec_dev es8311 driver also does nothing beyond the REG31 mute, so mirroring it wouldn't have found this.

So I think you're right that there's a better fix: implement the power-sequenced open/close in the ES8311 driver (dac_power(on) + ramp rate), have the board hooks use it, and keep WAVStream unchanged. If that removes the click on the bench, it's strictly simpler than the warm output (no timer, no I2S peripheral held, no first-clip residual); the cost is a few tens of ms of codec power-up + ramp latency at each clip start, which is fine for a soundboard.

Proposal: park this PR, I test the datasheet sequence on the 3.5 by ear, and report back with numbers/recording. If it works, I'll rework this into that (much smaller) change; if the click survives the proper sequence, that's evidence the transition is in the I2S peripheral start itself and the warm output is the pragmatic answer. Sound OK?

Bench results (Waveshare 3.5 with its speaker, ES8311; loud test clip = 150 ms digital silence then a 2 s near-full-scale 660/1320 Hz tone so any click is the hardware transition, not the file; volume 100; codec registers sampled mid-tone to confirm DAC powered + un-muted on every play; judged by ear):

So the datasheet's click-free start doesn't help here: the pop isn't in the codec's mute/power path, it's in the MCLK/I2S start itself (or the amp reacting to it), and only clock continuity removes it. Set C also answers the residual-click worry: with the silence-primed un-mute the first clip after a release was clean too, so the remaining cost of the warm approach is the clocks running for the idle window, not an audible artefact.

Caveats: one board, one listener, one clip. If you'd still rather avoid the complexity, the one cheaper idea the data leaves open is applying the same silence-primed un-mute to the non-warm path (start clocks → prime with silence → un-mute) and testing whether that alone is enough; I'm happy to bench that as a follow-up, but on this evidence I'd merge the warm output as-is.