Wiedergabesessions
Wiedergabesessions verwalten die Audio-Wiedergabe für Sammlungen, Tracks oder Playlists.
Die aufgelöste player_color jedes Tracks wird von zwei schreibgeschützten Begleitfeldern begleitet: player_color_light (angepasst für Lesbarkeit auf hellem Hintergrund) und player_color_dark (angepasst für dunklen Hintergrund), damit Ihr Player die passende Farbe für sein Theme wählen kann.
/v1/play_session/:scope Erstellt eine neue Wiedergabesession für eine Sammlung oder einen Track.
Parameter
| Name | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
scope | string | Erforderlich | "collection" oder "track" (Pfadparameter). "playlist" ist für eine zukünftige Version reserviert und gibt derzeit 400 zurück. |
variants | array of strings | Erforderlich | Nicht leere Liste von Varianten-Indexes für die Wiedergabesession (z. B. ["hq", "lq"]). |
collection_id | uuid | Erforderlich | Sammlungs-ID, wenn scope "collection" ist. Erforderlich, sofern der API-Key nicht auf eine Sammlung beschränkt ist. |
track_id | uuid | Erforderlich | Track-ID, wenn scope "track" ist. Erforderlich, sofern der API-Key nicht auf einen Track beschränkt ist. |
is_downloadable | boolean | Optional | Fordert an, dass Tracks dieser Session downloadbar sind. Wird nur berücksichtigt, wenn der API-Key ebenfalls Downloads erlaubt (pro Key im Dashboard gesetzt). Der gespeicherte Session-Wert ist api_key.is_downloadable AND diese Anfrage — ein Key, der Downloads verbietet, gewinnt immer — der Download-Endpunkt gibt dann 403 zurück. |
expires_in | number | Optional | Session-Dauer in Sekunden (Standard: 3600, min: 60, max: 86400) |
Beispielanfrage
curl -X POST "https://api.audiodelivery.net/v1/play_session/collection" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_id": "COLLECTION_ID",
"variants": [
"hq",
"lq"
],
"expires_in": 3600
}' Antwort
{
"ok": true,
"play_session_id": "uuid",
"play_session": {
"id": "uuid",
"creator_id": "uuid | null",
"variants": ["string"],
"is_downloadable": false,
"expires_at": "string"
},
"tracks": [
{ "id": "uuid", "index": "string", "duration": 0, "order": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null" }
],
"first_track": {
"track_id": "uuid",
"cover_image": {
"icon": { "type": "icon", "width": 80, "height": 80, "url": "string" },
"small": { "type": "small", "width": 200, "height": 200, "url": "string" },
"regular": { "type": "regular", "width": 400, "height": 400, "url": "string" }
},
"track": {
"id": "uuid",
"index": "string",
"duration": 0,
"player_title": "string | null",
"player_subtitle": "string | null",
"player_color": "string | null",
"player_color_light": "string | null",
"player_color_dark": "string | null",
"theme": [],
"file_name": "string",
"info": {},
"organization_index": "string | null",
"order": 0,
"metadata": {},
"is_dark": false
},
"levels": { "levels": [ 0, 0.5, 1 ] },
"variants": [
{ "path": "string", "url": "string", "variant": { "index": "string" } }
]
},
"expires_at": "string"
} Das Feld first_track enthält die vollständigen Wiedergabedaten des ersten Tracks (signierte Streaming-URLs, Wellenform-Levels, Coverbild und Varianten), damit Ihr Player sofort rendern kann, ohne einen zweiten API-Aufruf. Nutzen Sie GET /v1/play/:session_id/:track_id, um weitere Tracks bei Bedarf abzurufen.
/v1/play_session/:play_session_id Ruft Details einer Wiedergabesession ab
Parameter
| Name | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
play_session_id | uuid | Erforderlich | Die ID der Wiedergabesession (Pfadparameter) |
Beispielanfrage
curl -X GET "https://api.audiodelivery.net/v1/play_session/SESSION_ID" \
-H "Authorization: Bearer YOUR_API_KEY" Antwort
{
"ok": true,
"play_session_id": "uuid",
"play_session": {
"id": "uuid",
"creator_id": "uuid | null",
"variants": ["string"],
"is_downloadable": false,
"expires_at": "string"
},
"tracks": [
{ "id": "uuid", "index": "string", "duration": 0, "order": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null" }
],
"first_track": {
"track_id": "uuid",
"cover_image": { "icon": {}, "small": {}, "regular": {} },
"track": { "id": "uuid", "index": "string", "duration": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null", "theme": [], "file_name": "string", "info": {}, "organization_index": "string | null", "order": 0, "metadata": {}, "is_dark": false },
"levels": { "levels": [] },
"variants": [ { "path": "string", "url": "string", "variant": { "index": "string" } } ]
}
} Das Feld first_track enthält die vollständigen Wiedergabedaten des ersten Tracks, damit Ihr Player sofort rendern kann, ohne einen zweiten API-Aufruf.
/v1/play/:play_session_id/:play_track_id Ruft Details eines bestimmten Tracks in einer Wiedergabesession ab. Keine Authentifizierung erforderlich — die Session-ID dient als Bearer-Token.
Parameter
| Name | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
play_session_id | uuid | Erforderlich | Die ID der Wiedergabesession (Pfadparameter) |
play_track_id | uuid | Erforderlich | Die ID des Tracks in der Session (Pfadparameter) |
Antwort
{
"ok": true,
"play_session_id": "uuid",
"track_id": "uuid",
"play_session": {
"id": "uuid",
"variants": ["string"],
"is_downloadable": false,
"expires_at": "string"
},
"cover_image": {
"icon": { "type": "icon", "width": 80, "height": 80, "url": "string" },
"small": { "type": "small", "width": 200, "height": 200, "url": "string" },
"regular": { "type": "regular", "width": 400, "height": 400, "url": "string" }
},
"track": {
"id": "uuid",
"index": "string",
"duration": 0,
"player_title": "string | null",
"player_subtitle": "string | null",
"player_color": "string | null",
"player_color_light": "string | null",
"player_color_dark": "string | null",
"theme": [],
"file_name": "string",
"info": {},
"organization_index": "string | null",
"order": 0,
"metadata": {},
"is_dark": false
},
"levels": { "levels": [ 0, 0.5, 1 ] },
"variants": [
{ "path": "string", "url": "string", "variant": { "index": "string" } }
]
} /v1/play/:play_session_id/:play_track_id/:variant_index/download Lädt eine bestimmte Variante eines Tracks herunter. Nur verfügbar, wenn das gespeicherte is_downloadable der Session true ist (d. h. der API-Key erlaubt Downloads und die Session hat sie angefordert); sonst 403. Keine Authentifizierung erforderlich.
Parameter
| Name | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
play_session_id | uuid | Erforderlich | Die ID der Wiedergabesession (Pfadparameter) |
play_track_id | uuid | Erforderlich | Die ID des Tracks in der Session (Pfadparameter) |
variant_index | string | Erforderlich | Der Index/die Kennung der herunterzuladenden Variante (Pfadparameter) |
Antwort
Gibt eine kurzlebige signierte Download-URL zurück (30 s). Der Antwortkörper ist JSON (nicht die Audiodatei); navigieren Sie zu download.url, um die Datei abzurufen. Die URL wird mit Content-Disposition: attachment ausgeliefert, damit der Browser die Datei speichert statt sie inline abzuspielen. Wenn die Session nicht downloadbar ist, gibt der Endpunkt 403 mit einer Fehlermeldung zurück.
{
"ok": true,
"play_session_id": "uuid",
"track_id": "uuid",
"download": {
"variant": "string",
"url": "string"
}
}