Plugin distribution

• What stays built in
• Options considered
• Package format
• Catalog
• Publishing
• Install, update, rollback

What stays built in

A small core ships inside the binary: Music Visualizer, Skip Intro & Credits, Lyrics, Subtitle Search, Auto-tagger, Free Music and Network Streams. They draw Slint UI (visualizer canvas, Skip button, karaoke overlay, search and preview dialogs) that a script cannot render; the two music plugins also write tags with lofty. The ListenBrainz Scrobbler needs no UI, so it is a downloadable package. Discord Rich Presence and Remote Control are packages too: a Lua script plus a small native helper per platform that talks to mpv over its JSON IPC.

Keys: the Auto-tagger works without keys (MusicBrainz search by tags or file name, Cover Art Archive); an optional free AcoustID application key adds audio-fingerprint matching. Free Music searches the Internet Archive without a key; Jamendo needs a free client ID. The scrobbler needs your ListenBrainz user token. MusicBrainz is queried at most once per second with a descriptive User-Agent.

Everything else is a downloadable package, so the app stays small and plugins update on their own schedule.

Options considered

Package format

A zip named <id>-<version>.zip with manifest.toml at its root and the entry script <id>.lua:

id = "night-mode"          # lowercase-with-dashes
name = "Night Mode"
version = "1.0.0"          # semver
description = "..."
author = "Vivi"
kind = "mpv-lua"           # mpv-lua | mpv-js (wasm reserved)
entry = "night-mode.lua"
min_vivi = "0.8.0"
icon = "night"
lucide = "moon"
permissions = []           # network | filesystem | subprocess

[[settings]]
key = "strength"
title = "Strength"
type = "choice"            # toggle | choice | text | secret | action
options = ["Medium", "Light", "Strong"]

Settings appear in Settings → Extensions and reach the script as script-opts (<id>-<key>), updated live; action settings arrive as script messages. Permissions are shown before install; with mpv scripts they are reviewed declarations, not a sandbox.

Catalog

index.json (from plugins/index.json) lists built-in plugins and packages. A package entry carries version, min_vivi, permissions, size, the url of a GitHub release asset (tag plugin-<id>-v<version>) and its sha256. Zips are deterministic, so the committed sha256 equals what CI uploads. A minisign signature field is reserved.

Publishing

The Plugins workflow checks Lua syntax, verifies index.json is current, creates a release for every new plugin-<id>-v<version> (never marked “latest”) and re-downloads each asset to verify its sha256. The docs workflow publishes the catalog. See Package & publish.

Install, update, rollback

• Where: ~/.local/share/vivi/plugins/<id>/<version>/; <id>/current names the active version.
• Update check: at startup at most once a day (can be turned off) and with Check now. A toast announces updates.
• Install on a background thread: download → sha256 must match → unpack to a staging folder (no .., absolute paths or symlinks; size caps) → manifest must match the catalog and min_vivi → rename into place → atomically switch current. Any failure leaves the old version.
• Permissions prompt before installing a package that asks for any (or an update adding some).
• Rollback to the previous version, which is kept; older ones are pruned.
• Uninstall removes the folder; settings stay in config.toml.
• A new install loads immediately; disable, update, rollback and uninstall apply after a restart because mpv cannot unload scripts.

Full design notes: docs/plugins-architecture.md.