playerdemo: a small FFmpeg and SDL2 video player built for reading the source

A player whose purpose is to be studied

playerdemo is described as a video player, an open source version of PotPlayer, used to summarise and discuss media player development techniques, for learning and exchanging ideas about audio and video technology.

That framing is the whole point, and it changes how the project should be judged. This is not trying to be the best media player. It is a working, readable, small example of the stack a media player is made of, and the author explicitly welcomes questions from people working in the field.

The technical shape is three components, each one a well known library doing a well defined job. Decoding is FFmpeg 5.1 for x64, rendering is SDL2 2.0.7 for x64, and the interface on Windows is developed with Qt 5.12.x using the MinGW x64 toolchain.

That combination is a classic and a good teaching one. FFmpeg is where demuxing and codec handling live, SDL2 is where the frame gets onto the screen and where audio output and input handling live, and Qt is the application layer with its widgets, its file dialogs and its signals and slots. A reader who has never built a player can follow the path from a file on disk to a picture on screen by looking at these three boundaries.

The project is a demonstration and says so. The primary language is C++, the licence is GPL-3.0, and the repository is not archived with the last push on 2026-06-18.

One qmake project file opens on three platforms

The build system choice is worth noting, because it is unusual for a project of this vintage and it shapes the whole developer experience.

The project directory contains a `.pro` file, and it supports opening and building in Qt Creator on multiple platforms, Windows, Linux and Mac. That single file is the reason the three platform instructions in the documentation are nearly identical: open playerdemo.pro in Qt Creator, build, run.

The repository carries several build descriptions side by side, which tells you about the project's history. There is a `playerdemo.pro` for qmake, a `CMakeLists.txt`, a `playerdemo.sln` with a `playerdemo.vcxproj` and its filters file for Visual Studio.. The.pro is the one the documentation points at, and it is the one that carries the platform-specific configuration.

The macOS instructions show what that configuration looks like. The project file has a `macx` block where you set the include paths and libraries by hand:

macx {
    INCLUDEPATH += /usr/local/Cellar/sdl2/2.24.1/include
    LIBS += -L/usr/local/Cellar/sdl2/2.24.1/lib -lSDL2
    INCLUDEPATH += /usr/local/Cellar/[email protected]/5.1.1_1/include
    LIBS += -L/usr/local/Cellar/[email protected]/5.1.1_1/lib -lavcodec -lavdevice -lavfilter -lavformat -lavutil -lswresample -lswscale
}

The paths are absolute and version-pinned, so they have to be edited for your own machine, and the documentation says how to find the real ones: query the ffmpeg install directory with `brew info ffmpeg`, and query the SDL2 install directory with `brew info SDL2`, noting that installing ffmpeg brings the SDL2 dependency with it.

The set of FFmpeg libraries linked gives you the module map of the project, which is a nice free lesson. `lavcodec` is the codec layer, `lavformat` is the container demuxer, `lavdevice` is the device and input layer, `lavfilter` is the filter graph, `lavutil` is the shared utility code, `swresample` handles audio sample format conversion and `swscale` handles pixel format and scaling conversion. Anyone reading the source will find these names as the boundaries of the code.

Building on Linux is the shortest path

Of the three platform instructions, the Linux one is the cleanest, and it is the one to start with.

Install the SDL2 development package:

sudo apt-get install libsdl2-dev

Then the FFmpeg development packages, which the documentation lists as libavformat-dev, libavutil-dev, libavcodec-dev, libswscale-dev and others, installed individually:

sudo apt-get install libavformat-dev
sudo apt-get install libavutil-dev
sudo apt-get install libavcodec-dev
sudo apt-get install libswscale-dev

After that, open playerdemo.pro in Qt Creator and build.

The Windows path is different in kind, and the difference is instructive. Because the project was developed on Windows, the Windows instructions are the reference ones. The steps are to download the FFmpeg and SDL2 dynamic libraries, put the dlls in the `bin` directory, and replace the contents of the `lib` folder with the headers and lib files, downloading directly from the official sites. Then open playerdemo.pro in Qt Creator, build and run.

So on Windows the libraries are vendored into the project tree by hand, and on Linux they come from the system package manager. The reason is the same one that makes the macOS instructions fiddly: a qmake project with a checked-in library layout assumes you supply the binaries in a known place.

The macOS path is a hybrid. You install ffmpeg through Homebrew with:

brew install ffmpeg

