VMware ESXi and vSphere Cluster Management

Play Video from the Command Line on Raspberry Pi with omxplayer

Learn to play local video files from a Raspberry Pi terminal with omxplayer, route sound through HDMI, and control fullscreen playback without a desktop.

What omxplayer does

omxplayer is a historical Raspberry Pi command-line media player that was included with Raspbian. Raspbian was the earlier name of the Raspberry Pi operating system distribution now commonly associated with Raspberry Pi OS.

omxplayer was designed to use the Raspberry Pi GPU, or Graphics Processing Unit, for hardware-accelerated playback of supported video formats. Hardware acceleration allows suitable video decoding work to be handled by the graphics hardware instead of relying entirely on the CPU.

Because omxplayer runs in a command-line interface, you can start it from a terminal without opening a graphical desktop session. The video can occupy the display in fullscreen mode, meaning it is shown across the display rather than inside a desktop window.

Prerequisites

Open a terminal or log in to a Raspberry Pi text console.
Know how to enter shell commands.
Know the difference between filenames and filesystem paths.
Connect the Raspberry Pi to a display, such as a monitor or television, preferably through HDMI.

Understanding video file paths

A path tells Linux where a file is stored. An absolute path starts at the filesystem root directory, represented by /. For example:

/opt/vc/src/hello_pi/hello_video/test.h264

A relative path is interpreted from the terminal's current directory. For example, if a video is in the current directory, you can use:

omxplayer video.mp4

The general command structure is:

omxplayer /path/to/video-file

Replace /path/to/video-file with the actual location and filename. If the path contains spaces, quote it:

omxplayer "/home/pi/My Videos/demo video.mp4"

Play the bundled Big Buck Bunny sample

Some historical Raspbian installations included a Big Buck Bunny demonstration video as an H.264 elementary stream. H.264 is a video codec; the .h264 extension identifies the format of this sample file.

The historical sample path is:

/opt/vc/src/hello_pi/hello_video/test.h264

Start it with:

omxplayer /opt/vc/src/hello_pi/hello_video/test.h264

If the file and player are available, omxplayer opens the sample and begins fullscreen playback. The terminal remains associated with the running player until playback finishes or you quit.

Select HDMI audio output

HDMI is a connection that can carry video and audio. If your monitor, television, or receiver should produce the sound, explicitly select HDMI with the -o hdmi option:

omxplayer -o hdmi /opt/vc/src/hello_pi/hello_video/test.h264

The -o hdmi option goes after omxplayer and before the media path. It tells the player to direct audio to the HDMI-connected display or receiver.

Without this option, audio may use another configured route, such as the analog or local audio output where that output is available. The exact available routes depend on the Raspberry Pi model, operating-system configuration, player version, and connected hardware.

omxplayer command examples

Task	Command	Result
Play the bundled sample	`omxplayer /opt/vc/src/hello_pi/hello_video/test.h264`	Starts the bundled H.264 sample, normally fullscreen.
Play with HDMI audio	`omxplayer -o hdmi /opt/vc/src/hello_pi/hello_video/test.h264`	Starts the sample and directs audio to HDMI.
Play an arbitrary local file	`omxplayer /path/to/video-file`	Attempts to open the specified local media file.

Control playback from the keyboard

While omxplayer is running, its terminal session receives playback keys. These keystrokes are controls for the active player, not new shell commands. Keep the terminal focused and press the keys directly while the video is playing.

Keyboard controls during omxplayer playback

Key or key combination	Action	Notes
`Space` or `P`	Pause or resume	Press again to continue playback.
`Q` or `Esc`	Quit	Ends the active omxplayer session and returns to the shell.
Left and Right arrows	Short backward or forward seek	Moves through the video by a shorter interval.
Up and Down arrows	Longer backward or forward seek	Moves through the video by a larger interval.
`+` and `-`	Increase or decrease volume	Changes the player volume.
`1` and `2`	Decrease or increase audio delay	Useful when sound and picture are out of sync.
`Z` and `X`	Decrease or increase subtitle delay	Applies when subtitles are available and supported.
Version-specific aspect-ratio, zoom, and subtitle keys	Change display geometry or subtitle behavior	Common omxplayer versions provide additional keys for aspect ratio, zoom, subtitle selection, or subtitle visibility. Check the installed version's help output because these keys can vary.

Do not type Q, +, or an arrow key after the player has already exited and expect it to control playback. Once the process ends, the terminal is again waiting for shell commands.

Use omxplayer without a desktop environment

A Raspberry Pi can boot to a command-line environment instead of starting a graphical desktop. From that text-based environment, you can log in, run an omxplayer command, and watch video on a connected display.

This setup does not require a desktop window manager or a graphical application launcher. It does require that the display connection, permissions, media support, and player installation are working. A command-line-only setup is useful for simple video playback, signage, demonstrations, and systems where starting a full desktop is unnecessary.

Troubleshooting

The video file cannot be opened

Check the path, filename, and permissions. List the containing directory and verify that the file exists:

ls -l /opt/vc/src/hello_pi/hello_video/

For another file, check its parent directory and confirm that the current user can read it. A misspelled filename, wrong directory, or insufficient read permission can prevent playback.

Video appears but there is no HDMI sound

Run the command with -o hdmi.
Check that the monitor or television supports audio and is not muted.
Confirm that the intended HDMI cable and input are active.
Check whether the display or receiver is configured to receive audio from HDMI.

Playback controls do not work

Ensure that omxplayer is still running.
Click or switch to the terminal running the player so it has keyboard focus.
Send the keys directly during playback rather than entering them after the process has ended.

The video will not play or performs poorly

Not every codec, container, resolution, or encoding profile is supported equally by every Raspberry Pi and omxplayer installation. First test the supplied H.264 sample. Then try a known supported H.264 file. If a file still fails, inspect its codec, resolution, frame rate, and encoding settings; the file may also be damaged or the installed platform may lack the expected hardware support.

Key points

omxplayer starts local media from a terminal and historically used Raspberry Pi GPU capabilities for supported video.
Use an absolute or relative path after the player name.
The bundled sample is /opt/vc/src/hello_pi/hello_video/test.h264.
Use -o hdmi when sound should go through an HDMI-connected display or receiver.
Playback keys are sent to the active terminal session, not entered as separate shell commands.
A graphical desktop is not required, but the display, audio route, file permissions, and media format must be supported.

For related command-line media tasks, see other command-line video playback guidance.