简体中文

SDLplayerCore

A lightweight C++ audio/video player core, helping you to deeply understand the multi-threaded application of FFmpeg and SDL.

Table of Contents

• SDLplayerCore
  • Table of Contents
  • Introduction
  • Architecture Overview
  • Features
  • Quick Start
    • Prerequisites
    • Compilation and Building
    • Project File Structure
  • How to Use
  • Feedback
  • Planned Features
  • License
  • Acknowledgements
    • Core Dependencies
    • Learning and Reference Resources
    • Productivity Tools

Introduction

SDLplayerCore is a lightweight audio and video player application developed with C++11, FFmpeg 7, and SDL2. It primarily targets the Windows platform and serves as a complete case study for practical audio/video development.

Please note that the primary objective of this project is for teaching and demonstration purposes, not to create a full-featured daily-use player that can replace mature products like VLC or MPC.

Analysis with the Visual Studio Performance Profiler shows that SDLplayerCore maintains a stable CPU usage of under 3% when playing 1080P@30fps H.264 videos on a Windows 11 system with a Ryzen R7-5800H processor, demonstrating its high-performance capabilities.

The project currently implements the following:

• Buffer queue and flow control design in audio/video playback
• Core audio/video synchronization
• Play/Pause logic
• Window resizing

Through this project, developers can learn:

• FFmpeg 7 API: How to use the libavformat library for demuxing and the libavcodec library for audio/video decoding.
• SDL2 API: How to create windows, render video frames (AVFrame -> YUV -> RGB), and handle audio PCM data.
• Multithreaded Concurrent Programming: How to manage data reading/demuxing, audio/video decoding, and rendering modules in separate, safe threads, and communicate between them using modern C++11 mutexes and condition variables.
• Audio/Video Synchronization: A basic yet effective A/V sync strategy based on SDL_QueueAudio.
• CMake Build System: How to configure a cross-platform-oriented project with external library dependencies.

Live Demo:

The following GIF demonstrates the player's functionality, including playing video and audio-only files, window resizing, and pause/resume capabilities.

Architecture Overview

This project adopts a multi-threaded "producer-consumer" model, decoupling the playback process into five core threads. These threads exchange data through thread-safe buffer queues.

About design and implementation To gain a deep understanding of the player's architecture, data flow, and core mechanisms such as audio-video synchronization and flow control, please see our Design Document (DESIGN.md).

About Challenges & Solutions Throughout development, we tackled a series of complex technical challenges that shaped the project's final architecture. We have documented a few of the most representative cases—from diagnosis to the final solution—to share our hands-on experience with multithreading, performance, and stability. For a detailed breakdown, check out the Core Challenges Document (CHALLENGES.md)

About the Diagrams

Click to view diagram source files and editing instructions

The architecture diagrams and flowcharts in this project were created using Mermaid and Draw.io.

The illustrations displayed directly within the documentation are in .svg format. Their corresponding source files (the .drawio files and some mermaid source code stored in .md format) are located in the docs/assets/ directory.

If you need to modify the diagrams, the recommended workflow is as follows: first, edit the mermaid source code in the .md file, import it into the corresponding .drawio source file for adjustments, then export it as a new .svg image, update the image path in the documentation, and finally, commit all related files together.

Features

• Supports playback of major video formats (e.g., MP4, AVI, FLV)
• Supports playback of major audio formats (e.g., MP3, WAV, FLAC)
• Audio-video synchronization
• Video play, pause, and stop
• Window resizing

Quick Start

Prerequisites

Before compiling and running the program, ensure your development environment meets the following requirements:

• Operating System: Windows 10/11 (64-bit)
• IDE/Compiler: Visual Studio 2022 (v17.9+) with the "Desktop development with C++" workload installed.
• Build System: CMake (3.15+)
• Version Control: Git

Compilation and Building

1. Clone the project

   git clone https://github.com/Ko-vey/SDLplayerCore.git
   cd SDLplayerCore

