Play, Inspect and Troubleshoot Media with ffplay

Something plays for ten seconds then ffplay drops the picture, and now you need to know why. This page covers opening a local file or network URL, jumping to a position, controlling the window, and gathering diagnostics instead of guessing. The examples match FFplay 8.0.1 from the FFmpeg package installed on this machine. Allow about ten minutes for a local file, or longer if you are investigating a stream.

You need a graphical desktop for the normal windowed examples, a readable input file or a trusted URL, and the ffplay binary. Most commands are ordinary user commands. Do not use sudo: it will not repair a missing codec or grant a remote service access that your user does not have.

1. Check the installed player

Start with version and help output. These commands do not open a media file or change anything:

$ command -v ffplay
/home/linuxbrew/.linuxbrew/bin/ffplay
$ ffplay -version | head -3
ffplay version 8.0.1 Copyright (c) 2003-2025 the FFmpeg developers
...
$ ffplay -h | sed -n '1,35p'

The exact build path and configuration will differ on another host. The useful checkpoint is that the command exists and reports a version. The installed manual describes the command as ffplay [options] [input_url]; the input can be a file or a URL supported by this FFmpeg build.

2. Play a local file

Give the input path as the final argument. Quote paths that contain spaces:

$ ffplay -- '/path/to/recording.mp4'

A window should open and playback should begin. The title defaults to the input filename. Press q or Esc to quit, p or the space bar to pause, and f to toggle fullscreen.

FFplay prints status and diagnostic messages in the terminal as well as drawing the video. That output is not a saved copy of the media. Check the process exit status after quitting if you are scripting a smoke test:

$ ffplay -- '/path/to/recording.mp4'
$ printf 'exit status: %s\n' "$?"
exit status: 0

Exit status 0 says that FFplay completed normally. It does not prove that every stream was rendered or that the whole file was watched.

3. Start at a position and limit the run

Use -ss to seek to a time and -t to play for a duration. Both arguments use FFmpeg time-duration syntax:

$ ffplay -ss 00:12:30 -t 00:00:20 -- '/path/to/recording.mp4'

This opens around twelve minutes and thirty seconds into the file and stops after twenty seconds. Seeking is not guaranteed to be frame-exact for every format. FFplay normally chooses the nearest seek point, so a short clip can begin slightly before or after the requested position.

For repeated review, set the keyboard seek interval. The default left and right arrow interval is ten seconds:

$ ffplay -seek_interval 2 -- '/path/to/recording.mp4'

Use the arrow keys during playback and watch the position in the terminal statistics. If the display is distracting, press p to pause before seeking.

4. Control what is shown and heard

These options are useful when isolating a stream problem:

$ ffplay -an -- '/path/to/recording.mp4'
$ ffplay -vn -- '/path/to/audio-file.m4a'
$ ffplay -fs -- '/path/to/recording.mp4'
$ ffplay -volume 30 -- '/path/to/recording.mp4'

-an disables audio and -vn disables video. -fs starts fullscreen. Volume is on a scale where 0 is silence and 100 means no volume reduction or amplification; values below 0 are treated as 0 and values above 100 as 100. These settings affect the player process only. They do not alter the source file.

If you need a terminal-only check, use -nodisp. Some inputs still need a usable audio output, so this is not the same as a complete headless transcode:

$ ffplay -nodisp -autoexit -- '/path/to/audio-file.m4a'

-autoexit exits when the video is done. Without it, FFplay may keep the process open after an input reaches its end, depending on the input and display mode.

5. Inspect an audio-only input

When there is no video, FFplay automatically selects an audio visualisation. You can choose it explicitly with -showmode:

$ ffplay -showmode waves -- '/path/to/audio-file.flac'
$ ffplay -showmode rdft -- '/path/to/audio-file.flac'

The available values are video or 0, waves or 1, and rdft or 2. Press w while playing to cycle through the available show modes. FFplay's default is video when playable video exists, otherwise it selects the RDFT display.

6. Diagnose a failure without hiding the evidence

If playback fails, first check the input path without changing it:

$ test -r '/path/to/recording.mp4' && echo readable
$ file '/path/to/recording.mp4'
$ ffplay -loglevel warning -- '/path/to/recording.mp4'

A missing readable result points to a path or permission problem. file is only a quick identification check; it does not replace FFmpeg's demuxing and decoding. The warning level keeps warnings and errors while reducing normal informational output. For a bug report, use a temporary working directory and -report:

$ report_dir=$(mktemp -d)
$ cd "$report_dir"
$ ffplay -report -- '/path/to/recording.mp4'
$ ls -l ffplay-*.log

-report writes the command line and debug log in the current directory and implies debug logging. Treat the log as sensitive: it can expose the input URL and local paths. Read it, redact those values, and remove the temporary directory after the report is no longer needed:

$ rm -rf -- "$report_dir"

That final command permanently removes the report. Confirm that report_dir contains only the disposable diagnostic files before running it. Never paste an access-token-bearing URL into a public bug report.

7. Handle streams and awkward inputs carefully

FFplay can open network protocols supported by the local build, including HTTP and HTTPS in this installation. A URL can contain credentials, query strings or shell metacharacters, so quote it:

$ ffplay -- 'https://example.invalid/media/test.mp4'

Replace the example URL with one you are authorised to access. Network playback can consume bandwidth and may keep a connection open. Do not use a live stream as a first test when a local sample is available. If the remote service is rate-limited or requires authentication, FFplay's error output is the evidence to investigate; repeatedly retrying will not fix an invalid URL.

For a file with several streams, the default selection is the best available stream in the relevant programme. Advanced selection is possible with -ast, -vst and -sst, which take stream specifiers. Inspect the complete installed help before using them on an unfamiliar file:

$ ffplay -h full | less

Do not copy an option from another FFmpeg build without checking this one. The package version, enabled libraries and available protocols affect what can be opened.

Done means