Skip to content

Keep audio smooth during display auto-refresh too - #11923

Open
mikeysklar wants to merge 9 commits into
adafruit:mainfrom
mikeysklar:lvgl-autorefresh-yield
Open

mikeysklar wants to merge 9 commits into
adafruit:mainfrom
mikeysklar:lvgl-autorefresh-yield

Conversation

@mikeysklar

Copy link
Copy Markdown
Collaborator

What

Auto-refresh now lets audio refill while the screen redraws, like display.refresh() does.

Why

@tannewt asked on #11909 why only explicit refresh yields.

Follow-up to #11909, the Winamp player speedups.

Changes

Change Why
Framebuffer auto-refresh renders on the CircuitPython thread from a background callback, like BusDisplay already does. Both yield while rendering Audio refills during auto-refresh too
Update esp-idf for adafruit/esp-idf#25 Its SD teardown left a lock counted as held. With rendering on this thread, that hung USB on the Metro ESP32-P4 after Ctrl-C

The esp-idf commit moves to the merge commit once adafruit/esp-idf#25 merges.

Testing

Metro ESP32-P4, Liz's Winamp player on SD, Ctrl-C, 2 min REPL idle.

stock esp-idf this PR
USB and REPL still up 0 of 3 runs 3 of 3 runs

Audio during auto-refresh not measured; Liz's player turns it off.

Written with Claude Code. Measurements are from the hardware runs above.

🤖 Generated with Claude Code

mikeysklar and others added 3 commits November 19, 2026 10:09
sd_host_del_sdmmc_controller() deleted its mutex while holding it, which
left the calling task counted as holding a mutex forever. That task then
kept any priority it inherited. See espressif/esp-idf#19402.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Framebuffer auto-refresh now renders on the CircuitPython thread from a
background callback, the way BusDisplay already does. Both allow other
callbacks to run while they render, like the legacy framebufferio, so
audio can refill. A refresh skipped because another render is yielding
is queued again instead of dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Say what a yielding render needs from its caller instead of naming one
kind of caller, say why the UVC frame boundary renders without yielding,
comment the paced re-queue like its twin, and drop history from the
yield comments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@tannewt tannewt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is complicated. Could we move audio generation to a separate task instead? That way we can give it priority explicitly instead of requiring yields here.

Comment thread ports/espressif/supervisor/lvgl_port.c Resolved
mikeysklar and others added 3 commits November 19, 2026 19:12
The I2S interrupt now wakes a task, above the LVGL render task, instead of
queuing a background callback. So a long display render can't starve audio.

Preventing background callbacks still keeps refill out: a new port hook,
port_background_lock(), is taken while they are prevented or running, and
the fill task holds the same lock while it refills.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Audio now refills from its own task above LVGL, so auto-refresh no longer
needs to move to the CircuitPython thread and yield. This undoes the earlier
auto-refresh yield and its comment tidy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Static storage for it overflowed internal RAM on the ESP32-S2 devkit.
It is now created with the first I2SOut. Until then there is no fill
task, so lock and unlock do nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mikeysklar
mikeysklar requested a review from tannewt November 20, 2026 15:55
@mikeysklar

Copy link
Copy Markdown
Collaborator Author

Audio refill now runs on its own task, above the LVGL task.

Auto-refresh is back on the LVGL task with no yields, so the second callback and the yield argument are gone.

I2S underruns while scrolling the playlist, Metro ESP32-P4 main this PR
auto_refresh off 0 / 0 / 1 0 in 9 runs
auto_refresh on 61 / 65 / 59 0 in 4 runs

Like Zephyr's I2SOut thread, refill can now run mid-change. MP3Decoder.deinit() while playing and an SD read error mid-MP3 aren't safe yet.

Code that calls background_callback_prevent() still keeps refill out.

@tannewt tannewt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's introduce a specific audiocore lock instead of piggy backing on the background task stuff. (We want to remove background tasks completely when we're in an RTOS.)

Comment thread supervisor/port.h Resolved
mikeysklar and others added 3 commits November 20, 2026 10:10
Same code as before. adafruit/esp-idf#25 has merged, so use its merge
commit on circuitpython-v6.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tannewt asked for an audiocore lock rather than a hook in background
callbacks, which go away under an RTOS. Drop port_background_lock and
add audiocore_lock()/audiocore_unlock(): a no-op by default, a recursive
mutex on Espressif. The I2S fill task holds it while it fetches.

I2S play, stop and deinit take it, and so does MP3Decoder wherever it
changes the decoder, including deinit so the fill task can't use freed
buffers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
As tannewt suggested, loading code reports errors so the caller can give
the lock back first. MP3Decoder keeps a failed read's errno and returns
GET_BUFFER_ERROR, and set_file raises it after unlocking. I2S play sets
the clock, which can raise, before locking, so it no longer needs the
NLR jump callback.

This also stops an OSError being raised on the fill task, where nothing
can catch it. A read error mid-track now ends playback instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mikeysklar

Copy link
Copy Markdown
Collaborator Author

There's now an audiocore_lock() / audiocore_unlock() in shared-module/audiocore, a no-op by default and a recursive mutex on Espressif.

The background callback hook is gone.

Tested on a Metro ESP32-P4 with Liz's player from SD: Ctrl-C mid-track 2 of 2 with USB and the REPL still up after 2 min, and 0 underruns while scrolling in 5 runs.

@mikeysklar
mikeysklar requested a review from tannewt November 20, 2026 21:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants