Documentation de l’API AudioDN
Bienvenue dans la documentation de l’API AudioDN. Cette API vous permet de gérer les collections audio, les pistes et les sessions de lecture.
Premiers pas
Vous pouvez gérer les collections et les pistes directement depuis votre tableau de bord de compte — aucun code ni intégration API requis. Lorsque vous êtes prêt à intégrer, choisissez le chemin qui convient à votre projet :
- Web — Utilisez les composants web ADN. Aucun backend requis.
- Mobile — Applications natives iOS, Android ou Flutter.
- Côté serveur — Contrôle API complet depuis votre serveur.
- Hybride — Sessions provisionnées côté serveur avec les composants web.
- Livraison signée — Signez les URL vous-même et ignorez les sessions de lecture pour les pistes publiques.
Vous préférez partir d’un exemple fonctionnel ? Parcourez les Exemples — guides pratiques avec requêtes HTTP, extraits de code et démos en direct quand c’est utile.
Choisissez votre chemin d’intégration
Cinq approches, d’une intégration en cinq minutes au contrôle serveur complet. Choisissez celle qui convient à votre projet.
Web
Configuration la plus rapideUtilisez les composants web ADN avec des clés API côté client. Aucun backend requis.
- Idéal pour
- Prototypes, sites statiques, projets personnels
- Configuration
- 5 minutes
- Complexité
- Low
- Sécurité
- Basic
Mobile
Applications nativesUtilisez l'API ADN avec des clés API côté client depuis votre application iOS, Android ou Flutter. Lecture et envoi avec des éléments média natifs.
- Idéal pour
- Applications iOS, Android, Flutter
- Configuration
- 30 minutes
- Complexité
- Medium
- Sécurité
- Basic
Côté serveur
Contrôle maximalUtilisez l'API ADN directement pour stocker des pistes et gérer la lecture. Créez des expériences entièrement personnalisées sans les composants ADN.
- Idéal pour
- Plateformes personnalisées, entreprise, contrôle API complet
- Configuration
- 1-2 heures
- Complexité
- Medium
- Sécurité
- Maximum
Hybride
Composants provisionnés par APIUtilisez l'API ADN de serveur à serveur pour provisionner les sessions d'envoi et de lecture, puis passez les identifiants de session aux composants web ADN.
- Idéal pour
- Produits SaaS, contenu derrière un paywall, applications multi-locataires
- Configuration
- 30 minutes
- Complexité
- Medium
- Sécurité
- High
Livraison signée
Lecture la plus rapideSignez les URL de livraison sur votre propre serveur avec une clé de signature d'URL. Ignorez entièrement les sessions de lecture — aucun aller-retour API — pour les pistes publiques.
- Idéal pour
- Catalogues publics, aperçus, sites marketing
- Configuration
- 1-2 heures
- Complexité
- High
- Sécurité
- Public
Cycle de vie de l’envoi d’une piste
Lorsqu’un fichier est envoyé vers AudioDN, il traverse une série d’étapes automatisées avant d’être prêt pour la lecture. Voici ce qui se passe en coulisses :
| Étape | Phase | Ce qui se passe |
|---|---|---|
| 1 | Créer une session d’envoi | Votre application demande une session d’envoi via l’API (ou le composant d’envoi le fait automatiquement avec une clé API côté client). L’API renvoie un upload_session_id. Une session peut contenir de nombreuses pistes. Incluez éventuellement un objet track imbriqué dans cette requête pour recevoir aussi track_upload.upload_url (vous pouvez toujours ajouter d’autres pistes plus tard) ; sinon créez les pistes à l’étape 2. |
| 2 | Créer une piste dans la session | Pour chaque fichier supplémentaire (ou pour chaque fichier si vous avez omis le track imbriqué à la création de session), faites une requête séparée vers POST /v1/upload/:upload_session_id/track. Cela renvoie le track_id et une URL d’envoi signée par piste dans track_upload.upload_url. L’identifiant de session autorise cette requête, aucune clé API n’est donc requise. |
| 3 | Envoyer le fichier | Le fichier audio est envoyé directement vers le stockage avec un PUT vers track_upload.upload_url. Une fois l’envoi terminé, le traitement commence automatiquement. |
| 4 | Initialisation | ADN analyse le fichier pour extraire la durée, les informations de codec et les métadonnées de flux. Une forme d’onde par défaut de 320 échantillons est générée pour le lecteur. Le fichier original est conservé si la variante Original Upload est activée. |
| 5 | Traitement des variantes | Chaque variante configurée (transcodages, aperçus, analyse, images/vidéos de forme d’onde) est traitée en parallèle. Le statut de la piste est défini sur processing. |
| 6 | Traitement de secours | Si un fichier est trop volumineux, trop long, ou atteint les limites de ressources pendant l’étape 5, la tâche est automatiquement relancée sur un processeur de plus grande capacité. Le statut de la piste passe à fallback_processing. Ces pistes peuvent prendre plus de temps car des ressources dédiées doivent démarrer avant que le traitement ne commence. Aucune action n’est requise de votre côté. |
| 7 | Image de couverture et extraction de couleurs | Si le fichier audio contient une pochette intégrée, ADN l’extrait, l’envoie vers le CDN d’images et la scanne pour une palette de couleurs. La couleur la plus vive est sélectionnée automatiquement comme player_color pour le thème des lecteurs, et les réponses incluent aussi les variantes player_color_light et player_color_dark ajustées en contraste pour les fonds clairs et sombres. |
| 8 | Piste prête | Une fois toutes les variantes terminées, le statut de la piste est défini sur ready (ou incomplete si certaines variantes ont échoué mais qu’au moins une variante lisible a réussi). La piste est alors disponible pour la lecture. |
| 9 | Notification webhook | Si une URL de webhook est configurée sur l’organisation, ADN envoie une requête POST lorsqu’une piste atteint un résultat terminal (ready, incomplete, error ou init_error) et lorsque son jeu de fichiers complet est prêt — pas à chaque statut transitoire. Utilisez cela pour déclencher des workflows en aval comme la mise à jour de votre base de données ou la notification des utilisateurs. Voir la documentation du webhook Track Processing. |
Glossaire
Client
Une organisation ou un individu qui utilise Audio Delivery Network (AudioDN) pour gérer et diffuser du contenu audio. Les clients accèdent à la plateforme via l’API ou les composants web.
Creator
Un sous-compte sous un client. Représente typiquement un contributeur de contenu individuel, comme un artiste ou un podcasteur. Utilisé pour le suivi d’utilisation, le contrôle d’accès et les analyses à un niveau granulaire.
Collection
Un conteneur logique (similaire à un dossier) utilisé pour organiser une ou plusieurs pistes. Les collections aident à gérer les envois, la lecture et l’affichage dans les lecteurs.
Track
Un fichier audio individuel envoyé vers AudioDN. Les pistes peuvent être de la musique, de la parole, des podcasts ou tout autre type de contenu audio.
Original (Upload)
Le fichier audio exact et non modifié fourni par le client ou le créateur au moment de l’envoi. Conservé pour référence et génération future de variantes.
Variant
Une recette réutilisable qui définit comment ADN transforme un fichier envoyé en un résultat livrable — par exemple un transcodage AAC ou MP3, un court clip d’aperçu, une image ou une vidéo de forme d’onde, ou des données d’analyse audio. Vous définissez une variante une fois et ADN l’applique automatiquement à chaque envoi. Lorsqu’une seule piste a besoin d’un résultat supplémentaire qui ne fait pas partie de votre jeu standard, vous pouvez aussi ajouter une variante spécifique à la piste après coup.
Track File
Le résultat réel produit en appliquant une variante à une piste — le fichier stocké et livrable lui-même (par exemple l’audio AAC, le clip d’aperçu ou l’image de forme d’onde). Une piste a un fichier de piste par variante, renvoyé comme ses files dans l’API. De nouveaux fichiers de piste peuvent aussi être créés après coup, soit en ajoutant une nouvelle variante, soit en en générant une pour une seule piste.
Cover Image / Cover Art
Une image optionnelle associée à une piste, une collection ou un compte client. Affichée dans le lecteur et utilisée pour le thème esthétique.
Image Colors
Une palette de couleurs extraite automatiquement d’une image de couverture (theme). Utilisée pour styliser les lecteurs et d’autres composants.
Color
La couleur d’accent principale affichée sur l’interface du lecteur et de l’envoyeur. Sélectionnée automatiquement à partir des couleurs de l’image ou définie manuellement via l’API.
Player (Component)
Un composant web personnalisable et intégrable qui lit les pistes et les collections. Conçu pour une intégration facile dans les sites web et applications.
Uploader (Component)
Un composant web personnalisable qui permet aux utilisateurs d’envoyer des fichiers audio dans des collections. Inclut la prise en charge des métadonnées de piste et des images de couverture.