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.
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: vidlooper.py [-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
too).
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
both.
--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
output.
--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
Troubleshooting
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.
Conclusion
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!
Bluesky