Media Control

Control media playback and system volume.

WebSocket for Media

For building media widgets or dashboards, we strongly recommend the WebSocket API instead of polling this endpoint.

Why WebSocket?

Instant updates - Receive media_update events only when something changes (track, volume, mute)
Bidirectional - Send play/pause/skip commands and receive feedback through the same connection
Zero polling - No need to hammer the server every second to check for changes
Efficient - Cntrl uses smart change detection, so you only get data when it matters

macOS Permissions Required

On macOS, the first time you use media control endpoints, the system will prompt for Media & Apple Music permissions. Grant access in System Settings → Privacy & Security → Media & Apple Music to enable media playback control.

The media endpoints allow you to control system-wide media playback, system volume, and retrieve information about what's currently playing.

Get Media Status

Returns information about the currently playing media, including system volume.

GET /api/media/status

Response:

{
  "status": "active",
  "title": "Song Name",
  "artist": "Artist Name",
  "album": "Album Name",
  "source": "SpotifyAB.SpotifyMusic...",
  "has_image": true,
  "volume": 50,
  "muted": false
}

Field Reference

Field	Type	Description
`status`	string	Current status (`active`, `stopped`, or `idle`).
`title`	string	Current track title.
`artist`	string	Current artist name.
`album`	string	Current album name.
`source`	string	App ID of the media source (Win only).
`has_image`	boolean	If true, a thumbnail is available.
`volume`	number	Current system volume (0-100).
`muted`	boolean	True if system volume is muted.

Status Note

On Windows, status returns `