This guide was written for older Raspberry Pi boards. It will not work with Raspberry Pi 4 or 5 without changes. No ETA on an update.

Temporarily unable to load embedded content:

Do you need a simple way to display seamless looping video files, like in an art exhibit or digital sign?  Check out this Raspberry Pi video looper project to learn how to turn a Raspberry Pi into a dedicated video playback machine. Just stick a USB drive loaded with movies into the Raspberry Pi and it will play them over and over in a loop!

The Raspberry Pi is a great platform for building a video playback appliance since it's inexpensive, tiny, and has support for hardware video acceleration.  However it's confusing to sort through the many options for playing and looping videos, and even more troublesome to put everything into an easy to use package.  This project has done all the hard work for you to make the most popular and reliable video playback options on the Raspberry Pi easy to use.

Best of all, we've tweaked and optimized the video player for Raspberry Pi for seamless looping with audio! (There's a 100ms pause between loops on the last frame of the video but there's no black screen flicker)

To get started you'll need a Raspberry Pi computer.  Either the first generation models (A, B, A+, B+) or the second generation Pi 2 will work great.  You'll also want a USB stick that will be used to hold movies for playback.

If you're brand new to using the Raspberry Pi I recommend reading the first few learn Raspberry Pi guides to get an overview of the basic Raspberry Pi usage.

Continue on to learn how to setup and install the software for the Pi video looper project.

Begin by installing a suitable version of Raspberry Pi OS onto a SD card. If this is your first time or you need a refresher, we have a separate guide explaining the process (opens in new window).

If using the Raspberry Pi Imager application: from the “CHOOSE OS” menu, select Raspberry Pi OS (Other), then Raspberry Pi OS Lite (Legacy). Before writing the card, see “Enable SSH” below.

If using Balena Etcher or other application: download the latest Raspberry Pi OS Lite (Legacy) operating system image from the Raspberry Pi web site (opens in new window). After writing the card, see “Enable SSH” below.

In either case, use the “Lite (Legacy)” version. Both Lite and Legacy. This skips all the bulky GUI stuff that isn’t needed here, and is compatible with video software we’ll be using. The latest non-Legacy release will not work!

Enable SSH

It’s usually easiest to set up and install this project remotely over a network, so you can copy-and-paste commands from this page to the command line.

If using the Raspberry Pi Imager application: before writing the card, press Control+Shift+X (Windows) or Command+Shift+X (Mac) to open the Advanced Options menu. Here you can Enable SSH for remote access. If you want to set up WiFi instead of a wired Ethernet connection, those options are also in this menu. Now you can write the card!

If using Balena Etcher or other application: after writing the card, don’t eject! Create an empty file called ssh in the /boot partition. This will enable SSH over a wired Ethernet connection. If you want WiFi, you’ll have to connect temporarily with Ethernet and configure wireless through raspi-config…or see below.

A third option—and required if you only have WiFi but no Ethernet—is to do this on the Raspberry Pi after first boot, with monitor and keyboard connected. The raspi-config utility includes options for enabling WiFi and SSH. Then the rest of this installation can be done remotely.

Once your Raspberry Pi is powered up and connected to a network you can follow the steps below to install the video looper software.

If you're familiar with connecting to the Raspberry Pi over SSH you can use an SSH terminal application to connect and skip down to the install commands section below.

After a few moments you should see a terminal open with a message like the above.  At this point you're connected to the Raspberry Pi and ready to run commands to install the video looper.

Install Commands

To install the software first type the following commands exactly as follows:

sudo apt-get update
sudo apt-get install -y git
git clone

After pressing enter to run the command you should see something like the above displayed.  The source code for the video looper has been downloaded to your Raspberry Pi.

Now run these two commands to finish the install:

cd pi_video_looper
sudo ./

You should start to see a lot of messages printed to the screen as software is downloaded and installed.

After about 5 minutes you should see the installation stop with the message Finished! like the picture below shows.  If you see this message then the installation succeeded.

