LinTunes

[screenshot]

an mp3 library manager and player for linux. Absolutely no guarantees, if it wrecks your itunes library or wipes your harddrive that's on you (maybe just have your LLM of choice review the software for bugs and vulns?).

Features

• can import an iTunes 12 (untested on other versions) library, including smart playlists (auto-updating, editable, marked with a ❧)
• runs on several machines off one Syncthing-synced library (see below)

How it works

• Your music files are never moved or rewritten (except when you edit tags).
• The library lives as plain JSON files (library.json + one file per playlist) in a directory you choose — designed to be synced with Syncthing; sync conflicts are merged automatically on startup (play counts take the max, edits take the newest, playlists take the union).
• Playback via Qt Multimedia/FFmpeg (mp3, m4a, flac). Media keys work through MPRIS. Scrobbling to last.fm is optional (Edit → Preferences).

Why

I have been a mac user for ~34 years. I gave up daily driving mac os in 2020. I figured Apple

but my music library even some tracks I got from napster all the way back in 2000 (I have since paid for!!)

Quickstart

pip install -e .          # PyQt6, mutagen, numpy, requests
# one-time import from iTunes (XML from iTunes 12.x: File > Library > Export Library)
lintunes --import-xml "iTunes Library.xml" \
         --music-root "/path/to/iTunes Media" \
         --data-dir /path/to/library-data --save-config
lintunes                  # run the app

Running it

The lintunes command only exists after pip install -e ., and it lives in ~/.local/bin, so that has to be on your PATH (it is by default on most distros). If lintunes isn't found, you can always run it straight from this checkout without installing — from the project directory:

python3 -m lintunes.main   # same thing the desktop launcher runs

Fedora/Debian note: you need the FFmpeg codecs for Qt Multimedia (qt6-qtmultimedia with ffmpeg, usually via RPM Fusion / regular apt).

LinTunes looks best with Century Gothic installed (~/.local/share/fonts/); if it's missing, you'll be asked to pick a font on first run.

The desktop launcher runs lintunes with no --data-dir, so it always uses whatever is saved in ~/.config/lintunes/config.json. Point that config wherever you want and the dock icon follows.

Running on a second machine (Syncthing)

Keep the data dir (which holds library.json, the playlists, and preferences.json) inside your Syncthing-shared music folder, so the music and the library travel together. Track paths are stored relative to the data dir, so the library resolves correctly no matter where each machine mounts the shared folder — you never edit anything inside the library to move it.

~/.config/lintunes/config.json is per-machine (it is not synced), so on a new machine you just tell LinTunes where the synced folder landed:

# 1. get the code
git clone ssh://git@git.autonomic.zone:2222/trav/lintunes.git
cd lintunes && pip install -e .

# 2. let Syncthing finish replicating the music folder, then point the config at
#    THIS machine's paths and launch — no re-import, the data is already synced:
lintunes --data-dir  "/path/to/synced/music/lintunes" \
         --music-root "/path/to/synced/music/iTunes Media" \
         --save-config

# 3. install the launcher + icon, then pin it (see "App icon" below)
bash packaging/install-desktop.sh

(Step 2 just writes data_dir + music_root into ~/.config/lintunes/config.json — you can also create that file by hand. After it's saved, every launch, including the dock icon, uses the synced library automatically.)

Keys

Space play/pause · ←/→ previous/next · Ctrl+B column browser · Ctrl+I get info · Ctrl+, preferences · Ctrl+C/Ctrl+X/Ctrl+V copy/cut/paste tracks · double-click sidebar art for a big art window

App icon

packaging/install-desktop.sh installs the launcher entry and icon for your user (lets you pin LinTunes to the GNOME dash). The icon is just a file — replace packaging/lintunes.png (256×256 PNG) and re-run the script to use your own. GNOME caches icons, so if the old one lingers, log out and back in.

Unpinning from the dash does not uninstall LinTunes — it's still in the GNOME app grid (open Activities and search "LinTunes"). Right-click it there → Pin to Dash to get it back.

Development

python3 -m pytest tests/

spec.md is the original design brief; tasks*.md track what's built.