# Spec: Migrate to libmpv2 and declare the project licence

Status: Partially implemented — the `LICENSE` file has landed (part 2). The `libmpv` → `libmpv2` swap (part 1) is not done: `src-tauri/Cargo.toml` still pins the abandoned crate to a git branch. Requirements: UR-003 → IR-003 (revises the MPV integration); no new user-facing behaviour UX spec: n/a Supersedes / revises: dependency and licensing housekeeping identified in playback-backend-unification.md

## Summary

Two related pieces of housekeeping that block or complicate later work:

1. Replace the abandoned `libmpv` crate (pinned to a git branch) with the maintained `libmpv2`.
2. Add a `LICENSE` file. The project has none, which leaves its legal status undefined while it links GPL-licensed libmpv.

Neither changes user-visible behaviour. Both are prerequisites for windows-native-audio-backend.md.

## Motivation

### The dependency is dead

    # src-tauri/Cargo.toml
    libmpv = { git = "https://github.com/ParadoxSpiral/libmpv-rs.git", branch = "master" }

- crates.io `libmpv` 2.0.1 was published 2020-09-29.
- The upstream repo's last commit was 2023-01-08; nothing since was released.
- We pin a git branch, so builds are not reproducible — the same lockfile-less checkout can resolve differently over time, and CI has no protection if the branch moves or the repo disappears.

`libmpv2` (kohsine/libmpv2-rs) is a maintained fork of exactly this crate: 6.0.0 released 2026-05-12, ~23.5k recent downloads against the original's ~1.1k, releases roughly quarterly since 2024.

### The project has no licence

There is no `LICENSE`/`COPYING` file and `src-tauri/Cargo.toml` has no `license` field. The project is open source and will never be commercial, so this is purely an omission — but it matters because we link libmpv, and "no licence" defaults to all rights reserved, which is incompatible with distributing a GPL-derived work.

## Design

### Part 1 — licence

Use GPLv3. This is forced, not chosen:

- mpv's default build is GPLv2-or-later, so the combined work must be GPL-compatible.
- Apache-2.0 is GPLv2-incompatible (patent-termination and indemnification clauses) but GPLv3-compatible.
- A scan of the dependency tree found Apache-2.0-only crates with no alternative arm — most importantly `tao` (Tauri's own windowing crate), plus `sync_wrapper`, `gethostname`, and `ring` (Apache-2.0 AND ISC).

`tao` is unavoidable in a Tauri app, so GPLv2 is unavailable. Exercising mpv's "or later" option puts the combination at GPLv3.

Actions:

- Add `LICENSE` containing the GPLv3 text.
- Add `license = "GPL-3.0-or-later"` to `src-tauri/Cargo.toml` and `license` to `package.json`.
- Note in the README that the binary links libmpv (GPLv2+) and FFmpeg.

Because the project is open source, we use mpv's default GPL build — no `-Dgpl=false`, no LGPL FFmpeg build, and none of the LGPL §6 relinking analysis that a proprietary app would need. We keep VAAPI/VDPAU/X11 and every GPL FFmpeg filter.

🔴 Never build FFmpeg with `--enable-nonfree` — that produces a binary that is unredistributable under any licence, open source or not.

### Part 2 — libmpv → libmpv2

    # Linux (and later Windows, per the Windows audio spec)
    libmpv2 = "=6.0.0"

Pin exactly: `libmpv2` has broken its API in every major release.

Breaking changes to expect, from the changelog:

Version | Change | Impact here
--- | --- | ---
4.0.0 | Removed command helper methods — call `mpv.command(...)` directly | Low; we already use `command`/`set_property`
5.0.0 | Removed `mpv_node` support entirely (properties return strings; parse JSON yourself); `EventContext` folded into `Mpv`; `ProtocolContext` → `Protocol` | Medium — `start_event_loop` uses `create_event_context()`; check whether that call still exists
6.0.0 | `RenderContext::new()` → `Mpv::create_render_context()`; `'static` bound on `OpenGLInitParams`; render context now borrows `Mpv` (fixes a use-after-free) | None — we do not use the render API

The last row matters: we run mpv audio-only (`video = no`), so the entire render surface is irrelevant to us. Consider disabling the default `render` feature to reduce build surface.

The main porting work is the event loop in `mpv_backend.rs` — `wait_event`, `disable_deprecated_events`, and the `FileLoaded` / `PlaybackRestart` / `PropertyChange` / `EndFile` handling, given 5.0.0 folded `EventContext` into `Mpv`.

Everything else — `set_property` calls, the `af` filter graph, the 250ms position thread, the seek-suppression window — should port unchanged.

## Layer assignment

No logic moves. This is a dependency swap plus a licence file; the `PlayerBackend` trait boundary is untouched.

Logic / responsibility | Layer | Why it belongs there
--- | --- | ---
mpv event → `PlayerStatusEvent` mapping | Rust (unchanged) | Already correct; only the binding API beneath it changes.

## Out of scope

- Any behaviour change. If playback behaves differently after this, that is a bug.
- Windows support — separate spec, but this must land first.
- Adopting the render API. We are audio-only on mpv.
- Re-licensing decisions beyond adding the file the project already implies.

## Acceptance criteria

- `LICENSE` (GPLv3) present; `license` field set in `Cargo.toml` and `package.json`.
- A full dependency-licence audit has been run (`cargo install cargo-license && cargo license`) and confirms no GPLv3-incompatible dependency. (The scan behind this spec resolved 441 of 575 crates from the local registry cache; the remaining 134 are unverified.)
- `libmpv` git dependency removed; `libmpv2` pinned to an exact version.
- Linux audio playback works identically: play/pause/seek/volume, queue advance, gapless, EQ, normalization, sleep timer.
- Position updates still arrive at 250ms; the 150ms post-seek suppression still prevents the jump-to-zero glitch.
- `EndFile` still emits `PlaybackEnded` only for EOF (not STOP/QUIT/ERROR) — autoplay depends on this.
- Builder image updated if the libmpv dev package requirement changed; no toolchain install added to any CI step.
- `bun run check`, `bun run test`, `bun run check:boundary` pass.
- `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.

## Testing

The existing `mpv_backend_test.rs` plus the `build_af_filter`, `eq_filter_entries`, and `normalize_filter_entry` tests are the regression net — they must pass unchanged, since none of them touch the binding API.

The event loop has no unit tests and is where the risk concentrates. Verify manually on Linux:

1. Play → pause → play; confirm position does not flash to 0:00 (the known playing-event regression).
2. Seek mid-track; confirm no jump-to-zero within 150ms.
3. Let a track end naturally; confirm autoplay advances (exercises `EndFile` EOF).
4. Press stop; confirm autoplay does not advance.
5. Sleep-timer expiry; confirm it stops without triggering autoplay.

Cases 3–5 are the ones most likely to break silently, and each corresponds to a bug already fixed once in this codebase.

## TRACES

- `MpvBackend` construction / event loop → existing `// TRACES: UR-003 | IR-003`, unchanged
- No new requirement IDs; this is a dependency migration.

## Notes for the implementer

- Do this before the Windows audio backend.
- Read the 4.0/5.0/6.0 changelogs before writing code — the crate has broken API in every major release, most recently two months before this spec.
- The crates.io `repository` field for `libmpv2` points at `kohsine/libmpv-rs`, but the repo was renamed to `libmpv2-rs`; the old raw URLs 404.
- `libmpv2-sys` ships pregenerated bindings and vendored headers, so no libclang is needed at build time — relevant to keeping the builder image thin.
- A parallel Claude session may be active — `git diff` before "repairing" unexpected changes.