Watching Videos From the Command Line on the Raspberry Pi

It is easy to forget that the Raspberry Pi’s command line interface has full access to the video subsystem (e.g. to the framebuffer) which means that command line tools can display complex images and videos without starting the full graphical desktop.

This can be useful for games which are launched from the command line and also for other multimedia programs like video players. OMXPlayer is a command line video player for the Raspberry Pi. It was originally developed as a testbed for the Raspberry Pi implementation of XBMC, but it works equally well as a standalone video player.

To install the player, use the following command:

To launch it, call “omxplayer” along with the filename of the video you want to play:

The player will likely take a few seconds before any video is shown as the Raspberry isn’t the fastest computer in the world and the video player needs to perform some initial processing of the video file (e.g. it needs to work out which codecs are used in the file and so on).


Once the video is playing, you can control the playback using the keyboard. Use SPACE to pause/resume, right arrow to jump forward 30 seconds, up arrow to jump forward 10 minutes, + or Рto change the volume, and q to quit. Here is a full listing of the keyboard controls:

  • 1 decrease speed
  • 2 increase speed
  • < rewind
  • > fast forward
  • z show info
  • j previous audio stream
  • k next audio stream
  • i previous chapter
  • o next chapter
  • n previous subtitle stream
  • m next subtitle stream
  • s toggle subtitles
  • d decrease subtitle delay (- 250 ms)
  • f increase subtitle delay (+ 250 ms)
  • q exit omxplayer
  • p / space pause/resume
  • – decrease volume
  • + / = increase volume
  • left arrow seek -30 seconds
  • right arrow seek +30 seconds
  • down arrow seek -600 seconds
  • up arrow seek +600 seconds

You may find that the rewind and fast forward controls don’t perform as expected. During my testing, I found that the on screen display (OSD) reported that the playback speed had been changed, but the video continued to run at the same rate.

OMXPlayer tends to output a lot of information onto the command line. Because the video is overlaid upon the command line, this extra text can be quite distracting. To turn the background black and hide the extra output, invoke the player with the “-b” option.

By default, the sound is sent to the Raspberry Pi’s audio jack, however HDMI is capable of carrying sound as well as video. So if your Pi is connected to a TV (rather than a monitor) then you can send the audio via HDMI using the “-o hdmi” option.

The Raspberry Pi isn’t powerful enough to perform video decoding in software. This means that although it can decode a range of popular video formats, it won’t work with less popular codecs like DivX 3.0. It can play H.264 and MPEG-4 videos in 1080p HD as well as MJPEG, VP6, VP8 and OGG Theora videos. These last four are limited to SD, as they aren’t fully supported in hardware, and the decoding is performed in software with help from the GPU. If you need to play MPEG2 or VC-1 (used in some Blu-ray discs), you need to buy additional video codec licenses from the Raspberry Pi Foundation online shop.

If you do get an error related to unknown or unsupported codecs, then the chances are that OMXPlayer can’t playback the video. Your best move in this situation would be to re-encode the video on a PC using H.264. You can ask OMXPlayer to display information about a video file using the -i option:


The output can help you determine if the video is compatible with the Raspberry Pi.

If you have tried OMXPlayer, how are you using it? As a media player connected to your TV? With a projector? Please share your story in the comments below.

Gary Sims

Gary has been a technical writer, author and blogger since 2003. He is an expert in open source systems (including Linux), system administration, system security and networking protocols. He also knows several programming languages, as he was previously a software engineer for 10 years. He has a Bachelor of Science in business information systems from a UK University.


  1. Whenever I change the volume, pause or seek forward/backward, the video starts to flick, the screens goes black here and there…

    Actually, OMXPlayer is only usable if I launch a video a touch nothing… any tips?

  2. +1 to FutureZ’s comment. I don’t know who in their right mind thought “Have a nice day ;)” was a suitable error response to any situation.

  3. Omxplayer is great, I’ve been using it since I got my pi in July 2012. During this time it has got better and better and can now play most modern media as is.
    In the beginning you had to use the entire screen but now you can use a window of whatever size you choose. You can even use several windows and play a video in each concurrently. It will stream content from the internet now too, you don’t have to have the video on a local file system.
    To play streaming video in a window, try :-
    omxplayer –win ‘1200 40 1880 422′ –live
    This will play in the top right corner of a 1920×1080 screen in a window, to play in the top left corner change the –win parameters to –win ’40 40 720 422’.
    Used in conjunction with youtube-dl, you can stream youtube videos directly to the screen, either fullscreen or in a window using the -win ‘x1 y1 x2 y2’ option. To stream youtube to a window use:-
    omxplayer –win ‘1200 40 1880 550’ $(youtube-dl -g
    Omxplayer just keeps on improving.
    btw – “have a nice day ;)” is not an error message, it’s just a normal program exit.

Comments are closed.