trav
8237fe0fd2
Add a "Running on a second machine" section: clone + install, point the per-machine ~/.config/lintunes/config.json at the synced folder via --save-config (no re-import needed since paths are stored relative to the data dir), and run packaging/install-desktop.sh to install + pin the launcher. Note the desktop launcher follows the saved config, and add smart playlists + multi-machine sync to the feature list. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
129 lines
4.5 KiB
Markdown
129 lines
4.5 KiB
Markdown
# 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](https://syncthing.net); 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
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
# 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
|
||
|
||
```sh
|
||
python3 -m pytest tests/
|
||
```
|
||
|
||
`spec.md` is the original design brief; `tasks*.md` track what's built.
|