# Wiedergabesessions | AudioDN Docs

> API-Endpunkte zum Erstellen sicherer Audio-Wiedergabesessions. Steuern Sie den Zugriff auf Tracks, Sammlungen und Playlists mit zeitlich und thematisch begrenzten Wiedergabesessions.

Source: https://audiodeliverynetwork.com/de/docs/api/play-sessions/

---

# 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.

POST `/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
}'
```

```
const payload = {
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ],
  "expires_in": 3600
};

const response = await fetch('https://api.audiodelivery.net/v1/play_session/collection', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
```

```
import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/play_session/collection")!)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let bodyJSON = """
{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ],
  "expires_in": 3600
}
"""
    request.httpBody = bodyJSON.data(using: .utf8)
    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}
```

```
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val body = """{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ],
  "expires_in": 3600
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/play_session/collection")
        .post(body)
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}
```

```
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.post(
    Uri.parse("https://api.audiodelivery.net/v1/play_session/collection"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: jsonEncode({
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ],
  "expires_in": 3600
}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}
```

#### 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.

GET `/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"
```

```
const response = await fetch('https://api.audiodelivery.net/v1/play_session/SESSION_ID', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  }
});

const data = await response.json();
```

```
import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/play_session/SESSION_ID")!)
    request.httpMethod = "GET"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}
```

```
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/play_session/SESSION_ID")
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}
```

```
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.get(
    Uri.parse("https://api.audiodelivery.net/v1/play_session/SESSION_ID"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
    },
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}
```

#### 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.

GET `/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" } }
]
}
```

GET `/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"
}
}
```