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

15 KiB
Raw Blame History

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

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":