What it does

amdl is the maintenance layer for a collection you already own: MP3s, m4a and CD rips with patchy tags, gathered over years. Source folders are treated as read-only input and everything is written to an output library, ready for a self-hosted server such as Navidrome.

Convert to Opus with fidelity

convert transcodes .m4a, .mp3 and .flac to Opus, re-embeds the source cover so players show it, strips iTunes junk tags and mirrors .lrc files. It skips what exists, so an interrupted run resumes.

Tags and cover art

identify fixes untagged tracks by sound (an AcoustID fingerprint) and writes only confident matches. covers fills missing art from the source, a sibling library, online sources, then a URL you paste. tag groups compilations.

Synced lyrics

lyrics fetches synced or plain lyrics from LRCLIB as .lrc files, re-times plain ones when a synced version appears, and can embed them in the file. With a whisper.cpp endpoint set, it generates synced lyrics from plain ones.

Checks, and a way back

doctor finds missing covers and tags, truncated and corrupt files; dedup lists duplicates without deleting. Every mutating run is journaled, and undo reverts a run without touching edits made since. Each batch command takes --json.

A first look

A typical first pass, from the README: set the paths once, convert, see what still needs fixing, then backfill lyrics. amdl --llm prints the whole guide for an AI agent.

$ amdl config --init                         # optional: set default source/output once
$ amdl convert ~/Music/originals ~/Music/lib # m4a/mp3 → Opus (covers, lyrics, junk-stripped)
$ amdl doctor ~/Music/lib --source ~/Music/originals   # what still needs fixing
$ amdl doctor ~/Music/lib --json | jq '.truncated'     # feed a script/agent
$ amdl lyrics ~/Music/lib                    # backfill synced .lrc from LRCLIB
$ amdl undo                                  # revert the last run

Install

Homebrew, on macOS and Linux

Pours a prebuilt bottle on macOS and x86_64 Linux, so no compiler is needed. Pulls in gamdl and ffmpeg as dependencies. The tap is trusted once first, as Homebrew 6 and later ask.

brew trust --tap jakobhviid/tapbrew install jakobhviid/tap/amdl

Or one line, without Homebrew

No compiler and no root: installs to ~/.local/bin. It fetches only the amdl binary, so install gamdl and ffmpeg separately.

curl -fsSL https://raw.githubusercontent.com/jakobhviid/amdl/main/install.sh | sh

Or build from source

Needs Rust. The binary lands in ./target/release/amdl.

cargo build --release

Runtime dependencies

ffmpeg and ffprobe for transcoding and checks, fpcalc (Chromaprint) for identify, and gamdl for the optional download and recover --online commands. amdl is a maintainer, not a downloader: acquisition is gamdl's job, and amdl only thin-wraps a slice of it. Install and use gamdl per its own documentation, terms and your local laws; that part is at your own risk.

Documentation

README: every command, the common flags and installation
WORKFLOWS.md: end-to-end recipes for building, scanning, covers, identify, recover, de-dup and undo
Releases