some readme stuff

README.md

@@ -2,15 +2,25 @@
 
 ![LinTunes](screenshot.png)
 
+
+## trave notes
+
+
 an mp3 library manager and player for linux. Absolutely no guarantees, if it wrecks your itunes library or wipes your harddrive that's on you (maybe just have your LLM of choice review the software for bugs and vulns?).
 
+I have been a mac user for ~34 years. I gave up daily driving mac os in 2021. I got tired of my music being solely on my desktop for 5 years. So I vibe-coded this replacement of all the features I wanted from iTunes.
+
+
+# docs written by llms and cleaned up by me:
+
 ## Features
 
 **Library**
 - Sortable track list with 24 optional columns (plays, skips, rating, BPM,
   bit rate, date added…) — column choice, sort and widths are remembered
   *per playlist*.
-- **Column browser** (Ctrl+B) — filter by genre / artist / album, iTunes-style.
+- Keeps track of date song was last played
+- **Column browser** (Ctrl+B) — filter by genre / artist / album.
 - Instant **search** over name, artist, album, composer and more.
 - **Get Info** (Ctrl+I) edits tags on one track or a whole selection at once,
   writing them back to the file. Artwork can be pasted, dragged in, or fetched
@@ -22,49 +32,31 @@ an mp3 library manager and player for linux. Absolutely no guarantees, if it wre
 
 **Playlists**
 - Regular playlists, **folders**, and **smart playlists** (auto-updating, with a
-  full rule editor — nested groups, limits; marked with a ❧).
+  full rule editor).
 - Drag and drop to reorder or insert at a spot; duplicate-aware adds;
   copy/cut/paste tracks between playlists.
 
 **Playing**
-- mp3, m4a, flac, aac, wav, aiff via Qt Multimedia/FFmpeg.
+- mp3, m4a, flac, aac, wav, aiff.
-- Shuffle, per-track **start/stop times**, play counts, skip counts and ratings.
+- Shuffle, per-track start/stop times, play counts, skip counts and ratings.
-- **Media keys** work (MPRIS), plus Space and ←/→ anywhere in the app.
+- Media keys work, plus Space and ←/→ anywhere in the app.
 - Live **spectrum visualizer** — click it to cycle bright / dim / off.
-- Optional **last.fm scrobbling** (Edit ▸ Preferences).
+- last.fm scrobbling
-- Theming: highlight color, UI scale, and custom colors for most of the chrome.
+- Theming: highlight color, UI scale, and custom colors
 
 **Sending music elsewhere**
-- **Chromecast** (Connections menu) — streams the original file bit-for-bit,
+- **Chromecast**
-  no transcode, with album art on the TV.
 - **Export a playlist** (File ▸ Export Playlist…) — either a folder of
-  `Artist - Title.mp3` files plus an `.m3u`, or a self-contained **web mix**
+  `Artist - Title.mp3` files plus an `.m3u`, or a self-contained `index.html` you can upload anywhere.
-  (`index.html` you can upload anywhere).
 - **Sync a playlist to a Rabbit R1** over MTP, `.m3u` included.
 
 **Living on more than one machine**
 - The whole library is **plain JSON**, designed to be synced with
   [Syncthing](https://syncthing.net). Sync conflicts merge themselves on
-  startup, and a change synced in from elsewhere shows up **while the app is
+  startup.
-  running**.
+- The version number in the status bar checks for updates (via git) and you can click it to update to the latest version.
-- Play counts can't conflict: every machine keeps its own tally and they're
-  summed.
-- The version number in the status bar checks for updates and, on a click,
-  pulls and restarts.
 
-## How it works
 
-- Your music files are never moved or rewritten (except when you edit tags,
-  rename an artist/album, or delete a track on purpose).
-- The library lives as **plain JSON files** (`library.json` + one file per
-  playlist) in a directory you choose. Track paths are stored *relative to that
-  directory*, so the library works no matter where each machine mounts it.
-- Playback via Qt Multimedia/FFmpeg. Media keys through MPRIS. Scrobbling to
-  last.fm is optional (Edit → Preferences).
-
-## Why
-
-I have been a mac user for ~34 years. I gave up daily driving mac os in 2021. I got tired of my music being solely on my desktop for 5 years. So I vibe-coded this replacement of all the features I wanted from iTunes.
 
 ## Never used a terminal? Start here
 
@@ -72,7 +64,9 @@ If the commands below look intimidating, they're friendlier than they look.
 
 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". Everything in a grey box below is
+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.
 
@@ -93,9 +87,9 @@ 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.
 
-In detail, for anyone who wants it:
+In detail:
 
-- **Linux** with Python **3.10 or newer** (already installed on essentially
+- **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
@@ -103,6 +97,21 @@ In detail, for anyone who wants it:
   missing. They come from `qt6-qtmultimedia` built with ffmpeg (Fedora: enable
   RPM Fusion; Debian/Ubuntu: it comes along with `python3-pyqt6.qtmultimedia`).
 
+**On a Mac or on 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!!
+
 ## Installing
 
 Pick whichever fits your distro:
@@ -139,10 +148,6 @@ whichever your install gave you.
 
 ## Starting from scratch (no iTunes needed)
 
-LinTunes doesn't care where your music came from — a shelf of ripped CDs, a
-Bandcamp folder, twenty years of downloads. You do **not** need iTunes, and you
-don't need to have ever owned a Mac.
-
 Tell it where to keep the library, once:
 
 ```sh
@@ -155,18 +160,11 @@ to keep your music — and suggests `~/Music`. Pick a folder, or click **Not
 Now** and set it later in **Edit ▸ Preferences**.
 
 Now add music: **File ▸ Add Files to Library** (Ctrl+O), or drag files and
-folders straight onto the window. Whole folders are fine — LinTunes looks
+folders straight onto the window. Whole folders are fine.
-inside them, reads each song's tags, and skips anything already in your library.
 
 Your songs are **copied** into the folder you chose and filed by artist and
-album, iTunes-style:
+album.
 
-```
-~/Music/Neko Case/Fox Confessor Brings the Flood/Star Witness.mp3
-```
-
-The originals are left exactly where they were, so nothing is lost if you
-change your mind. From there, make playlists and go.
 
 ## Importing an existing iTunes library
 
@@ -192,17 +190,9 @@ than 12.
 lintunes            # uses the saved config
 ```
 
-LinTunes looks best with **Century Gothic** installed
-(drop the font in `~/.local/share/fonts/`); if it's missing, the first launch
-asks you to pick a substitute or use the default.
-
 The desktop launcher runs LinTunes with no arguments, so it always uses whatever
-is saved in `~/.config/lintunes/config.json` — point that config wherever you
+is saved in `~/.config/lintunes/config.json`
-want and the dock icon follows.
 
-The now-playing panel uses **Century Gothic** if you have it and quietly picks
-the closest match installed if you don't — it never interrupts you to ask. To
-choose a different one, see **Edit ▸ Preferences ▸ Now-playing font**.
 
 ## Keys