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, wählen Sie den Pfad, der zu Ihrem Projekt passt:

Web — Nutzen Sie ADN-Webkomponenten. Kein Backend erforderlich.
Mobile — Native iOS-, Android- oder Flutter-Apps.
Server-Side — Volle API-Kontrolle von Ihrem Server aus.
Hybrid — Server-provisionierte Sessions mit Webkomponenten.
Signed Delivery — Signieren Sie URLs selbst und überspringen Sie Wiedergabesessions für öffentliche Tracks.

Lieber von einem funktionierenden Beispiel starten? Durchstöbern Sie die Beispiele — praktische Anleitungen mit HTTP-Requests, Snippets und Live-Demos, wo sie helfen.

Wählen Sie Ihren Integrationspfad

Fünf Ansätze — von einer Fünf-Minuten-Einbindung bis zur vollen Serverkontrolle. Wählen Sie den, der zu Ihrem Projekt passt.

Web

Schnellste Einrichtung

Nutzen Sie ADN-Webkomponenten mit Client-Side-API-Keys. Kein Backend erforderlich.

Ideal für: Prototypen, statische Sites, persönliche Projekte
Einrichtung: 5 Minuten
Komplexität: Low
Sicherheit: Basic

Leitfaden ansehen →

Mobile

Native Apps

Nutzen Sie die ADN-API mit Client-Side-API-Keys aus Ihrer iOS-, Android- oder Flutter-App. Wiedergabe und Upload mit nativen Medienelementen.

Ideal für: iOS-, Android-, Flutter-Apps
Einrichtung: 30 Minuten
Komplexität: Medium
Sicherheit: Basic

Leitfaden ansehen →

Server-Side

Maximale Kontrolle

Nutzen Sie die ADN-API direkt, um Tracks zu speichern und die Wiedergabe zu verwalten. Bauen Sie vollständig individuelle Erlebnisse ohne ADN-Komponenten.

Ideal für: Individuelle Plattformen, Enterprise, volle API-Kontrolle
Einrichtung: 1–2 Stunden
Komplexität: Medium
Sicherheit: Maximum

Leitfaden ansehen →

Hybrid

API-provisionierte Komponenten

Nutzen Sie die ADN-API Server-zu-Server, um Upload- und Wiedergabesessions zu provisionieren, und übergeben Sie die Session-IDs an ADN-Webkomponenten.

Ideal für: SaaS-Produkte, Paywall-Inhalte, Multi-Tenant-Apps
Einrichtung: 30 Minuten
Komplexität: Medium
Sicherheit: High

Leitfaden ansehen →

Signed Delivery

Schnellste Wiedergabe

Signieren Sie Delivery-URLs auf Ihrem eigenen Server mit einem URL-Signing-Key. Überspringen Sie Wiedergabesessions vollständig — kein API-Roundtrip — für öffentliche Tracks.

Ideal für: Öffentliche Kataloge, Previews, Marketing-Sites
Einrichtung: 1–2 Stunden
Komplexität: High
Sicherheit: Public

Leitfaden ansehen →

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