Core Concepts
These building blocks appear across the dashboard, APIs, web components, and webhooks.
Compatibility note
Output presets were previously called variants. Track outputs were previously called track files. Some API fields, webhook event names, and legacy routes still use those historical names.
The object model
Organization (Client)
The AudioDN customer account. Product language sometimes says Client; the API object is
organization / organization_id.
Creator
A sub-account under an organization — typically an artist, podcaster, or contributor — used for access control and usage tracking.
Collection
A folder-like container for tracks. Collections are the multi-track scope you can play today. A separate playlist scope is reserved for a future release and is not available yet.
Track
One uploaded audio file plus its metadata, status, and processing results.
Source file / original upload
The exact bytes the uploader sent. Retention is controlled by the reserved original-upload setting
(type id original), not by configuring a normal transcode preset. See
Original Upload.
Output presets and outputs
You configure output presets once for the organization (or add one to a single track). When a track is uploaded, AudioDN runs those presets and stores each result as an output on that track.
One upload → many outputs
Track
episode.wav
Your output presets
- hq — MP3 320 kbps
- lq — AAC 96 kbps
- transcript — Transcription
Outputs on that track
- hq MP3 file
- lq AAC file
- WebVTT caption file (+ plain text on the track)
Each preset is one recipe. Each output is that recipe applied to this track.
A preset’s kind of work (transcode, preview, transcription, and so on) is its
output type — useful when browsing the catalog, but day to day you configure and request
presets by their delivery index (for example hq), and you consume
outputs on the track.
Play-session JSON still returns deliverable outputs under the historical variants key.
Configure presets in the dashboard or via the Output Presets API.
Browse the catalog on Output Presets.
Track lifecycle
When a file is uploaded, AudioDN moves it through these stages:
| Step | Stage | What happens |
|---|---|---|
| 1 | Create upload session | Your app (or the Uploader / Recorder) requests an upload session. Optionally include a nested track object to also receive track_upload.upload_url for the first file. |
| 2 | Register each track | POST /v1/upload/:upload_session_id/track returns track_id and a per-track signed upload URL. The session ID authorizes this request — no API key is required. |
| 3 | Upload file bytes | PUT the audio to track_upload.upload_url. Processing begins after the upload completes. |
| 4 | Initialization | AudioDN probes the file, extracts duration and codec info, generates a free 320-sample waveform for the player, and saves the original upload when retention is enabled. |
| 5 | Output processing | Configured output presets run (often in parallel). Status moves through processing, and sometimes fallback / fallback_processing for large or resource-heavy jobs. |
| 6 | Playback-ready | When required presets succeed and a playable transcode or original file exists, status becomes ready. Optional outputs (including transcription) may still be running. |
| 7 | All outputs attempted | files_completed_at is stamped when every configured preset has been attempted. Status may already be ready; AudioDN does not downgrade a ready track. |
| 8 | Webhooks | Track Processing notifies on terminal outcomes and when the full file set completes. The Output webhook notifies as each individual output succeeds or fails. See Track Processing. |
ready is playback-ready, not fully finished
ready means a required playable output succeeded. It does not mean every output — including optional transcription — has finished.
Use files_completed_at, the Output webhook, or GET /v1/track/:id/processing when you need per-output completion.
Track statuses
| Status | Terminal | Meaning |
|---|---|---|
| initialized | No | Track record created; waiting for upload / init. |
| processing | No | Configured outputs are being generated. |
| fallback | No | Queued for a higher-capacity processor. |
| fallback_processing | No | Fallback processor is actively working. |
| ready | Yes* | Required playable output succeeded. Optional outputs may still run until files_completed_at is set. |
| incomplete | Yes* | A playable file exists, but a required preset did not succeed at final settle. The track may still be playable. |
| error | Yes | No playable file could be produced. |
| init_error | Yes | Initialization failed (invalid or unreadable upload). |
*Status no longer changes after ready or incomplete, but files_completed_at can still be stamped later and can trigger a second Track Processing webhook.
Next steps
- Output Presets — recipes for what to generate from each upload
- Integrations — choose Web Components, REST, MCP, or webhooks
- Uploading audio — end-to-end upload flows
- Track Processing webhook — async notifications