docs
This commit is contained in:
@@ -79,57 +79,8 @@ click sidebar art for a big art window
|
|||||||
|
|
||||||
# LLM-written docs:
|
# 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
|
## Importing an existing iTunes library
|
||||||
|
|
||||||
@@ -150,47 +101,7 @@ case/accent differences. Anything it couldn't find is written to
|
|||||||
than 12.
|
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)
|
## 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
|
- Browse a friend's library and press the little cassette buttons on anything
|
||||||
you'd like; those songs arrive in your library by themselves.
|
you'd like; those songs arrive in your library by themselves.
|
||||||
- Follow a friend's playlist and play it right from your own sidebar.
|
- 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
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
Reference in New Issue
Block a user