Play, Inspect and Test Media Safely with ffplay

A stray video file lands in your downloads folder, and ffplay is the fastest way to check it plays before you trust it anywhere else. You will preview a local media file, start at a chosen position, limit playback, and test an input without opening a window. The examples target the installed FFmpeg 8.0.1 package on this machine. Allow about 10 minutes if FFmpeg is already installed and your media file is easy to find.

Before you start

You need a shell, the ffplay command, and a readable audio or video file. Playback normally needs a graphical session and an available audio device. No command in this guide needs elevated privileges. Do not run a media file as a shell command, and do not use sudo to solve a missing desktop or device: that changes the problem rather than fixing it.

Set a shell variable to a real path. Quoting it protects spaces and shell metacharacters in the filename.

MEDIA_FILE='/path/to/media file.mp4'
test -r "$MEDIA_FILE" && printf 'Readable: %s
' "$MEDIA_FILE"

Expected output is one line beginning Readable:. If the test fails, correct the path or permissions before continuing. ffplay can read URLs as well as files, but start with a local file so network delays and remote content do not obscure a playback problem.

1. Check the installed build

Confirm which executable is being used and record its version. Options can vary between FFmpeg releases, so this is useful when comparing another machine or an old bug report.

command -v ffplay
ffplay -hide_banner -version

This guide was checked with FFplay 8.0.1. The second command prints the version and linked FFmpeg library versions, then exits. If the shell reports that ffplay is not found, install the distribution package that provides FFplay, then repeat this step. Installation is deliberately outside this guide because package names and privileges differ between distributions.

2. Play the file and use the essential keys

Run the file as the final argument. FFplay opens its display window, selects suitable streams, and prints playback statistics by default at the normal information log level.

ffplay "$MEDIA_FILE"

While the window has focus, use p or the space bar to pause, f to toggle fullscreen, and m to mute. The left and right arrow keys seek by 10 seconds; the down and up arrows seek by one minute. Press q or Escape to quit. A right mouse click seeks to the corresponding percentage of the file.

The player is interactive, so an apparent hang may simply be a window behind another application or a window waiting for focus. If the terminal fills with messages, that is usually diagnostic output rather than a second playback process. Keep the terminal visible when testing a new file.

3. Start at a position or stop automatically

Use -ss to seek to a time position before playback and -t to play only a duration. Both accept FFmpeg time duration syntax, such as seconds or a clock-style value. In most formats, -ss seeks to the nearest available seek point, so it is not guaranteed to begin on the exact frame.

ffplay -ss 00:02:30 -t 20 "$MEDIA_FILE"

This asks for roughly 20 seconds starting near two minutes and 30 seconds. The duration is a playback limit, not a conversion: it does not edit the original file. For a command that ends when the media ends, add -autoexit.

ffplay -autoexit "$MEDIA_FILE"

Use -loop 0 only when you really want an endless loop. It keeps the player running until you quit it, which is easy to forget in a test or unattended shell. A positive loop value repeats the movie that many times according to the installed manpage.

4. Test audio without opening a display

-nodisp disables the graphical display. Combine it with -autoexit and a short -t when you only need to confirm that an input can be opened and decoded.

ffplay -nodisp -autoexit -t 10 "$MEDIA_FILE"

Successful playback reaches the end of the requested interval and returns you to the shell. A missing audio device, unsupported format, or unreadable input produces an error on standard error. If the file contains no audio stream, this is the wrong test: use ordinary playback for video, or add -an when deliberately checking video only.

For a repeatable local smoke test, generate a one-second tone in memory. This does not create a file or change your system:

SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy ffplay -hide_banner -nodisp -autoexit -t 1   -f lavfi -i 'sine=frequency=440:duration=1'

The command should exit with status zero and report an audio stream from the lavfi input. The dummy SDL devices are useful on a headless test shell. They are not a way to hear audio, so remove those two environment assignments when checking real speakers.

5. Choose streams and viewing modes

A file can contain several audio, video, or subtitle streams. FFplay normally chooses the best available stream, but the interactive keys can cycle choices: a for audio, v for video, and t for subtitles. Use -ast, -vst, or -sst when you need a repeatable selection with a stream specifier.

ffplay -vst 0 -ast 1 "$MEDIA_FILE"

Do not copy those stream numbers blindly. Stream numbering depends on the input, so first read the stream information in the normal FFplay output or inspect the file with ffprobe if it is installed. If the selected stream does not exist, FFplay will fail or fall back differently from what you intended.

For an audio-only file, -showmode waves displays a waveform and -showmode rdft displays an audio frequency view. The default is video, with RDFT selected automatically when video is absent or cannot be played. Press w while playing to cycle through available show modes and video filters.

6. Keep troubleshooting evidence

When a file fails, make the error reproducible and preserve the log. -report writes a report containing the command line and log output in the current directory and implies debug logging. That file may include local paths and URLs, so review it before sharing and remove it afterwards if it is no longer needed.

ffplay -report -autoexit -t 5 "$MEDIA_FILE"
ls -1t ffplay-*.log | head -1

If you only need less output, -loglevel error shows errors and omits ordinary informational messages. If you need to see the normal statistics again after changing the log level, use -stats; statistics are shown by default unless the log level is below info. These switches affect diagnostics, not the media itself.

Common traps and recovery

• No window: check that a graphical session is available and that the window is not on another workspace. Use -nodisp only for an audio or decode test.
• No sound: check mute, the selected audio stream, and the desktop output device. -volume accepts 0 to 100, where 100 means no volume reduction or amplification.
• Seeking seems inaccurate: that is expected for many formats because FFplay seeks to the nearest seek point. Try a nearby position rather than treating it as file corruption.
• The terminal will not return: press q with the player focused. If a command was left looping with -loop 0, quit it before starting another copy.
• A report was created: it is ordinary output, not a system change. Inspect it, then remove that specific ffplay-*.log file when you no longer need it. Check the filename first; do not use a broad recursive deletion.