README: replace terminal intro with a Linux quick start; clone over HTTPS

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 21:28:47 -07:00
co-authored by Claude Opus 5.5
parent 27abdbdb63
commit 5edc3bded2
+51 -35
View File
@@ -87,46 +87,61 @@ I have been a mac user for ~34 years. I gave up daily driving mac os in 2021. Af
## Never used a terminal? Start here
## Quick start
If the commands below look intimidating, they're friendlier than they look.
**1. Open a terminal.** Press the Super key (the one with the Windows logo),
type `terminal`, press Enter. Paste each command below with **Ctrl+Shift+V**
(plain Ctrl+V doesn't work in a terminal), then press Enter. If it asks for
your password, type it — nothing shows while you type, that's normal.
The **terminal** is a window where you type commands instead of clicking. On
most Linux desktops you open it by pressing the Super key (the one with the
Windows/Command logo) and typing "terminal". (On a Mac it's Terminal, from
Spotlight; on Windows it's PowerShell, from the Start menu — but read the
Mac/Windows note under *What you need* first.) Everything in a grey box below is
meant to be **copied and pasted** into that window — paste it, press Enter,
done. You don't need to understand a command to run it.
**2. Install what LinTunes needs.** Paste the line for your Linux (not sure?
it's probably Ubuntu or Mint):
Two bits of shorthand that show up everywhere:
```sh
# Debian / Ubuntu / Mint
sudo apt install git python3-pyqt6 python3-pyqt6.qtmultimedia python3-mutagen python3-numpy python3-requests
```
- **`~`** means your home folder. `~/Music` is just the Music folder inside your
home folder — the same one your file manager shows you.
- **Your "distro"** is which flavour of Linux you're running (Ubuntu, Fedora,
Debian, Mint…). If you don't know, it's almost certainly Ubuntu or Mint, and
you want the **Debian/Ubuntu** instructions below.
```sh
# Fedora
sudo dnf install git python3-pyqt6 qt6-qtmultimedia python3-mutagen python3-numpy python3-requests
```
If a command fails, nothing is broken — copy the error into a search engine, or
ask whoever pointed you here. You cannot damage your music by running these.
**3. Download LinTunes** into a `lintunes` folder in your home folder:
## What you need
```sh
cd ~
git clone https://git.autonomic.zone/trav/lintunes.git
cd lintunes
```
Linux, Python, and a handful of free add-ons. **Nothing to compile, no account
to make, no database to set up, nothing that phones home.** LinTunes keeps your
library as ordinary files on your own computer.
(That link is the **HTTPS** address from the clone box on the project page —
if you copy it yourself, pick HTTPS, not SSH.)
In detail:
**4. Add it to your app menu and start it:**
- **Linux** with Python **3.11 or newer** (already installed on essentially
every Linux machine — check with `python3 --version`)
- **PyQt6** (including its QtMultimedia part), **mutagen**, **numpy**, **requests**
- The **FFmpeg codecs for Qt Multimedia**. Without these the window opens fine
but nothing plays — so if you get a silent LinTunes, this is the thing that's
missing. They come from `qt6-qtmultimedia` built with ffmpeg (Fedora: enable
RPM Fusion; Debian/Ubuntu: it comes along with `python3-pyqt6.qtmultimedia`).
```sh
bash packaging/install-desktop.sh
mkdir -p ~/Music/lintunes
python3 -m lintunes.main --data-dir ~/Music/lintunes --save-config
```
**On a Mac or on Windows?** LinTunes is only built and tested on Linux and
It asks once where to keep your music (`~/Music` is fine). Add songs with
**File ▸ Add Files to Library**, or drag folders onto the window. From now on,
open LinTunes from your app menu like any other app.
Coming from iTunes? Replace the last line with the one in
*Importing an existing iTunes library* below.
**Updating:** click the version number at the bottom of the window.
**Window opens but nothing plays?** Your system is missing audio codecs. On
Fedora, enable [RPM Fusion](https://rpmfusion.org/Configuration), then run
`sudo dnf swap ffmpeg-free ffmpeg --allowerasing`.
## 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 .`,
@@ -141,9 +156,10 @@ first: a couple of places call a POSIX-only function (`os.getuid()`, in
error out until someone routes that through the Recycle Bin instead — a small
patch, not a rewrite. If you get either one going, lmk!!
## Installing
## Other ways to install
Pick whichever fits your distro:
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`:
@@ -243,8 +259,8 @@ shared folder — you never edit anything inside the library to move it.
new machine you just tell LinTunes where the synced folder landed:
```sh
# 1. get the code, then install the deps (see "Installing" above: pip / apt / venv)
git clone ssh://git@git.autonomic.zone:2222/trav/lintunes.git
# 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
@@ -290,7 +306,7 @@ You'll both need LinTunes and Syncthing.
### 1. Install and start Syncthing (once)
Open a terminal (see *Never used a terminal?* above) and paste the line for
Open a terminal (see *Quick start* above) and paste the line for
your distro:
```sh