Uploading tracks

Choose who creates or authorizes the upload session, then — if your server creates it — how files are transferred. Playback is a separate decision; see Playing and accessing tracks.

Per-file upload lifecycle

An upload session may authorize many files, but each file needs its own track and upload URL. Create the session, then for each file call POST /v1/upload/{upload_session_id}/track and PUT the bytes to track_upload.upload_url. Optionally include a nested track on session create for the first file. Full reference: Upload Sessions.

Uploading tracks

Choose who creates the upload session, then — if needed — how files are transferred. Upload and playback choices are independent.

Who should create or authorize the upload session?

AudioDN Uploader or (voice) Recorder web components Fastest setup. Drop-in web components with a scoped Client-Side Upload key; they handle session creation and file transfer. The (voice) Recorder captures from the microphone. Your browser or native application A scoped Client-Side Upload key. Your app creates the upload session and uploads each file to the provided URL. Your server An API Access key on your server. Your server applies application-specific authorization and creates a short-lived upload session.

How should the user transfer the files?

AudioDN Uploader or (voice) Recorder web components Pass the server-created upload session to the AudioDN Uploader or (voice) Recorder web components. Custom browser or native upload interface Use the provided upload information in your own upload UI.

AudioDN Uploader or (voice) Recorder web components with a Client-Side Upload key

Fastest setup. Drop-in web components with a scoped Client-Side Upload key; they create the session and upload each file. The (voice) Recorder captures from the microphone.

Create a Client-Side Upload key

In the dashboard go to Settings → API Keys and create a Client-Side Upload key. Optionally scope it to a collection. This key can only create upload sessions — not read or delete tracks.

Install the web component

npm install @audiodn/components

Uploader:

import '@audiodn/components/uploader'

Or (voice) Recorder:

import '@audiodn/components/recorder'

CDN alternatives:

<script type="module" src="https://unpkg.com/@audiodn/components@latest/dist/uploader.js"></script>

<script type="module" src="https://unpkg.com/@audiodn/components@latest/dist/recorder.js"></script>

Render the web component

<audiodn-uploader
  api-key="CLIENT-SIDE-UPLOAD-KEY"
  collection-id="COLLECTION-ID"
  accent-color="#ff00ff"
></audiodn-uploader>

<audiodn-recorder
  api-key="CLIENT-SIDE-UPLOAD-KEY"
  collection-id="COLLECTION-ID"
  accent-color="#ff00ff"
></audiodn-recorder>

If the key is scoped to a collection, you can omit collection-id. Never set both api-key and upload-session-id. The (voice) Recorder uses the microphone to capture audio in the browser.

What the web component does

For each file, the web component creates (or reuses) an upload session, calls POST /v1/upload/:upload_session_id/track, and uploads the bytes to track_upload.upload_url. AudioDN then processes your configured variants.

Optional: configure a track-processing webhook to learn when a track is ready.

Custom client upload with a Client-Side Upload key

Your browser or native app creates the upload session and uploads each file. You build the interface.

Create a Client-Side Upload key

Create a scoped Client-Side Upload key in the dashboard. Safe to embed in the app. Never use an API Access key in client code.

Create an upload session

const response = await fetch('https://api.audiodelivery.net/v1/upload_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer CLIENT-SIDE-UPLOAD-KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ collection_id: 'COLLECTION-ID', expires_in: 3600 })
});
const { upload_session_id } = await response.json();