and then you still have to edit the .pro file to point at the Homebrew Cellar paths, as shown above. The library versions there are 2.24.1 for SDL2 and 5.1.1 for ffmpeg, which do not match the versions the introduction lists, so the .pro file in the repository is not a configuration you can use as is on macOS.

The bitness warning is the one that bites

There is a short section at the end of the documentation with two notes, and the first is the important one.

When compiling, pay attention to unifying the versions and the bitness of the static and dynamic libraries. If the development environment is 64-bit, both the libraries and the header files must be 64-bit.

This is the classic native toolchain failure and it is worth understanding rather than memorising. A 32-bit FFmpeg DLL next to a 64-bit executable, or a header file from one build against a library from another, produces link errors that name the wrong symbols, or a program that loads and then fails deep inside a decoder with no useful message. Because the project is a 64-bit build using MinGW x64 and the libraries are x64 downloads, the mismatch only appears if you substitute something.

The reason it is called out is that the project ships its own `lib/` directory with placeholder content that you are told to replace. Someone who skips the replacement, or who copies 32-bit libraries in, gets a confusing failure rather than a clear one.

The second note explains the release situation. The packaged versions in the tag are built with actions and do not include the FFmpeg and SDL2 dynamic libraries, with the note that bundling them together is something to be worked out later.

So a tagged release is a source snapshot with a binary that needs the two runtimes supplied separately. For a study project that is fine, and it is honest, since the reason given is that the bundling question is unresolved rather than that it was overlooked.

The release history shows how rarely this happens. Version 0.1.0 came out on 2018-06-24 and v0.2.0 on 2023-01-26, and the repository has not been archived. Continuous integration covers three platforms, with build status badges for Windows, macOS and Ubuntu, which is a reasonable amount of infrastructure for a demonstration project.

What this project is not

It is worth being clear that playerdemo is not a PotPlayer and does not try to be one, even though the description calls it an open source version of PotPlayer.

The comparison to PotPlayer is about the shape of the application, a native desktop media player with a full feature set, not about the feature list. What is here is a player that plays a file and shows you how the pieces fit together. There is no playlist management, no subtitle pipeline described, no codec configuration UI, no recording.

The second thing to be clear about is that the project is a learning artefact rather than a maintained product, and the release history says so more plainly than any disclaimer would. Two releases in five years, with the most recent in January 2023, and a last push in June 2026. The recent push suggests someone still visits the repository, but a project that has not cut a release since 2023 is not going to gain features.

That is exactly the right shape for the stated purpose, and it is the reason to use it. A demonstration that is rewritten every six months is useless as a reference, and a demonstration that is stable and readable is a good one. Here the code has sat long enough that the author has had time to write it clearly, and the dependency versions it names are versions a reader can still find documentation for.

The alternative approaches to the same learning goal are worth naming. Reading the FFmpeg documentation and the SDL2 documentation separately gives you the reference but not the integration, and the integration is the hard part, because the demuxer hands you packets, the decoder turns them into frames, and the renderer has to convert the pixel format and scale before it can present it. That conversion chain, swscale and swresample in the linked library list, is exactly what a small project like this makes legible.

The other alternative is to write your own, which is the recommendation the project itself makes in spirit, since it exists to be read and then reimplemented. The GPL-3.0 licence permits that, with the obligation to keep the derivative under the same terms and to keep the notice, which is the practical constraint to be aware of if you plan to publish a player of your own.

One structural limitation follows from the design. The .pro file in the repository carries hardcoded Homebrew paths for a specific macOS configuration, and the Windows instructions require you to populate the `lib` and `bin` directories yourself. So a first build on either of those platforms is a configuration task before it is a compile task, and the Linux path is the one that works out of the box.

Editorial conclusion

playerdemo fits a developer who wants to read a complete, small video player end to end, because it wires FFmpeg decoding to SDL2 rendering through a Qt interface in one repository, and because the build is a single qmake project you can open in Qt Creator. Skip it if you want a usable player, since it is a demonstration and the packaged releases do not even bundle the FFmpeg and SDL2 shared libraries. Before you build it, line up the dependency versions yourself, since the project warns that static and dynamic library versions and bitness must match, and note the maintenance picture, with the last push on 2026-06-18 and the most recent release v0.2.0 from 2023-01-26.

Frequently asked questions

Official sources

1. Issues
2. itisyang/playerdemo on GitHub
3. License: GPL-3.0
4. README
5. Releases