Skip to main content
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);
});