2. Install Dependencies

   This project depends on FFmpeg 7 and SDL2. There are two ways to configure them:

   Method 1: Use vcpkg

   vcpkg is an efficient C++ library manager that simplifies the dependency installation process.

   # (If not already installed) Install vcpkg...
   git clone https://github.com/microsoft/vcpkg.git
   ./vcpkg/bootstrap-vcpkg.bat # or bootstrap-vcpkg.sh for other systems
   
   # Install dependencies for this project (e.g., for Windows x64)
   # Ensure they are FFmpeg 7 and SDL2 versions
   vcpkg install ffmpeg:x64-windows sdl2:x64-windows

   Method 2: Manual Download and Configuration

   If you prefer to manage dependencies manually, follow these steps.

   1. SDL2

      • Download SDL2-devel-2.32.2-VC.zip (for Visual C++) from the SDL2 official releases page.
      • Create a third_party/sdl2 folder in the project root and organize the extracted contents as follows:

        third_party/sdl2/
        ├── include/SDL2/  (contains all .h files)
        ├── lib/      (contains all .lib/.pdb files)
        └── bin/      (contains all .dll files)

   2. FFmpeg 7

      • Download the shared version of the library (libffmpeg_7.0_msvc17_x64.zip) from the Windows Builds recommended by FFmpeg's website.
      • Create a third_party/ffmpeg folder in the project root and organize the extracted contents as follows:

        third_party/ffmpeg/
        ├── include/  (contains libav* headers)
        ├── lib/      (contains .lib files)
        └── bin/      (contains .dll files)

      Note: When configuring manually, ensure the find_package paths in CMakeLists.txt match the directory structure.

   3. Build the Project

      • If using vcpkg:

        # -DCMAKE_TOOLCHAIN_FILE points to vcpkg's toolchain file
        cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=[vcpkg_path]/scripts/buildsystems/vcpkg.cmake
        
        # Compile
        cmake --build build

      • If configuring dependencies manually:

        # In a terminal like Developer Command Prompt for VS 2022
        # From the project root directory
        cmake -S . -B build
        # Compile
        cmake --build build

   After the build is complete, the executable will be located in the build/ Release directory. You can also open build/SDLplayerCore.sln with Visual Studio to compile and debug.

Project File Structure

After completing the basic setup, the project file structure will look roughly like this:

SDLplayerCore/
├── .github/              # GitHub related configurations
├── CMakeLists.txt        # CMake configuration file
├── README.md             # Project guide (Chinese version)
├── LICENSE               # License file
├── build/                # (Generated) CMake build directory for intermediate and final files
├── docs/                 # Project documentation
│   ├── assets/           # Image source files, etc., used in documentation
│   ├── CHALLENGES.md     # Core challenges document
│   └── DESIGN.md         # Design document
├── src/                  # Project source code
│   ├── include/          # Header files (.h)
│   │   ├── MediaPlayer.h # Main player class definition
│   │   └── ...           # Other core component headers
│   └── source/           # Source files (.cpp)
│       ├── MediaPlayer.cpp # Main player class implementation
│       ├── main.cpp      # Program entry point, handles user input and window events
│       └── ...           # Other core component implementations
└── third_party/          # (Optional) For manually placing third-party libraries
    ├── ffmpeg/           # FFmpeg library files
    └── sdl2/             # SDL2 library files

How to Use

1. Run the program:

   • Copy the .dll files from FFmpeg and SDL2 (located in third_party/.../bin/) to the directory where the executable SDLPlayer.exe resides (e.g., build/Release/).
   • Open a command-line tool (like CMD or PowerShell), navigate to that directory, and run the program.

