Files
lintunes/extra-docs.md
T
trav d93a265c33 v0.87.1: one app icon (lint.jpg, wave's corner radius) on desktop and andTunes 0.4.2; quitting no longer segfaults
The swap-a-PNG icon is gone: scripts/make_icons.py renders packaging/lint.jpg
into packaging/lintunes.png and the andTunes launcher. Quitting ends with
os._exit once aboutToQuit has saved everything — Python's teardown of the
QApplication wrapper segfaulted on every quit.
2026-11-06 02:01:06 -08:00

118 lines
5.0 KiB
Markdown

## Importing an existing iTunes library
In iTunes 12.x: **File ▸ Library ▸ Export Library** to get the XML, then:
```sh
lintunes --import-xml "iTunes Library.xml" \
--music-root "/path/to/iTunes Media" \
--data-dir /path/to/library-data --save-config
lintunes # from now on, just run it
```
This brings across your tracks, playlists, playlist folders and smart playlists
(auto-updating and still editable), along with play counts, ratings and dates.
Mac paths are remapped to `--music-root` automatically, including
case/accent differences. Anything it couldn't find is written to
`import_missing_files.txt` in your data dir. Untested on iTunes versions other
than 12.
## 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`:
```sh
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:
```sh
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:
```sh
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:
```sh
# 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)_
`packaging/install-desktop.sh` installs the launcher entry and icon for your
user (lets you pin LinTunes to the GNOME dash). The icon is the same on the
desktop and the Rabbit; GNOME caches icons, so if an old one lingers after
re-running the script, 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.