OMXPlayer on the Raspberry Pi?

OMXPlayer is a command-line video player for the Raspberry Pi. It can efficiently decode a wide range of media formats utilizing the Pi’s hardware video acceleration with the help of OpenMAX. With some configuration, OMXPlayer allows you to smoothly play videos on your Raspberry Pi.

OMXPlayer on the Raspberry Pi?

Benefits of Using OMXPlayer on the Raspberry Pi

Here are some of the major benefits of using OMXPlayer on your Raspberry Pi:

  • Hardware-accelerated video decoding utilizing the Pi’s GPU for silky smooth playback
  • Light-weight and optimized for the Pi’s ARM architecture
  • Supports a wide variety of video and audio codecs out of the box
  • Completely free and open-source
  • Easy to integrate into Python and Bash scripts
  • Customizable using command-line arguments and configuration files

Installing OMXPlayer on the Raspberry Pi OS

OMXPlayer comes pre-installed on standard Raspberry Pi OS images. To confirm, open up the terminal on your Pi and run:

omxplayer -h

If you get an output showing OMXPlayer’s command-line options, it is already installed.

If not installed, run the following to install it:

sudo apt update

sudo apt install omxplayer

Playing Your First Video

To simply play a video file with OMXPlayer, navigate to the folder with your video in the terminal and run:

omxplayer example-video.mp4

OMXPlayer will launch in fullscreen and start playing the video.

Key Controls

When playing a video, you can use the following key controls:

  • Space – Pause/Resume
  • Arrow Keys – Seek forwards/backwards
  • W and S – Increase and decrease volume
  • Q and ESC – Stop and quit OMXPlayer
  • F – Toggle fullscreen
  • I – Show/hide video info overlay

There are many more controls available – check out the man page linked for all options.

Configuration Tips for Smooth Playback

Here are some configuration tweaks to enable smooth video playback with OMXPlayer:

  1. Adjust GPU Memory Split

By default, the Raspberry Pi only allocates 64MB to the GPU which runs video decoding. For smooth HD video playback, this needs to be increased to at least 128MB.

To do so, edit /boot/config.txt and add/edit this line:


  1. Enable Hardware Acceleration

Make sure the following line is present to enable hardware video decoding:


  1. Disable Desktop GUI

Temporarily disabling the desktop GUI can allocate more CPU and GPU resources just for video decoding:

sudo systemctl stop lightdm.service

  1. Lower Video Resolution

If you are still getting performance issues, try lowering the resolution of the video with OMXPlayer’s –win argument:

omxplayer –win “800 600” example-video.mp4

Start testing the maximum resolution your Pi can handle smoothly.

Integrating OMXPlayer into Python Scripts

You can launch and control OMXPlayer straight from a Python script.

First, install the omxplayer-wrapper module:

sudo pip install omxplayer-wrapper

Then you can initialize OMXPlayer and play a video:


import omxplayer 

from omxplayer.player import OMXPlayer