2. Provide a media file:

   After the program starts, you will see a prompt. Enter or drag and drop the full path to the media file and press Enter.

   # Example
   PS D:\path\to\SDLplayerCore\build\Release> ./SDLPlayer.exe
   
   Please enter the path to the media file and press Enter:
   D:\Videos\demo.mp4

   About Test Files

   Click here for standard, copyright-free test resources\

   You can use any audio or video file on your computer for testing. If you need some, here are some commonly used, copyright-free standard test resources available for download:

   • Video with Audio Track:

     • Big Buck Bunny (BBB) (Multiple formats, for performance testing)

   • Video-Only:

     • Big Buck Bunny (1080p@60fps, MP4) (For quick tests)
     • Jellyfish Bitrate Test Files (Multiple formats, for performance testing)

   • Audio-Only:

     • Sample MP3 File (For quick tests)
     • Sample WAV File (For quick tests)

     After downloading, save the files on your computer and enter their full path into the program.

3. Playback Control:

   • Play/Pause: Press the Spacebar.
   • Stop Playback: Press the ESC key or close the player window.
   • Adjust Window: Drag the window edges with the mouse; the video frame will scale adaptively.

Feedback

This project primarily serves as a personal learning record and technical showcase. Therefore, I am not actively seeking code contributions (Pull Requests) at this time.

However, any form of discussion and feedback is highly welcome! If you encounter any issues, find a bug, or have suggestions and ideas about the project design, please contact me by creating an Issue: submit your problem or suggestion on the project's Issues page. I will check and respond periodically.

Thank you for your attention and understanding!

Planned Features

The priority order for planned features is as follows:

• Interaction Control
  • Simple UI and volume control (considering ImGui, implementing a progress bar, control buttons)
  • Progress seeking (Seek)
• Feature Enrichment
  • Subtitle rendering (e.g., .srt, .ass)
  • Network stream support (e.g., RTSP, HLS)
• Performance and Algorithm Optimization
  • Hardware acceleration (considering Direct3D 11)
  • Variable speed playback (considering FFmpeg's avfilter)
  • Dynamic clock synchronization

License

This project is licensed under the LGPLv3 (GNU Lesser General Public License v3.0). For the full license text, please see the LICENSE file.

Important Notice:

• This project depends on FFmpeg (usually licensed under LGPL) and SDL2 (licensed under the zlib License).
• When you use, modify, or distribute this software, you must comply with the license of this project as well as the licenses of all its dependencies.
• As required by the LGPL, you should use the FFmpeg library via dynamic linking to allow users to replace the library.

Acknowledgements

The realization of this project would not have been possible without the following excellent projects, efficient tools, and generously shared knowledge. I extend my sincere gratitude to them.

Core Dependencies

• FFmpeg - A powerful open-source multimedia framework that forms the basis for the core functions of this project, such as video/audio decoding and demuxing.
• SDL2 (Simple DirectMedia Layer) - An excellent cross-platform multimedia development library responsible for window creation, video rendering, and audio playback in this project.

Learning and Reference Resources

• Lei Xiaohua's (also known as Leixiaohua) Audio and Video Technology Blog - A profound tribute to the late Dr. Lei Xiaohua, a trailblazer in China's audio-visual technology field who passed away prematurely. His article 《最简单的基于FFMPEG+SDL的视频播放器 ver2 （采用SDL2.0）》 (The simplest video player based on FFMPEG+SDL ver2 (using SDL2.0)) and its series have been the starting point for countless audio-visual developers in China and served as the initial inspiration for this project.
• ffplay.c Source Code - The official player implementation provided by FFmpeg. It is the most authoritative and classic example for learning the core logic of a player, such as A/V synchronization and multithreaded processing.
• FFmpeg Development Getting Started Tutorial (Zhihu) - An excellent tutorial for C++ FFmpeg development, especially suitable for beginners who are not familiar with the FFmpeg API. It helps you understand A/V concepts and quickly set up and run your first demo.

Productivity Tools

• The successful completion of this project also benefited from the integration and application of various Large Language Models (LLMs) in the development process. They provided countless guidance and assistance in various stages such as information retrieval, solution design, code implementation, and documentation writing, greatly enhancing the development efficiency and quality of this project.