Files
lintunes/docs/mac-testing.md
T
trav f21c31940f
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
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
2026-11-17 22:41:48 -08:00

271 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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":
-