mirror of
https://github.com/kirbylink/mpv-natives
synced 2026-11-21 09:54:39 +01:00
Merge pull request #5 from kirbylink/docs/generalize-README
docs: generalize the README and add release/download badges
This commit is contained in:
@@ -1,23 +1,37 @@
|
||||
# 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):
|
||||
|
||||

|
||||

|
||||

|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user