Skip to content

Building on Linux

Jump to bottom
Martin Vallevand edited this page Mar 27, 2026 · 10 revisions

Building libmpv

Custom libmpv SDK builds for yauiclient with teletext support (libzvbi) and hardware decoding.

Linux x86_64

Built on Debian 11 (glibc 2.31) for broad compatibility. Works on Ubuntu 20.04+, Debian 11+, Linux Mint 20+, and any Debian-based distro with glibc 2.31+.

Raspberry Pi / ARM builds are in development. aarch64 support is planned for a future release.

Feature Profile

  • OpenGL render API (mpv_render_context / MPV_RENDER_API_TYPE_OPENGL)
  • VAAPI hardware decoding (Intel/AMD)
  • VDPAU hardware decoding (NVIDIA)
  • ALSA, PulseAudio and PipeWire audio output
  • LuaJIT scripting
  • Blu-ray playback (libbluray)
  • Teletext subtitles (libzvbi — statically linked into avcodec)
  • Wayland + X11 display output
  • Generic x86-64 CPU baseline (SSE2 minimum)
  • No Vulkan, no encoders, no capture devices

MPV Versions

mpv tag FFmpeg libplacebo
v0.41.0 7.1.1 source-built (no Vulkan)
v0.40.0 7.1.1 source-built
v0.39.0 6.1.1 source-built
v0.38.0 6.1.1 source-built
v0.37.0 6.1.1 source-built

Prebuilt Downloads (Linux)

Built on Debian 11 — compatible with Ubuntu 20.04+, Debian 11+, Mint 20+.

v0.41.0

File Link
SDK libmpv-sdk-v0.41.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.41.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.41.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.41.0-linux-x86_64.sha256

v0.40.0

File Link
SDK libmpv-sdk-v0.40.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.40.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.40.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.40.0-linux-x86_64.sha256

v0.39.0

File Link
SDK libmpv-sdk-v0.39.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.39.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.39.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.39.0-linux-x86_64.sha256

v0.38.0

File Link
SDK libmpv-sdk-v0.38.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.38.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.38.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.38.0-linux-x86_64.sha256

v0.37.0

File Link
SDK libmpv-sdk-v0.37.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.37.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.37.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.37.0-linux-x86_64.sha256

Using the Prebuilt Linux SDK

# Download SDK and runtime for your chosen mpv version
curl -L -o /tmp/libmpv-sdk-v0.41.0-linux-x86_64.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-sdk-v0.41.0-linux-x86_64.tar.gz
curl -L -o /tmp/libmpv-runtime-v0.41.0-linux-x86_64.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-runtime-v0.41.0-linux-x86_64.tar.gz

# Extract SDK to ~/.local
mkdir -p ~/.local
tar xzf /tmp/libmpv-sdk-v0.41.0-linux-x86_64.tar.gz -C ~/.local

# Install runtime to /usr/local/lib
sudo mkdir -p /usr/local/lib
sudo tar xzf /tmp/libmpv-runtime-v0.41.0-linux-x86_64.tar.gz -C /usr/local/lib
sudo ldconfig

Install yauiclient build dependencies (x64):

sudo apt install -y \
  build-essential cmake ninja-build pkg-config git \
  libglfw3-dev libfmt-dev \
  nlohmann-json3-dev zlib1g-dev \
  libcurl4-dev

Note: cpr (C++ HTTP library) is not packaged on most distros and will be fetched automatically via CMake FetchContent during the build.

Then build yauiclient (x64) using build-linux.sh from the yauiclient repo:

LIBMPV_SDK_DIR=$HOME/.local ./build-linux.sh Release

Or manually with cmake:

cmake -B build -S /path/to/yauiclient \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLIBMPV_SDK_DIR=$HOME/.local
cmake --build build --parallel

Building on Debian-based Systems

For Ubuntu 20.04+, Debian 11+, Linux Mint 20+ and derivatives.

Install Prerequisites

sudo apt-get install -y \
  build-essential nasm yasm pkg-config \
  meson ninja-build cmake git \
  autoconf automake libtool gettext \
  libass-dev libfreetype6-dev libfribidi-dev libharfbuzz-dev \
  libbluray-dev liblcms2-dev libluajit-5.1-dev \
  libfontconfig-dev libjpeg-dev zlib1g-dev libpng-dev \
  libva-dev libvdpau-dev

