# Media Control

Control media playback and system volume.

## WebSocket for Media

For building media widgets or dashboards, we **strongly recommend** the [WebSocket API](/content/docs/ws/media/index.html) 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 `