var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/upload_session")!)
request.httpMethod = "POST"
request.setValue("Bearer CLIENT-SIDE-UPLOAD-KEY", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode(["collection_id": "COLLECTION-ID", "expires_in": 3600])
let (data, _) = try await URLSession.shared.data(for: request)
// Decode upload_session_id from data

val body = """{"collection_id":"COLLECTION-ID","expires_in":3600}"""
  .toRequestBody("application/json".toMediaType())
val request = Request.Builder()
  .url("https://api.audiodelivery.net/v1/upload_session")
  .post(body)
  .addHeader("Authorization", "Bearer CLIENT-SIDE-UPLOAD-KEY")
  .build()
val response = client.newCall(request).execute()
// Parse upload_session_id from response body

final response = await http.post(
  Uri.parse('https://api.audiodelivery.net/v1/upload_session'),
  headers: {
    'Authorization': 'Bearer CLIENT-SIDE-UPLOAD-KEY',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({'collection_id': 'COLLECTION-ID', 'expires_in': 3600}),
);
final json = jsonDecode(response.body) as Map<String, dynamic>;
final uploadSessionId = json['upload_session_id'] as String;

Create a track for each file

const response = await fetch(
  `https://api.audiodelivery.net/v1/upload/${upload_session_id}/track`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ file_name: 'song.wav' })
  }
);
const { track_id, track_upload } = await response.json();
const { method, upload_url } = track_upload;

var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/upload/\(sessionId)/track")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode(["file_name": "recording.m4a"])
let (data, _) = try await URLSession.shared.data(for: request)
// Decode track_upload.upload_url and method

val body = """{"file_name":"recording.m4a"}""".toRequestBody("application/json".toMediaType())
val request = Request.Builder()
  .url("https://api.audiodelivery.net/v1/upload/$uploadSessionId/track")
  .post(body)
  .build()
val response = client.newCall(request).execute()
// Parse track_upload.upload_url

final response = await http.post(
  Uri.parse('https://api.audiodelivery.net/v1/upload/$uploadSessionId/track'),
  headers: {'Content-Type': 'application/json'},
  body: jsonEncode({'file_name': 'recording.m4a'}),
);
final trackUpload = (jsonDecode(response.body) as Map)['track_upload'] as Map;
final uploadUrl = trackUpload['upload_url'] as String;

You can also include a nested track object on session create for the first file, then use this step for additional files. The upload URL is at track_upload.upload_url (not on the track object).

Upload the bytes

await fetch(upload_url, {
  method,
  headers: { 'Content-Type': file.type },
  body: file
});

var request = URLRequest(url: uploadURL)
request.httpMethod = method
request.setValue("audio/mp4", forHTTPHeaderField: "Content-Type")
request.httpBodyStream = InputStream(url: fileURL)
let (_, response) = try await URLSession.shared.data(for: request)
print((response as! HTTPURLResponse).statusCode) // 200 on success

val fileBody = File(filePath).asRequestBody("audio/mp4".toMediaType())
val request = Request.Builder()
  .url(uploadUrl)
  .put(fileBody)
  .addHeader("Content-Type", "audio/mp4")
  .build()
client.newCall(request).execute().code

final response = await http.put(
  Uri.parse(uploadUrl),
  headers: {'Content-Type': 'audio/mp4'},
  body: await File(filePath).readAsBytes(),
);

Wait for processing

Poll GET /v1/track/{track_id} until track.track_status_id is ready (requires an API Access key or dashboard), or use a webhook. Client-Side Upload keys cannot read track status — prefer webhooks or a server poll for readiness.

Server-created upload session with the AudioDN Uploader or (voice) Recorder web components

Your server authorizes the upload, creates a short-lived session, and passes it to the Uploader or (voice) Recorder web component.

Keep an API Access key on your server

Create an API Access key in the dashboard. Never send it to the browser or mobile app.

Authorize, then create an upload session

Apply your own checks (login, quota, permissions), then:

const response = await fetch('https://api.audiodelivery.net/v1/upload_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_ACCESS_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    collection_id: 'COLLECTION-ID',
    expires_in: 3600
    // Optional: track: { file_name: 'song.wav' } to also create the first track
  })
});

const { upload_session_id, upload_session } = await response.json();
// Pass upload_session_id to the client (Uploader) or continue with per-track create.

Pass the session to the web component

npm install @audiodn/components

import '@audiodn/components/uploader'

<audiodn-uploader
  upload-session-id="UPLOAD-SESSION-ID"
  accent-color="#ff00ff"
></audiodn-uploader>

<audiodn-recorder
  upload-session-id="UPLOAD-SESSION-ID"
  accent-color="#ff00ff"
