Files
mpv-natives/README.md
T
david 4a0f1686b5 refactor: build libmpv on the LGPL license path
mpv is dual-licensed (LGPL-2.1+/GPL-2+). We build it with -Dgpl=false
and FFmpeg without --enable-gpl (every enabled feature - mjpeg/png
encoders, spdif muxer, libdav1d, all decoders - is LGPL-available), so
the resulting library is LGPL-2.1-or-later instead of GPL. That is the
license path applications embedding libmpv in-process (via JNA, as
jlibmpv does) need, since a GPL build's copyleft obligations would
reach into them.

Also ship a LICENSE-NOTICE.txt with each release and fix the release
workflow's reference to the reusable workflows' job outputs (needs.<id>.
<jobname>.outputs). Docs: README license section now states the LGPL
position explicitly.
2026-10-02 19:59:21 +02:00

4.4 KiB

mpv-natives

Self-built libmpv native binaries for jlibmpv, the Java/JNA wrapper library.

Why this repository exists

jlibmpv is 100% MIT and deliberately does not bundle any native binaries. The build here targets mpv's LGPL-2.1-or-later license path (-Dgpl=false, ffmpeg without --enable-gpl), so the resulting libmpv can be embedded into arbitrary — including closed-source — applications that load it in-process via JNA, without the GPL's copyleft obligations reaching into their code. End users who want a drop-in native they can point mpv.libmpv.path at (or that a RemoteNativeLocator can download) find them here, as versioned GitHub release assets.

  • Pinned version: mpv v0.41.0 — the exact client API (131077) the jlibmpv JNA bindings are validated against. A libmpv update means bumping MPV_REF (and the affected dependency pins) in ci/versions.env — the single source of truth for every version in this repository.
  • Build source: the mpv source tree is checked out at that tag by GitHub Actions and built with the vendored scripts in ci/ (build-libmpv-mingw64.sh, build-libmpv-macos.sh, build-libmpv-linux.sh). No mpv source or third-party binaries are stored in this repository.

Releases

Each platform produces a single self-contained library file plus a combined checksums.txt (SHA-256) for verification. Assets are published by pushing a tag of the form v<mpv-version> (e.g. v0.41.0), which triggers release.yml:

Asset Contents
mpv-natives-windows-x86_64-<ver>.dll libmpv-2.dll (all dependencies statically linked, mingw64 build)
mpv-natives-macos-universal-<ver>.dylib libmpv.dylib (universal arm64 + x86_64, all dependencies statically linked)
mpv-natives-linux-x86_64-<ver>.so libmpv.so (all dependencies statically linked, native x86_64 build)

Each native is fully self-contained: every dependency (ffmpeg, libass, libplacebo, harfbuzz, freetype, fribidi, …) is statically linked into the single library together with the C/C++ runtime where needed. The library depends only on the platform's system libraries, so there is no dependency closure to ship alongside it — jlibmpv loads it at runtime via JNA and never compiles against it, so no public headers are shipped.

Audio is the one area deliberately left to the OS stack: on Linux the PipeWire / Pulse / ALSA libraries are linked dynamically (mirroring CoreAudio on macOS and WASAPI on Windows), and mpv auto-probes them in the order pipewire → pulse → alsa. On Linux the self-built libmpv.so additionally removes the need for the distribution package (libmpv1), which lags behind in codec support (dav1d/AV1, x264/x265): the pinned ffmpeg 8.0.1 guarantees the full codec set on any recent glibc distribution.

How to use with jlibmpv

  1. Download the release asset for your platform (a single library file).

  2. Point jlibmpv at it: -Dmpv.libmpv.path=/path/to/mpv-natives-<platform>-<ver>.<ext>.

    Or let a RemoteNativeLocator fetch it — the download URL is deterministic from (platform, mpv version):

    https://github.com/kirbylink/mpv-natives/releases/download/v<ver>/mpv-natives-<platform>-<ver>.<ext>
    

    where <platform> is windows-x86_64 / macos-universal / linux-x86_64 and <ext> is dll / dylib / so respectively.

Building

Builds run on GitHub Actions. There is nothing to build locally.

  • A pull request runs the three per-platform builds as the check.
  • A v* tag builds all three and publishes the GitHub Release.
  • Manual runs are available in the Actions tab.

License

The release artifacts are built from mpv on its LGPL-2.1-or-later path (-Dgpl=false) and from FFmpeg without --enable-gpl, so the resulting libmpv is LGPL-2.1-or-later (the ffmpeg libraries inside are likewise LGPL, with BSD-licensed components such as dav1d). Distributing an application that loads one of these libraries is fine under any license; the LGPL only requires that the user be able to replace the library with a different build (which is exactly what mpv.libmpv.path allows) and that you keep the library's license and source-available terms for the library itself. If you use a GPL distribution instead, the GPL's obligations apply.

The build scripts and workflows in this repository are MIT-licensed. See LICENSE for the repository's license terms.