Introduction

Play RV565 video files on CircuitPython displays.

RV565 stores video as independently zlib-compressed frames whose decoded bytes are already big-endian RGB565, the native pixel format of ST7789-class SPI panels (format specification, paper: arXiv:2610.35935). This library reads them in pure Python with CircuitPython’s built-in zlib and shows them with displayio, or sends them straight to an ST7789.

It is the easy way to try RV565 on a board without a C toolchain. The RV565 C library (Arduino, ESP-IDF, Pico SDK) is the fast way: it reaches the clip’s full 24 FPS.

Dependencies

This library depends on:

• Adafruit CircuitPython 9 or later (8.x should work but is untested), on a board whose build includes zlib, displayio and bitmaptools. Most ESP32-S3 and RP2350 builds include all three; check the module support matrix for your board.

• Adafruit CircuitPython ST7789, only for the examples that drive an external ST7789.

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle or individual libraries can be installed using circup.

Performance

Measured on a Raspberry Pi Pico 2 (RP2350, CircuitPython 10.3.1), playing the 180x135, 24 FPS test pattern to a 320x240 ST7789 on SPI at 40 MHz. Colours, orientation and position were correct with both players:

DirectPlayer’s draw is close to the SPI wire time (9.7 ms for the frame), so inflating with CircuitPython’s zlib (about 48 ms a frame, against about 16 ms for the C library’s tinfl on the same chip) is what limits it. Film clips compress less than the test pattern and inflate more slowly.

Expect a fraction of the clip’s rate, not 24. The C library reaches 24 FPS by inflating on one core while DMA sends the previous frame from the other. Here, inflating and drawing happen one after the other in a single Python thread. Frames that fall behind are skipped, so playback keeps the clip’s timing, and play() returns the frame rate it actually achieved.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the library locally from PyPI. To install for current user:

pip3 install circuitpython-rv565

To install system-wide (this may be required in some cases):

sudo pip3 install circuitpython-rv565

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .venv
source .venv/bin/activate
pip3 install circuitpython-rv565

The reader (rv565.open(), Clip.frame()) works under CPython too; the players need displayio.

Installing to a Connected CircuitPython Device with Circup

Make sure that you have circup installed in your Python environment. Install it with the following command if necessary:

pip3 install circup

With circup installed and your CircuitPython device connected use the following command to install:

circup install circuitpython_rv565

Or the following command to update an existing version:

circup update

Without circup, copy circuitpython_rv565.mpy from the CircuitPython Community Bundle (or from this repository’s releases) to the lib folder on your CIRCUITPY drive.

Usage Example

Copy examples/testpattern.rv565 (180x135, 24 FPS, 24 frames, 6 KB) to the root of CIRCUITPY, then run this as code.py:

import board

import circuitpython_rv565 as rv565

clip = rv565.open("/testpattern.rv565")  # path, file object or bytes
print(clip.width, clip.height, clip.fps, len(clip))

player = rv565.Player(clip, board.DISPLAY)
stats = player.play()  # paced to clip.fps, late frames skipped
print(stats)  # <PlayStats x.xx of 24 FPS: n shown, m skipped ...>

rv565.open() reads only the 12-byte header. The frame index is built on first use with one pass over the length fields (4 bytes of RAM per frame), which also validates the whole container; call clip.build_index() to do that before playback. Frames are read from the file one at a time, so a clip on CIRCUITPY or an SD card does not have to fit in RAM. clip.frame(i) returns frame i as big-endian RGB565 bytes and raises RV565Error if it does not inflate to exactly 2 * width * height bytes.

The examples folder has:

• rv565_simpletest.py: any board with board.DISPLAY.

• rv565_pico2_st7789.py: Raspberry Pi Pico 2 with a 2.0” 320x240 ST7789 on SPI0 (SCK GP18, MOSI GP19, CS GP17, DC GP20, RST GP21, BL GP22).

• rv565_pico2_direct.py: the same wiring with DirectPlayer.

• rv565_esp32s3_tft.py: Adafruit ESP32-S3 TFT Feather (built-in 240x135 ST7789).

pip install rv565
rv565 encode input.mp4 clip.rv565 --size 180x135 --fps 12
rv565 verify clip.rv565

python3 -m pytest

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

RV565

• Project, C library and encoder: https://github.com/elixpo/rv565

• Format specification: https://github.com/elixpo/rv565/blob/main/docs/FORMAT.md

• Paper: Ayushman Bhattacharya, RV565: Cross-Layer Co-Design for Frame-Independent Video Playback on MicroPython-Class ESP32-S3 Systems, arXiv:2610.35935

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.