AudioDN API Documentation
Welcome to the AudioDN API documentation. This API allows you to manage audio collections, tracks, and playback sessions.
Getting Started
You can manage collections and tracks directly from your account dashboard — no code or API integration required. When you're ready to integrate, choose the path that fits your project:
- Web — Use ADN web components. No backend required.
- Mobile — Native iOS, Android, or Flutter apps.
- Server-Side — Full API control from your server.
- Hybrid — Server-provisioned sessions with web components.
Choose Your Integration Path
Compare the four approaches to find the best fit for your project.
| Web Fastest setup | Mobile Native apps | Server-Side Maximum control | Hybrid API-provisioned components | |
|---|---|---|---|---|
| Description | Use ADN web components with Client-Side API Keys. No backend required. | Use ADN's API with Client-Side API Keys from your iOS, Android, or Flutter app. Play and upload with native media elements. | Use ADN's API directly to store tracks and manage playback. Build fully custom experiences without ADN components. | Use ADN's API server-to-server to provision upload and play sessions, then pass session IDs to ADN web components. |
| Best For | Prototypes, static sites, personal projects | iOS, Android, Flutter apps | Custom platforms, enterprise, full API control | SaaS products, paywalled content, multi-tenant apps |
| Complexity | Low | Medium | High | Medium |
| Security | Basic | Basic | Maximum | High |
| Setup Time | 5 minutes | 30 minutes | 1-2 hours | 30 minutes |
| View Guide → | View Guide → | View Guide → | View Guide → |
Track Upload Lifecycle
When a file is uploaded to AudioDN, it moves through a series of automated steps before it's ready for playback. Here's what happens behind the scenes:
| Step | Stage | What happens |
|---|---|---|
| 1 | Create upload session | Your app requests an upload session via the API (or the uploader component does it automatically with a Client-Side API key). The API returns a signed upload URL and a session ID. |
| 2 | Upload file | The audio file is uploaded directly to storage using the signed URL. Once the upload completes, processing begins automatically. |
| 3 | Initialization | ADN probes the file to extract duration, codec info, and stream metadata. A default 320-sample waveform is generated for the player. The original file is saved if the Original Upload variant is enabled. |
| 4 | Variant processing | Each configured variant (transcodes, previews, analysis, waveform images/videos) is processed in parallel. The track status is set to processing. |
| 5 | Fallback processing | If a file is too large, too long, or hits resource limits during step 4, the job is automatically retried on a higher-capacity processor. The track status changes to fallback_processing. These tracks can take longer because dedicated resources need to spin up before processing begins. No action is needed from your side. |
| 6 | Cover image & color extraction | If the audio file contains embedded cover art, ADN extracts it, uploads it to the image CDN, and scans it for a color palette. The most vibrant color is auto-selected as the player_color for theming players. |
| 7 | Track ready | Once all variants finish, the track status is set to ready (or incomplete if some variants failed but at least one playable variant succeeded). The track is now available for playback. |
| 8 | Webhook notification | If a webhook URL is configured on the organization, ADN sends a POST request with the track ID, status, variant details, and metadata. Use this to trigger downstream workflows like updating your database or notifying users. |
Glossary
Client
An organization or individual that uses Audio Delivery Network (AudioDN) to manage and deliver audio content. Clients access the platform via API or web components.
Creator
A sub-account under a client. Typically represents an individual content contributor, such as an artist or podcaster. Used for tracking usage, access control, and analytics at a granular level.
Collection
A logical container (similar to a folder) used to organize one or more tracks. Collections help manage uploads, playback, and display in players.
Track
An individual audio file uploaded to AudioDN. Tracks can be music, spoken word, podcasts, or any other type of audio content.
Original (Upload)
The exact, unmodified audio file provided by the client or creator at upload time. Stored for reference and future variant generation.
Variant
A processed version of the original track. Variants are generated for specific use cases such as streaming optimization, compression, previews, or waveform generation.
Cover Image / Cover Art
An optional image associated with a track, collection, or client account. Displayed in the player and used for aesthetic theming.
Image Colors
A palette of colors automatically extracted from a cover image (image_colors). Used to style players and other components.
Color
The primary accent color shown on the player and uploader UI. Selected automatically from the image colors or set manually via API.
Player (Component)
A customizable, embeddable web component that plays tracks and collections. Designed for easy integration into websites and apps.
Uploader (Component)
A customizable web component that allows users to upload audio files into collections. Includes support for track metadata and cover images.