If the installation fails for some reason it will immediately stop and display an error.  Check the terminal for the error to see if it's something you can easily correct like a failure to access the internet, or try asking for more help on the Adafruit forums.

After the software installs you should see the video looper display on the HDMI port.  Assuming no USB drives with movies are connected to your Pi, there should be a message telling you to insert a USB drive like below:

If you see the message above then congratulations the video looper software is installed!  Continue on to learn how to use the video looper.

Playing Videos

After installation video looper is configured to play movies off of USB drives inserted in the Raspberry Pi.  The default video player, omxplayer, can play most videos encoded with the H.264 video codec and in a video format with an extension like .avi, .mov, .mkv, .mp4, or .m4v.  You can even play 720p and 1080p movies because omxplayer will use the Pi's GPU (graphics processing unit) to efficiently play videos!

With video looper running if you insert a USB stick with movies a message will display with the number of detected movies, and a 10 second countdown as shown below:

If only one movie is available it will play continually in a loop.

If more than one movie is found then each movie will be played in alphabetical order by filename.  Once the last movie has played video looper will loop back to the first video and play all videos again in order repeatedly.

Single movie playback with omxplayer has more 'seamless' looping compared to multiple video playback.  With multiple videos there will be a small visible delay between movies, but with only one video the loop delay will only be about 100 milliseconds.  See the tips for looping section for advice on how to get the best results with playing videos in a loop.

When videos are playing audio will be output on both the HDMI output and the analog sound output on the Raspberry Pi.  You can connect either output to a speaker to hear movie audio.


You can customize the behavior of video looper by changing settings in its configuration file.  If you only need to play movies off of USB drives then you don't need to change the configuration, everything is ready to go after installation!  However if you'd like to play movies from a directory on the SD card, change the video player, disable the on-screen display messages, or more then continue reading.

The configuration file is stored in the /boot part of the Raspberry Pi's SD card which means you can edit it directly on your computer.  Shutdown your Raspberry Pi (see this page if you aren't sure how), pull out the micro SD card, and insert it into your computer.  After your computer displays the files on the card open the video_looper.ini file in a text editor.

At the top of the configuration file you'll see text like:

# Main configuration file for video looper.
# You can change settings like what video player is used or where to search for
# movie files.  Lines that begin with # are comments that will be ignored.
# Uncomment a line by removing its preceding # character.

# Video looper configuration block follows.

# What video player will be used to play movies.  Can be either omxplayer or
# hello_video.  omxplayer can play common formats like avi, mov, mp4, etc. and
# with full audio and video, but it has a small ~100ms delay between loops.
# hello_video is a simpler player that doesn't do audio and only plays raw H264
# streams, but loops seemlessly.  The default is omxplayer.
video_player = omxplayer
#video_player = hello_video

# Where to find movie files.  Can be either usb_drive or directory.  When using
# usb_drive any USB stick inserted in to the Pi will be automatically mounted
# and searched for video files (only in the root directory).  Alternatively the
# directory option will search only a specified directory on the SD card for
# movie files.  Note that you change the directory by modifying the setting in
# the [directory] section below.  The default is usb_drive.
file_reader = usb_drive
#file_reader = directory

Lines that start with # are comments which will be completely ignored.  Read the comments to help understand what options are available in the configuration.

Two of the most common options to change are at the top of the file, the video_player option and the file_read option.

video_player controls what video player will be used to play movies.  You can pick one of two options for the video player configuration:

  • omxplayer is the default video player and works great for playing videos in typical video formats like .avi, .mov, etc.  Videos will play with sound output over both the HDMI and analog audio output by default.  However, omxplayer has a small delay when looping videos.  See the looping tips section for hints on how to reduce the impact of this delay in your videos.
  • hello_video is a more limited video player but with very fast and seamless looping of videos.  Unfortunately hello_video does not support playing audio, and requires movies to be converted into a raw H.264 stream.  Video files in formats like .avi, .mov, etc. won't play directly.  You can find out how to convert a video into the format used by hello_video on this page.  

