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.
- Signed Delivery — Sign URLs yourself and skip play sessions for public tracks.
Prefer to start from a working example? Browse the Examples — practical walkthroughs with HTTP requests, snippets, and live demos where they help.
Choose Your Integration Path
Five approaches, from a five-minute drop-in to full server control. Pick the one that fits your project.
Web
Fastest setupUse ADN web components with Client-Side API Keys. No backend required.
- Best for
- Prototypes, static sites, personal projects
- Setup
- 5 minutes
- Complexity
- Low
- Security
- Basic
Mobile
Native appsUse ADN's API with Client-Side API Keys from your iOS, Android, or Flutter app. Play and upload with native media elements.
- Best for
- iOS, Android, Flutter apps
- Setup
- 30 minutes
- Complexity
- Medium
- Security
- Basic
Server-Side
Maximum controlUse ADN's API directly to store tracks and manage playback. Build fully custom experiences without ADN components.
- Best for
- Custom platforms, enterprise, full API control
- Setup
- 1-2 hours
- Complexity
- Medium
- Security
- Maximum
Hybrid
API-provisioned componentsUse ADN's API server-to-server to provision upload and play sessions, then pass session IDs to ADN web components.
- Best for
- SaaS products, paywalled content, multi-tenant apps
- Setup
- 30 minutes
- Complexity
- Medium
- Security
- High
Signed Delivery
Fastest playbackSign delivery URLs on your own server with a URL Signing key. Skip play sessions entirely — no API round trip — for public tracks.
- Best for
- Public catalogs, previews, marketing sites
- Setup
- 1-2 hours
- Complexity
- High
- Security
- Public
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 an upload_session_id. A session can hold many tracks. Optionally include a nested track object on this request to also receive track_upload.upload_url (you can still add more tracks later); otherwise create tracks in step 2. |
| 2 | Create a track in the session | For each additional file (or for every file if you skipped the nested track on session create), make a separate request to POST /v1/upload/:upload_session_id/track. This returns the track_id and a per-track signed upload URL in track_upload.upload_url. The session ID authorizes this request, so no API key is required. |
| 3 | Upload file | The audio file is uploaded directly to storage with a PUT to track_upload.upload_url. Once the upload completes, processing begins automatically. |
| 4 | 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. |
| 5 | Variant processing | Each configured variant (transcodes, previews, analysis, waveform images/videos) is processed in parallel. The track status is set to processing. |
| 6 | Fallback processing | If a file is too large, too long, or hits resource limits during step 5, 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. |
| 7 | 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, and responses also include contrast-adjusted player_color_light and player_color_dark variants for light and dark backgrounds. |
| 8 | 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. |
| 9 | Webhook notification | If a webhook URL is configured on the organization, ADN sends a POST request when a track reaches a terminal outcome (ready, incomplete, error, or init_error) and when its full file set is complete — not on every transitional status. Use this to trigger downstream workflows like updating your database or notifying users. See the Track Processing webhook docs. |
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 reusable recipe that defines how ADN turns an uploaded file into a deliverable output—for example an AAC or MP3 transcode, a short preview clip, a waveform image or video, or audio-analysis data. You define a variant once and ADN applies it automatically to every upload. When a single track needs an extra output that isn’t part of your standard set, you can also add a track-specific variant after the fact.
Track File
The actual output produced by applying a variant to a track—the stored, deliverable file itself (for example the AAC audio, the preview clip, or the waveform image). A track has one track file per variant, returned as its files in the API. New track files can also be created after the fact, either by adding a new variant or by generating one for a single track.
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 (theme). 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.