diff --git a/README.md b/README.md index 2ff783c..397365e 100644 --- a/README.md +++ b/README.md @@ -79,57 +79,8 @@ click sidebar art for a big art window # LLM-written docs: -## 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. ## Importing an existing iTunes library @@ -150,47 +101,7 @@ case/accent differences. Anything it couldn't find is written to than 12. -## 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. ## Sharing music with friends (Cassette) @@ -441,3 +352,9 @@ _(written by LLM and cleaned up a bit by me)_ - Browse a friend's library and press the little cassette buttons on anything you'd like; those songs arrive in your library by themselves. - Follow a friend's playlist and play it right from your own sidebar. + + + +# BUT WAIT, THERE'S MORE + +there's a file [extra-docs.md](extra-docs.md) with more documentation that might be handy if you have more questions diff --git a/extra-docs.md b/extra-docs.md new file mode 100644 index 0000000..b7fd262 --- /dev/null +++ b/extra-docs.md @@ -0,0 +1,97 @@ +## 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. +