v0.97.0: macOS port (Round 129): OS-aware paths, config and cookies; Mac now-playing, packaging (PyInstaller .app, dmg build, signing notes, CI workflow) and docs
macOS / Tests (AppleSilicon) (push) Canceled after 0s
macOS / Tests (Intel) (push) Canceled after 0s
macOS / Build (AppleSilicon) (push) Canceled after 0s
macOS / Build (Intel) (push) Canceled after 0s
macOS / Publish the GitHub Release (push) Canceled after 0s

This commit is contained in:
2026-11-17 22:41:48 -08:00
parent b78b6c5275
commit f21c31940f
66 changed files with 6047 additions and 164 deletions
+270
View File
@@ -0,0 +1,270 @@
# Mac test checklist
This is for a person with a real Mac, testing a LinTunes build from start
to finish. Use **test music only**: a few albums you don't mind being
retagged, moved or trashed. Don't point LinTunes at a music collection
you'd miss.
Mark every line **✓** (works), **✗** (broken, and say what happened), or
**–** (skipped, and say why). A screenshot helps whenever something looks
wrong (⇧⌘4 selects an area). Send back the whole file.
| | |
|---|---|
| Tester | |
| Date | |
| LinTunes version (bottom-left corner) | |
| Download (AppleSilicon / Intel .dmg) | |
| Mac model, chip | |
| macOS version | |
| Speakers / Chromecast / AirPlay devices available | |
To see the app's log, quit LinTunes and start it from Terminal instead:
`/Applications/LinTunes.app/Contents/MacOS/LinTunes`. Copy whatever it
prints around a failure into the notes.
---
## 1. Download and install
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 1.1 | Download the .dmg for this Mac, and `SHA256SUMS` | | |
| 1.2 | `shasum -a 256 -c SHA256SUMS --ignore-missing` in Downloads | `…dmg: OK` | |
| 1.3 | Open the .dmg | A window with LinTunes and an Applications shortcut | |
| 1.4 | Drag LinTunes to Applications, then eject | Copies, no errors | |
| 1.5 | Double-click LinTunes in Applications | macOS refuses: *"LinTunes" Not Opened*. Note the exact wording. | |
| 1.6 | System Settings › Privacy & Security › Security › **Open Anyway**, then your password | LinTunes opens | |
| 1.7 | Quit, and open it again from Launchpad/Spotlight | Opens with no warning | |
| 1.8 | Get Info on the app in Finder | Version matches, the lint-ball icon, size noted: ____ MB | |
| 1.9 | The Dock icon and the ⌘-Tab icon | The lint-ball icon, not a generic Python one | |
| 1.10 | The app menu (left of File) | Says **LinTunes**, not "Python" | |
## 2. First run and library setup
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 2.1 | First launch | The window appears. A library is created in `~/Music/LinTunes`. You're asked where the music should go. | |
| 2.2 | Choose a music folder | Accepted. Nothing is copied yet. | |
| 2.3 | Look in `~/Library/Application Support/LinTunes` | `config.json` exists | |
| 2.4 | Quit and relaunch | Same library, no questions this time | |
| 2.5 | Window: resize, minimize, full screen (green button), zoom | Behaves like a Mac window. Corners and title bar look right in light and dark. | |
| 2.6 | System Settings › Appearance › Dark, then Light | LinTunes follows, or keeps its own theme setting. Note which. | |
| 2.7 | Menu bar: File, Edit, Controls, View, Track, Connections | Present. **Preferences…/Settings…** is in the LinTunes menu (⌘,). **Quit LinTunes** is there too (⌘Q). | |
| 2.8 | Keyboard shortcuts use ⌘ (⌘O, ⌘I, ⌘Z, ⌘B, ⌘L, ⌘N) | Each one works | |
| 2.9 | Connections menu | No Rabbit / andTunes / Shazam entries | |
## 3. Importing
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 3.1 | Drag a folder of songs into the window | Copied into the music folder, filed as Artist/Album | |
| 3.2 | File › Add Files to Library… (⌘O) | The file picker opens, and the files are added | |
| 3.3 | Drop an audio file on LinTunes' **Dock icon** while it's running | Imported | |
| 3.4 | Right-click an mp3 in Finder › Open With › LinTunes | Imported (LinTunes may need to be running) | |
| 3.5 | Drag a song onto a playlist in the sidebar | Added at the drop point | |
| 3.6 | Importing an iTunes/Music library: `LinTunes --import-xml "Library.xml" --music-root … --data-dir …` from Terminal (optional) | Imports | |
| 3.7 | Preferences › Importing › compress lossless to MP3, then import a FLAC | Converted to MP3 | |
## 4. Playback, one format at a time
Play each one for a few seconds, seek in the middle, and let one play to
the end.
| # | Format | Plays | Seeks | Duration right | Notes |
|---|---|---|---|---|---|
| 4.1 | MP3 | | | | |
| 4.2 | AAC (.m4a) | | | | |
| 4.3 | Apple Lossless (.m4a) | | | | |
| 4.4 | FLAC | | | | |
| 4.5 | WAV | | | | |
| 4.6 | AIFF | | | | |
| 4.7 | A protected iTunes .m4p (if you have one) | Refused with a message, never a crash | | | |
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 4.8 | Space, ←/→ | Play/pause, previous/next | |
| 4.9 | Volume slider; per-track volume (Get Info) | Changes the volume | |
| 4.10 | Controls › Normalize Volume on, then play two very different songs | The loudness evens out. No error about ffmpeg. | |
| 4.11 | Shuffle and repeat (off/all/one) | As on Linux | |
| 4.12 | Change the output in System Settings › Sound (e.g. headphones) while playing | Audio follows, or note what happens | |
| 4.13 | Play counts go up after a song finishes | | |
## 5. Media keys and Now Playing
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 5.1 | Keyboard ⏯ ⏮ ⏭ keys (F7–F9) with LinTunes in the background | Control LinTunes, not Music.app | |
| 5.2 | Control Center › Now Playing | Shows title, artist, artwork and position | |
| 5.3 | Play/pause/next from Control Center | Works | |
| 5.4 | Seek using the Now Playing scrubber | Works | |
| 5.5 | AirPods/headphone controls (if any) | Work | |
| 5.6 | Lock screen Now Playing | Shows the song | |
## 6. Trash and Put Back
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 6.1 | Delete a song from the library (and its file) | Gone from the list. The file is in the **Trash**. | |
| 6.2 | In the Trash, right-click the file › **Put Back** | Returns to its folder | |
| 6.3 | Delete a song whose file is on an external drive | Goes to the Trash (that drive's), and Put Back works | |
| 6.4 | ⌘Z after a delete | The song comes back into the library | |
## 7. Get Info and tags
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 7.1 | ⌘I on a song, change title/artist/album/year, OK | Saved. Check the file in Finder's Get Info or another player. | |
| 7.2 | Rename an album | The file moves to the new Artist/Album folder | |
| 7.3 | Edit several songs at once | All changed | |
| 7.4 | Paste artwork (copy an image in Preview, paste in Get Info) | Embedded, shown in the sidebar | |
| 7.5 | Drag an image file onto the artwork square | Embedded | |
| 7.6 | Download Album Art… | Finds covers | |
| 7.7 | Edit the tags of the song that's **playing** | Playback doesn't glitch | |
| 7.8 | Right-click › Calculate BPM | A BPM appears | |
## 8. Visualizers
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 8.1 | The transport-bar visualizer during playback | Moves with the music | |
| 8.2 | Each style: bars, radial, oscilloscope, Kaleidostrobe, Lint Oontz | Each draws | |
| 8.3 | Click the visualizer for the **big window**, especially Kaleidostrobe (the OpenGL one) | Smooth, no black window. Note the fps feel. | |
| 8.4 | Big window on a Retina display | Sharp, not blurry or quarter-sized | |
| 8.5 | Preferences › visualizer sync slider | Changes the lag | |
## 9. Chromecast and AirPlay
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 9.1 | Connections › Connect to Chromecast… | macOS asks to **find devices on local networks**. Note the exact text. | |
| 9.2 | Allow | Your Chromecasts appear | |
| 9.3 | Cast a song | Plays on the TV/speaker. A firewall prompt about incoming connections may appear: allow it. | |
| 9.4 | Pause/seek/next while casting | Works | |
| 9.5 | Connections › Connect to AirPlay… | AirPlay speakers listed (Apple TV, HomePod, AirPlay speakers) | |
| 9.6 | Play to an AirPlay speaker | Sound comes out, within about 2 s | |
| 9.7 | If you denied the network prompt: System Settings › Privacy & Security › Local Network › LinTunes on | Devices appear after that | |
## 10. Import from URL
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 10.1 | Without yt-dlp: File › Import from URL… | A clear message saying yt-dlp is needed (`brew install yt-dlp`) | |
| 10.2 | `brew install yt-dlp`, restart LinTunes, then import a song link | Downloads, imports, and Identify proposes tags | |
| 10.3 | A playlist link | The checklist of songs appears | |
| 10.4 | A Spotify link | Each song is found on YouTube | |
## 11. Identify Track
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 11.1 | Preferences: set an AcoustID key, then right-click a song › Identify Track… | Candidates appear. No "fpcalc not found". | |
| 11.2 | Accept a candidate | Tags written | |
## 12. Export and web mix
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 12.1 | File › Export Playlist… › folder | Files and an .m3u | |
| 12.2 | Export as a web mix, then open `index.html` in Safari | Plays; previous/next/shuffle work | |
| 12.3 | A playlist with an ALAC song, as a web mix | Converted to FLAC | |
| 12.4 | Upload to web server (only if you have one in `~/.ssh/config`) | Uploads | |
| 12.5 | Right-click › Convert to MP3… on a FLAC | Replaced by an MP3, and the original goes to the Trash | |
## 13. DJ mode
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 13.1 | View › DJ Mode | The shelf slides open | |
| 13.2 | Drag a song onto each record | Loads, shows BPM, waveforms | |
| 13.3 | Play both, crossfader, tempo, Keep pitch, Sync, loops | Sound is clean (no crackles). Note any. | |
| 13.4 | Scratch a record; drag a waveform | Works | |
| 13.5 | Air horn, click and hold | Plays | |
| 13.6 | Preferences › DJ › set up **Instant** vocals (download) | Installs. Note how long, and any error. | |
| 13.7 | Vocals slider on a loaded song | Splits, then fades vocals | |
| 13.8 | Preferences › DJ › High quality (Demucs): follow the shown setup | Note what happens | |
| 13.9 | Close DJ mode with a song playing on deck A | The main player carries on | |
| 13.10 | Switch audio output while in DJ mode | Sound follows | |
## 14. Cassette (sharing with a friend)
Needs Syncthing (`brew install syncthing && brew services start syncthing`)
and a second person or computer.
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 14.1 | With Syncthing **not** running: open Cassette | A clear "Syncthing isn't running" message | |
| 14.2 | With Syncthing running: make this Mac the host, then create an invite | An invite code | |
| 14.3 | The friend accepts | Connected | |
| 14.4 | Browse the friend's library; request a song; Save and Close | The song arrives and is imported | |
| 14.5 | Follow a friend's playlist (the UFO) | Plays from the cache | |
| 14.6 | A sync conflict between two of your own computers (optional) | The merge summary shows | |
## 15. Sleep, quitting, updates
| # | Step | Expect | Result / notes |
|---|---|---|---|
| 15.1 | Play an album with the display set to sleep in 1–2 minutes | The **Mac** doesn't sleep while music plays (the display may). Check with `pmset -g assertions` in Terminal: a `caffeinate` assertion while playing. | |
| 15.2 | Pause for a while | The assertion goes away | |
| 15.3 | ⌘Q while playing | Quits at once, no "unexpectedly quit" report | |
| 15.4 | Close the window with the red button | Note: does it quit, or stay in the Dock like Music.app? | |
| 15.5 | Relaunch | Same library, playlists, play counts and column widths | |
| 15.6 | Version button in the bottom-left corner | `vX.Y.Z`. If a newer release exists, `*`, and a click opens the release page in your browser. | |
| 15.7 | Force-quit during an import (⌥⌘Esc), then relaunch | The library is intact | |
---
<!-- OTHER AGENTS' CHECKLISTS: the coordinator merges the OS-integration
and Cassette/DJ/AirPlay checklists here. Keep the table shape. -->
## 16. Additional checks (merged in)
### Desktop integration
- [ ] First launch from Finder with no settings: it starts, makes `~/Music/LinTunes`, and the app menu reads "LinTunes".
- [ ] Preferences (⌘,) and Quit (⌘Q) are in the LinTunes menu.
- [ ] Playing a song: Control Centre's Now Playing shows title, artist, album, cover and a moving progress bar; paused, the time stops.
- [ ] F8 pauses and resumes, F9 / F7 skip, the Now Playing scrubber seeks — also with another app in front.
- [ ] Embedding new art on the playing song updates the Now Playing cover.
- [ ] While playing, `pmset -g assertions` lists `caffeinate`; paused, it's gone. Force-quit while playing: `pgrep caffeinate` finds nothing.
- [ ] Right-click a song › Show in Finder selects the file.
- [ ] Delete a song (move to Trash): it's in the Trash and Put Back works; Edit › Undo brings it back into the library.
- [ ] The delete key (⌫) removes songs from a playlist; context menus show ⌘I / ⌘C / ⌫, never "Ctrl+".
- [ ] ⌘N, ⌘B, ⌘L, ⌘I, ⌘Z, ⌘⇧Z each fire once. Space and ← → play/pause and skip, but not while typing in the search box.
- [ ] Renaming an artist by capitals only ("Rjd2" → "RJD2") leaves the file where it is, with its own name.
- [ ] Connections has no Rabbit, Shazam or andTunes items; Preferences › Appearance has no "Hide the menu bar" row.
- [ ] The look is the Linux one (flat buttons, the app's own scrollbars), not native Mac controls.
- [ ] An mp3 dropped on the Dock icon is imported, with the app running and with it closed.
- [ ] Web-mix upload with only Apple's rsync says to `brew install rsync`; with Homebrew's it uploads.
- [ ] Import from URL after `brew install yt-dlp` downloads; on a YouTube bot check it retries with Firefox or Chrome cookies.
### Cassette
- [ ] With the Syncthing app running, Sync Settings shows its version (the key is read from `~/Library/Application Support/Syncthing/config.xml`). Same with Homebrew's `syncthing`.
- [ ] With Syncthing stopped, the status says how to open or get it.
- [ ] An invite and handshake between this Mac and a Linux friend completes. Syncthing accepts the folders under `~/Library/Application Support/LinTunes/cassette/` (the path has a space).
- [ ] Songs with accents in their names (é, ü) arrive and import, both ways.
- [ ] The disk-space verdict looks right; the host name shows without `.local`.
### DJ mode
- [ ] Decks play through speakers, headphones and AirPods; switching output while playing follows it.
- [ ] Activity Monitor: LinTunes' CPU with DJ mode open and nothing playing is low.
- [ ] Preferences › DJ › Download Instant Vocal Splitting finishes, and a split puts `.opus` files in `~/Library/Caches/LinTunes/stems`.
- [ ] Download High-Quality Vocal Splitting finishes; splitting an m4a and an mp3 works; the ✕ beside the vocals note stops it.
- [ ] A split is found again after editing the song's tags. BPM is detected on load.
### AirPlay and Chromecast
- [ ] The local-network prompt appears once; after Allow, speakers and Chromecasts are listed.
- [ ] AirPlay plays to a speaker of your own; pause, seek and next behave.
- [ ] With `"airplay_backend": "cli"` in config.json the helper downloads and plays. If macOS refuses to run it, note its exact words.
- [ ] Chromecast: the TV plays the song, seeking works, the cover shows. Note whether the firewall prompt blocked the first try.
---
## Anything else
Note anything that felt un-Mac-like, slow, ugly or confusing, even if it
"worked":
-