Documentación de la API de AudioDN
Bienvenido a la documentación de la API de AudioDN. Esta API te permite gestionar colecciones de audio, pistas y sesiones de reproducción.
Primeros pasos
Puedes gestionar colecciones y pistas directamente desde tu panel de cuenta — sin código ni integración de API. Cuando estés listo para integrar, elige la ruta que mejor encaje con tu proyecto:
- Web — Usa los componentes web de ADN. No se requiere backend.
- Mobile — Apps nativas iOS, Android o Flutter.
- Server-Side — Control total de la API desde tu servidor.
- Hybrid — Sesiones aprovisionadas en el servidor con componentes web.
- Signed Delivery — Firma URLs tú mismo y omite las sesiones de reproducción para pistas públicas.
¿Prefieres empezar desde un ejemplo funcional? Explora los Ejemplos — guías prácticas con solicitudes HTTP, fragmentos de código y demos en vivo donde ayudan.
Elige tu ruta de integración
Cinco enfoques, desde un drop-in de cinco minutos hasta el control total del servidor. Elige el que encaje con tu proyecto.
Web
Configuración más rápidaUsa los componentes web de ADN con claves API Client-Side. No se requiere backend.
- Ideal para
- Prototipos, sitios estáticos, proyectos personales
- Configuración
- 5 minutos
- Complejidad
- Low
- Seguridad
- Basic
Mobile
Apps nativasUsa la API de ADN con claves API Client-Side desde tu app iOS, Android o Flutter. Reproduce y sube archivos con elementos multimedia nativos.
- Ideal para
- Apps iOS, Android, Flutter
- Configuración
- 30 minutos
- Complejidad
- Medium
- Seguridad
- Basic
Server-Side
Máximo controlUsa la API de ADN directamente para almacenar pistas y gestionar la reproducción. Crea experiencias totalmente personalizadas sin componentes de ADN.
- Ideal para
- Plataformas a medida, enterprise, control total de la API
- Configuración
- 1-2 horas
- Complejidad
- Medium
- Seguridad
- Maximum
Hybrid
Componentes aprovisionados por APIUsa la API de ADN de servidor a servidor para aprovisionar sesiones de subida y reproducción, y luego pasa los IDs de sesión a los componentes web de ADN.
- Ideal para
- Productos SaaS, contenido con paywall, apps multi-tenant
- Configuración
- 30 minutos
- Complejidad
- Medium
- Seguridad
- High
Signed Delivery
Reproducción más rápidaFirma URLs de entrega en tu propio servidor con una clave URL Signing. Omite por completo las sesiones de reproducción — sin round trip a la API — para pistas públicas.
- Ideal para
- Catálogos públicos, previews, sitios de marketing
- Configuración
- 1-2 horas
- Complejidad
- High
- Seguridad
- Public
Ciclo de vida de la subida de pistas
Cuando un archivo se sube a AudioDN, pasa por una serie de pasos automatizados antes de estar listo para reproducirse. Esto es lo que ocurre entre bastidores:
| Paso | Etapa | Qué ocurre |
|---|---|---|
| 1 | Crear sesión de subida | Tu app solicita una sesión de subida vía la API (o el componente uploader lo hace automáticamente con una clave API Client-Side). La API devuelve un upload_session_id. Una sesión puede contener muchas pistas. Opcionalmente incluye un objeto anidado track en esta solicitud para también recibir track_upload.upload_url (puedes seguir añadiendo más pistas después); de lo contrario, crea las pistas en el paso 2. |
| 2 | Crear una pista en la sesión | Por cada archivo adicional (o por cada archivo si omitiste el track anidado al crear la sesión), haz una solicitud separada a POST /v1/upload/:upload_session_id/track. Esto devuelve el track_id y una URL de subida firmada por pista en track_upload.upload_url. El ID de sesión autoriza esta solicitud, así que no se requiere clave API. |
| 3 | Subir archivo | El archivo de audio se sube directamente al almacenamiento con un PUT a track_upload.upload_url. Una vez completada la subida, el procesamiento comienza automáticamente. |
| 4 | Inicialización | ADN analiza el archivo para extraer duración, información del códec y metadatos del stream. Se genera una forma de onda predeterminada de 320 muestras para el player. El archivo original se guarda si la variante Original Upload está habilitada. |
| 5 | Procesamiento de variantes | Cada variante configurada (transcodificaciones, previews, análisis, imágenes/vídeos de forma de onda) se procesa en paralelo. El estado de la pista se establece en processing. |
| 6 | Procesamiento de respaldo | Si un archivo es demasiado grande, demasiado largo o alcanza límites de recursos durante el paso 5, el trabajo se reintenta automáticamente en un procesador de mayor capacidad. El estado de la pista cambia a fallback_processing. Estas pistas pueden tardar más porque hay que levantar recursos dedicados antes de que comience el procesamiento. No se necesita ninguna acción por tu parte. |
| 7 | Extracción de portada y color | Si el archivo de audio contiene arte de portada incrustado, ADN lo extrae, lo sube al CDN de imágenes y lo analiza para obtener una paleta de colores. El color más vibrante se selecciona automáticamente como player_color para tematizar los players, y las respuestas también incluyen variantes ajustadas por contraste player_color_light y player_color_dark para fondos claros y oscuros. |
| 8 | Pista lista | Cuando terminan todas las variantes, el estado de la pista se establece en ready (o incomplete si algunas variantes fallaron pero al menos una variante reproducible tuvo éxito). La pista ya está disponible para reproducción. |
| 9 | Notificación por webhook | Si hay una URL de webhook configurada en la organización, ADN envía una solicitud POST cuando una pista alcanza un resultado terminal (ready, incomplete, error o init_error) y cuando su conjunto completo de archivos está listo — no en cada estado de transición. Úsalo para disparar flujos posteriores como actualizar tu base de datos o notificar a usuarios. Consulta la documentación del webhook Track Processing. |
Glosario
Client
Una organización o individuo que usa Audio Delivery Network (AudioDN) para gestionar y entregar contenido de audio. Los clientes acceden a la plataforma vía API o componentes web.
Creator
Una subcuenta bajo un cliente. Suele representar a un contribuidor individual de contenido, como un artista o podcaster. Se usa para seguimiento de uso, control de acceso y analítica a un nivel granular.
Collection
Un contenedor lógico (similar a una carpeta) usado para organizar una o más pistas. Las colecciones ayudan a gestionar subidas, reproducción y visualización en players.
Track
Un archivo de audio individual subido a AudioDN. Las pistas pueden ser música, palabra hablada, podcasts o cualquier otro tipo de contenido de audio.
Original (Upload)
El archivo de audio exacto e inalterado proporcionado por el cliente o creador en el momento de la subida. Se almacena como referencia y para la generación futura de variantes.
Variant
Una receta reutilizable que define cómo ADN convierte un archivo subido en una salida entregable—por ejemplo una transcodificación AAC o MP3, un clip de preview corto, una imagen o vídeo de forma de onda, o datos de análisis de audio. Defines una variante una vez y ADN la aplica automáticamente a cada subida. Cuando una sola pista necesita una salida extra que no forma parte de tu conjunto estándar, también puedes añadir una variante específica de pista a posteriori.
Track File
La salida real producida al aplicar una variante a una pista—el archivo almacenado y entregable en sí (por ejemplo el audio AAC, el clip de preview o la imagen de forma de onda). Una pista tiene un track file por variante, devuelto como sus files en la API. También se pueden crear nuevos track files a posteriori, ya sea añadiendo una nueva variante o generando uno para una sola pista.
Cover Image / Cover Art
Una imagen opcional asociada a una pista, colección o cuenta de cliente. Se muestra en el player y se usa para tematización estética.
Image Colors
Una paleta de colores extraída automáticamente de una imagen de portada (theme). Se usa para estilizar players y otros componentes.
Color
El color de acento principal mostrado en la UI del player y el uploader. Se selecciona automáticamente a partir de los colores de la imagen o se establece manualmente vía API.
Player (Component)
Un componente web personalizable e integrable que reproduce pistas y colecciones. Diseñado para una integración sencilla en sitios web y apps.
Uploader (Component)
Un componente web personalizable que permite a los usuarios subir archivos de audio a colecciones. Incluye soporte para metadatos de pista e imágenes de portada.