Let visitors preview a clip

Offer a short public sample of every track. Upload an audio file, generate a preview variant, then embed the AudioDN player so visitors see the full-track waveform while playback is limited to the clip window.

When the active variant has isPreview: true, the player maps its playable region to preview.offsetStart–preview.offsetEnd on the full track duration. Seeking outside that window is blocked; the waveform still draws the entire track.

1. Upload an Audio File

Create an upload session against a collection, then create a track inside that session and PUT the file bytes to the returned upload URL. AudioDN accepts common audio formats; a lossless source (WAV, FLAC, or AIFF) is best so the preview clip and any streaming transcodes are derived from the highest-quality original. The examples below use a WAV file for concreteness.

Create an upload session

Example Request

# COLLECTION_ID: uuid of the collection to upload into
curl -X POST "https://api.audiodelivery.net/v1/upload_session" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": "COLLECTION_ID",
  "expires_in": 7200
}'

// COLLECTION_ID: uuid of the collection to upload into

const payload = {
  "collection_id": "COLLECTION_ID",
  "expires_in": 7200
};

const response = await fetch('https://api.audiodelivery.net/v1/upload_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();

# COLLECTION_ID: uuid of the collection to upload into

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "collection_id": "COLLECTION_ID",
    "expires_in": 7200
}

response = requests.post(
    "https://api.audiodelivery.net/v1/upload_session",
    headers=headers,
    json=payload,
)
data = response.json()

Create a track in the session

No Bearer header — the upload_session_id in the path authorizes the call.

Example Request

# SESSION_ID: upload_session_id returned by the previous call
curl -X POST "https://api.audiodelivery.net/v1/upload/SESSION_ID/track" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "track.wav"
}'

// SESSION_ID: upload_session_id returned by the previous call

const payload = {
  "file_name": "track.wav"
};

const response = await fetch('https://api.audiodelivery.net/v1/upload/SESSION_ID/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();

# SESSION_ID: upload_session_id returned by the previous call

import requests

headers = {
    "Content-Type": "application/json",
}

payload = {
    "file_name": "track.wav"
}

response = requests.post(
    "https://api.audiodelivery.net/v1/upload/SESSION_ID/track",
    headers=headers,
    json=payload,
)
data = response.json()

Upload the file bytes

PUT track_upload.upload_url

# After create-track returns track_upload.upload_url, PUT the file bytes:
# This example uses a WAV — any supported audio works; lossless (WAV/FLAC/AIFF) is best.
curl -X PUT "$UPLOAD_URL" \
  --data-binary @track.wav \
  -H "Content-Type: audio/wav"

Poll GET /v1/track/:track_id until track_status_id is ready (organization-wide variants, including waveforms, finish during this step). See the Upload Sessions API for the full lifecycle.

2. Add a preview variant

Configure a preview variant once in the dashboard so it applies to every upload, or append one to a ready track with the Variants API. Clip length is measured in seconds or percent; the start point is always a percent of total duration.

Example Request

# TRACK_ID: uuid of the ready track
curl -X POST "https://api.audiodelivery.net/v1/track/TRACK_ID/variant" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "variant_type_id": "preview",
  "index": "preview",
  "codec": "aac",
  "bitrate": 96,
  "is_stereo": true,
  "is_strip_tags": true,
  "is_strip_cover": true,
  "preview_type": "seconds",
  "preview_seconds": 90,
  "preview_percent": 25,
  "preview_min_percent": 0,
  "preview_max_percent": 60,
  "preview_min_seconds": 0,
  "preview_max_seconds": 90,
  "preview_start_percent": 25
}'

// TRACK_ID: uuid of the ready track

const payload = {
  "variant_type_id": "preview",
  "index": "preview",
  "codec": "aac",
  "bitrate": 96,
  "is_stereo": true,
  "is_strip_tags": true,
  "is_strip_cover": true,
  "preview_type": "seconds",
  "preview_seconds": 90,
  "preview_percent": 25,
  "preview_min_percent": 0,
  "preview_max_percent": 60,
  "preview_min_seconds": 0,
  "preview_max_seconds": 90,
  "preview_start_percent": 25
};

const response = await fetch('https://api.audiodelivery.net/v1/track/TRACK_ID/variant', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();

# TRACK_ID: uuid of the ready track

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "variant_type_id": "preview",
    "index": "preview",
    "codec": "aac",
    "bitrate": 96,
    "is_stereo": True,
    "is_strip_tags": True,
    "is_strip_cover": True,
    "preview_type": "seconds",
    "preview_seconds": 90,
    "preview_percent": 25,
    "preview_min_percent": 0,
    "preview_max_percent": 60,
    "preview_min_seconds": 0,
    "preview_max_seconds": 90,
    "preview_start_percent": 25
}

response = requests.post(
    "https://api.audiodelivery.net/v1/track/TRACK_ID/variant",
    headers=headers,
    json=payload,
)
data = response.json()

The example above requests an AAC 96 kbps stereo clip: up to 90 seconds (also capped at 60% of duration), starting at 25% into the track, with tags and cover art stripped. On this demo track (~2:38), that 90-second preview_seconds target is not reached — preview_max_percent (60%) wins first and shortens the clip. The track briefly re-enters processing and returns to ready when the clip is built. Full parameter reference: Variants API.

3. Embed the player with the preview variant

Point <audiodn-player> at the track and request only the preview variant. Use a Client-Side Player API key (safe in the browser). The player loads full-track waveform levels and restricts playback to the clip.

Dependency

npm install @audiodn/components

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

Usage

<script type="module">
import '@audiodn/components/player';
</script>

<audiodn-player
api-key="YOUR_PLAYER_API_KEY"
scope="track"
id="TRACK_ID"
variants="preview"
size="regular"
></audiodn-player>

Live demo

Play the sample below — the waveform spans the whole track, but only the preview window is seekable and playable.

Music by Nyktrn

Need cover art, playlists, themes, or sizes? See the Player component docs.

Checklist

Audio file (WAV shown here; lossless is best) uploads and reaches ready.
A preview variant exists on the track (dashboard recipe or POST /v1/track/:id/variant).
Player is scoped to the track with variants=“preview” and a Client-Side Player key.
Waveform shows the full track; seeking outside the clip window is blocked.