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. This solution is using the pi_video_looper script, 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.

Contents of this page

Download the image file

This is the software that turns the Raspberry into a video looper. Tested on Raspberry 1 B+ / 2B / 3B / 3B+ / 4B and Pi Zero WH.

Version uses pi_video_looper script version based on works with all boards up to MD5 checksum
v.2.6 – March 2022 (690 MB) v1.0.11
+ fixes a bug with copy_mode by automatically expanding the file system if possible
DietPi/Buster Raspberry Pi 4 *rpi4 3fb125b66977d9faf1214d9e8d05a30d

No need to unpack the zip file. Most SD-card flashing software (like Etcher or Raspberry Pi Imager) can use the zipped image file.

The image is based on the DietPi distribution. It is optimised to minimize drag on SD cards, to be more resilient against corruption from sudden power loss, and the image file is halved in size, compared to stock Raspberry Pi OS lite. Still using Debian Buster as its operating system because omxplayer (the looper's core component) is deprecated on the newer Debian Bullseye.


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.5 – Jan 2022 (726 MB) v1.0.10 DietPi/Buster Raspberry Pi 4 *rpi4 94c70f5e2b429315c00ea2ca5cb125bf
v.2.4 – Dec 2021 (722 MB) v1.0.8 DietPi/Buster Raspberry Pi 4 *rpi4 a18dcab441f66fca9c6455dd6f5e35a0
v.2.3 – Dec 2020 (530MB) v1.0.7 DietPi/Buster Raspberry Pi 4 *rpi4 d2496ac08bdd1a038e3b84e4c80516aa
v.2.2 – Sept 2019 (1.1GB) v1.0.4 2019-07-10-raspbian-buster-lite Raspberry Pi 4 *rpi4 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

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. The Raspberry Pi Imager works well, as does balenaEtcher. 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 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 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.

Keyboard commands

That's it

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

Audio/Video output options

A note on sound

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.

Using a sound card/DAC

Version 2.3 and newer of this looper are 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.

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 at Keyboard commands.

Analogue video

By default, the looper outputs to both HDMI and analogue PAL video (except on a Raspberry 4, 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.

Stuttering using analogue video

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.

Analogue video playback on Raspberry 4

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.

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 synchronized players. Have a look instead at omxplayer-sync or my own (very outdated) image of that.

Customize it to your needs

Setting advanced options

Activate advanced options like playlist resume, M3U playlists, copy_mode, video file location, etc in the videolooper.ini. This file is stored in the /boot part of the Raspberry Pi's SD card. See here for the default configuration (which is what we use). All the options are nicely explained in the file itself.

Example advanced option: Playing in random order

Here's how to enable random order, as an example:

Logging in to the system

Connect a keyboard. Hit escape (esc) to quit the player. Hit (Return) 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).

Good to know before editing the system

Some useful commands

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.

Remote login via SSH

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, check out the console (what you see when you exit the looper with escape (esc)). If you can't see an IP address there, your Raspberry is not connected to a network.

Use sudo dietpi-config to enable Wi-Fi.

Further documentation

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:

https://learn.adafruit.com/raspberry-pi-video-looper?view=all

https://github.com/adafruit/pi_video_looper

Thank You!

Many thanks to Adafruit and to the maintainers on Github, especially Tobias Perschon/@tofuSCHNITZEL.

License

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.

About

This image for the Raspberry was compiled by Christian Sievers, originally for students at the KHM Surveillant Architectures/ctrl-space seminars from 2015 onwards. 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.

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 own site documenting my artwork

Impressum