Laisser les visiteurs prévisualiser un clip

Proposez un court échantillon public de chaque piste. Uploadez un fichier audio, générez une variante d’aperçu, puis intégrez le lecteur AudioDN pour que les visiteurs voient la forme d’onde de la piste entière tandis que la lecture est limitée à la fenêtre du clip.

Quand la variante active a isPreview: true, le lecteur mappe sa région lisible sur preview.offsetStart–preview.offsetEnd de la durée totale de la piste. Le seek hors de cette fenêtre est bloqué ; la forme d’onde dessine toujours la piste entière.

1. Uploader un fichier audio

Créez une session d’upload contre une collection, puis créez une piste dans cette session et PUT les octets du fichier vers l’URL d’upload renvoyée. AudioDN accepte les formats audio courants ; une source lossless (WAV, FLAC ou AIFF) est préférable pour que le clip d’aperçu et tout transcoder de streaming dérivent de l’original de plus haute qualité. Les exemples ci-dessous utilisent un fichier WAV pour concrétude.

Créer une session d’upload

Exemple de requête

# COLLECTION_ID: uuid de la collection dans laquelle uploader
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 collection dans laquelle uploader

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 collection dans laquelle uploader

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

Créer une piste dans la session

Pas d’en-tête Bearer — l’upload_session_id dans le chemin autorise l’appel.

Exemple de requête

# SESSION_ID: upload_session_id renvoyé par l’appel précédent
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 renvoyé par l’appel précédent

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 renvoyé par l’appel précédent

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

Uploader les octets du fichier

PUT track_upload.upload_url

# Après que create-track a renvoyé track_upload.upload_url, PUT les octets du fichier :
# Cet exemple utilise un WAV — tout audio pris en charge fonctionne ; lossless (WAV/FLAC/AIFF) est préférable.
curl -X PUT "$UPLOAD_URL" \
  --data-binary @track.wav \
  -H "Content-Type: audio/wav"

Interrogez GET /v1/track/:track_id jusqu’à ce que track_status_id soit ready (les variantes à l’échelle de l’organisation, y compris les formes d’onde, se terminent pendant cette étape). Voir l’API Upload Sessions pour le cycle de vie complet.

2. Ajouter une variante d’aperçu

Configurez une variante d’aperçu une fois dans le tableau de bord pour qu’elle s’applique à chaque upload, ou ajoutez-en une à une piste prête avec l’API Variants. La longueur du clip se mesure en secondes ou en pourcentage ; le point de départ est toujours un pourcentage de la durée totale.

Exemple de requête

# TRACK_ID: uuid de la piste prête
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 piste prête

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 piste prête

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

L’exemple ci-dessus demande un clip AAC 96 kbps stéréo : jusqu’à 90 secondes (aussi plafonné à 60 % de la durée), démarrant à 25 % dans la piste, avec tags et pochette retirés. Sur cette piste de démo (~2:38), la cible preview_seconds de 90 secondes n’est pas atteinte — preview_max_percent (60 %) gagne en premier et raccourcit le clip. La piste repasse brièvement en processing et revient à ready quand le clip est construit. Référence complète des paramètres : API Variants.

3. Intégrer le lecteur avec la variante d’aperçu

Pointez <audiodn-player> vers la piste et demandez uniquement la variante preview. Utilisez une clé API Client-Side Player (sûre dans le navigateur). Le lecteur charge les niveaux de forme d’onde de la piste entière et restreint la lecture au clip.

Dépendance

npm install @audiodn/components

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

Utilisation

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

Démo live

Lisez l’échantillon ci-dessous — la forme d’onde couvre toute la piste, mais seule la fenêtre d’aperçu est seekable et lisible.

Musique par Nyktrn

Besoin de pochette, playlists, thèmes ou tailles ? Voir les docs du composant Player.

Checklist

Le fichier audio (WAV montré ici ; lossless est préférable) s’uploade et atteint ready.
Une variante preview existe sur la piste (recette tableau de bord ou POST /v1/track/:id/variant).
Le lecteur est limité à la piste avec variants=“preview” et une clé Client-Side Player.
La forme d’onde montre la piste entière ; le seek hors de la fenêtre du clip est bloqué.