Files
lintunes/docs/mac.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

143 lines
5.7 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.
# 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
```