korimako

Hardware media keys support for ncspot, and some pretty feathers

Korimako is the te reo Māori name for the New Zealand bellbird, named for its clear, bell-like song. They have also been known to reproduce some sounds such as ringtones. Similarly, this app listens for media key presses and sings them across to ncspot.

Features

Your keyboard media keys ⏮ ⏯ ⏭ can now control ncspot. korimako registers as a Now Playing source, so the keys follow whatever is currently playing: ncspot when it's active, your browser when a video is playing there, just like Spotify or Music would behave.

The track ncspot is currently playing is now visible in the menubar.

The full menu shows the current track with album art, your two most recent tracks played via ncspot as long as korimako was running, and for funsies, a style picker that applies Core Image effects to album art live.

korimako also hooks into the macOS Control Center media widget, so the album art will appear there too, and you can control playback there too, including with the position scrubber.

If the "Launch at Login" option doesn't work properly, ensure you placed korimako in the /Applications directory.

How it works

 media key  ──▶  MPRemoteCommandCenter  ──▶  korimako  ──▶  ncspot.sock
 (play/pause)                                    │           (playpause/next/previous/seek)
                                                 ▼
 menubar + Control Center  ◀──  MPNowPlayingInfoCenter  ◀──  JSON status stream

• Media keys are claimed via the public MPRemoteCommandCenter: enough to win ownership over browsers on macOS 13–26, and it preserves natural now-playing handoff (pause ncspot and your browser gets the keys back, just like Spotify).
• IPC uses ncspot's Unix domain socket (USER_RUNTIME_PATH/ncspot.sock, discovered via ncspot info, with a /tmp/ncspot-$UID fallback). Status frames are newline-delimited JSON; commands are plain text tokens.
• Scrubber: the Control Center position scrubber maps to ncspot's seek command, so you can drag to any point in the current track.
• Resilience: auto-reconnects when ncspot starts/stops; relinquishes Now Playing when ncspot isn't running so keys fall back to other apps.

Requirements

• macOS 13+ (Apple Silicon or Intel) — built and tested on macOS 26; should work on 13+, untested below 26
• Swift Command Line Tools, no Xcode required (xcode-select --install)
• ncspot with IPC (Homebrew's build includes it)

Install

Option A — Homebrew (recommended):

brew install --cask gouegd/korimako/korimako

Option B — download (no build tools needed):

1. Download korimako.zip from the latest release
2. Unzip and drag korimako.app to /Applications
3. Open it — macOS will block it on first launch because it isn't notarised; go to System Settings → Privacy & Security → Open Anyway

Option C — build from source:

git clone https://github.com/gouegd/korimako
cd korimako
./scripts/build-app.sh          # produces korimako.app (ad-hoc signed)
cp -R korimako.app /Applications/
open /Applications/korimako.app

The menubar icon appears; there is no Dock icon. Enable Launch at Login from the menubar menu for automatic start on login.

Development

Debug, preview, and tuning

Debug logging: set KORIMAKO_DEBUG=1 to print IPC frames, remote commands, and now-playing state to stderr:

KORIMAKO_DEBUG=1 open korimako.app
# or tail the log:
KORIMAKO_DEBUG=1 ./korimako.app/Contents/MacOS/korimako 2>/tmp/korimako.log &
tail -f /tmp/korimako.log

Preview an artwork style without touching Control Center. This renders [original | styled] side-by-side PNG through the real pipeline:

./korimako.app/Contents/MacOS/korimako --render <style> <coverURL> [out.png]
# e.g.
./korimako.app/Contents/MacOS/korimako --render cartoon https://i.scdn.co/image/<id> /tmp/preview.png

Watch ncspot live: scripts/watch-ncspot.py tails the IPC socket and prints track/playback changes (read-only, great for debugging).

Artwork styles live in Sources/korimako/ArtworkTransform.swift. The Cartoon style is a cel-shading pipeline (flat posterised colour fills + thresholded inked outlines). Key knobs: posterize levels (4), edge threshold (0.22), edge intensity (4).

Private MediaRemote nudge: KORIMAKO_USE_PRIVATE=1 enables a private eligibility call. Off by default: it blocks now-playing handoff on macOS 15.4+.

TODO

• Add a minimal Preferences window to surface: Launch at Login toggle, artwork style picker, and future options such as Spotify API credentials (for release year and BPM-driven flame effect).

Notes

• Ad-hoc signed for personal use. macOS Gatekeeper will prompt you to approve it on first launch (System Settings → Privacy & Security → Open Anyway).
• Disclaimer: this is somewhat (as in, entirely) vibe-coded, I am yet to write a single line of Swift. This is "works on my machine" software.

License

MIT © gouegd