mrr(1)

NAME

mrr - normalize and organize a local music library

SYNOPSIS

mrr <command> [options] [path]

DESCRIPTION

mr normalizes a local music library into a consistent, sanitized directory hierarchy derived from internal metadata tags. Files are moved; no metadata tags are modified by rename.

The intended workflow for a full library update is:

    mrr rename # move files into the normalized structure mrr lyrics # fetch and embed lyrics from LRCLIB mrr check # audit for metadata and structural issues mrr sums # generate md5 checksums

All commands accept an optional path argument and default to the current directory. Mode is auto-detected from the path: a directory containing audio files directly is treated as a single album; a directory without audio files directly inside is treated as a library root and processed recursively; some commands also accept a path to a single audio file.

DIRECTORY STRUCTURE

Files are organized as:

    first-letter/artist/[year] album/track title.ext

The first-letter bucket is a single lowercase character: a-z for artists whose name begins with a letter, or 0 for all others (digits, symbols). If the DATE tag is absent the year prefix is omitted entirely. Multi-disc albums prefix each track with the disc number (1-01 title.flac); single-disc albums do not.

All strings pass through a sanitization pipeline before use: Unicode transliteration to ASCII, lowercasing, stripping of non-alphanumeric characters, space normalization, and truncation. A small hardcoded set of overrides handles known edge cases (e.g. AC/DC → ac⁄dc).

  Album directory contents

Each album directory may contain the following:

Path | Contents
*.flac, *.mp3, *.m4a | Audio files
folder.jpg, folder.png | Primary artwork
*.log, *.cue, *.m3u, *.m3u8 | Text assets
sums.md5 | Checksums (generated by sums)
artwork/ | Additional images
scans/ | High-resolution scans
extras/ | All other files

COMMANDS

  mrr rename [_path_]

Reads metadata tags and moves files into the normalized hierarchy. Unknown files (those that don't match any recognized category) are left in place and reported as warnings. The extras/ subdirectory acts as a catch-all for known non-audio assets and opts out of the unknown-file check.

Collision detection runs before any files are moved. If two source files resolve to the same destination path, or if any destination path already exists on the filesystem, the entire run is aborted and all conflicts are reported.

--dry-run
    Preview all planned moves without touching the filesystem.

  mrr lyrics [_path_]

Fetches lyrics from LRCLIB (https://lrclib.net) and embeds them into audio tags. For each track, LRCLIB is queried by title, artist, album, and duration. The search progressively relaxes the duration constraint (±1 s, ±2 s) before falling back to a fuzzy search; tracks with no result are skipped and reported in the summary.

Synced (LRC) lyrics are embedded in FLAC files only. Unsynced lyrics are embedded in MP3 and M4A via the normalized LYRICS tag. If only synced lyrics are available from LRCLIB for an MP3 or M4A track, that track is skipped.

Existing lyrics tags are never overwritten unless --force is passed.

--force
    Re-fetch and overwrite existing lyrics tags.

  mrr check [_path_]

Audits a library or album for metadata and structural issues. Emits all findings to stdout grouped by album and exits non-zero if any are present.

Checks include:

•   Missing TITLE, TRACKNUMBER, DATE, or artist tags
•   Inconsistent ALBUMARTIST or ALBUM across tracks
•   Partial DISCNUMBER coverage or duplicate track numbers
•   Missing REPLAYGAIN_TRACK_GAIN or REPLAYGAIN_ALBUM_GAIN tags
•   Embedded artwork inside audio files
•   Missing or duplicate primary artwork (folder.jpg / folder.png)
•   Missing sums.md5
•   Path conformance: whether rename would move any file (library mode only)

Read-only; makes no filesystem changes.

  mrr sums [_path_]

Computes MD5 checksums for all files in an album and writes a sums.md5 file formatted for use with md5sum -c. Binary files (audio, images) use an asterisk prefix; text files (.log, .cue, .m3u, .m3u8) use a two-space prefix. sums.md5 itself is never included. Filenames are listed in sorted order for stable, diffable output.

In library mode, albums that already have a sums.md5 are silently skipped. In single-album mode, an existing sums.md5 is an error unless --force is passed.

--force
    Regenerate sums.md5 even if one already exists.

  mrr inspect _file_

Displays the raw tag values for a single audio file alongside the sanitized forms that rename would use for path construction. Accepts .flac, .mp3, and .m4a files only. Read-only; makes no filesystem changes.

METADATA

Album artist
    Uses the ALBUMARTIST tag. Falls back to the ARTIST tag of the track with the lowest TRACKNUMBER on the album if ALBUMARTIST is absent.

Year
    Extracted from the DATE tag. Full ISO-8601 dates and year-month values are accepted; only the four-character year component is used.

Disc numbers
    All-or-nothing per album. If any track has a DISCNUMBER tag, every track must have one; otherwise the album is skipped with an error.

Track numbers
    Zero-padded to two digits. Switches to three digits for the whole album if any track number exceeds 99. A value of 0 is valid and represents a pre-gap or hidden track.

Missing tags
    A missing YEAR omits the year prefix from the album folder. A missing TITLE falls back to the original filename stem. A missing TRACKNUMBER sorts the file alphabetically among its untracked peers. Missing both ARTIST and ALBUMARTIST is a fatal error for that album.

SEE ALSO

md5sum(1)