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
+209
View File
@@ -0,0 +1,209 @@
# Releasing the Mac app
Notes for trav. The repo still lives on the Gitea/Forgejo host
(`origin`). GitHub gets a **read-only push mirror** of it, and GitHub
Actions' macOS runners build the two `.dmg` files and attach them to a
GitHub Release. Nothing about the Linux workflow changes: Linux machines
keep updating with `git pull` from `origin`.
```
your push ──> origin (Gitea/Forgejo) ──push mirror──> GitHub
└─ tag vX.Y.Z → .github/workflows/mac.yml
→ Release vX.Y.Z: two .dmg + SHA256SUMS
```
## One-time setup
### 1. Public or private?
Make the GitHub repo **public**, for three reasons:
- **Downloads.** Mac users download from the Releases page. A private
repo's releases are invisible to anyone you haven't invited, and the
app's update check asks GitHub's API without logging in, so it can't see
them either.
- **Cost.** Standard GitHub-hosted runners are **free on public repos**. On
a private repo, GitHub Free includes **$12 a month** of Actions usage.
macOS runners cost **$0.062 a minute** (Linux is $0.006, so a Mac minute
costs about ten Linux minutes). $12 buys about **190 macOS minutes** a
month. One release runs tests and a build on two Macs, roughly 60–80
minutes in all, so a private repo covers two or three releases a month.
(Prices are from GitHub's billing docs, November 2026.)
- **License.** The .dmg bundles PyQt6, which is GPL-3.0, so LinTunes as
shipped is a GPL combination. Before the first public .dmg, add a
`LICENSE` file (GPL-3.0-or-later fits) to the repo. See
`packaging/mac/THIRD-PARTY.md`.
A private repo still works for trying the pipeline out. Builds then show
up as workflow artifacts, which only you can download.
### 2. Create the GitHub repo
Create an **empty** repository: no README, no license, no .gitignore. The
mirror's first push fills it. Its `owner/name` is what goes into
`GITHUB_REPO` in step 5.
### 3. A token for the mirror
On GitHub, go to Settings › Developer settings › **Fine-grained personal
access tokens** › Generate new token:
- **Repository access:** only the new repo.
- **Permissions:** **Contents: Read and write**, and **Workflows: Read
and write**. GitHub refuses any push that changes a file under
`.github/workflows/` from a token without the Workflows permission.
Metadata: Read is added for you.
- **Expiration:** as long as you're comfortable with. When the token
expires, the mirror stops, so put the date in your calendar.
(A classic token works too, with the `repo` and `workflow` scopes.)
### 4. The push mirror on Gitea/Forgejo
In the repo on the Gitea/Forgejo host, open **Settings › Repository ›
Mirror settings** and add a **push mirror**:
- **Git remote repository URL:** `https://github.com/<owner>/<name>.git`
- **Username:** your GitHub username. **Password:** the token.
- Tick **Sync when commits are pushed**, and leave a periodic interval as
well (say 8h) as a backstop.
- Click **Synchronize now** once, and check that the code shows up on
GitHub.
Two things to know about push mirrors:
- **The mirror force-pushes and prunes.** Anything that exists only on
GitHub is deleted on the next sync: commits, branches **and tags**. Never
edit, commit, tag or merge pull requests on GitHub. In particular,
never let GitHub create a tag (the "create a new tag on publish" box in
the Releases UI, or a workflow that tags). The next sync removes that
tag, and the release on it turns back into a draft. This is why tags
are made where the code lives (below).
- If the Gitea/Forgejo host runs Actions of its own, it may pick up
`.github/workflows/mac.yml` too, and those jobs then sit queued forever
waiting for a macOS runner. If that happens, turn Actions off for this
repo there (Settings › Repository › untick Actions).
### 5. Name the repo in the app
In `lintunes/release_info.py`, set:
```python
GITHUB_REPO = "<owner>/<name>"
```
While this is empty, the Mac app never checks for updates. Commit and
release as usual. Every Mac build made after that checks.
## Making a release
Releasing is **bump, commit, tag, push**. The tag is the only new step:
```sh
# __version__ in lintunes/__init__.py is already bumped and committed
v="v$(python3 setup.py --version 2>/dev/null | tail -1)"
git tag -a "$v" -m "LinTunes $v"
git push origin master --follow-tags
```
Run `git config push.followTags true` once, and a plain `git push` takes
annotated tags along from then on. That keeps the existing habit (each
round ends with a commit and a push), and the round's final step only
gains the `git tag -a`.
The mirror carries the tag to GitHub, and the tag starts **macOS**
(`.github/workflows/mac.yml`). The workflow:
1. runs the test suite on both kinds of Mac (reported, not blocking, until
the Linux-only tests are marked);
2. builds both apps with `packaging/mac/build.sh`. It refuses to build if
the tag and `__version__` disagree;
3. starts each app against a throwaway library (`smoke_test.sh`), and
checks the disk image mounts and verifies;
4. creates the GitHub Release `vX.Y.Z` with
`LinTunes-X.Y.Z-AppleSilicon.dmg`, `LinTunes-X.Y.Z-Intel.dmg` and
`SHA256SUMS`.
It takes around half an hour. Mac apps that are running see the new
release at their next check (a few hours at most) and show the `*`.
Not every version has to be a Mac release. An untagged version simply
never gets a .dmg. To rebuild a release (say, after a failed run), go to
**Actions › macOS › Run workflow** and pick the tag as the ref. The files
on the existing release are replaced.
A push to master that touches `packaging/mac/` or the workflow builds
without publishing, so packaging changes get tested. A plain push to
master doesn't build at all, which keeps macOS minutes for releases.
**Why not tag automatically when `__version__` changes?** A workflow on
GitHub could do that, but the tag would exist only on GitHub, and the next
mirror sync would delete it (see above). Tagging at the source is the only
version that survives the mirror.
## Turning on Developer ID signing (later)
Unsigned builds make every Mac user go through **Open Anyway** once. To
stop that:
1. Join the Apple Developer Program ($99 a year).
2. In Xcode or on developer.apple.com, create a **Developer ID
Application** certificate, and export it with its private key as a
`.p12` with a password.
3. Create an **app-specific password** for your Apple ID at
account.apple.com › Sign-In and Security.
4. On GitHub, add these under Settings › Secrets and variables › Actions:
| Secret | Value |
|---|---|
| `MACOS_CERTIFICATE` | `base64 -i DeveloperID.p12` (the whole output) |
| `MACOS_CERTIFICATE_PASSWORD` | the .p12's password |
| `MACOS_SIGNING_IDENTITY` | `Developer ID Application: Your Name (TEAMID)` |
| `MACOS_NOTARY_APPLE_ID` | your Apple ID email |
| `MACOS_NOTARY_TEAM_ID` | the 10-character team ID |
| `MACOS_NOTARY_PASSWORD` | the app-specific password |
The next tagged build signs every binary inside out, with the hardened
runtime and `packaging/mac/entitlements.plist`. It then signs the .dmg,
notarizes it with `notarytool`, and staples the ticket. Without the
secrets, `build.sh` says "Developer ID signing skipped" and signs ad hoc,
as it does today. Once a signed build is confirmed, take the "Open
Anyway" section out of `docs/mac.md`. Also try removing
`disable-library-validation` from the entitlements.
The signing path has never been run. Expect the first signed build to
need fixes.
## Building on a Mac by hand
On any Mac with Python 3.11 or later for that Mac's architecture, plus
Xcode's command line tools (`xcode-select --install`):
```sh
git clone <origin> lintunes && cd lintunes
PYTHON=python3.13 packaging/mac/build.sh
packaging/mac/smoke_test.sh build/mac/dist/LinTunes.app 20
open build/mac/LinTunes-*.dmg
```
Everything goes in `build/mac/`: the venv, the downloaded tools, the
app, and the .dmg with its `.sha256`. A Mac builds only for itself: an
Apple Silicon Mac makes the AppleSilicon dmg, and an Intel Mac makes the
Intel one.
## Updating what's bundled
- **ffmpeg / fpcalc**: `packaging/mac/tools.json` pins each download's URL
and SHA-256. To bump one, download the new file, run
`shasum -a 256` on it yourself, compare the result with the publisher's
checksum, then change the URL and hash together. Also update the
versions in `THIRD-PARTY.md`. The ffmpeg builds' publisher stops making
**Intel** release builds from January 2027. Keep the pinned 9.0.2 for
Intel until a replacement is chosen.
- **PyInstaller**: pinned at the top of `build.sh`.
- **Python**: `PYTHON_VERSION` in the workflow.
- **Minimum macOS**: `MINIMUM_MACOS` in `packaging/mac/plist.py`. It
follows PyQt6's macOS wheel tag (14.0 for PyQt6 6.12).
- **The icon**: `python3 scripts/make_icons.py --only mac` rewrites
`packaging/mac/LinTunes.icns` from `packaging/lint.jpg`. Commit the
result.
+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":
-
+142
View File
@@ -0,0 +1,142 @@
# LinTunes on a Mac
LinTunes started on Linux, and there is now a Mac version. You install it
the usual way, by dragging it to Applications. It needs **macOS 14 Sonoma
or later**.
## 1. Download the right one
Every release has two disk images:
| Your Mac | Download |
|---|---|
| Apple Silicon (M1, M2, M3, M4 and later) | `LinTunes-<version>-AppleSilicon.dmg` |
| Intel | `LinTunes-<version>-Intel.dmg` |
To find out which Mac you have, open the Apple menu › **About This
Mac**. If it says **Chip: Apple M…**, you have Apple Silicon. If it says
**Processor: … Intel …**, you have an Intel Mac.
Releases are on the project's GitHub **Releases** page. The newest one is
at the top.
## 2. (Optional) Check the download
Each release also has a file called `SHA256SUMS`. Download it to the same
folder as the .dmg, open Terminal, and run:
```sh
cd ~/Downloads
shasum -a 256 -c SHA256SUMS --ignore-missing
```
If the download is intact, you'll see `LinTunes-…dmg: OK`.
## 3. Install
1. Double-click the `.dmg`. A window opens with **LinTunes** and an
**Applications** folder.
2. Drag **LinTunes** onto **Applications**.
3. Eject the disk image (the ⏏ next to it in the Finder sidebar).
## 4. The first launch: "Open Anyway"
LinTunes isn't signed by Apple (that costs a yearly fee the project doesn't
pay yet), so macOS won't open it until you say so. You only have to do this
once:
1. Open **Applications** and double-click **LinTunes**. macOS says
*"LinTunes" Not Opened* (or *can't be opened*). Click **Done**. Don't
choose Move to Trash.
2. Open the Apple menu › **System Settings…** › **Privacy & Security**.
3. Scroll down to the **Security** section. It shows *"LinTunes" was
blocked to protect your Mac.* Click **Open Anyway**. (Some versions
label the button **Open**.) The button only appears for about an hour
after step 1. If it isn't there, do step 1 again.
4. Confirm with **Open Anyway**, then enter your login password.
From then on LinTunes opens like any other app.
On macOS 15 Sequoia and later, Control-click › **Open** **no longer** gets
you past this. Use System Settings as described above.
(If you're comfortable with Terminal, `xattr -dr com.apple.quarantine
/Applications/LinTunes.app` does the same thing.)
## 5. First run
When LinTunes opens for the first time, it creates a new library in
**~/Music/LinTunes** and asks where your music should go. To add songs,
drag them into the window, or use **File › Add Files to Library…** (⌘O). You can also
drop audio files onto LinTunes' Dock icon.
### "Allow LinTunes to find devices on local networks?"
The first time you open the Chromecast or AirPlay picker (the
**Connections** menu), macOS asks whether LinTunes may use your local
network. Click **Allow**. Without it LinTunes can't see your speakers.
If you said no, change it later under System Settings › **Privacy &
Security › Local Network**.
If your Mac's firewall is on, macOS may also ask whether LinTunes may
**accept incoming connections** when you cast. A Chromecast fetches the
song from LinTunes, so allow it.
## What's included, and what's optional
Included in the app, with nothing extra to install: playback (MP3, AAC/M4A,
Apple Lossless, FLAC, WAV, AIFF), the visualizers, DJ mode, Chromecast,
AirPlay, Identify Track, volume normalization, BPM detection, export, web
mixes, converting to MP3, Cassette, media keys and the Now Playing widget.
LinTunes ships with its own copies of `ffmpeg` and `fpcalc`.
Optional extras you install yourself (easiest with [Homebrew](https://brew.sh)):
- **Import from URL** (File menu) needs `yt-dlp`: `brew install yt-dlp`.
It isn't bundled, because YouTube changes often and yt-dlp has to keep
up. Run `brew upgrade yt-dlp` when downloads start failing.
- **Cassette** (sharing with friends) needs
[Syncthing](https://syncthing.net): `brew install syncthing`, then
`brew services start syncthing`. Syncthing is also how a library is kept
in step between computers.
- **DJ mode's vocal slider** needs Instant (Spleeter) or High quality
(Demucs). Set them up in Preferences › DJ, the same as on Linux.
- **Upload a web mix to your server** uses `ssh` and `rsync`, and macOS
already has both.
Not on the Mac: the **Rabbit R1** features (andTunes, Sync to Rabbit,
Import Shazams). They need the R1 plugged into a Linux machine.
## Where LinTunes keeps things
| What | Where |
|---|---|
| Your library (songs list, playlists, play counts, preferences) | `~/Music/LinTunes` unless you chose another folder |
| This Mac's settings (`config.json`), Cassette folders, the DJ vocal-splitter downloads | `~/Library/Application Support/LinTunes` |
| Things that can be rebuilt (loudness, vocal splits, album-art cache) | `~/Library/Caches/LinTunes` |
To remove LinTunes, drag it from Applications to the Trash. You can also
delete those two `~/Library` folders. Your library folder and your music
are never removed for you.
## Updates
LinTunes checks for a new release a little after it starts, and then every
few hours. When one is out, the version number in the bottom-left corner
gets a `*`. Click it and the release page opens in your browser. Download
the new `.dmg` and drag LinTunes to Applications again, replacing the old
one. Your library and settings are kept. If the new version is still
unsigned, macOS may ask for **Open Anyway** again.
The app never downloads or installs anything by itself.
## Something wrong?
[mac-testing.md](mac-testing.md) is the checklist a tester goes through.
When you report a problem, include the LinTunes version (bottom-left
corner), your macOS version, and Apple Silicon or Intel. To get the log,
start LinTunes from Terminal and send what it prints:
```sh
/Applications/LinTunes.app/Contents/MacOS/LinTunes
```