If you'd like to change from omxplayer to hello_video, update the configuration to look like (notice the omxplayer line is commented and the hello_video line is uncommented): 

#video_player = omxplayer
video_player = hello_video

file_reader controls where videos are found, either on USB drives or from a directory on the Raspberry Pi.  Again you can pick one of two options:

  • usb_drive is the default and will search all attached USB drives for movies.  You can plug in a USB drive and it will automatically be searched for movies to play.
  • directory will search a single directory on the Raspberry Pi for movies.  This is useful if you can't have a USB drive attached to the Raspberry Pi.

If you'd like to change from usb_drive to directory, update the configuration to look like:

#file_reader = usb_drive
file_reader = directory

To choose the directory that will be used for movies, scroll down to this part of the configuration and change the value of the path configuration:

# Directory file reader configuration follows.

# The path to search for movies when using the directory file reader.
path = /home/pi

There are more setting in the full configuration file which will change video looper's behavior and appearance, like if it prints messages on the screen, the color of the background, and more.  It's not common to change these settings but you can read through the the comments in the configuration to learn more about them.

Once you've finished editing the configuration file you should save it, dismount the micro SD card from your computer, and insert the card back in the Raspberry Pi.  Boot up the Raspberry Pi and video looper should load the updated configuration.

Disable Video Looper

Once installed video looper will run automatically every time the Raspberry Pi is booted.  If you'd like to stop or disable video looper you have a few options available.

To temporarily stop video looper, connect to the Raspberry Pi in a terminal/SSH session (you can use Pi Finder like mentioned in the installation) and run this command:

sudo supervisorctl stop video_looper

After a few moments video looper should stop playing movies and exit.  TVideo looper will not run again until the Raspberry Pi is rebooted.

To permanently disable video looper, i.e. to prevent it from ever starting on boot again, you can run a small script included with the video looper code.  Connect to the Raspberry Pi in a terminal/SSH session and navigate to the folder where video_looper was downloaded.  If you followed the installation in this guide then run:

cd pi_video_looper

Now run the disable script by executing:

sudo ./

Don't worry if you see an error message displayed that video looper is already stopped (this might happen if video looper isn't running when its disabled).  After running the script above video looper will be disabled and should not run on boot.

To ever enable video looper again just run the installation steps again.

Tips for Looping Videos

To improve performance and get near seamless looping of videos, keep in mind some of these tips:

  • If you have multiple videos, combine them all into a single video.  Looping a single video is a little bit faster and more seamless compared to looping multiple videos (there will be a brief pause and blank screen with multiple videos).  You can use a video editing tool like iMovie to combine multiple videos into one longer video and even add transitions between videos like cross-fades, wipes, etc.  Make sure to export your movie from the editing program in a H.264 video format in a .avi, .mov, .mkv, .mp4, or .m4v file.
  • Start and end your movie with the same image and with audio faded down.  This way when the video loops to the start it will not be noticeable if there is a small delay or hiccup.  Alternatively let the end of the movie and start of the movie be a natural point for a cut so it appears that the video flows directly from the end back to the start.
  • If you need the absolute most seamless looping of video only (audio is not supported unfortunately), consider changing to the hello_video video player.  This video player can only play raw H.264 video and can't play audio, but it does loop without any noticeable delay.  See the configuration section for details on changing to hello_video, and the hello_video page for details on how to convert a video to the required format.

Shutting Down the Raspberry Pi

Once you're up and running with the video looper you might be curious how to shut down your Raspberry Pi.  Resist the temptation to just yank out the power cord as you will likely corrupt the Pi's SD card and require a full operating system and video looper reinstallation!  Instead you should cleanly shutdown the Pi so that there is no chance of corrupting the operating system.

