Understanding ffplay: Playback Workflow and Core Components

The FFmpeg framework consists of command‑line tools and libraries; ffplay is one of the tools that can play local and network media streams. This article examines ffplay’s overall playback process and extracts design ideas for building a simple media player.

1. Player Workflow

Protocol demuxing: Network streams are segmented by protocols (RTMP, HTTP, HLS, MPEG‑DASH, etc.) into packets. The demuxing step removes signaling data and outputs raw audio/video container data.

Container demuxing: Containers (MP4, FLV, MPEG‑TS, AVI, MKV, MOV…) are split into separate audio and video streams for decoding.

Decoding: Compressed video (H.264/H.265, MPEG‑2, AV1, VP8/9…) and audio (AAC, MP3…) are decoded back to raw frames (YUV/RGB for video, PCM for audio).

AV sync: Decoded audio and video are synchronized before being sent to the sound card and GPU.

2. main() Function

Running ffplay -i input.mp4 -loop 2 launches the player. The entry point resides in fftools/ffplay.c . The source is based on FFmpeg 4.4.

2.1 Environment Initialization

init_dynload : Calls SetDllDirectory("") to remove the current working directory from the DLL search path (Windows security measure).

av_log_set_flag : Sets log flag AV_LOG_SKIP_REPEATED to suppress duplicate messages.

parse_loglevel : Parses -loglevel and enables -report to write logs to a file.

avdevice_register_all : Registers special device input formats.

avformat_network_init : Initializes network resources for streaming.

parse_options : Parses command‑line options (e.g., -i , -loop ) and stores filename and format.

2.2 SDL Initialization

SDL_Init : Initializes SDL with default flags for video, audio, and timers (flags can disable audio/video via -an or -vn ).

SDL_CreateWindow : Creates a window (default size 640×480) for video output.

SDL_CreateRenderer : Creates a rendering context associated with the window.

2.3 Media Stream Parsing

The stream_open function creates a VideoState structure, initializes FrameQueue (ring buffer for decoded frames), PacketQueue (linked list for demuxed packets), and clocks for AV sync. It also limits volume range and sets the default sync mode ( AV_SYNC_AUDIO_MASTER ).

2.4 Read Thread

read_thread runs in a separate SDL thread, performing protocol demuxing, packet queuing, and stream discovery. Key steps include:

Allocate AVFormatContext ( avformat_alloc_context ).

Set interrupt callback: ic->interrupt_callback.callback = decode_interrupt_cb; ic->interrupt_callback.opaque = is;

Open input ( avformat_open_input ) and find stream info ( avformat_find_stream_info ).

Determine video size via av_guess_sample_aspect_ratio and set_default_window_size .

Create decoder threads for each selected stream using stream_component_open .

3. stream_component_open

This function creates an AVCodecContext , finds the appropriate decoder with avcodec_find_decoder (or avcodec_find_decoder_by_name ), opens it via avcodec_open2 , and starts a decoder thread using SDL_CreateThread :

switch (avctx->codec_type) {
    case AVMEDIA_TYPE_AUDIO:
        // start audio decoder thread
        break;
    case AVMEDIA_TYPE_VIDEO:
        // start video decoder thread
        break;
    case AVMEDIA_TYPE_SUBTITLE:
        // start subtitle decoder thread
        break;
}

4. Video Decoder Thread (video_thread)

The thread repeatedly calls get_video_frame , which uses decoder_decode_frame (internally avcodec_receive_frame ) to obtain decoded AVFrame objects. Frames are placed into the video FrameQueue via queue_picture (which calls frame_queue_push ).

static void frame_queue_push(FrameQueue *f) {
    if (++f->windex == f->max_size)
        f->windex = 0;
    SDL_LockMutex(f->mutex);
    f->size++;
    SDL_CondSignal(f->cond);
    SDL_UnlockMutex(f->mutex);
}

5. Audio‑Video Synchronization

ffplay defaults to video‑sync‑to‑audio ( AV_SYNC_AUDIO_MASTER ). The sync logic in video_refresh compares video and master clocks, decides whether to drop a frame, repeat the previous frame, or display the current one. Frame dropping is controlled by the -framedrop option and the sync mode.

6. Rendering

After a frame is ready, video_display uploads the frame to an SDL texture (via upload_texture ) and presents it with SDL_RenderPresent(render) . Audio rendering follows a similar path, with resampling if needed.

7. Conclusion

The article provides a high‑level overview of ffplay’s playback pipeline, introduces key FFmpeg functions, and offers insight useful for building a simple media player.