Skip to content

Keep audio smooth while an LVGL display redraws - #11909

Merged
tannewt merged 5 commits into
adafruit:mainfrom
mikeysklar:lvgl-refresh-audio
Nov 18, 2026
Merged

tannewt merged 5 commits into
adafruit:mainfrom
mikeysklar:lvgl-refresh-audio

Conversation

@mikeysklar

@mikeysklar mikeysklar commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

What

Screen redraws now pause to let audio refill.

Why

On the Metro ESP32-P4, scrolling a playlist slowed and garbled MP3 audio.

@BlitzCityDIY found this while testing her Winamp player on the P4.

Changes

  1. display.refresh() runs background tasks while it draws, so I2S can refill. The old framebufferio path already does this (Fix garbled I2S audio on the ESP32-P4 #11875).
  2. Palette TileGrids are drawn straight into the canvas through a lookup table.

Results

Liz's Winamp player, Raspberry Pi Touch Display 2, scripted playlist scroll:

Playlist scroll main this PR
audio speed (1.0 = normal) 0.670 0.996
audio dropouts 118 0

App tips (not in this PR)

Two user code changes that help on the P4:

  • RaspberryPiTouchDisplay2(bus, i2c, color_depth=16): redraws about 35% faster than the 24-bit default.
  • sdioio.SDCard(..., frequency=40_000_000): the 40 MHz maximum instead of 25 MHz
The two changes in Liz's code.py
panel = adafruit_ili9881.RaspberryPiTouchDisplay2(bus, i2c, color_depth=16)
sd = sdioio.SDCard(
    clock=board.SD_CLK,
    command=board.SD_CMD,
    data=(board.SD_DATA0, board.SD_DATA1, board.SD_DATA2, board.SD_DATA3),
    frequency=40_000_000)

Follow-up

Playing from the SD card still drops some audio while scrolling (about 45 per 20 s). Refilling audio from its own high-priority task, so SD reads and decoding never wait on the display, should fix that. @tannewt idea that would be good to add as a separate PR.

Written with Claude Code.

mikeysklar and others added 5 commits November 18, 2026 11:46
An explicit refresh() renders on the VM thread, so audio buffers were
not refilled until it returned. A playlist scroll on the Metro ESP32-P4
with the Pi Touch Display 2 ran audio at 0.67x speed. Run background
tasks after each flushed chunk, like the legacy framebufferio path does
since adafruit#11875. A paced frame callback that fires during that yield waits
for the next frame instead of starting a nested render.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A full re-render of a large text grid is one flush chunk but can take
longer than the I2S DMA buffers last. Run background tasks after each
batch of 64 cells when called from an explicit refresh().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
For 1/2/4/8 bit bitmaps with a Palette, write cell pixels straight into
the ARGB8888 or RGB565 canvas through a 256 entry lookup table instead
of one lv_draw_image() per cell. Clear cells with memset rather than
lv_draw_buf_clear(), which flushed the cache for whole rows each call.
Framebuffer CRCs match the old path at both color depths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A BusDisplay auto-refresh queued while an explicit refresh() runs
background tasks could start a nested lv_refr_now() in the middle of the
framebuffer render. Skip it; it draws on the next tick, like the paced
framebuffer displays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The per-display lv_refresh_yield was always set together with the global
displayio_lvgl_refresh_yield. The LVGL lock is held for the whole
explicit refresh, so only that display's flush can see the global.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mikeysklar
mikeysklar requested a review from tannewt November 18, 2026 20:26
@mikeysklar
mikeysklar marked this pull request as ready for review November 18, 2026 20:29

@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.

Why do we want to yield only on explicit refresh? Isn't it true that auto-refreshes also need to yield?

Comment thread shared-module/displayio/lvgl/TileGrid.c Resolved
Comment thread shared-module/displayio/lvgl/TileGrid.c Resolved
@mikeysklar

Copy link
Copy Markdown
Collaborator Author

Auto-refresh needs a yield too.

Liz's player sets auto_refresh = False, so I got overly focused on that one scenario.

BusDisplay and UVC auto-refresh draw inside a background callback with nothing yielding.

Plan: render framebuffer auto-refresh on the CircuitPython thread, the way BusDisplay already does.

All three paths then yield with background_callback_allow(), like legacy framebufferio.

@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.

Thank you!

@tannewt
tannewt merged commit 9a6e4f2 into adafruit:main Nov 18, 2026
643 checks passed
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