Skip to main content

​
Overview

ffplay is a minimalistic multimedia player built on the FFmpeg libraries and SDL (Simple DirectMedia Layer). It provides a simple way to play audio and video files with minimal overhead.
ffplay is described as a “simple media player based on the FFmpeg libraries” and was first released in 2003.

​
Basic Syntax

ffplay [options] input_url

​
Playback Options

​
input_url
string
required
Input file or URL to playExamples: video.mp4, http://example.com/stream.m3u8, rtsp://camera.local/stream
​
-f
string
Force input formatExample: -f mp4
​
-codec
string
Force decoder for specific stream typeVariants:
  • -vcodec - Video codec
  • -acodec - Audio codec
  • -scodec - Subtitle codec

​
Display Options

​
-x
integer
Force displayed widthDefault: 640
​
-y
integer
Force displayed heightDefault: 480
​
-fs
boolean
Start in fullscreen mode
​
-an
boolean
Disable audio
​
-vn
boolean
Disable video
​
-sn
boolean
Disable subtitles
​
-ss
time
Seek to specified position at startExample: -ss 00:01:30
​
-t
duration
Play duration in secondsExample: -t 60
​
-nodisp
boolean
Disable graphical display (audio only)
​
-noborder
boolean
Borderless window
​
-alwaysontop
boolean
Window always on top

​
Audio/Video Sync

​
-sync
string
Set A/V sync typeValues:
  • audio - Sync to audio clock (default)
  • video - Sync to video clock
  • ext - Sync to external clock
​
-autoexit
boolean
Exit when playback finishes
​
-exitonkeydown
boolean
Exit on any key press
​
-exitonmousedown
boolean
Exit on any mouse button press

​
Advanced Playback

​
-loop
integer
Set number of times to loop playbackDefault: 1 (loop indefinitely: 0)
​
-framedrop
boolean
Drop video frames if behindDefault: Enabled for non-reference frames
​
-infbuf
boolean
Enable infinite buffer (for realtime streams)
​
-window_title
string
Set window titleDefault: Input filename
​
-showmode
string
Set initial show modeValues:
  • 0, video - Show video
  • 1, waves - Show audio waves
  • 2, rdft - Show audio frequency band using RDFT

​
Filter Options

​
-vf
string
Video filtersExample: -vf "scale=1280:720"
​
-af
string
Audio filtersExample: -af "volume=0.5"

​
Hardware Acceleration

​
-hwaccel
string
Use hardware acceleration methodExamples: vaapi, cuda, qsv, videotoolbox
​
-vulkan
boolean
Enable Vulkan renderer

​
Keyboard Shortcuts

ffplay supports numerous keyboard shortcuts for controlling playback:
  • q, ESC - Quit
  • Space, p - Pause/Resume
  • m - Mute/Unmute
  • 9, 0 - Decrease/Increase volume
  • **/, *** - Decrease/Increase volume (numpad)
  • Left arrow - Seek backward 10 seconds
  • Right arrow - Seek forward 10 seconds
  • Down arrow - Seek backward 1 minute
  • Up arrow - Seek forward 1 minute
  • Page Down - Seek to previous chapter
  • Page Up - Seek to next chapter
  • Mouse click - Seek to percentage in file (relative to window width)
  • f - Toggle fullscreen
  • w - Cycle video display modes (video/waves/rdft)
  • s - Step to next frame (pause if playing)
  • t - Cycle subtitle display
  • c - Cycle program/channel
  • v - Cycle video streams
  • a - Cycle audio streams
  • i - Toggle stats display
  • d - Cycle through deinterlacing modes

​
Real-World Examples

​
Play a Video File

ffplay video.mp4

​
Play Audio Only

ffplay -vn audio.mp3

​
Play with Volume Adjustment

ffplay -af "volume=0.5" video.mp4

​
Play in Fullscreen

ffplay -fs video.mp4

​
Play and Auto-Exit

ffplay -autoexit video.mp4

​
Play from Network Stream

ffplay http://example.com/stream.m3u8

​
Play with Specific Start Time

ffplay -ss 00:05:00 video.mp4

​
Loop Video Indefinitely

ffplay -loop 0 video.mp4

​
Display Audio Waveform

ffplay -showmode waves audio.mp3

​
Display Audio Spectrum

ffplay -showmode rdft audio.mp3

​
Play with Custom Window Size

ffplay -x 1280 -y 720 video.mp4

​
Play Scaled Video

ffplay -vf "scale=1280:720" video.mp4

​
Test Pattern (No Input File)

ffplay -f lavfi -i testsrc=size=1280x720:rate=30

​
Visualize Audio Input

ffplay -f lavfi -i "amovie=audio.mp3,asplit[a][out1];[a]showwaves[out0]"

​
Performance Considerations

Low Latency

Use -fflags nobuffer -flags low_delay for minimal latency in live streams

Frame Dropping

Disable with -framedrop 0 for smooth playback on capable hardware

Buffer Size

Use -infbuf for infinite buffering on unstable network streams

Threading

Use -threads to control decoder thread count

​
Display Modes

ffplay supports three display modes (cycle with w key):
Standard video display - shows video frames as they are decoded

​
Source Code Reference

Key implementation details from the source code:
  • Program Birth Year: 2003 (fftools/ffplay.c:63)
  • SDL Integration: Uses SDL2 for rendering (fftools/ffplay.c:55)
  • Queue Sizes: Max queue size is 15MB (fftools/ffplay.c:65)
  • Sync Thresholds: AV sync threshold between 0.04 and 0.1 (fftools/ffplay.c:79-81)
  • Volume Step: 0.75 dB per volume change (fftools/ffplay.c:76)
ffplay is designed for testing and development purposes. For production playback applications, consider using dedicated media players or integrating FFmpeg libraries directly.

​
Troubleshooting

Try disabling frame dropping: ffplay -framedrop 0 video.mp4Or use hardware acceleration: ffplay -hwaccel auto video.mp4
Explicitly set sync method: ffplay -sync audio video.mp4
Enable hardware acceleration: ffplay -hwaccel cuda video.mp4
Use infinite buffer: ffplay -infbuf http://stream.url

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us