Remove these dev packages to prevent mpv picking them up:

sudo apt-get remove -y libavdevice-dev libcdio-dev libcdio-paranoia-dev

Note on libcurl: Only one curl SSL backend dev package can be installed at a time. Keep whichever is already present:

sudo apt-mark hold libcurl4-gnutls-dev   # or libcurl4-openssl-dev

Runtime Dependencies

These need to be present on any machine running yauiclient:

sudo apt install -y \
  libluajit-5.1-2 \
  libjpeg62-turbo \
  libass9 \
  libbluray2 \
  libfontconfig1 \
  libfreetype6 \
  libharfbuzz0b \
  liblcms2-2

Build

chmod +x build-libmpv-linux.sh
./build-libmpv-linux.sh v0.41.0 v0.40.0 v0.39.0 v0.38.0 v0.37.0

If you only need a specific mpv version and want to save time, the FFmpeg build is stamped and reused — building a single tag after the first full run is much faster.

Proxmox VM Settings

A minimal VM is sufficient — the prebuilt FFmpeg stamps mean subsequent builds only rebuild mpv itself:

Setting Value
CPU 4 cores, type: host
RAM 4 GB (3 GB is workable), balloon: disabled
Disk 20 GB SSD
Guest OS Debian 11 for maximum compatibility

balloon: 0 prevents memory reclaim during linking which can cause OOM kills.

Building on Arch Linux

Install Prerequisites

sudo pacman -S --needed \
  base-devel nasm yasm pkgconf meson ninja cmake git \
  autoconf automake libtool gettext \
  libass freetype2 fribidi harfbuzz \
  libbluray lcms2 luajit \
  fontconfig libjpeg-turbo zlib libpng \
  libva libvdpau

Remove conflicting packages:

sudo pacman -R libavdevice 2>/dev/null || true

Build

chmod +x build-libmpv-linux.sh
./build-libmpv-linux.sh v0.41.0

Building on Other Distributions

TBA — guides for Fedora/RHEL, openSUSE and other RPM-based distros are planned. The build-libmpv-linux.sh script should work on most distributions with equivalent packages installed. The main requirements are meson 0.60+, ninja, nasm, and the development headers listed above.

macOS x86_64

Built on macOS 13.0+ (Ventura) with deployment target 13.0 for broad compatibility. Works on macOS 13 (Ventura), 14 (Sonoma), and 15 (Sequoia) on Intel x86_64.

Apple Silicon (arm64) — the build script supports arm64 but prebuilt tarballs are not yet available. Build from source on Apple Silicon using the same script.

Feature Profile

  • OpenGL render API (mpv_render_context / MPV_RENDER_API_TYPE_OPENGL)
  • VideoToolbox hardware decoding (H.264, HEVC, AV1)
  • AudioToolbox audio output
  • AVFoundation / CoreMedia integration
  • LuaJIT scripting
  • Blu-ray playback (libbluray)
  • Teletext subtitles (libzvbi — statically linked into avcodec)
  • No Vulkan, no encoders, no capture devices

MPV Versions

mpv tag FFmpeg libplacebo
v0.41.0 7.1.1 source-built (no Vulkan)

Prebuilt Downloads (macOS)

Built on macOS 15.2 (Sequoia) with deployment target 13.0 — compatible with macOS 13+.

v0.41.0

File Link
SDK libmpv-sdk-v0.41.0-macos-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.41.0-macos-x86_64.sha256
Runtime libmpv-runtime-v0.41.0-macos-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.41.0-macos-x86_64.sha256

Using the Prebuilt macOS SDK

# Download SDK and runtime
curl -L -o /tmp/libmpv-sdk-v0.41.0-macos-x86_64.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-sdk-v0.41.0-macos-x86_64.tar.gz
curl -L -o /tmp/libmpv-runtime-v0.41.0-macos-x86_64.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-runtime-v0.41.0-macos-x86_64.tar.gz

# Extract SDK to ~/.local
mkdir -p ~/.local
tar xzf libmpv-sdk-v0.41.0-macos-x86_64.tar.gz -C ~/.local

# Extract runtime alongside yauiclient binary
mkdir -p ~/yauiclient/build/macos-Release
tar xzf libmpv-runtime-v0.41.0-macos-x86_64.tar.gz -C ~/yauiclient/build/macos-Release

