Skip to content

Setup

Jump to bottom
lpcornel edited this page May 13, 2026 · 4 revisions

Setup

← Home | Installation

First-Time Setup

musiclib-cli setup

The wizard runs 7 steps automatically:

Step What happens
1 Detects MPRIS2-compatible player (e.g., Audacious, Strawberry)
2 Locates your music root directory (~/Music, /mnt/music, or custom)
3 Sets a download/staging directory for new music imports
4 Detects optional tools: rsgain, kid3 GUI, K3b
5 Creates XDG directories (~/.config/musiclib/, ~/.local/share/musiclib/)
6 Enables the musiclib-mpris.service daemon (MPRIS2 playback tracking)
7 Offers to build the initial database (musiclib.dsv)

Restore last-played data? — Only say YES if rebuilding an existing MusicLib library that already has Songs-DB_Custom1 tags in the files. For a brand-new library, say NO.

Re-run at any time with --force after installing optional tools (e.g., K3b):

musiclib-cli setup --force

Non-Conforming Filenames

MusicLib requires filenames to use lowercase, digits, underscores, hyphens, and periods only — no spaces, uppercase, or accented characters. If setup warns about non-conforming files:

# 1. Preview renames (safe, no changes)
/usr/lib/musiclib/bin/conform_musiclib.sh /path/to/music

# 2. Apply renames (make a backup of your library first!)
/usr/lib/musiclib/bin/conform_musiclib.sh --execute /path/to/music

# 3. Re-run setup
musiclib-cli setup

The full non-conforming file report is saved at: ~/.local/share/musiclib/data/library_analysis_report.txt

Build the Database

If you skipped the database build during setup:

musiclib-cli build              # build (new library)
musiclib-cli build -b           # build with backup
musiclib-cli build --dry-run    # preview first

For ~16,000 files this takes roughly 10 minutes. After building, launch the GUI:

musiclib        # launch GUI
musiclib-cli    # CLI utilities

Directory Structure Created

~/.config/musiclib/
    musiclib.conf          ← main config
    tag_schema.conf        ← ID3 frame allowlist
    k3brc                  ← MusicLib-managed K3b config (if K3b detected)

~/.local/share/musiclib/
    data/
        musiclib.dsv       ← the database
        tag_backups/       ← per-file tag backups
        conky_output/      ← now-playing files for Conky
    playlists/             ← .m3u and .audpl files
    logs/                  ← operation logs

Clone this wiki locally