From 5edc3bded282de2bb6c192711ae06fa6f1fb9829 Mon Sep 17 00:00:00 2001 From: trav Date: Thu, 1 Oct 2026 21:28:47 -0700 Subject: [PATCH] README: replace terminal intro with a Linux quick start; clone over HTTPS Co-Authored-By: Claude Opus 5.5 --- README.md | 86 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 23774df..f6d763b 100644 --- a/README.md +++ b/README.md @@ -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