ThUNER

A Swiss army knife for what's playing on a Mac. It's a menu bar app that takes the track from wherever the music comes from (a turntable, the room, Apple Music, Spotify, a browser or any app) and sends it wherever you want it: the cover to a Tuneshine or any screen, the play to Last.fm or a self-hosted service, what's playing to Shortcuts and your own scripts, and the audio itself to another Mac's speakers.

Download: idallas.com/software/thuner. The download is notarized and keeps itself up to date.

What it does

• Listens carefully. It identifies a line-in, a microphone or the Mac's own audio (a Core Audio process tap, which can be limited to certain apps) with ShazamKit. It waits for two results that agree before changing anything. It stays quiet below an adjustable silence threshold, and checks each confirmed track again near its predicted end.
• Reads players directly. It takes Apple Music and Spotify tracks from the apps' own notifications, with no permissions needed, and turns the mic off while they play.
• Follows websites. Point the Web Scrobbler browser extension's Webhook at ThUNER (Settings → General copies the URL) and YouTube Music, Bandcamp, SoundCloud and the rest count as a player too: cover on the Tuneshine, scrobbled by ThUNER.
• Follows other apps and browsers. Anything that shows up in Control Center's Now Playing (VLC, a browser tab playing YouTube Music, Bandcamp and so on) is followed too, with no setup; videos are left out.
• Shows the cover:
  • on a Tuneshine, found on the network, by uploading a 64×64 WebP to its local API
  • in a floating window or a pinnable panel
  • on a web display any browser can open
• Two Macs, one display. Tell one Mac to defer to another (Settings → General), coordinated over Bonjour and UDP. While the turntable Mac plays, the desk Mac keeps its mic off and shows the turntable's track.
• Streams the audio. One ThUNER shares its input and another plays it, so the turntable in one room comes out of the speakers in another: uncompressed, a few milliseconds of buffer on Ethernet, resilient to loss on Wi-Fi, optionally encrypted.
• Scrobbles:
  • to Last.fm, with an offline queue and duplicate detection
  • to ListenBrainz-compatible servers (ListenBrainz, Maloja, Koito, multi-scrobbler)
  • with a Scrobble switch in the menu to pause it whenever you like
• Can be controlled. Through Applug, by any app on the Mac that speaks it (Twist Commando, Action Hero), plus a small HTTP API with Server-Sent Events. Both use one control list (ControlSurface).

Requirements

• macOS 15 or later, Apple silicon or Intel.
• Xcode 16 or later to build.

Building

swift test

Scripts/build-app.sh

This builds build/Thuner.app, signed ad-hoc unless you configure a signing identity.

ShazamKit needs a signed app. Apple only answers ShazamKit queries from an app that meets both of these conditions:

• It's signed by a paid Apple Developer team.
• Its App ID has the ShazamKit App Service turned on (Certificates, Identifiers & Profiles → Identifiers → your App ID → App Services).

An ad-hoc build runs fine, and Apple Music and Spotify, the Tuneshine, scrobbling, the web display and the API all work. But identifying audio fails with ShazamKit error 102. To build with your own team:

1. Copy Scripts/config.example.sh to Scripts/config.local.sh. Git ignores the copy.
2. Set SIGN_IDENTITY to your Developer ID Application certificate.
3. Set BUNDLE_ID to an App ID in your team that has ShazamKit turned on.

Last.fm needs an API key. No key is included in the source. Create one at last.fm/api/account/create and enter it in Settings → Scrobbling. Once it's saved, build-app.sh builds it into your builds, so other Macs only need to approve the app on last.fm.

Updates and stats. Builds made from source never update themselves to official releases: development builds carry a version Sparkle won't replace. They also send no usage stats. If you publish your own builds, change SUFeedURL and SUPublicEDKey in Resources/Info.plist to point at your own appcast and key.

Layout

• Sources/ThunerCore: pure logic, unit tested. Contains:
  • the Idle / Identifying / Playing state machine
  • the level gate
  • the two-Mac push arbiter
  • track identity
  • scrobble timing
  • play history
• Sources/Thuner: the app. Contains:
  • Core Audio and AVAudioEngine capture, and the System Audio process tap
  • ShazamKit matching and the player monitor
  • the Tuneshine client and the peer link
  • scrobbling services
  • the HTTP server and web display
  • the SwiftUI and AppKit interface
• Scripts: build, release (notarize, Sparkle appcast) and website deploy. The website itself lives in a separate repo.
• docs: images for this README.

CLAUDE.md has the detailed design notes: the Tuneshine API quirks, scrobbling rules and the control API.

The control API

When the web display is on, ThUNER serves the following on port 47480:

• GET /: the web display.
• GET /now.json: what's playing.
• GET /api/controls: every control and its state.
• GET /api/events: Server-Sent Events.
• POST /api/controls/<id>: changes a control. The body is {"value": 0-1}, {"press": true} or {"on": bool}.

Changing anything needs the token from Settings → Controls, except from scripts on the same Mac. Settings → Display can also limit the server to this Mac only.

Contributing

See CONTRIBUTING.md. To report a security problem, see SECURITY.md.

License

MIT; see LICENSE. Third-party licenses are in THIRD_PARTY_NOTICES.md.

Name and icon

The MIT license covers the code, not the name or the icon. "ThUNER" and the ThUNER icon identify this project and the builds published at idallas.com/software/thuner. If you distribute a fork or a modified build, give it its own name and icon. Saying it's based on ThUNER is fine, and appreciated.

ThUNER isn't affiliated with or endorsed by Apple, Shazam, Spotify, Last.fm, ListenBrainz, Web Scrobbler or Tuneshine. Their names are used only to describe what ThUNER works with.

The name comes from an old nickname, after the surname Bethune, and it's a tuner: the bold letters spell TUNER. The h is silent.