nowplayingd help

First launch

You need macOS 26 or later. nowplayingd has no Dock icon: it lives in the menu bar, as a record. The record is full while music plays and empty when it stops.

On first launch, a setup assistant walks you through it, one screen at a time:

1. Permissions: what macOS will ask, and why. The local network, to find your Sonos speakers; the Music app and Spotify, to see what's playing and control playback from the menu.
2. Speakers: finds the Sonos speakers on your network.
3. Accounts: Last.fm and ListenBrainz, both optional.
4. Scrobbling: optional, off by default.
5. On this Mac: Apple Intelligence for the haiku, translation languages.
6. Full screen: the shortcut, and automatic full screen when your Mac is idle.

Run it again any time: Settings → About → Run the setup assistant again…

Connecting your services

In Settings → Accounts, or in the assistant. Every account is optional: with Sonos speakers or the Music app alone, nowplayingd already works.

Last.fm

Last.fm gives each user a free, personal API key. You create yours once; the Last.fm tile walks you through it in three steps:

1. Open the Last.fm form. Signed in to Last.fm, enter nowplayingd as the application name, leave the other fields empty and submit.
2. Copy the API key and the Shared secret shown by Last.fm into the two fields.
3. Save and authorize. The Last.fm authorization page opens in your browser: click Yes, allow access, then come back to nowplayingd. Your name shows up with a green check.

You never type your Last.fm password into nowplayingd. Your key, your secret and the session key stay in your Mac's keychain. Disconnect ends the session; Remove also deletes your API key. You can revoke access on last.fm too (Settings → Applications).

ListenBrainz

1. Click Connect: your ListenBrainz settings page opens.
2. Copy your User token.
3. Come back to nowplayingd and click Paste. The app checks the token and shows your name.

The token stays in your keychain; My API key lets you change or remove it.

Mastodon and Bluesky

Only needed to share what you're listening to. See Sharing.

Sonos speakers

nowplayingd reads your speakers directly on your local network: no Sonos account, no cloud, no need for the Sonos app to be open.

To make it work:

1. Your Mac and your speakers are on the same network. A guest network, a separate VLAN or Wi-Fi client isolation hide them.
2. When macOS asks whether nowplayingd may find devices on your local network, choose Allow. If you declined: System Settings → Privacy & Security → Local Network → turn nowplayingd on.
3. If your Sonos app has a UPnP setting, keep it on.
4. If the macOS firewall asks whether nowplayingd may accept incoming connections, choose Allow: your speakers use them to report every change instantly. If you deny, everything still works, a little slower (checked every 2 s).

To check: Settings → Sources → Test the speakers. A healthy result looks like this:

ok  Bonjour: 9 speakers in 5 rooms.
ok  Port 1400: all 9 speakers answer.
ok  Topology: 4 groups (Living Room, Kitchen, TV, Bedroom).
ok  Living Room: Massive Attack — Teardrop
--  TV: playing the TV, ignored.

Message	What to do
No speaker found	Check points 1 and 2 above. Otherwise, enter one speaker's IP address as Fallback address (Settings → Sources).
No speaker answers	A firewall, a VLAN or a guest network is in the way: put the Mac on the speakers' network.
Groups could not be read	Check the UPnP setting in the Sonos app.
Radio needs Last.fm	Connect Last.fm (see above): it's what recognises songs on the radio.

You'll find a speaker's IP address in the Sonos app (Settings → System → About My System) or in your router.

What is shown, and what isn't

• Shown: streaming started from the Sonos app (Apple Music, Spotify, Tidal, Deezer, Qobuz…), your library, and radio. On the radio, a song only appears once it's recognised, which leaves out ads, jingles and talk.
• Ignored: line-in (a turntable, say), AirPlay, Spotify Connect and the TV. Either there's nothing to read, or the app that started the music already scrobbles it.

Music and Spotify on this Mac

On by default (Settings → Sources). nowplayingd shows what the Music app and Spotify are playing on this Mac, with the audio output: AirPlay, Bluetooth, the Mac's own speakers…

• macOS asks once whether nowplayingd may control Music and Spotify. With that permission, it sees what's already playing at launch, and the menu's play, pause and next buttons work. Without it, a track only shows up at the first change (play, pause, next).
• When the Music app sends sound to an AirPlay speaker through its own AirPlay button, that choice isn't visible to other apps.
• Tidal, Deezer, Qobuz, YouTube Music: their apps can't be read from the Mac. Link them to Last.fm in their own settings, and nowplayingd will see those listens through your account.

Full screen

• ⌥⌘N, or “Full screen” in the menu. Esc or a click closes it.
• Big artwork, artist and album, the animated haiku and, along the bottom, the backstage: cards picked at random from Wikipedia, Wikidata, Wikimedia Commons, Last.fm, MusicBrainz and the Cover Art Archive.
• On a large display (iMac, Studio Display), your history appears in a column on the right.

In Settings → Full screen:

• automatic full screen after 2 to 30 minutes idle, optionally only while music plays;
• all displays, or the main one only;
• Keep the display awake and Keep the screen saver away: on by default, they only apply while in full screen. macOS counts idle time once for both, so keeping only the screen saver away also delays display sleep;
• the backstage cards and the haiku can be turned off.

