# AudioDN API Documentation > Welcome to the AudioDN API documentation. Learn how to manage audio collections, tracks, and playback sessions. Source: https://audiodeliverynetwork.com/docs/ --- # 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](https://account.audiodeliverynetwork.com/) — no code or API integration required. When you're ready to integrate, choose the path that fits your project: 1. [Web](/docs/integration/web) — Use ADN web components. No backend required. 2. [Mobile](/docs/integration/mobile) — Native iOS, Android, or Flutter apps. 3. [Server-Side](/docs/integration/server-side) — Full API control from your server. 4. [Hybrid](/docs/integration/hybrid) — Server-provisioned sessions with web components. 5. [Signed Delivery](/docs/integration/signed-delivery) — Sign URLs yourself and skip play sessions for public tracks. Prefer to start from a working example? Browse task-oriented [Recipes](/docs/recipes) — including two runnable projects (Next.js secure upload and a Cloudflare Worker signed-playback edge worker). ## 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 setup Use 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 View guide →](/docs/integration/web)[ ### Mobile Native apps Use 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 View guide →](/docs/integration/mobile)[ ### Server-Side Maximum control Use 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 High Security Maximum View guide →](/docs/integration/server-side)[ ### Hybrid API-provisioned components Use 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 View guide →](/docs/integration/hybrid)[ ### Signed Delivery Fastest playback Sign 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 20 minutes Complexity Medium Security Public View guide →](/docs/integration/signed-delivery) ## 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 — it does not return an upload URL on its own. | | 2 | Create a track in the session | For each file, 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/webhooks/track-processing) 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.