## 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)_

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.