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!

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

This page (Usage) was last updated on Feb 11, 2015.

Text editor powered by tinymce.