Raspberry Pi Video Looper

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. If you don't have the time or the desire or the means to learn to code it yourself, this is for you.

Contents of this page

Download the image file

This is the software that turns the Raspberry into a video looper.

Version uses adafruit/pi_video_looper release works with all boards up to MD5 checksum
v.2.3 (Dec 2020) (530MB) v1.0.7 Raspberry Pi 4 *rpi4 d2496ac08bdd1a038e3b84e4c80516aa

Based on the DietPi distribution for the first time. Less drag on SD cards, more resilient against corruption from sudden power loss, and an image file halved in size, compared to the previous version.

*rpi4 Note that while the video looper does work on the Raspberry Pi 4, the new hardware seems to be a little to powerful for this job. As such it may get very hot (at least without active cooling), which in turn may start to interfere with reliable video playback – which is what this project is all about.

My recommendation is to use this script with a Raspberry Pi 3b+ or earlier, which is unaffected by these problems, and absolutely powerful enough for Full HD/1080p video playback (which is done by a dedicated hardware component anyway, not the CPU or GPU). Tested on Raspberry 1B / 2B / 3B / 3B+ / 4B and Pi Zero WH.

Earlier versions of the video looper, which might come in handy if you experience problems with older hardware.

Version uses adafruit/pi_video_looper release works with all boards up to MD5 checksum
v.2.2 (Sept 2019) (1.1GB) v1.0.4 Raspberry Pi 4* 2921472a60374a164b8f21f9a92bf853
v.2.1 (June 2019) v1.0.2 Raspberry Pi 3 Model B+ (but not on the Raspberry Pi 4) a2d47a852a54f6b50d5cb85ca87af67a
v.2 (June 2018) v1.0.0 Raspberry Pi 3 Model B 8cdf01374ed9e25d62f34f27df8c4425
v.1 (2015) v1.0.0 Raspberry Pi 2 Model B cc6a2deed113967666cd5a95e8071593

You will also need

How do I get this running?

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. I use 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 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 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 frees the stick up for other purposes. This is called copymode; see the instructions on the script's Github for more info.

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 it forever, 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 Escape key (top left on your keyboard) to quit the player. Enter the username "pi" and the password "video". Then enter sudo poweroff.

Keyboard commands

Customize it to your needs

A note on sound

The script uses both the 3,5mm jack and HDMI by default for sound output. Note that the quality of the sound output on the analogue 3,5mm 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.

Using a sound card/DAC

Version 2.3 of this looper is now based on DietPi. This distribution makes it easy to add a digital-analogue converter (DAC) for high quality audio. Connect the DAC to the Raspberry and boot it up. 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

Analogue sound

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 below.

Analogue video

By default, the looper outputs to both HDMI and analogue PAL video (except on a Raspberry 4, see below).


If you experience playback issues (stuttering video using the Raspberry's analogue output) 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.

Analogue video playback on Raspberry 4

Disabled by default. Find this line in /boot/config.txt and remove the leading #:

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.
Generally speaking, I've found it's a lot easier to use earlier versions of the Raspberry Pi for composite video.

No 4K video playback

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.

Multi-channel video in sync

Note that this setup doesn't sync multiple players. Have a look instead at omxplayer-sync or my own (outdated) image of that.

For the advanced: I want to learn more about this / I need to tweak some settings

Before editing the system you'll need to know:

Some useful commands

sudo nano /boot/config.txt to edit basic Raspberry settings like HDMI and composite video and sound output settings.

sudo nano /boot/video_looper.ini to change video looper parameters, like the new copy mode. This is also where you can change the video resolution or position. Omxplayer doesn't respect anything you set in config.txt. Instead you'd edit the line 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.

sudo supervisorctl stop video_looper or just stop to stop the video.

sudo supervisorctl start video_looper or just start to start it up again.

Likewise, use restart to reload with changed settings. (These are useful i.e. when tinkering with the Omxplayer options as detailed just above - no need to restart the Pi)

If you don't want to work with a directly connected keyboard, use ssh pi@raspberrypi.local to ssh into it when connected via Ethernet with a Mac.
ssh pi@raspberrypi if you're on Windows.

To read up on things

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 more extensive documentation is where to look if you need to change anything, i.e. to enable advanced playlist features, etc.

Many thanks to Adafruit and to the maintainers/@tofuSCHNITZEL on Github (the people doing all the heavy lifting).


This image for the Raspberry was originally compiled for students at the KHM Surveillant Architectures seminar from 2015–2020. I had had enough of students freaking out about expensive and shitty 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.

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 @chrsiev on Twitter // my homepage documenting my own artwork

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.