video = OMXPlayer(‘example-video.mp4’

See theomxplayer-wrapper documentation for the full API reference.

Troubleshooting Tips

Here are solutions for common OMXPlayer issues on the Raspberry Pi:

Choppy Playback at High CPU Usage

Lower display resolution, enable hardware acceleration in config.txt, or upgrade your Pi for smoother playback.

No Audio

Check audio output settings with omxplayer -h. Try changing device parameter, like omxplayer –adev hdmi video.mp4.

Window Out of Bounds Errors

Specify window size that fits your display using –win option.

Video is Distorted or Green/Pink

The video codec may be incompatible. Try converting source video to H.264 MP4 which has wide compatibility.

Can’t Open Display

If playing video over SSH, export the display with export DISPLAY=:0 first.

Performance Optimization Tips

To squeeze the max video playback performance from your Pi with OMXPlayer:

  • Overclock your Pi’s CPU and GPU
  • Attach heatsinks to chips if overclocking
  • Use active cooling fan or case if overclocking
  • Make sure using appropriate high quality power supply
  • Disable background processes and desktop environment
  • Lower graphical intensity of video where possible
  • Use hardware accelerated H.264 MP4 videos where possible

Even with optimization – the Pi has hardware limitations on video decoding, especially at high resolutions. So manage your expectations accordingly!


Hopefully this guide has given you a good overview of utilizing OMXPlayer to smoothly play videos on the Raspberry Pi. It may require some tweaking of configuration but can enable a lightweight media center option leveraging the GPU’s video acceleration.

Key Takeaways

  • OMXPlayer utilizes hardware acceleration for smooth video playback
  • Increase GPU memory and enable hardware acceleration
  • Lower resolution if struggling with performance
  • Integrate into Python scripts with omxplayer-wrapper
  • Overclocking the CPU/GPU can help increase performance

Frequently Asked Questions

Q: How do I exit or quit OMXPlayer?
A: Press the Q key or ESC while a video is playing to stop and quit OMXPlayer.

Q: Can I resize the OMXPlayer window?
A: Yes, use the –win argument followed by the video resolution. For example, omxplayer –win “1920 1080” my-video.mp4 opens the video playback window at 1080p resolution.

Q: Why is my video corrupted or green/pink colors?
A: This usually indicates codec incompatibility. Try converting the source video to H.264 MP4 format for maximum compatibility.

Q: Can I speed up or slow down playback?
A: Yes! Use – and + keys while playing to slow down or speed up playback respectively.

Q: How can I loop or repeat video playback?
A: Use the –loop argument when launching OMXPlayer to continually loop playback. For example, omxplayer –loop my-video.mp4.

Q: How do I take a screenshot with OMXPlayer?
A: Press s while a video is playing to take a screenshot that will be saved to your home directory.

Q: Why is OMXPlayer only playing audio?
A: If only getting audio, it usually means a display environment is not available. Make sure you are not running OMXPlayer strictly from SSH.

Q: Can OMXPlayer play YouTube or online media?
A: No, OMXPlayer is made for playing local media files. To play online video, use a streaming application like Kodi instead.

Q: How can I customize OMXPlayer controls and key bindings?
A: The config file is located at /etc/omxplayer.ini – you can remap keys by editing this file.

Q: What video and audio formats work with OMXPlayer?
A: It supports most codecs out of the box like H.264, VC-1, MPEG-2, MPEG-4, VP8, Theora, and Vorbis in common containers like MP4, WebM, MKV, MOV without additional libraries or binary blobs.

Q: Why is my video playback slow and choppy?
A: Try lowering the video resolution, disabling background processes, overclocking the GPU, and enabling hardware acceleration in /boot/config.txt. Video playback can be resource intensive on the Raspberry Pi.

Q: Can I use OMXPlayer remotely from my PC?
A: Yes, you can access OMXPlayer over SSH. Just export the display with export DISPLAY=:0 before launching omxplayer. The video will play on the Pi’s screen.

Q: Does OMXPlayer work on Android?
A: No, OMXPlayer is specifically made for Linux on the Raspberry Pi utilizing VideoCore APIs. It does not run on Android or other platforms.

Q: How do I play a video from YouTube or the web?
A: OMXPlayer only supports playing local video files. To stream online media, use Kodi or install a web browser like Chromium.

Q: Can I schedule or automate video playback?
A: Yes, create a cron job or systemd service that runs omxplayer with your desired video file at the times needed.

Q: How can I control OMXPlayer from my own program?
A: Import the omxplayer-wrapper module in Python to control and launch OMXPlayer straight from a Python script.

Q: Why am I getting an error – “Error: Unable to open display”
A: This means OMXPlayer is not able to access the X environment. Make sure you are not running strictly via SSH without exporting the display first.

Q: How do I always play videos muted by default
A: Use the -o both argument to always mute audio, e.g. omxplayer -o both my-video.mp4

Q: Can I add subtitles to video playback?
A: Yes! Pass in the subtitle file (SRT or VTT format) with the –subtitles argument.

Q: How can I adjust audio sync if video and audio is out of sync?
A: Use -I or -D while playing back a video to nudge the audio sync by +/- 100ms until properly aligned with video.

Q: Instead of playing videos full screen, can I embed inside a GUI window?
A: Look into omxplayer-wrapper’s OMXPlayerGUI class to show the video output in a movable and resizable window instead.

Leave a Comment