> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velora.crickdevs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket

> Real-time event stream for the Velora local API.

The local API exposes a WebSocket endpoint for playback updates.

## Endpoint

`ws://127.0.0.1:39031/ws?access_token=<token>`

Requirements:

* Token must be valid and active
* Token must include `read` permission
* Connection must originate from localhost

If auth fails, the upgrade is rejected with `401`.

## Initial events after connect

When a connection is accepted, Velora sends these events immediately:

* `connected`
* `track_changed`
* `playback_state_changed`

## Runtime events

As playback changes, Velora broadcasts:

* `track_changed`
* `playback_state_changed`

Event envelope format:

```json theme={null}
{
  "event": "track_changed",
  "data": {
    "id": "track_456",
    "title": "New Song",
    "artist": "Artist Name",
    "cover_url": "https://..."
  }
}
```

Playback state event example:

```json theme={null}
{
  "event": "playback_state_changed",
  "data": {
    "is_playing": true,
    "shuffle": false,
    "repeat": "off"
  }
}
```

## JavaScript example

```javascript theme={null}
const token = 'velora_your_token';
const ws = new WebSocket(`ws://127.0.0.1:39031/ws?access_token=${encodeURIComponent(token)}`);

ws.addEventListener('message', (event) => {
  const payload = JSON.parse(event.data);
  console.log(payload.event, payload.data);
});
```