Make your Raspberry Pi loop a video file endlessly and seamlessly, without showing any logo or breaks.
A simple, cheap and reliable media player/digital signage solution that just works. Free software. No configuration needed. The pi_video_looper script is all installed and configured. If you don't have the time, or the desire, or the means to learn to code it yourself, this is for you.
If you have specific needs or just want to know more:
This is the complete software package that turns the Raspberry into a video looper. Tested on Raspberry Pi 1 B+ / 2B / 3B / 3B+ / 4B and Pi Zero WH. It probably doesn't work with the Raspberry Pi 5 - let me know what happens if you try, if you have one.
| Version | uses pi_video_looper script version | based on | works with all boards up to | MD5 checksum/ notes |
|---|---|---|---|---|
| v.2.8 – February 2024 (820 MB) | v1.0.17 | Raspberry OS Lite Legacy (2022-01-28-raspios-buster-armhf-lite) |
Raspberry Pi 4 | 53afed4e87e2908adfd0e1581795f2a7 Built with sdm. Expand the filesystem with raspi-config if you want to play video directly from the SD card. |
Earlier versions of the video looper, which might come in handy if you experience problems with older hardware.
| Version | uses pi_video_looper script version | based on | works with all boards up to | MD5 checksum |
|---|---|---|---|---|
| v.2.7 – January 2024 (765 MB) | v1.0.15 | Raspberry OS Lite Legacy (2022-01-28-raspios-buster-armhf-lite) |
Raspberry Pi 4 | cd7e76f73f62fe2160a46a211b900522 Built with sdm. Expand the filesystem with raspi-config if you want to play video directly from the SD card. |
| v.2.6 – March 2022 (690 MB) | v1.0.11 | DietPi/Buster | Raspberry Pi 4 | 943660dd1828b3d6f4016ade95c53261 + fixes a bug with copy_mode by automatically expanding the file system if possible + fixes bad permissions of the image file inside the zip container |
| v.2.5 – Jan 2022 (726 MB) | v1.0.10 | DietPi/Buster | Raspberry Pi 4 | 94c70f5e2b429315c00ea2ca5cb125bf |
| v.2.4 – Dec 2021 (722 MB) | v1.0.8 | DietPi/Buster | Raspberry Pi 4 | a18dcab441f66fca9c6455dd6f5e35a0 |
| v.2.3 – Dec 2020 (530MB) | v1.0.7 | DietPi/Buster | Raspberry Pi 4 | d2496ac08bdd1a038e3b84e4c80516aa |
| v.2.2 – Sept 2019 (1.1GB) | v1.0.4 | 2019-07-10-raspbian-buster-lite | Raspberry Pi 4 | 2921472a60374a164b8f21f9a92bf853 |
| v.2.1 – June 2019 | v1.0.2 | raspbian_lite-2019-04-09 | Raspberry Pi 3 Model B+ (but not on the Raspberry Pi 4) | a2d47a852a54f6b50d5cb85ca87af67a |
| v.2 – June 2018 | v1.0.0 | Raspbian Stretch lite | Raspberry Pi 3 Model B | 8cdf01374ed9e25d62f34f27df8c4425 |
| v.1 – 2015 | v1.0.0 | Raspbian Jessie lite | Raspberry Pi 2 Model B | cc6a2deed113967666cd5a95e8071593 |
A note on the Raspberry Pi 4: The micro-HDMI connectors are not very sturdy and the cable can come loose more easily, at least in situations that call for robust connectors, like when you're setting up an exhibition. If you need something sturdy and don't care about the booting process taking 30 seconds longer, my recommendation is to use this script with a Raspberry Pi 3b+ or earlier, which have standard HDMI sockets, and absolutely powerful enough for Full HD/1080p video playback (which is done by a dedicated hardware component anyway, not the CPU or GPU).
Raspberry Pi boards are small in size, but they're full computers, and as such they need an operating system to start from. In this case that's the video looper. You'll need to copy all the information from the image file you downloaded onto the SD card, which then serves as the system hard disk. Please follow i.e. these instructions to clone the downloaded image file to the card. No need to unpack the zip file. Most SD-card flashing software can use compressed image files. The Raspberry Pi Imager works well, as does balenaEtcher. I still like ApplePiBaker.
Once that is done, insert the SD card into the Raspberry and connect it to a display (using either the HDMI or the analogue video output, depending on what you're working with).
As the last step start it up by plugging the power adapter into the mains socket. That's literally it.
Now the only thing that is missing is your video, which should be a standard h.264 mp4 file. It can be up to 1080p ("Full HD") in size. Smaller resolutions are OK, of course, but it won't play anything higher. When you encode your video or export it from your editing suite, don't make the bitrate too high: The difference won't show but it might make the video stutter if you go crazy with quality. Adafruit provide some (still valid) tips on encoding video for the video looper.
The video needs to be in the root folder of your USB flash drive/stick (meaning, directly on it). If you have more than one video, it'll play them in alphabetical order, and then loop around. The script will ignore anything that is kept in subfolders.
You can hot-swap USB sticks. Remove and insert a new one and it'll automatically start to play any files on it.
It's also possible to configure the video looper to copy any files it finds on a connected USB stick to its internal SD card, which means you don't need the stick connected anymore. This is called copy_mode; see Setting advanced options for more info. Same goes for playback in random order.
A tip: As a full, working computer, the Raspberry would prefer to be shut down properly. It seems to be OK for a while with simply being unplugged from power, but probably won't tolerate dozens of times, as the SD card can corrupt. If you can, just leave it running. It's built to run forever (and as a bonus uses very little energy).
To shut it down properly, connect a keyboard and hit the p key, or connect a button via GPIO.
k to skip the playback of the current video (or restart playback if you have just one video file)s to stop playback; hit it again to restartescape (esc) to quit the player (after which you can log in)p to power off the systemIf you just want simple looping playback, this is really all you need to do. Feel free, of course, to read on, if you have specific needs or just want to know more.
There are several ways to output the video and audio signals. In most cases, you will probably want to use HDMI for both.
The script uses both the 3,5 mm jack and HDMI by default for sound output. Note that the quality of the sound output on the analogue 3,5 mm jack is not as high-end as with some other media players. Using the digital HDMI sound output is the easiest and best-quality option.
Versions 2.3 up to 2.6 of this looper were based on DietPi. This distribution makes it easy to add a digital-analogue converter (DAC) for high quality analogue audio. Connect the DAC to the Raspberry and boot it up. Exit the looper with escape (esc). Log in, enter sudo dietpi-config and in Audio Options choose your soundcard. Wait for the drivers to install (your Raspi needs an Internet connection for that) and reboot. Then edit /boot/video_looper.ini, deactivate sound = both by inserting a # in front, and activate sound = alsa. Save and quit. Then enter restart to reload with changed settings.
If you have to use analogue sound, but you're not satisfied with its quality, try editing /boot/config.txt and add the line audio_pwm_mode=2 at the bottom.
Then edit /boot/video_looper.ini and find the line that says sound = both and disable it by adding a # in front. Then remove the hash from the line that says sound = local to activate it. Save and quit. Then reboot.
You can edit these files directly on your computer when the SD card is inserted. Alternatively, attach a keyboard, hit esc to quit the looper and follow the instructions at Logging in.
On older versions of the Raspberry Pi (up to the 3), the looper outputs to both HDMI and analogue PAL video (this changes on a Raspberry 4 and higher, see below).
If you need to change the video resolution or position, do that also via editing the video_looper.ini file. See below for how to do that. Omxplayer doesn't respect anything you set in config.txt (which is where you'd normally set the Raspberry's resolution). Instead you need to edit the line in video_looper.ini that starts with extra_args and add i.e. --win 40, 20, 704, 560 to position the video directly. See the Omxplayer docs for all options. If you do that while logged in via SSH you can save a lot of time, no need for constant SD-card swapping between your computer and the Raspberry.
If you experience playback issues using the Raspberry's analogue output (stuttering video) it helps to change some settings by editing the video_looper.ini text file that's in the boot partition of the SD card. Find the line that says sound = both and disable it by adding a # in front. Then remove the hash from the line that says sound = local, effectively activating it.
Another solution to the stuttering analogue video problem is to edit /boot/config.txt and add the line audio_pwm_mode=0 at the bottom. From what I understand this degrades the analogue sound quality, though, so try the above solution first.
If all this fails, try earlier versions of the looper (which will then require earlier versions of the Raspberry board). Video playback is done by a dedicated chip, which hasn't changed since forever. So if 1080p videos play flawlessly even on Raspberry Pi 1 Model B, why not use those for analogue video.
Disabled by default. Find this line in /boot/config.txt and remove the leading #:
enable_tvout=1
to enable analogue video output on the RPi4. Once rebooted, HDMI stops working. To re-enable HDMI output, just comment out those two lines again.
TBH, I've found it's a lot easier to use earlier versions of the Raspberry Pi for composite video.
I'm sorry to say that this won't play video in 4K. Omxplayer, the software that actually plays the videos in the looper, relies on a hardware component of the Raspberry to play video. This is why even the first Raspberries can smoothly play 1080p video. This hardware component is designed to play back H.264 video, with 1080p video as the maximum resolution (1920x1080 px).
4K video uses a different codec called HEVC/ H.265, which is not supported by the Raspberry GPU or omxplayer.
Omxplayer can display to a 4K screen but can only decode video with codecs supported by the hardware, which are limited to 1920x1080. See here for detailed info.
Note that this setup doesn't sync multiple synchronized players. Have a look instead at omxplayer-sync or my own (very outdated) image of that.
video/boot/config.txt was amended to output analogue PAL videono_hello_video option).bashrc and I've added an motd.sshsudo raspi-config.
Connect a keyboard. Hit the escape key to quit the player. Hit the Return key once, then enter pi, followed by another Return. Then enter the password video (yes, it's ok that you cannot see what you're typing), and confirm again with Return. Note that the keyboard is still the default GB layout.
If you don't want to work with a directly connected keyboard, connect the Pi to a local network using an Ethernet cable. Then use ssh pi@raspberrypi.local to ssh into it when connected via Ethernet with a Mac.
This should be ssh pi@raspberrypi if you're on Windows.
Alternatively, you can use the looper's IP address, i.e. ssh pi@192.168.0.5. To find the LAN IP address, log in with an attached keyboard as described above. You'll see the IP adress, printed near the top, starting with 'inet'. If you can't see an IP address there, your Raspberry is not connected to a network.
Wireless networking is still disabled, as it is on any default Raspberry OS images, because you need to set your country code first. Use sudo dietpi-config to enable Wi-Fi and connect to a network.
Once you're logged in you can change settings directly via sudo nano /boot/videolooper.ini. Move around with the arrow keys on your keyboard, make your edits, and then hit CTRL+X to quit nano and then Y to confirm. Then enter restart to restart the looper with the changed settings.
Use sudo nano /boot/config.txt to edit basic Raspberry settings like HDMI and composite video and sound output settings.
Again, use restart to reload with changed settings. This becomes very useful i.e. when tinkering with the Omxplayer options as detailed just above - no need to restart the Pi.
Activate advanced options like playlist resume, M3U playlists, copy_mode, video file location, GPIO control, etc in the videolooper.ini. This file is stored in the /boot part of the Raspberry Pi's SD card, so you can edit it on your main computer. Or access it directly when logged in to the system. See here for the default configuration (which is what we use). All the options are nicely explained in the file itself, and on the project's README.
Here's how to enable random order, as an example:
videolooper.ini file and open it in a text editor. Change the line that says is_random = false to is_random = true.In addition to the info given on this page, here are the original instructions on how to set up the VideoLooper yourself, i.e. for the learning experience, or if you don't trust a downloaded image file. This page also documents a ton of additional options that have been added in the last year, like support for GPIO control and other various special playback scenarios.
https://github.com/adafruit/pi_video_looper
https://learn.adafruit.com/raspberry-pi-video-looper?view=all
Many thanks to Adafruit and to the maintainers on Github, especially Tobias Perschon/@tofuSCHNITZEL.
Released under the GNU General Public License (GPL)
This software is supplied as is, with no guarantees whatsoever. If you like it, please consider giving something back to the community. Personally I think we should support any effort that helps to keep the globe a healthy habitat for our children and all other species. We urgently need to team up to make sure the biosphere survives.
This image for the Raspberry was compiled by Christian Sievers, originally for students at the KHM Surveillant Architectures/ctrl-space seminars from 2015 to 2022. I had seen too many students freaking out about expensive and unreliable commercial media players, when really they should be thinking about their art. So the idea was and still is to make a hassle-free, cheap and reliable media player available to everyone. It's about accessibility. As it says on the tin, If you don't have the time or the desire or the means to learn to code it yourself, this is for you.
Also, Fuck Nazis and support your local anti-fascist initiatives.
Any questions, comments or ideas to improve please get in touch. I'd be happy to hear from you if you like it, or just to know where it's being used (all over the world, apparently):
My profile at
Academy of Media Arts Cologne //
I'm @Sie@mastodon.social on Mastodon //
my own site documenting my artwork