What it is.
A small system image for the Raspberry Pi. It boots directly into playback — no X11, no Wayland, nothing else running — and plays whatever .mp4 files are on the connected USB stick.
Built because every installation I'd seen had someone's desktop wallpaper showing. Runs on any Pi from the Zero 2 W up to the Pi 5, rendering via mpv straight to KMS/DRM on Raspberry Pi OS Lite.
- Any recent Pi Pi Zero 2 W through Pi 5. Resolution and frame-rate scale with the model.
-
USB-drop workflow
Write
.mp4files to a USB stick, plug it in — a systemd service mounts it and builds the playlist. - Silent boot Custom kernel parameters hide text output. The screen stays black until the first frame.
- H.264 & H.265 Hardware-accelerated decode where the Pi supports it; graceful fallback where it doesn't.
-
Direct framebuffer
No X11, no Wayland —
mpvrenders straight to KMS/DRM for the lowest possible latency. - Flash & go Pre-built images on GitHub Releases, or install manually on an existing Pi OS Lite setup.
How it works.
Three steps from a blank SD card to something playing on the wall.
-
Flash
Write the ZoetroPi image onto an SD card with Raspberry Pi Imager or
dd. Or run the install script on an existing Pi OS Lite setup. -
Drop files
Put one or more
.mp4files on a USB stick. ZoetroPi picks them up on insert and builds a playlist in the order it finds them. -
Plug in & power on
Connect display, USB stick, and power. A few seconds later the first frame fills the screen, and it keeps going until someone pulls the plug.
curl -fsSL https://raw.githubusercontent.com/fritzgnad/zoetroPi/main/install.sh | sudo bash
The command above is a copy-paste shortcut. The README is the source of truth.