To cleanly shut down the Pi you can use the Pi Finder tool that was used to install the software.  Run Pi Finder like when you did the installation and find your Raspberry Pi.  Then click the Shutdown button in Pi Finder and your Pi should shutdown.  After the green light on the circuit board stops flashing and the red light is steadily lit you can safely remove the Pi's power cord.

Again unless you absolutely can't avoid it, do not abruptly remove power from the Raspberry Pi without cleanly shutting it down first!

omxplayer is no longer installed on the latest Raspberry Pi OS installs. This guide is deprecated.

The default video player used by video looper is omxplayer.  This is a great general purpose video player that offloads video decoding to the Pi's GPU so it can render 720p and even 1080p video on the Raspberry Pi 1 and Pi 2.

To use omxplayer you'll want to make sure your video is encoded with an H.264 codec and is in a file format like .avi, .mov, .mkv, .mp4, or .m4v.  If you have a video in a different format or that won't play you convert it into an H.264 video easily with some free tools.

For converting a video to H.264 that omxplayer can play I recommend the Handbrake video transcoder tool.  This tool is available for free for Windows, Mac, and Linux machines, and has a relatively simple interface.  

To use Handbrake, after installing it open the program and you'll see a display like this:

Click Source in the upper left and load your video to see information like the dimensions, framerate, encoding, etc.  By default Handbrake's normal encoding preset works well, but I recommend tweaking a few of the settings to improve the quality and reduce issues with looping short videos.

Once a video is loaded click the Video tab and adjust the settings to:

  • RF = 18
  • Profile = high
  • Level = 5.0

Below is an example: 

Then enter a new destination file name and press the Start button at the top to transcode the video into a .m4v file.  

Be aware video transcoding can take some time if your computer has a slow CPU or the video has a long length.

Once Handbrake is done transcoding the file copy it to a USB drive and try playing it with the video looper.

omxplayer Version

Note that the version of omxplayer installed by video looper is actually a fork of the original code and was made to help reduce the latency when looping a single video.  You don't need to worry about how to install or use this updated omxplayer as the video looper install script takes care of everything automatically.  

In the future it's possible the main omxplayer project will integrate these changes.  Be aware if you manually install video looper or wish to modify and extend it that you'll want to use the forked omxplayer code above.

Another video player you can use with the Raspberry Pi is hello_video.  This player is based on example video playback code shipped with the Raspberry Pi so it doesn't have many features but is very fast at looping and playing videos.

One big limitation with hello_video is that it does not support playing sound from videos.

Another limitation of hello_video is that it requires videos to be in a raw H.264 stream format.  You can't give hello_video a .avi, .mov, etc. file!  However it's straightforward to convert a video into the format required by hello_video using the free ffmpeg tool.

To convert a video with ffmpeg, first download and install ffmpeg for your platform (Windows, Mac, and Linux are supported).  ffmpeg is a command line tool so you'll need to open a terminal on your computer and navigate to the directory that contains your video.  Then run a command like:

ffmpeg -i input_file.avi -vcodec copy -an -bsf:v h264_mp4toannexb output_file.h264

Where input_file.avi is the name of your video to convert (don't worry ffmpeg supports almost all video formats, so you can send it a .avi, .mov, .mkv, .mp4, m4v, etc.) and output_file.h264 is the name of the output file.  Make sure to keep the .h264 extension on the output file as it's required when using hello_video with video looper.

After ffmpeg finishes running (usually the operation is quite fast since it's just extracting the H.264 stream) copy the output .h264 file to a USB drive, make sure video looper is configured to use hello_video, and try playing the video.  You should see great video playback with no delay during looping.

hello_video Version

Also like omxplayer, the version of hello_video used by video looper is a special version forked from the original code.  This fork was made to turn hello_video into an application that can be installed separate from all the other example code, and to add a simple loop option to the program.  Don't worry about the details of this forked version unless you want to dive deeper into the source code--the install script for video looper will take care of everything!

This guide was first published on Feb 13, 2015. It was last updated on Apr 23, 2024.