README
¶
mxlrcgo-svc
Command line tool and webhook service to fetch synced lyrics from Musixmatch and save them as .lrc files.
Documentation
Full documentation is published at https://sydlexius.github.io/mxlrcgo-svc/:
- Getting Started - onboarding guide: pick a path (one-shot, directory, or daemon) and get to working lyrics.
- User Guide - webhook server, Docker/Unraid, the filesystem watcher, inspection commands.
- CLI Reference - every subcommand and flag.
- Configuration - env vars, TOML keys, token precedence, XDG paths.
- Developer Guide - build, test, the quality gate, design decisions.
Install
macOS / Linuxbrew (Homebrew):
brew install sydlexius/tap/mxlrcgo-svc
Linux (.deb / .rpm / .apk): Download the appropriate package for your distro from the GitHub Releases page and install it with your package manager:
# Debian / Ubuntu
sudo dpkg -i mxlrcgo-svc_*.deb
# RHEL / Fedora / Rocky
sudo rpm -i mxlrcgo-svc_*.rpm
# Alpine
sudo apk add --allow-untrusted mxlrcgo-svc_*.apk
The package installs the binary to /usr/local/bin/mxlrcgo-svc, a systemd unit
(or OpenRC script on Alpine), and an example config at
/etc/mxlrcgo-svc/config.example.toml. Copy the example to
/etc/mxlrcgo-svc/config.toml and edit it before starting the service.
Tarballs / macOS / Windows: Versioned archives for all platforms are also available on the GitHub Releases page.
Build from source (requires Go 1.26.4+):
go install github.com/sydlexius/mxlrcgo-svc/cmd/mxlrcgo-svc@latest
This fork starts its release line at
v1.0.0. The upstreamfashni/mxlrc-gorepository does not publish semver release tags, sov1.0.0is reserved as the firstmxlrcgo-svcversion.
Quickstart
# One song
mxlrcgo-svc adele,hello
# Multiple songs into a custom output directory
mxlrcgo-svc adele,hello "the killers,mr. brightside" -o some_directory
# Directory mode (recursive): writes each lyric file next to its audio file
mxlrcgo-svc "Dream Theater"
# Lidarr webhook server
MUSIXMATCH_TOKEN=YOUR_TOKEN MXLRC_WEBHOOK_API_KEY=mxlrc_your_webhook_key \
mxlrcgo-svc serve --listen 127.0.0.1:3876
Directory mode overrides -o/--outdir; the output extension is .lrc for synced lyrics and .txt for unsynced lyrics or an instrumental marker. See the CLI Reference for every flag and the User Guide for Docker, Unraid, and webhook deployment.
Token
A Musixmatch API token is required. Supply it via the --token CLI flag, the MUSIXMATCH_TOKEN environment variable, or a .env/config file, in that order of precedence (CLI > env > file). To get a token, follow steps 1 to 5 from the Spicetify guide. See Configuration for the full env-var and TOML surface.
Credits
- Spicetify Lyrics Plus
- Forked from fashni/mxlrc-go.
Legal
- Privacy Policy - what data leaves your machine during a lyrics lookup and what does not.
- Code Signing Policy - SignPath attribution, team roles, and release approval process.
License
GPL-3.0. This project is a fork of fashni/mxlrc-go, which is MIT-licensed; the original MIT copyright and permission notice are retained in NOTICE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
genlib
command
Command genlib generates a synthetic music library: tagged .mp3 files (ID3v2.4/UTF-8) with optional embedded USLT lyrics and optional .lrc sidecars, for load- and concurrency-testing mxlrcgo-svc against a #131-style large library without touching real music.
|
Command genlib generates a synthetic music library: tagged .mp3 files (ID3v2.4/UTF-8) with optional embedded USLT lyrics and optional .lrc sidecars, for load- and concurrency-testing mxlrcgo-svc against a #131-style large library without touching real music. |
|
mxlrcgo-svc
command
|
|
|
internal
|
|
|
backoff
Package backoff provides shared retry-delay formulas used by the worker, the durable queue, and the legacy fetch loop.
|
Package backoff provides shared retry-delay formulas used by the worker, the durable queue, and the legacy fetch loop. |
|
circuit
Package circuit provides a concurrency-safe circuit breaker that models a single provider lane's rate-limit / throttle response.
|
Package circuit provides a concurrency-safe circuit breaker that models a single provider lane's rate-limit / throttle response. |
|
detector
Package detector provides an optional audio-based instrumental detection sidecar.
|
Package detector provides an optional audio-based instrumental detection sidecar. |
|
langguard
Package langguard classifies and filters lyric text by Unicode script so a configured allowlist can reject unwanted-language results (e.g.
|
Package langguard classifies and filters lyric text by Unicode script so a configured allowlist can reject unwanted-language results (e.g. |
|
pathutil
Package pathutil provides path-containment checks used to confine filesystem targets to configured roots.
|
Package pathutil provides path-containment checks used to confine filesystem targets to configured roots. |
|
petitlyrics
Package petitlyrics implements a lyrics provider adapter for petitlyrics.com.
|
Package petitlyrics implements a lyrics provider adapter for petitlyrics.com. |
|
testutil
Package testutil provides helpers for generating synthetic tagged audio files used by load/concurrency tests and the genlib tool.
|
Package testutil provides helpers for generating synthetic tagged audio files used by load/concurrency tests and the genlib tool. |
|
watcher
Package watcher provides an optional filesystem watcher that triggers targeted library scans when files change under configured library roots.
|
Package watcher provides an optional filesystem watcher that triggers targeted library scans when files change under configured library roots. |