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

5.7 KiB
Raw Blame History

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:

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

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

/Applications/LinTunes.app/Contents/MacOS/LinTunes