Lyrics

Optional, off by default: Settings → Full screen → Show lyrics while playing.

• They come from LRCLIB, a free community database. Not every song is there.
• In full screen they replace the haiku, which moves to the backstage cards. The current line is in amber and follows the track (Sonos speakers, Music, Spotify).
• Original or translated: the switch in the menu, or the T key in full screen. The translation is done on your Mac.

Scrobbling

Optional and off by default (Settings → Scrobbling).

• What: the Sonos speakers, the Music app, and Spotify (off by default: Spotify scrobbles by itself when it's linked to Last.fm).
• Where: Last.fm and/or ListenBrainz, connected in Settings → Accounts.
• When: the track is announced as “now playing” when it starts, then scrobbled at half its length, or after 4 minutes if it's long (tracks over 30 seconds only), dated from its start. On the radio, it is marked as not chosen by you.
• No duplicates: right before writing, nowplayingd reads your latest listens. If another app has already scrobbled the same track, it sends nothing. It also never sends the same title twice within 10 minutes.
• Offline: scrobbles wait on your Mac's disk and go out in order when the connection is back.
• Several Macs: turn scrobbling on for one of them only, or use a hub.

Haiku and translation

• The haiku is written on your Mac by Apple Intelligence, in the language of the titles when the model speaks it, otherwise in English. You need a Mac that supports Apple Intelligence, with it turned on (System Settings → Apple Intelligence & Siri). Otherwise, there's simply no haiku.
• Texts (Wikipedia, bios) appear in your language when they exist. Otherwise they are translated on your Mac by Apple's Translation framework and marked “Translated on device”. Download the languages you need in Settings → Language (English first: most bios are in English).
• Artist, album and track names are never translated.

Sharing on Mastodon or Bluesky

Connect once, in Settings → Accounts:

• Mastodon: enter your server (for example mastodon.social) and click Connect. Your server's page opens in the browser: authorize nowplayingd, and you're done.
• Bluesky: enter your handle (for example you.bsky.social) and click Connect. The Bluesky page opens: click Accept. No password goes through nowplayingd.

You can revoke access at any time, in Mastodon or Bluesky, or with Disconnect.

Then: Share on Mastodon or Bluesky… in the menu (⇧⌘M). You get an editable preview with the track, the album, the haiku, hashtags and the artwork with its alt text. Pick the network, review, and nothing goes out until you click Post. On Bluesky the text fits in 300 characters: with a very long title, the haiku goes first. If a network has ended the session, nowplayingd simply asks you to connect again.

A hub and displays

An always-on Mac (a Mac mini, say) can act as the hub: it reads every source, writes the haiku and is the only one that scrobbles. Your other Macs become displays: they show what the hub publishes on the local network and read nothing by themselves. By default, each Mac is Standalone.

1. On the Mac mini: Settings → Role → Hub (always on). Turn on Open at login, and note the six-digit pairing code.
2. On the iMac or the MacBook: Settings → Role → Display. The hub shows up; type the code once.
3. For the hub to come back by itself after a power cut: System Settings → Users & Groups → automatic login.

Play/pause, next and Love on a display act on the hub. If the hub goes quiet for more than two minutes, the display can show its own sources (without scrobbling) and says so in the menu. New code and Forget all displays, on the hub, cut off every display already paired.

Useful settings

Setting	Where
Refresh rate: online services 15 s to 5 min (30 s by default), speakers 3 s to 1 min (10 s by default)	Settings → Sources
A speaker's fallback address	Settings → Sources
Refresh now	Menu, ⌘R
App and content language, translation languages	Settings → Language, then restart

Troubleshooting

Last.fm doesn't show up. Settings → Accounts → Last.fm: if the tile asks for a key, follow its three steps (see above), then Connect.

“Unknown user.” Check the spelling of your Last.fm or ListenBrainz username.

The radio doesn't show up. You need to be connected to Last.fm, the station must send “ARTIST - TITLE”, and Last.fm must know the song. During a show or an ad, nothing appears: that's on purpose.

A track stays “now playing” after it stopped. Last.fm sometimes keeps the announcement until the track's theoretical end. nowplayingd removes it as soon as another track is scrobbled, or as soon as Sonos stops.

No haiku. Apple Intelligence is unavailable or off, or the haiku is turned off in Settings → Full screen.

Start over. In Settings → Accounts, disconnect each account (and Remove your Last.fm key). Quit nowplayingd, then delete the folder ~/Library/Containers/ch.patrickostertag.nowplayingd. Details in the privacy policy.

Privacy

nowplayingd collects no data. No server, no account with me, no tracking, no analytics. The app talks directly to your speakers and to the services you choose. Your credentials stay in your Mac's keychain; the haiku is written and texts are translated on your Mac.

Details, service by service: privacy policy.

A question, a bug, an idea? Reach me on Mastodon. To help with a diagnosis, include the result of Test the speakers (select the text and copy it) and your version (Settings → About).

nowplayingd is in beta. Want to test it? Here's how.