Events
The Media Server pushes real-time events over server-sent events (SSE). An app opens one long-lived connection and receives events as they happen, such as a waveform finishing or an indexing run making progress.
Subscribing
GET /api/v1/events/subscribe
Authenticate with the Authorization header. The browser's EventSource cannot send headers, so pass the credential as the token query parameter instead:
const events = new EventSource(`${serverUrl}/api/v1/events/subscribe?token=${token}`)
events.onmessage = (message) => {
const { type, payload } = JSON.parse(message.data)
if (type === 'music.waveform_ready') {
showWaveform(payload.musicTrackId, payload.waveform)
}
}
In other languages, use any SSE client, or read the response body line by line.
Message format
Every event arrives as a single data: line holding a JSON object:
data: {"type":"music.waveform_ready","payload":{"musicTrackId":"a826e28d-...","waveform":{...}}}
Messages have no event: field, so listen for the default message event and switch on type.
Events
type | Sent when |
|---|---|
music.waveform_ready | A waveform requested from the waveform endpoint is ready. The payload carries musicTrackId and waveform. |
indexing.started, indexing.current_progress, indexing.completed | An indexing run starts, progresses, and finishes. |
indexing.paused, indexing.resumed, indexing.stopped | An indexing run is paused, resumed, or stopped. |
indexing.music_release_added, indexing.music_artist_added | Indexing adds a release or an artist. |
job.started, job.current_progress, job.completed | A job starts, progresses, and finishes. |
photo.updated | A photo's data changes. |
photo_album.created, photo_album.updated, photo_album.deleted | A photo album changes. |
photo_album.photos_added, photo_album.photos_removed | Photos are added to or removed from an album. |
playback_queue.extended | The server adds tracks to one of the user's playback queues. |
This table lists the events most useful to a client app. Payloads follow the server's data model and can change between versions, so read the fields you need and tolerate the rest.
Reconnecting
Events are not stored. Anything sent while an app is disconnected is lost, so after reconnecting, re-fetch whatever state the app shows instead of waiting for events to bring it up to date.
EventSource reconnects on its own after a dropped connection. When the token in the URL has expired, the server refuses the reconnection and EventSource stops retrying: open a new one with a fresh token.
Live updates with events has a complete client loop, with backoff, and which data to refresh for each event.
Was this article helpful?