Software for a button-driven Raspberry Pi video player

3D-printed, button-driven, dedicated video player, based around Raspberry Pi Zero

Previously, I described how to build a dedicated video player using a Raspberry Pi Zero – a small, very cheap (~$10) computer and a set of physical buttons to switch the active video. The Pi Zero works for 1080p HD video. If you want to use 4K video, you'll need the more powerful Raspberry Pi 4, which sells for ~$35. It could be useful for museum displays, art or science projects, and other scenarios where visitors can choose from a selection of short videos.

In this article, I'll cover how to install and configure the software and load the videos onto the player.

The image at the top shows it set up at Jefferson Street Sound Museum in Nashville, Tennessee. The video player is the blue box in the bottom right, with the four video selector buttons on the top in light blue. The smaller black box to its left is a headphone amplifier.

Install the operating system, boot the Raspberry Pi, and log in

⚠️ Update in 2024: the omxplayer which the approach currently depends on is deprecated, so you'll need to use a Pi 4 or older, with an older version of Raspberry Pi OS based on Debian Buster. Note that Debian Buster is end of life, so won't receive any security updates - I would recommend against leaving it network connected where possible. ⚠️

First, you'll need to install the Raspberry Pi operating system (previously called Raspbian) onto a microSD card. The Raspberry Pi website provides a tool called Raspberry Pi Imager to prepare the microSD card on Windows, macOS, and Ubuntu.

Download and run the Raspberry Pi Imager, and select the Raspberry Pi OS (other) option from the menu, then the Raspberry Pi OS Lite (32-bit) option. The lite option is all we need, since we don't need a full desktop for this project. The Imager will prepare the SD card with the OS.

Raspberry Pi Lite OS installation

When the microSD card is ready, place in into the Raspberry Pi, connect the Pi to a monitor or TV and a keyboard, and turn it on.

When the system has booted, you'll see a login screen. The default username is pi and the default password is raspberry. Enter those details, and you'll be logged in and see a command prompt.

Install the video player software

We'll need to use Raspberry Pi's OMXplayer, which has hardware acceleration; a necessary feature to get smooth video playback on the Raspberry Pi.

I've written a small, free (MIT licence) Python video player called rpi-vidlooper. It is a wrapper around OMXplayer which handles the button interactions and video selection. rpi-vidlooper uses button callbacks and thread locking to avoid issues where multiple buttons are pressed quickly (someone is inevitably going to try that in a museum setting!).

First, the software dependencies must be installed:

sudo apt-get update
sudo apt-get install python3-pip omxplayer fbi

Then install rpi-vidlooper itself:

pip3 install rpi-vidlooper

This creates the vidlooper command. For usage help, see:

vidlooper --help

You'll might run into a couple of permission problems when you first run vidlooper - see the Troubleshooting section below. But first, we need to load some videos onto the Raspberry Pi.

Loading videos onto the player

Videos should be in h264 format (.mp4 extension) in order to benefit from hardware acceleration. 1080p resolution is recommended. The Raspberry Pi Zero probably won't work with a higher resolution, however, if you're using a Raspberry Pi 4, you could use 4K video.

Videos will be played in alphabetical filename order. Thus, you can reorder them by prefixing their filenames with 1, 2, 3 and 4.

The easiest way to load videos onto the player is using a microUSB-USB adapter and a USB memory stick. You could copy the files onto the SD card, or leave the USB stick attached.

The latter is useful if you want to allow non-techies to change the video roster - they simply turn off the video player, replace the videos on the USB stick on a PC/Mac, and replace the stick. In the case of leaving the stick attached, you'll need to configure the USB stick to automatically mount on boot.

The website Raspberry Pi Spy has information on how to mount, unmount, and automatically mount on boot for a USB memory stick.

rpi_vidlooper usage and examples

The vidlooper --help command will show you the available options. I've reproduced them here for convenience:

usage: [-h] [--audio {hdmi,local,both}] [--no-autostart]
                    [--no-loop] [--restart-on-press] [--video-dir VIDEO_DIR]
                    [--gpio-pins GPIO_PINS] [--debug] [--countdown COUNTDOWN]
                    [--splash SPLASH]
                    [videos [videos ...]]

Raspberry Pi video player controlled by GPIO pins

This program is designed to power a looping video display, where the active
video can be changed by pressing a button (i.e. by shorting a GPIO pin).
The active video can optionally be indicated by an LED (one output for each
input pin; works well with switches with built-in LEDs, but separate LEDs work

This video player uses omxplayer, a hardware-accelerated video player for the
Raspberry Pi, which must be installed separately.

positional arguments:
  videos                List of video paths (local, rtsp:// or rtmp://)

optional arguments:
  -h, --help            show this help message and exit
  --audio {hdmi,local,both}
                        Output audio over HDMI, local (headphone jack),or
  --no-autostart        Don't start playing a video on startup
  --no-loop             Loop the active video indefinitely.
  --restart-on-press    If True, restart the current video if the button for
                        the active video is pressed. If False, pressing the
                        button for the active video will be ignored.
  --video-dir VIDEO_DIR
                        Directory containing video files. Use this or specify
                        videos one at a time at the end of the command.
  --gpio-pins GPIO_PINS
                        List of GPIO pins. Either INPUT:OUTPUT pairs, or just
                        INPUT pins (no output), separated by commas.
  --debug               Debug mode (don't clear screen or suppress terminal
  --countdown COUNTDOWN
                        Add a countdown before start (time in seconds)
  --splash SPLASH       Splash screen image to show when no video is playing

Here's a simple example:

vidlooper --no-autostart --splash /home/pi/splash.png --no-loop --countdown=5 --video-dir /home/pi/videos

In this example:

  • Nothing will play automatically on startup: --no-autostart
  • An image will display when no video is active: --splash /home/pi/splash.png
  • Videos won't loop: --no-loop
  • A 5 second countdown will run before the video looper first starts. This is useful to give time to abort loading the player when administrators access the pi: --countdown=t
  • Videos will load in alphabetical order from the specified directory: --video-dir /home/pi/videos


RuntimeError: No access to /dev/mem. Try running as root!

By default, you'll need to run sudo vidlooper, to gain access to the GPIO pins and the graphics card (GPU) for omxplayer. Generally, this is not recommended.

To avoid this, the user you want to run the vidlooper as will need to be in the gpio group. For example, for the pi user, you'd need to do this:

sudo usermod -a -G gpio pi

No rights to /dev/vchiq

See the OMXplayer page for a fix to this problem.

Set up automatic login and start the video player on boot

To have the video player work unattended, you can set the Raspberry Pi to log in automatically, and start the video player on boot.

To log in automatically, run:

sudo raspi-config
  • Select Boot Options
  • Select Desktop / CLI
  • Select Console Autologin
  • Select Finish

There are many ways to get a program to start on boot, but here's a simple one:

sudo nano /home/pi/.bashrc

At the end of that file, add the video player command, editing the options as needed:

vidlooper --countdown 5 --no-loop --video-dir /home/pi/videos

Save and close the file. When you reboot your Pi, the video player will start automatically.


In a previous post, I covered how to build a Raspberry Pi button-based video player from cheap hardware. Here, I've shown how to set up and configure the software to run the player.

Thanks for reading!

Related Posts