Build yauiclient against the SDK:

export PKG_CONFIG_PATH="$HOME/.local/lib/pkgconfig:$PKG_CONFIG_PATH"
cmake -B build/macos-Release -S . -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLIBMPV_SDK_DIR=$HOME/.local
cmake --build build/macos-Release --parallel $(sysctl -n hw.logicalcpu)

Run (runtime dylibs are found automatically via @executable_path rpath):

./build/macos-Release/yauiclient

Building from Source on macOS

Install Prerequisites

brew install cmake meson ninja pkg-config nasm autoconf automake \
  libtool gettext luajit libbluray lcms2 libass freetype harfbuzz \
  fribidi fontconfig jpeg-turbo zlib libpng uchardet

Build

chmod +x build-libmpv-macos.sh
./build-libmpv-macos.sh v0.41.0

Output tarballs will be in out/:

  • libmpv-sdk-v0.41.0-macos-x86_64.tar.gz
  • libmpv-runtime-v0.41.0-macos-x86_64.tar.gz

Notes

  • The script is fully resumable — stamp files prevent redundant rebuilds of FFmpeg, libplacebo and libzvbi
  • libplacebo is built from source with Vulkan disabled
  • libzvbi is built from source and statically linked into avcodec
  • MACOSX_DEPLOYMENT_TARGET defaults to 13.0 — override to target older macOS versions
  • On Apple Silicon the script auto-detects arm64 and produces macos-arm64 tarballs

Build Script Environment Overrides

Linux (build-libmpv-linux.sh)

Variable Default Purpose
FFMPEG6_VERSION 6.1.1 FFmpeg version for mpv < v0.40.0
FFMPEG7_VERSION 7.1.1 FFmpeg version for mpv >= v0.40.0
LIBPLACEBO_VERSION 7.351.0 libplacebo version (source-built, no Vulkan)
ZVBI_VERSION 0.2.44 libzvbi version (source-built, static)
WORK_DIR $PWD/work Scratch space for sources and builds
OUT_DIR $PWD/out Output directory for tarballs
INSTALL_PREFIX $HOME/.local Optional install prefix
JOBS nproc Parallel build jobs

macOS (build-libmpv-macos.sh)

Variable Default Purpose
FFMPEG7_VERSION 7.1.1 FFmpeg version
LIBPLACEBO_VERSION 7.351.0 libplacebo version (source-built, no Vulkan)
ZVBI_VERSION 0.2.44 libzvbi version (source-built, static)
MACOSX_DEPLOYMENT_TARGET 13.0 Minimum macOS version
WORK_DIR $PWD/work Scratch space for sources and builds
OUT_DIR $PWD/out Output directory for tarballs
INSTALL_PREFIX $HOME/.local Optional install prefix
JOBS sysctl -n hw.logicalcpu Parallel build jobs

SDK and Runtime Layout

Linux

SDK:
include/mpv/client.h  render.h  render_gl.h  stream_cb.h
lib/libmpv.so.2  libmpv.so  pkgconfig/libmpv.pc

Runtime (/usr/local/lib/):
libmpv.so.2  libplacebo.so.351
libavcodec.so.NN  libavfilter.so.NN  libavformat.so.NN
libavutil.so.NN  libswresample.so.N  libswscale.so.N

macOS

SDK:
include/mpv/client.h  render.h  render_gl.h  stream_cb.h
lib/libmpv.2.dylib  libmpv.dylib  pkgconfig/libmpv.pc

Runtime (alongside binary or in app bundle Frameworks/):
libmpv.2.dylib  libplacebo.351.dylib
libavcodec.NN.dylib  libavfilter.NN.dylib  libavformat.NN.dylib
libavutil.NN.dylib  libswresample.N.dylib  libswscale.N.dylib
libass.9.dylib  liblcms2.2.dylib  libbluray.3.dylib
libluajit-5.1.2.dylib  libuchardet.0.dylib  libjpeg.8.dylib

The source-built libplacebo coexists safely with any system libplacebo since the sonames differ.

On Linux run sudo ldconfig after installing to /usr/local/lib. On macOS dylibs are found via @rpath — no ldconfig needed.

Clone this wiki locally