AudioDN-API-Dokumentation
Willkommen in der AudioDN-API-Dokumentation. Diese API ermöglicht Ihnen die Verwaltung von Audio-Sammlungen, Tracks und Wiedergabesessions.
Erste Schritte
Sie können Sammlungen und Tracks direkt über Ihr Konto-Dashboard verwalten — ohne Code oder API-Integration. Wenn Sie bereit zur Integration sind, behandeln Sie AudioDN als zwei unabhängige Aufgaben:
- Tracks hochladen — wer die Upload-Session erstellt, und ob Sie AudioDN-Komponenten oder eine eigene Oberfläche nutzen.
- Tracks abspielen und darauf zugreifen — Client-Side Player-Schlüssel, serverseitig erstellte Play-Sessions oder Signed Delivery ohne Play-Session.
Lieber zuerst eine nicht-technische Einführung? Starten Sie bei Get Started. Lieber ein funktionierendes Beispiel? Durchstöbern Sie die Examples.
Tracks hochladen
Client-Side Upload-Schlüssel, serverseitig erstellte Upload-Sessions, AudioDN Uploader/Recorder oder eine eigene Web- oder Native-Oberfläche.
Leitfaden ansehen →Tracks abspielen und darauf zugreifen
AudioDN Player, eigene Player, Server-Play-Sessions oder Signed Delivery ohne Play-Session.
Leitfaden ansehen →Siehe auch die Integrations-Übersicht für Credentials auf einen Blick.
Lebenszyklus des Track-Uploads
Wenn eine Datei zu AudioDN hochgeladen wird, durchläuft sie eine Reihe automatisierter Schritte, bevor sie zur Wiedergabe bereit ist. So läuft es hinter den Kulissen ab:
| Schritt | Phase | Was passiert |
|---|---|---|
| 1 | Upload-Session erstellen | Ihre App fordert über die API eine Upload-Session an (oder die Uploader-Komponente erledigt das automatisch mit einem Client-Side Upload-Key). Die API gibt eine upload_session_id zurück. Eine Session kann viele Tracks enthalten. Optional können Sie in dieser Anfrage ein verschachteltes track-Objekt mitsenden, um auch track_upload.upload_url zu erhalten (Sie können später weitere Tracks hinzufügen); andernfalls erstellen Sie Tracks in Schritt 2. |
| 2 | Track in der Session erstellen | Für jede weitere Datei (oder für jede Datei, wenn Sie das verschachtelte track bei der Session-Erstellung weggelassen haben) stellen Sie eine separate Anfrage an POST /v1/upload/:upload_session_id/track. Das liefert die track_id und eine track-spezifische signierte Upload-URL in track_upload.upload_url. Die Session-ID autorisiert diese Anfrage, daher ist kein API-Key erforderlich. |
| 3 | Datei hochladen | Die Audiodatei wird direkt in den Speicher mit einem PUT an track_upload.upload_url hochgeladen. Sobald der Upload abgeschlossen ist, beginnt die Verarbeitung automatisch. |
| 4 | Initialisierung | ADN analysiert die Datei, um Dauer, Codec-Info und Stream-Metadaten zu extrahieren. Eine Standard-Wellenform mit 320 Samples wird für den Player erzeugt. Die Originaldatei wird gespeichert, wenn die Variante Original Upload aktiviert ist. |
| 5 | Variantenverarbeitung | Jede konfigurierte Variante (Transcodes, Previews, Analyse, Wellenform-Bilder/-Videos) wird parallel verarbeitet. Der Track-Status wird auf processing gesetzt. |
| 6 | Fallback-Verarbeitung | Wenn eine Datei zu groß, zu lang ist oder während Schritt 5 an Ressourcenlimits stößt, wird der Job automatisch auf einem leistungsstärkeren Prozessor wiederholt. Der Track-Status wechselt zu fallback_processing. Diese Tracks können länger dauern, weil dedizierte Ressourcen erst starten müssen, bevor die Verarbeitung beginnt. Von Ihrer Seite ist keine Aktion nötig. |
| 7 | Coverbild & Farbextraktion | Wenn die Audiodatei eingebettetes Cover-Artwork enthält, extrahiert ADN es, lädt es in das Image-CDN hoch und scannt es auf eine Farbpalette. Die lebendigste Farbe wird automatisch als player_color für das Theming von Playern ausgewählt, und Antworten enthalten auch kontrastangepasste Varianten player_color_light und player_color_dark für helle und dunkle Hintergründe. |
| 8 | Track bereit | Sobald alle Varianten fertig sind, wird der Track-Status auf ready gesetzt (oder incomplete, wenn einige Varianten fehlgeschlagen sind, aber mindestens eine abspielbare Variante erfolgreich war). Der Track ist jetzt zur Wiedergabe verfügbar. |
| 9 | Webhook-Benachrichtigung | Wenn für die Organisation eine Webhook-URL konfiguriert ist, sendet ADN eine POST-Anfrage, wenn ein Track ein terminales Ergebnis erreicht (ready, incomplete, error oder init_error) und wenn sein vollständiger Dateisatz fertig ist — nicht bei jedem Übergangsstatus. Nutzen Sie das, um nachgelagerte Workflows wie das Aktualisieren Ihrer Datenbank oder das Benachrichtigen von Nutzern auszulösen. Siehe die Docs zum Track-Processing-Webhook. |
Glossar
Client
Eine Organisation oder Person, die Audio Delivery Network (AudioDN) nutzt, um Audioinhalte zu verwalten und bereitzustellen. Clients greifen über die API oder Webkomponenten auf die Plattform zu.
Creator
Ein Unterkonto unter einem Client. Steht typischerweise für einen einzelnen Content-Beitragenden, z. B. einen Künstler oder Podcaster. Wird für Nutzungsverfolgung, Zugriffskontrolle und Analysen auf granularem Niveau verwendet.
Collection
Ein logischer Container (ähnlich einem Ordner) zur Organisation eines oder mehrerer Tracks. Sammlungen helfen bei Upload, Wiedergabe und Anzeige in Playern.
Track
Eine einzelne Audiodatei, die zu AudioDN hochgeladen wurde. Tracks können Musik, Spoken Word, Podcasts oder jede andere Art von Audioinhalt sein.
Original (Upload)
Die exakte, unveränderte Audiodatei, die vom Client oder Creator beim Upload bereitgestellt wurde. Wird als Referenz und für spätere Variantenerzeugung gespeichert.
Variant
Ein wiederverwendbares Rezept, das definiert, wie ADN eine hochgeladene Datei in eine lieferbare Ausgabe verwandelt — z. B. ein AAC- oder MP3-Transcode, ein kurzer Preview-Clip, ein Wellenform-Bild oder -Video oder Audioanalyse-Daten. Sie definieren eine Variante einmal, und ADN wendet sie automatisch auf jeden Upload an. Wenn ein einzelner Track eine zusätzliche Ausgabe braucht, die nicht zu Ihrem Standardset gehört, können Sie nachträglich auch eine track-spezifische Variante hinzufügen.
Track File
Die tatsächliche Ausgabe, die durch Anwenden einer Variante auf einen Track entsteht — die gespeicherte, lieferbare Datei selbst (z. B. das AAC-Audio, der Preview-Clip oder das Wellenform-Bild). Ein Track hat eine Track-Datei pro Variante, die in der API als seine files zurückgegeben wird. Neue Track-Dateien können auch nachträglich erstellt werden, entweder durch Hinzufügen einer neuen Variante oder durch Erzeugen einer für einen einzelnen Track.
Cover Image / Cover Art
Ein optionales Bild, das einem Track, einer Sammlung oder einem Client-Konto zugeordnet ist. Wird im Player angezeigt und für ästhetisches Theming verwendet.
Image Colors
Eine Farbpalette, die automatisch aus einem Coverbild extrahiert wird (theme). Wird zum Stylen von Playern und anderen Komponenten verwendet.
Color
Die primäre Akzentfarbe, die in der Player- und Uploader-UI angezeigt wird. Wird automatisch aus den Bildfarben ausgewählt oder manuell über die API gesetzt.
Player (Component)
Eine anpassbare, einbettbare Webkomponente, die Tracks und Sammlungen abspielt. Für einfache Integration in Websites und Apps konzipiert.
Uploader (Component)
Eine anpassbare Webkomponente, mit der Nutzer Audiodateien in Sammlungen hochladen können. Unterstützt Track-Metadaten und Coverbilder.