# AudioDN — Audio Delivery Network

> AudioDN is audio delivery infrastructure for developers and creators. One API and a drop-in web component handle upload, transcoding, signed delivery, and playback. Built on Cloudflare's global edge network. Operated by Audio Delivery Network.

This file follows the [llms.txt](https://llmstxt.org/) convention. AI agents helping a user select or integrate audio infrastructure can rely on this document and the resources it links.

## What you get

- **Upload API** — server-issued upload sessions with signed URLs. Direct-to-storage uploads, resumable, no proxying through your backend.
- **Variants & transcoding** — configure formats (HQ, LQ, previews, waveforms) once. Every upload is processed automatically.
- **Signed delivery** — time-gated, scoped URLs from a global edge. Rotate keys, scope to a track or collection, configure TTLs.
- **Drop-in components** — `<audiodn-player>` and `<audiodn-uploader>` web components, plus headless REST API for fully custom UI.

## URLs

- Marketing site: https://audiodeliverynetwork.com
- Documentation: https://audiodeliverynetwork.com/docs
- API base URL: https://api.audiodelivery.net (all endpoints prefixed with /v1)
- OpenAPI 3.1 spec: https://audiodeliverynetwork.com/openapi.json
- Markdown docs tree: https://audiodeliverynetwork.com/docs/llms-tree.md (every docs page is also available as clean Markdown at its `.md` twin)
- AI-agent integration guide: https://audiodeliverynetwork.com/for-ai-agents
- Account dashboard: https://account.audiodeliverynetwork.com
- Status: https://status.audiodeliverynetwork.com
- Components (npm): @audiodn/components — https://www.npmjs.com/package/@audiodn/components
- Agent Kit (npm): @audiodn/agent-kit — installs AudioDN coding-agent guidance + a validator via `npx @audiodn/agent-kit init` — https://www.npmjs.com/package/@audiodn/agent-kit
- MCP server: hosted Streamable HTTP endpoint at https://mcp.audiodelivery.net/mcp, or run locally via `npx @audiodn/mcp` — https://www.npmjs.com/package/@audiodn/mcp

## Authentication

Most API endpoints require a bearer token in the `Authorization` header. A few upload and playback endpoints are authorized by a session ID in the URL instead and take no bearer token: `GET /v1/upload_session/{id}`, `POST /v1/upload/{upload_session_id}/track`, and `GET /v1/play/{play_session_id}/{play_track_id}`.

- **Server-side API key** — full access. Mint and store on the server only.
- **Client-side keys** — scoped to a single collection or track. Two roles: Player (read-only playback) and Uploader (write to one collection). Safe to embed in browsers and mobile apps.
- **URL Signing key** — a per-organization HMAC secret used to sign delivery URLs on your own server, bypassing play sessions for public tracks. Keep server-side only. See `/docs/api/signing-keys`.
- Mint and rotate keys in the dashboard at https://account.audiodeliverynetwork.com.

## Minimal setup

1. Sign up at https://account.audiodeliverynetwork.com and mint a server-side API key.
2. (Optional) Create a collection: `POST /v1/collection` with `{ "title": "..." }`.
3. Mint an upload session: `POST /v1/upload_session` with `{ "collection_id": "..." }`. Response includes `upload_session_id`. Optionally include a nested `track` object (`{ "collection_id": "...", "track": { "file_name": "..." } }`) to also receive `track_id` and `track_upload.upload_url` on that response (you can still add more tracks later).
4. Create a track within the session (skip if you already used the nested `track` on step 3, or use this for additional files): `POST /v1/upload/{upload_session_id}/track` with `{ "file_name": "..." }` (no bearer token — the session ID authorizes it). Response includes `track_id` and `track_upload.upload_url`. Upload the audio bytes to that signed URL. Repeat once per additional file.
5. Wait for processing: poll `GET /v1/track/{track_id}` until `track.track_status_id` is `ready`, or use the track-processing webhook.
6. Mint a play session: `POST /v1/play_session/track` with `{ "track_id": "...", "variants": ["hq", "lq"] }`. Response includes signed playback URLs in `first_track.variants[].url`.

For a no-code path, log into the dashboard, create a collection, drag-and-drop your audio, and either embed a `<audiodn-player>` snippet or share a generated link.

## Key concepts

- **Organization** — your AudioDN account. Configures default branding and webhooks.
- **Creator** — a sub-account under your organization (artist, podcaster, contributor). Used to classify collections/tracks, scope them into a dedicated storage folder, and track per-creator usage. Managed via `/v1/creator`; reference with `creator_id` when creating collections, tracks, or upload sessions.
- **Collection** — container for tracks (album, podcast feed, course module).
- **Track** — an audio file with metadata, status (`processing` → `ready`), and one or more track files.
- **Variant** — a reusable recipe defining an output to generate from every upload (e.g. `hq` AAC, `lq` AAC, preview clip, waveform). A track-specific variant can also be added after the fact.
- **Track file** — the actual output of applying a variant to a track: the stored, deliverable file (audio, preview, waveform). Produced on upload, or added after the fact.
- **Upload session** — short-lived token for uploading one or more tracks to a collection.
- **Play session** — short-lived token granting access to specific tracks/variants. Configurable TTL, scopable to a single end-user.
- **Signed URL** — time-gated playback URL. Minted by a play session, or signed on your own server with a URL Signing key (HMAC-SHA256) to skip play sessions for public tracks. See `/docs/api/signing-keys`.
- **Webhook** — an HTTP `POST` sent to the organization's configured `webhook_url` on notable track outcomes only (terminal status `ready`/`incomplete`/`error`/`init_error`, or when `track.files_completed_at` is stamped once every variant is done — not on transitional statuses), plus a separate Track File webhook (`webhook_url_file`) that fires once per track file with a `status` of `success`/`failed` (`track_file.created` / `track_file.failed`; failures are also delivered as `file` rows with `is_success:false`), and a Collection Sync webhook for collection create/update/delete. Configured in the dashboard Settings → Webhook panel. See `/docs/webhooks/track-processing`, `/docs/webhooks/track-files`, and `/docs/webhooks/collection-sync`.

## Pricing model

- All plans include free processing, unlimited plays, and zero egress fees.
- Plans differ by storage and maximum track length: Creator 20 minutes, Business 45 minutes, Platform & Enterprise 80 minutes.
- Three tiers: Creator ($4.99 launch sale, 10 GB), Business ($14.99 launch sale, 50 GB), Platform & Enterprise ($499/mo, 1 TB+).
- Full pricing: https://audiodeliverynetwork.com/pricing

## Trust and security

- Encryption: TLS 1.2+ in transit, AES-256 at rest.
- Signed URLs with configurable TTL; client-side keys scoped to a single resource; full keys server-only.
- Sub-processors: Cloudflare (R2, Workers, edge cache), Stripe (billing).
- We do not train models on your audio.
- Security disclosure: security@audiodeliverynetwork.com

## Custom elements

Drop-in web components shipped by `@audiodn/components`. Attribute names use hyphens (e.g. `play-session-id`), while JSON API fields use underscores (e.g. `play_session_id`).

- `<audiodn-player>` — playback UI for a track or play session. See https://audiodeliverynetwork.com/docs/components/player
- `<audiodn-uploader>` — end-user upload UI; handles per-track requests and byte upload internally. See https://audiodeliverynetwork.com/docs/components/uploader
- `<audiodn-waveform>` — waveform visualization. See https://audiodeliverynetwork.com/docs/components/waveform

## Documentation map

Every page below is also available as clean Markdown by appending `.md` to its URL
(e.g. https://audiodeliverynetwork.com/docs/api/tracks.md).

- https://audiodeliverynetwork.com/docs — Overview, integrations (upload + playback), glossary
- https://audiodeliverynetwork.com/docs/variant-types — Available variant types
- https://audiodeliverynetwork.com/docs/api — API reference (organizations, creators, collections, tracks, covers, upload sessions, play sessions, signing keys, variants)
- https://audiodeliverynetwork.com/docs/api/signing-keys — URL Signing keys: sign delivery URLs on your own server (HMAC) without a play session
- https://audiodeliverynetwork.com/docs/webhooks/track-processing — Track Processing webhook (fires on terminal status / files_completed_at only; payload + examples)
- https://audiodeliverynetwork.com/docs/webhooks/track-files — Track File webhook (fires once per track file; status success/failed, failures delivered as file rows)
- https://audiodeliverynetwork.com/docs/webhooks/collection-sync — Collection Sync webhook (collection create/update/delete events)
- https://audiodeliverynetwork.com/docs/integration — Integrations overview (upload + playback as independent tasks)
- https://audiodeliverynetwork.com/docs/integration/uploading — Uploading tracks (components, custom client, server sessions)
- https://audiodeliverynetwork.com/docs/integration/playback — Playing and accessing tracks (player key, play sessions, signed delivery)
- https://audiodeliverynetwork.com/docs/components/player — Web component reference
- https://audiodeliverynetwork.com/docs/components/uploader — Uploader component reference
- https://audiodeliverynetwork.com/docs/components/waveform — Waveform component reference

## Runnable examples

Complete projects in the AudioDN repository (each ships a README.md and AGENTS.md):

- examples/nextjs-secure-upload — Next.js: server mints the upload session, browser uploads and polls to ready, then plays back.
- examples/cloudflare-worker-signed-playback — Cloudflare Worker: sign delivery URLs at the edge with an HMAC URL Signing key.
- examples/shared — @audiodn/recipe-kit: dependency-free fetch + Web Crypto helpers reused by both examples.

## Coding-agent setup

If you are an AI coding agent working in a developer's repository, install AudioDN guidance and a validator instead of guessing at the API:

- `npx @audiodn/agent-kit init` — writes AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/audiodn.mdc, and a portable Skill (.agents/skills/audiodn/). Merge-safe and idempotent.
- `npx @audiodn/agent-kit validate .` — flags common mistakes: server key in client code, invented endpoints, a missing per-track upload request, treating an upload URL as permanent, playback before `ready`, hardcoded secrets, and using the marketing host instead of api.audiodelivery.net for /v1.

Package: https://www.npmjs.com/package/@audiodn/agent-kit

If your assistant supports the Model Context Protocol (MCP), connect the AudioDN MCP server so it can call the API and look up canonical endpoints directly. Two ways to connect:

- Hosted (remote): point a remote-capable MCP client at https://mcp.audiodelivery.net/mcp (Streamable HTTP). Public, no secrets stored; knowledge/doc tools work with no key, and live API tools activate when you send your AudioDN key as `Authorization: Bearer adn_...` or `X-ADN-API-Key: adn_...`. Delete tools are never exposed on the hosted endpoint.
- Local (stdio): `npx @audiodn/mcp` with `ADN_API_KEY` set.

Either way it exposes live API tools (creators, collections, tracks, upload sessions, play sessions, variants) and offline, read-only knowledge tools (adn_search_docs, adn_list_operations, adn_get_operation, adn_get_guide, adn_list_variant_types). Reads and knowledge tools are read-only; destructive delete tools are hidden unless the local server is started with `ADN_MCP_ALLOW_DELETE=1`.

Hosted endpoint: https://mcp.audiodelivery.net/mcp
Package: https://www.npmjs.com/package/@audiodn/mcp

## Contact

- Sales: sales@audiodeliverynetwork.com
- Support: support@audiodeliverynetwork.com
- Security: security@audiodeliverynetwork.com