Deja que los visitantes previsualicen un clip

Ofrece una muestra pública corta de cada pista. Sube un archivo de audio, genera una variante de vista previa e incrusta el player de AudioDN para que los visitantes vean el waveform de la pista completa mientras la reproducción se limita a la ventana del clip.

Cuando la variante activa tiene isPreview: true, el player mapea su región reproducible a preview.offsetStart–preview.offsetEnd sobre la duración total de la pista. El seek fuera de esa ventana está bloqueado; el waveform sigue dibujando la pista entera.

1. Sube un archivo de audio

Crea una sesión de carga contra una colección, luego crea una pista dentro de esa sesión y haz PUT de los bytes del archivo a la URL de carga devuelta. AudioDN acepta formatos de audio habituales; una fuente sin pérdida (WAV, FLAC o AIFF) es lo mejor para que el clip de vista previa y cualquier transcode de streaming se deriven del original de mayor calidad. Los ejemplos siguientes usan un archivo WAV por concreción.

Crear una sesión de carga

Ejemplo de solicitud

# COLLECTION_ID: uuid de la colección a la que subir
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 de la colección a la que subir

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 de la colección a la que subir

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()

Crear una pista en la sesión

Sin encabezado Bearer — el upload_session_id en la ruta autoriza la llamada.

Ejemplo de solicitud

# SESSION_ID: upload_session_id devuelto por la llamada anterior
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 devuelto por la llamada anterior

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 devuelto por la llamada anterior

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()

Subir los bytes del archivo

PUT track_upload.upload_url

# Tras create-track, que devuelve track_upload.upload_url, haz PUT de los bytes del archivo:
# Este ejemplo usa un WAV — cualquier audio compatible funciona; sin pérdida (WAV/FLAC/AIFF) es lo mejor.
curl -X PUT "$UPLOAD_URL" \
  --data-binary @track.wav \
  -H "Content-Type: audio/wav"

Haz polling de GET /v1/track/:track_id hasta que track_status_id sea ready (las variantes a nivel de organización, incluidos los waveforms, terminan en este paso). Consulta la API de sesiones de carga para el ciclo de vida completo.

2. Añade una variante de vista previa

Configura una variante de vista previa una vez en el dashboard para que se aplique a cada carga, o añádela a una pista ready con la API de variantes. La longitud del clip se mide en segundos o porcentaje; el punto de inicio es siempre un porcentaje de la duración total.

Ejemplo de solicitud

# TRACK_ID: uuid de la pista ready
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 de la pista ready

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 de la pista ready

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()

El ejemplo anterior solicita un clip AAC estéreo a 96 kbps: hasta 90 segundos (también limitado al 60% de la duración), empezando al 25% de la pista, con tags y cover art eliminados. En esta pista de demo (~2:38), ese objetivo de preview_seconds de 90 segundos no se alcanza — preview_max_percent (60%) gana primero y acorta el clip. La pista vuelve brevemente a processing y regresa a ready cuando el clip está construido. Referencia completa de parámetros: API de variantes.

3. Incrusta el player con la variante de vista previa

Apunta <audiodn-player> a la pista y solicita solo la variante preview. Usa una clave Client-Side Player de la API (segura en el navegador). El player carga los levels del waveform de la pista completa y restringe la reproducción al clip.

Dependencia

npm install @audiodn/components

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

Uso

<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>

Demo en vivo

Reproduce la muestra de abajo — el waveform abarca toda la pista, pero solo la ventana de vista previa admite seek y reproducción.

Música de Nyktrn

¿Necesitas cover art, playlists, temas o tamaños? Consulta la Documentación del componente Player.

Lista de comprobación

El archivo de audio (aquí se muestra WAV; sin pérdida es lo mejor) se sube y alcanza ready.
Existe una variante preview en la pista (receta del dashboard o POST /v1/track/:id/variant).
El player está acotado a la pista con variants=“preview” y una clave Client-Side Player.
El waveform muestra la pista completa; el seek fuera de la ventana del clip está bloqueado.