WebSocket

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:

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

Playback state event example:

{
  "event": "playback_state_changed",
  "data": {
    "is_playing": true,
    "shuffle": false,
    "repeat": "off"
  }
}

JavaScript example

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);
});

Velora API

Velora Local API

Endpoint

Initial events after connect

Runtime events

JavaScript example

​Endpoint

​Initial events after connect

​Runtime events

​JavaScript example

Endpoint

Initial events after connect

Runtime events

JavaScript example