# Sessions de lecture | Docs AudioDN

> Points de terminaison API pour créer des sessions de lecture audio sécurisées. Contrôlez l

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

---

# Sessions de lecture

Les sessions de lecture gèrent la lecture audio pour les collections, pistes ou playlists.

Le `player_color` résolu de chaque piste est accompagné de deux compagnons en lecture seule : `player_color_light` (ajusté pour rester lisible sur un fond clair) et `player_color_dark` (ajusté pour un fond sombre), afin que votre lecteur puisse choisir le bon pour son thème.

POST `/v1/play_session/:scope`

Crée une nouvelle session de lecture pour une collection ou une piste.

#### Paramètres

| Nom | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `scope` | string | Obligatoire | "collection" ou "track" (paramètre de chemin). "playlist" est réservé à une version future et renvoie actuellement 400. |
| `variants` | array of strings | Obligatoire | Liste non vide d'index de variantes pour la session de lecture (par ex. \["hq", "lq"\]). |
| `collection_id` | uuid | Obligatoire | Identifiant de la collection lorsque scope est "collection". Requis sauf si la clé API est limitée à une collection. |
| `track_id` | uuid | Obligatoire | Identifiant de la piste lorsque scope est "track". Requis sauf si la clé API est limitée à une piste. |
| `is_downloadable` | boolean | Facultatif | Demande que les pistes de cette session soient téléchargeables. Ceci n'est honoré que lorsque la clé API autorise aussi les téléchargements (défini par clé dans le tableau de bord). La valeur stockée de la session est api\_key.is\_downloadable AND cette requête, donc une clé qui interdit les téléchargements l'emporte toujours — le point de terminaison de téléchargement renverra 403. |
| `expires_in` | number | Facultatif | Durée de la session en secondes (par défaut : 3600, min : 60, max : 86400) |

#### Exemple de requête

    

```
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>;
}
```

#### Réponse

```
{
"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"
}
```

Le champ `first_track` inclut les données de lecture complètes de la première piste (URL de streaming signées, niveaux de forme d’onde, image de couverture et variantes) afin que votre lecteur puisse s’afficher immédiatement sans un second appel API. Utilisez `GET /v1/play/:session_id/:track_id` pour récupérer des pistes supplémentaires à la demande.

GET `/v1/play_session/:play_session_id`

Récupère les détails d'une session de lecture

#### Paramètres

| Nom | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `play_session_id` | uuid | Obligatoire | L'identifiant de la session de lecture (paramètre de chemin) |

#### Exemple de requête

    

```
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>;
}
```

#### Réponse

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

Le champ `first_track` inclut les données de lecture complètes de la première piste afin que votre lecteur puisse s’afficher immédiatement sans un second appel API.

GET `/v1/play/:play_session_id/:play_track_id`

Récupère les détails d'une piste spécifique dans une session de lecture. Aucune authentification requise - l'identifiant de session sert de jeton bearer.

#### Paramètres

| Nom | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `play_session_id` | uuid | Obligatoire | L'identifiant de la session de lecture (paramètre de chemin) |
| `play_track_id` | uuid | Obligatoire | L'identifiant de la piste dans la session (paramètre de chemin) |

#### Réponse

```
{
"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`

Télécharge une variante spécifique d'une piste. Disponible uniquement lorsque le is\_downloadable stocké de la session est true (c.-à-d. que la clé API autorise les téléchargements et que la session les a demandés) ; sinon renvoie 403. Aucune authentification requise.

#### Paramètres

| Nom | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `play_session_id` | uuid | Obligatoire | L'identifiant de la session de lecture (paramètre de chemin) |
| `play_track_id` | uuid | Obligatoire | L'identifiant de la piste dans la session (paramètre de chemin) |
| `variant_index` | string | Obligatoire | L'index/identifiant de la variante à télécharger (paramètre de chemin) |

#### Réponse

Renvoie une URL de téléchargement signée de courte durée (30 s). Le corps de la réponse est du JSON (pas le fichier audio) ; naviguez vers `download.url` pour récupérer le fichier. L’URL est servie avec `Content-Disposition: attachment` pour que le navigateur enregistre le fichier au lieu de le lire en ligne. Si la session n’est pas téléchargeable, le point de terminaison renvoie `403` avec un message d’erreur.

```
{
"ok": true,
"play_session_id": "uuid",
"track_id": "uuid",
"download": {
  "variant": "string",
  "url": "string"
}
}
```