π§ Usage
Wire a Node player up to Control Center, from first update to clean shutdown.
Requirements
- macOS (the package declares
"os": ["darwin"], andcreateNowPlayingBridge()throws on any other platform) - Node.js 20 or later
swiftcon yourPATH, which comes with the Xcode Command Line Tools (xcode-select --install)
A minimal player
import { createNowPlayingBridge } from "@kud/macos-nowplaying-bridge"
const bridge = await createNowPlayingBridge()
bridge.on("toggle", () => player.toggle())
bridge.on("next", () => player.next())
bridge.on("previous", () => player.previous())
bridge.update({
title: "Intro",
artist: "The xx",
album: "xx",
duration: 126,
elapsed: 0,
state: "playing",
})Open Control Center and the track appears in the Now Playing tile. Pressing its buttons, or the media keys, calls your handlers.
Keep Control Center in step with your player
Call update() whenever something worth showing changes: a new track, a pause, a seek. Control Center extrapolates the progress bar from elapsed and rate between updates, so you do not need to push a tick every second.
// Track changed
bridge.update({ title, artist, album, duration, elapsed: 0, state: "playing" })
// Paused at 41 seconds
bridge.update({ title, elapsed: 41, state: "paused" })
// User scrubbed
bridge.update({ title, elapsed: seekPosition, state: "playing" })Fields you omit keep their previous value in Control Center. rate follows state when you do not send it: a pause stops the progress bar and resuming restores the last playing rate. See the API reference for the details.
Handle every button
play and pause are sent by the dedicated commands, while toggle is sent when the system asks for play/pause as a single action (the usual media-key behaviour). Handle all three, and update Control Center afterwards so it reflects what your player actually did.
bridge.on("play", () => {
player.play()
bridge.update({ title: player.title, elapsed: player.position, state: "playing" })
})
bridge.on("pause", () => {
player.pause()
bridge.update({ title: player.title, elapsed: player.position, state: "paused" })
})Artwork
Pass artworkUrl as a remote URL or a file:// URL. The image is fetched once; repeated updates with the same URL do not trigger another download.
bridge.update({
title: "Intro",
artworkUrl: "file:///Users/me/Music/xx/cover.jpg",
})Shut down
process.on("SIGINT", () => {
bridge.stop()
process.exit(0)
})stop() kills the co-process and releases the Now Playing slot. The co-process also exits on its own when your Node process goes away, because it quits as soon as its stdin closes.
Try it
The repository ships a throwaway driver that claims the slot with a fixed track and logs every button press:
npx tsx examples/demo.ts