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
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:
@@ -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.
|
||||
@@ -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
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user