Merge pull request #5 from kirbylink/docs/generalize-README

docs: generalize the README and add release/download badges
This commit is contained in:
kirbylink
2026-10-06 10:45:08 +02:00
committed by GitHub
+49 -30
View File
@@ -1,23 +1,37 @@
# mpv-natives
![Release](https://img.shields.io/github/v/release/kirbylink/mpv-natives)
![mpv v0.41.0](https://img.shields.io/badge/mpv-v0.41.0-informational)
![Downloads (latest release)](https://img.shields.io/github/downloads/kirbylink/mpv-natives/latest/total)
![Downloads (all releases)](https://img.shields.io/github/downloads/kirbylink/mpv-natives/total)
![License](https://img.shields.io/github/license/kirbylink/mpv-natives)
Self-built [libmpv](https://mpv.io/manual/#libmpv) native binaries for
[jlibmpv](https://github.com/kirbylink/jlibmpv), the Java/JNA wrapper library.
Linux, macOS and Windows. The binaries are plain library files with no
language-specific content, so they can be loaded from any language or
binding (FFI, JNA, ctypes, …). The repository started as the native
provider for [jlibmpv](https://github.com/kirbylink/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.
The official mpv releases do not ship a standalone `libmpv` — it is only
embedded in the platform packages — and the community daily builds ship
rolling versions with debug symbols intact (the Windows `libmpv-2.dll`
alone is ~220 MB, versus ~35 MB stripped here). For a library that
applications can pin as a dependency, this repository provides a pinned,
stripped, self-contained `libmpv`, reproducible from its tag alone.
- **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.
The artifacts target 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, without the GPL's copyleft obligations reaching into their code.
- **Pinned version:** mpv `v0.41.0` (client API 131077) — the exact,
stable revision every release asset is built from. 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`).
@@ -30,18 +44,25 @@ Each platform produces a single self-contained library file plus a combined
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) |
| Asset | Contents | Size |
|---|---|---|
| `mpv-natives-windows-x86_64-<ver>.dll` | `libmpv-2.dll` (all dependencies statically linked, mingw64 build) | ~35 MB |
| `mpv-natives-macos-universal-<ver>.dylib` | `libmpv.dylib` (universal arm64 + x86_64, all dependencies statically linked) | ~68 MB |
| `mpv-natives-linux-x86_64-<ver>.so` | `libmpv.so` (all dependencies statically linked, native x86_64 build) | ~35 MB |
Per-asset download counts of the latest release (the release page only
shows a combined total):
![windows x86_64](https://img.shields.io/github/downloads/kirbylink/mpv-natives/latest/mpv-natives-windows-x86_64-0.41.0.dll)
![macos universal](https://img.shields.io/github/downloads/kirbylink/mpv-natives/latest/mpv-natives-macos-universal-0.41.0.dylib)
![linux x86_64](https://img.shields.io/github/downloads/kirbylink/mpv-natives/latest/mpv-natives-linux-x86_64-0.41.0.so)
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.
closure to ship alongside it. Consumers load the library at runtime and
never compile 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
@@ -51,14 +72,11 @@ 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
## Using the release assets
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):
Use the release asset for your platform (a single library file) directly,
or fetch it programmatically — the download URL is deterministic from
(platform, mpv version):
```
https://github.com/kirbylink/mpv-natives/releases/download/v<ver>/mpv-natives-<platform>-<ver>.<ext>
@@ -83,9 +101,10 @@ The release artifacts are built from mpv on its **LGPL-2.1-or-later** path
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.
different build (trivially possible since it is loaded as a separate file
at runtime) 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](LICENSE) for the repository's license terms.