Build Garlic-Player for Desktop OS

Builds for desktop requires QWebengine. So, under Windows you cannot use mingw, and you need to install Microsoft Visual Studio. Free community version is sufficient. Currently, the build server uses VS 2017. You also need to compile or install a multimedia API first.

Mandatory Knowledge

You should be familiar with C++, Qt, and qt creator on your operating system. Furthermore, you have to know how to install the operating system SDK. Have a look at the supported platforms for your selected Qt version.

Multimedia APIs

The widget variant of the garlic-player supports for multimedia APIs. You can change then with the config variable set in Possible values are support_qtavaplayer, support_qtmm, support_libvlc, and support_qtav (deprectated).

  1. QtAVPlayer
  2. QtMultimedia
  3. libVLC
  4. QtAV (deprecated and replaced in v0.6.0)

QtAVPlayer (default)

QtAVPlayer is a small Qt wrapper around FFmpeg. It works fast and stable with FFmpeg 4.4 and 5.x.

Since Build 655 QtAVPlayer is default for the binary downloads.

QtAVPlayer is related to the Qt version. You find compile instructions in the readme here.

The stable v0.6.0 binaries use QtAVPlayer.

For Linux you need to install: apt install libavcodec-dev libavdevice-dev libavfilter-dev libavformat-dev libavresample-dev libavutil-dev libpostproc-dev libswresample-dev libswscale-dev fuse


One alternative to QtAVPlayer especially for Linux based systems is libVLC. On a Raspberry Pi 4 VLC is the only chance to get 4K work accelerated in full screen. FFmpeg hardware acceleration consumes more resources than libVLC.

The easiest way to install, is to use Linux package management or brew with macOS. There are compile instructions for Windows. Be aware that you have to compile it with Visual Studio and not mingw or cygwin.

LibVlc works fine on Linux X11, but it crashes on macOS for unknown reasons.


QtMultimedia is the standard Multimedia interface for Qt. Unfortunately, in Qt5 it is slow buggy and require the installation of additional libraries. Windows needs DirectShow and tons of codecs, Linux require gstreamer, which had also plenty of bugs in the past. With macOS, you had also to some QuickTime codes, otherwise VP8/9 and other video codecs Apple do not want to support will fail to play. Maybe things change in Qt6.

Some user reported that the K-Lite Codec Pack will work for Windows.

QtAV (default until build 654)

QtAV is a Qt wrapper around FFmpeg. It works until FFmpeg 4.4. Unfortunately, the maintainer has lost interest and abandoned it. His follow-up project is not open-source.

QtAV was default for the current binary downloads until build 654 and stable v0.5.0. Due to missing zero-copy features in Qt, QtAV produces lags on Raspberry Pi 3. Only Raspberry 4 plays videos smooth with garlic-player.

As QtAV is related to the Qt version, you had to compile it. The instructions are here. Keep in mind that FFmpeg 5 will not work, so use FFmpeg 4.4 as highest version.

In newer versions of garlic-player after July 2022 the pause behaviour was enhanced. Unfortunately this revealed an annoying memory leak. In stable release v0.6.0 QtAV is replaced by QtAVPlayer. Code will removed.

In short: Do not use it anymore.

Build Order

The build process for garlic-player desktop requires this order:

  1. zlib
  2. quazip
  3. garlic-lib
  4. player-widget

Automation and Deploying

If you want to deploy install files, throw a look in the script directory.