lintunes/extra-docs.md

Mac or Windows?

LinTunes is only built and tested on Linux and that's not changing — but very little of it is actually Linux-specific: Python, PyQt6, mutagen and the rest run everywhere, and your library is just JSON files. On macOS it will most likely run as-is — clone the repo, pip install -e ., then python3 -m lintunes.main — with three things quietly missing: media keys and the now-playing widget, the keep-the-machine-awake-while-playing bit (both of those go through a Linux-only service), and Rabbit R1 sync. Deleting a track would also drop the file in a Linux-style .Trash folder rather than Finder's Trash — recoverable, but not where you'd look — and there's no .app or dock icon, so you'd launch it from Terminal. Windows needs a little real work first: a couple of places call a POSIX-only function (os.getuid(), in lintunes/trash.py and lintunes/device_sync.py), so deleting a track would error out until someone routes that through the Recycle Bin instead — a small patch, not a rewrite. If you get either one going, lmk!!

Other ways to install

LinTunes needs Python 3.11+, PyQt6 (with QtMultimedia), mutagen, numpy, requests, and the FFmpeg codecs for Qt Multimedia. Pick whichever fits:

• pip — simplest where your distro allows it; also puts a lintunes command in ~/.local/bin:

  pip install -e .
  

• Debian/Ubuntu — system pip is locked down (the externally-managed-environment / PEP 668 error), so install the deps from apt and skip pip entirely:

  sudo apt install python3-pyqt6 python3-pyqt6.qtmultimedia \
                   python3-mutagen python3-numpy python3-requests
  

  (If python3-pyqt6.qtmultimedia isn't found, apt search python3-pyqt6 and grab the multimedia one.) There's no lintunes command this way — run it with python3 -m lintunes.main.
• venv — isolated:

  python3 -m venv .venv && .venv/bin/pip install -e .
  

  Run with .venv/bin/lintunes. One caveat: the dock launcher (see App icon) uses the system python, which can't see a venv's packages — so for the icon to work, edit the installed lintunes.desktop's Exec= line to the absolute venv path (…/lintunes/.venv/bin/lintunes %F).

You never strictly need pip or the lintunes command. As long as those four deps import, python3 -m lintunes.main from the checkout runs the app — which is exactly what the desktop launcher does.

Below, lintunes and python3 -m lintunes.main are interchangeable — use whichever your install gave you.

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, then install the deps (see "Quick start" above)
git clone https://git.autonomic.zone/trav/lintunes.git
cd lintunes

# 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:
python3 -m lintunes.main --data-dir "/path/to/synced/music/lintunes" --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 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.)

App icon

(written by LLM, cleaned up by me)

You can change the app icon if you want.

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.