></audiodn-recorder>

Use upload-session-id only — do not also set api-key.

Web component uploads

The Uploader or (voice) Recorder web component performs per-track create and byte upload for you. Optional: webhook for readiness.

Server-created upload session with a custom interface

Your server creates the session; your custom web or native UI creates tracks and uploads files.

Keep an API Access key on your server

Create an API Access key. Server only.

Create an upload session on the server

const response = await fetch('https://api.audiodelivery.net/v1/upload_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_ACCESS_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    collection_id: 'COLLECTION-ID',
    expires_in: 3600
    // Optional: track: { file_name: 'song.wav' } to also create the first track
  })
});

const { upload_session_id, upload_session } = await response.json();
// Pass upload_session_id to the client (Uploader) or continue with per-track create.

Return upload_session_id to the client. Do not return the API Access key.

Create a track for each file (client or server)

const response = await fetch(
  `https://api.audiodelivery.net/v1/upload/${upload_session_id}/track`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ file_name: 'song.wav' })
  }
);
const { track_id, track_upload } = await response.json();
const { method, upload_url } = track_upload;

var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/upload/\(sessionId)/track")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode(["file_name": "recording.m4a"])
let (data, _) = try await URLSession.shared.data(for: request)
// Decode track_upload.upload_url and method

val body = """{"file_name":"recording.m4a"}""".toRequestBody("application/json".toMediaType())
val request = Request.Builder()
  .url("https://api.audiodelivery.net/v1/upload/$uploadSessionId/track")
  .post(body)
  .build()
val response = client.newCall(request).execute()
// Parse track_upload.upload_url

final response = await http.post(
  Uri.parse('https://api.audiodelivery.net/v1/upload/$uploadSessionId/track'),
  headers: {'Content-Type': 'application/json'},
  body: jsonEncode({'file_name': 'recording.m4a'}),
);
final trackUpload = (jsonDecode(response.body) as Map)['track_upload'] as Map;
final uploadUrl = trackUpload['upload_url'] as String;

Upload the bytes

await fetch(upload_url, {
  method,
  headers: { 'Content-Type': file.type },
  body: file
});

var request = URLRequest(url: uploadURL)
request.httpMethod = method
request.setValue("audio/mp4", forHTTPHeaderField: "Content-Type")
request.httpBodyStream = InputStream(url: fileURL)
let (_, response) = try await URLSession.shared.data(for: request)
print((response as! HTTPURLResponse).statusCode) // 200 on success

val fileBody = File(filePath).asRequestBody("audio/mp4".toMediaType())
val request = Request.Builder()
  .url(uploadUrl)
  .put(fileBody)
  .addHeader("Content-Type", "audio/mp4")
  .build()
client.newCall(request).execute().code

final response = await http.put(
  Uri.parse(uploadUrl),
  headers: {'Content-Type': 'audio/mp4'},
  body: await File(filePath).readAsBytes(),
);

Wait until ready

// Processing starts automatically. Poll until ready, or use a webhook.
let track;
do {
  await new Promise((r) => setTimeout(r, 5000));
  const res = await fetch(`https://api.audiodelivery.net/v1/track/${track_id}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_ACCESS_KEY' }
  });
  ({ track } = await res.json());
} while (track.track_status_id !== 'ready');

Or use the track-processing webhook instead of polling.

Uploading tracks

Per-file upload lifecycle

Uploading tracks

AudioDN Uploader or (voice) Recorder web components with a Client-Side Upload key

Create a Client-Side Upload key

Install the web component

Render the web component

What the web component does

Custom client upload with a Client-Side Upload key

Create a Client-Side Upload key

Create an upload session

Create a track for each file

Upload the bytes

Wait for processing

Server-created upload session with the AudioDN Uploader or (voice) Recorder web components

Keep an API Access key on your server

Authorize, then create an upload session

Pass the session to the web component

Web component uploads

Server-created upload session with a custom interface

Keep an API Access key on your server

Create an upload session on the server

Create a track for each file (client or server)

Upload the bytes

Wait until ready

Related references