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.
/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
}' 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.
/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" 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.
/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" } }
]
} /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"
}
}