Skip to Content
macos-nowplaying-bridge

πŸ“– API reference

Every export of @kud/macos-nowplaying-bridge, with field types and exact behaviour.

The package has a single entry point and one runtime export, createNowPlayingBridge, plus three types.

import {
  createNowPlayingBridge,
  type NowPlayingBridge,
  type NowPlayingInfo,
  type RemoteEvent,
} from "@kud/macos-nowplaying-bridge"

createNowPlayingBridge

createNowPlayingBridge(): Promise<NowPlayingBridge>

Compiles the Swift source if no cached binary exists for its current hash, then spawns it as a persistent co-process and resolves with the bridge. The first call per machine, and the first after an upgrade that changes the Swift source, waits for swiftc; later calls start immediately. See How it works.

It rejects with @kud/macos-nowplaying-bridge only works on macOS when process.platform is not darwin, and with the swiftc error if compilation fails.

Each call spawns its own co-process, so create one bridge per app and share it.

NowPlayingBridge

type NowPlayingBridge = {
  update: (info: NowPlayingInfo) => void
  on: (event: RemoteEvent, handler: () => void) => void
  stop: () => void
}

update

bridge.update(info: NowPlayingInfo): void

Serialises info as one JSON line and writes it to the co-process. It returns immediately and does not report errors.

FieldTypeNotes
titlestringRequired by the type
artiststringOptional
albumstringOptional
artworkUrlstringRemote or file:// URL, downloaded once per distinct URL
durationnumberTrack length in seconds
elapsednumberCurrent position in seconds
ratenumberPlayback rate; 1 is normal speed
state"playing" | "paused"Sets the system playback state

Behaviour worth knowing:

  • Updates merge. The co-process starts from whatever is already published and overwrites only the fields you send, so an omitted artist keeps its last value.
  • rate is remembered. An explicit rate is published as sent. Without one, state: "paused" publishes 0 so the progress bar stops, state: "playing" restores the last non-zero rate (initially 1), and any other update keeps the last published rate.
  • state is only touched when sent. Leaving it out keeps the current playback state.
  • Artwork is cached by URL. A different URL replaces the artwork once the download finishes; a failed download leaves the previous artwork in place.

on

bridge.on(event: RemoteEvent, handler: () => void): void

Registers a handler for a Control Center or media-key press. Handlers receive no arguments. You can register several handlers for the same event and all of them run. There is no off; call stop() to tear everything down.

stop

bridge.stop(): void

Kills the co-process, which releases the Now Playing slot. Calling update() afterwards writes to a dead pipe and has no effect.

NowPlayingInfo

type NowPlayingInfo = {
  title: string
  artist?: string
  album?: string
  artworkUrl?: string
  duration?: number
  elapsed?: number
  rate?: number
  state?: "playing" | "paused"
}

RemoteEvent

type RemoteEvent = "play" | "pause" | "toggle" | "next" | "previous"
EventFired when
playThe system asks to start playback
pauseThe system asks to pause playback
toggleThe system asks to switch between play and pause
nextNext track is pressed
previousPrevious track is pressed

The bridge does not change playback itself. It reports the press and leaves the decision, and the follow-up update(), to you.