Play Sessions

Play sessions manage audio streaming for collections, tracks, or playlists.

POST /v1/play_session/:scope

Creates a new play session for a collection, track, or playlist

Parameters

Name	Type	Required	Description
`scope`	string	Required	One of "collection", "track", or "playlist" (path parameter)
`variants`	array of strings	Optional	Variant settings for the play session
`collection_id`	uuid	Optional	ID of the collection (required if scope is 'collection')
`track_id`	uuid	Optional	ID of the track (required if scope is 'track')
`playlist_id`	uuid	Optional	ID of the playlist (required if scope is 'playlist')
`is_downloadable`	boolean	Optional	Whether tracks in this session can be downloaded

Example Request

{
  "variants": ["high", "medium", "low"],
  "collection_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response

{
  "ok": true,
  "play_session_id": "uuid",
  "play_session": {
    "id": "uuid",
    "variants": ["string"],
    "expires_at": "string"
  },
  "tracks": [ /* Array of track details */ ],
  "expires_at": "string"
}

GET /v1/play_session/:play_session_id

Retrieves details about a play session

Parameters

Name	Type	Required	Description
`play_session_id`	uuid	Required	The ID of the play session (path parameter)

Response

{
  "ok": true,
  "play_session_id": "uuid",
  "play_session": {
    "id": "uuid",
    "variants": ["string"],
    "expires_at": "string"
  },
  "tracks": [ /* Array of track details */ ]
}

GET /v1/play/:play_session_id/:play_track_id

Retrieves details about a specific track within a play session. No authentication required - the session ID acts as a bearer token.

Parameters

Name	Type	Required	Description
`play_session_id`	uuid	Required	The ID of the play session (path parameter)
`play_track_id`	uuid	Required	The ID of the track within the session (path parameter)

Response

{
  "ok": true,
  "play_session_id": "uuid",
  "track_id": "uuid",
  "play_session": { "id": "uuid", "variants": ["string"], "expires_at": "string" },
  "cover_image": "string",
  "track": {
    "id": "uuid",
    "duration": "number",
    "file_name": "string",
    "color": "string"
  },
  "levels": "object",
  "variants": [{ "path": "url", "url": "url" }]
}

GET /v1/play/:play_session_id/:play_track_id/:variant_index/download

Downloads a specific variant of a track. Only available if the play session was created with is_downloadable: true. No authentication required.

Parameters

Name	Type	Required	Description
`play_session_id`	uuid	Required	The ID of the play session (path parameter)
`play_track_id`	uuid	Required	The ID of the track within the session (path parameter)
`variant_index`	string	Required	The index/identifier of the variant to download (path parameter)

Response

Returns the audio file as a download, or an error if the session doesn't allow downloads.