Migra de Mux a Transloadit

Mux recibe video, lo codifica y lo empaqueta para reproducción HLS⁠. Transloadit es una plataforma de procesamiento de medios más amplia: puedes subir o importar archivos, generar múltiples variantes, crear salidas HLS o MPEG-DASH, producir miniaturas, añadir subtítulos, transcribir audio y almacenar los resultados en tu propio almacenamiento.

Esta guía cubre un catálogo de video bajo demanda: recepción, codificación, miniaturas, exportación a tu propio almacenamiento y los cambios de aplicación relacionados. Identifica decisiones sobre metadatos, subidas, webhooks y seguridad. La implementación del SDK de reproductor, el análisis de reproducción, la transmisión en vivo, DRM, el empaquetado de pistas multilingües y la reconstrucción de flujos de IA quedan fuera del ejemplo trabajado.

Alcance de almacenamiento y DAM. El flujo siguiente exporta a tu bucket de S3 y CDN. La migración de un DAM alojado, la importación de carpetas y metadatos, la transición de entrega de tlcdn.com, los simulacros/manifiestos de migración, los roles de la biblioteca de medios, los widgets y las integraciones con CMS/editores requieren un plan de migración aparte. Esta guía no ofrece un importador de DAM alojado.

Mapa de migración

Una Assembly no recrea un asset de Mux, sus IDs de reproducción, políticas de acceso ni historial de análisis. Decide qué aplicación es responsable de cada una de esas funciones antes de mover los bytes del medio.

Elige codificación anticipada o bajo demanda

Migración de ajustes preestablecidos y URL. Mux actualmente nombra sus niveles de calidad basic, plus y premium; plus usa codificación por título. La escala fija de tres variantes que se muestra abajo no reproduce ese comportamiento. Compara calidad, tamaño de archivo, relación de aspecto, velocidad de cuadros y la resolución máxima requerida en videos representativos antes de elegir tus propios ajustes preestablecidos. Consulta la guía de niveles de calidad de Mux⁠. Inventaría las opciones de URL de miniatura⁠, como el momento del cuadro, las dimensiones y el modo de ajuste, y genera las salidas correspondientes de forma deliberada; trasladar esas cadenas de consulta a una imagen exportada no aplica transformaciones.

Para catálogos predecibles, codifica las variantes por adelantado con /video/encode y /video/adaptive. Para catálogos grandes donde solo se ve una fracción de los videos, evalúa /video/ondemand con Smart CDN para que los assets HLS se generen a medida que los espectadores los solicitan. Este Robot necesita un Template de Smart CDN compatible y aparte cuya rama de respuesta termine en /file/serve. Firma las URL en tu backend para proteger tu presupuesto de codificación contra el abuso. El Template de subida y exportación de abajo es para la codificación anticipada, no para Smart CDN.

Ejemplo de Template de video adaptativo

Este Template recibe un video, codifica tres variantes, las segmenta, escribe listas de reproducción de variantes y una lista de reproducción multivariante, crea una miniatura y almacena el paquete en S3. Usa un video fuente por Assembly para este ejemplo y elige variantes adecuadas a su resolución; los tres ajustes preestablecidos no añaden detalle faltante a una fuente de baja resolución:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded_480p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/480p",
      "ffmpeg_stack": "v7"
    },
    "encoded_720p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/720p",
      "ffmpeg_stack": "v7"
    },
    "encoded_1080p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/1080p",
      "ffmpeg_stack": "v7"
    },
    "hls": {
      "use": {
        "steps": ["encoded_480p", "encoded_720p", "encoded_1080p"],
        "bundle_steps": true
      },
      "robot": "/video/adaptive",
      "technique": "hls",
      "playlist_name": "playlist.m3u8",
      "result": true
    },
    "poster": {
      "use": ":original",
      "robot": "/video/thumbs",
      "count": 1,
      "result": true
    },
    "exported_hls": {
      "use": "hls",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "videos/${assembly.id}/${file.meta.relative_path}/${file.name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    },
    "exported_poster": {
      "use": "poster",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "videos/${assembly.id}/posters/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

/video/adaptive establece relative_path en sus salidas. Consérvalo en la ruta de exportación para que las referencias de la lista de reproducción se resuelvan. Configura credenciales de terceros y un CDN que pueda leer la raíz del bucket; url_prefix no configura la entrega ni concede acceso. acl: "bucket-default" no envía ninguna ACL de objeto; configura el acceso mediante la política de tu bucket y el acceso de origen del CDN.

Define notify_url en tu solicitud de Assembly firmada, verifica las firmas de las notificaciones y requiere ASSEMBLY_COMPLETED. La exportación actualiza las URL bajo los Steps que las producen: results.hls enumera los segmentos y las listas de reproducción; selecciona la entrada llamada playlist.m3u8 con un meta.relative_path vacío. Lee la miniatura desde results.poster, comprobando is_temp_url: false antes de guardar su URL. Las URL temporales de Transloadit expiran después de 24 horas y no deben usarse para reproducción; consulta guardar los resultados de la conversión. Prueba el manifiesto exportado, las listas de reproducción de variantes y los segmentos a través de tu CDN en el reproductor HLS previsto antes de cambiar el tráfico.

Importa archivos fuente existentes de Mux

Exportar desde Mux. Lista los assets en cada entorno⁠ y sigue la paginación. Conserva en un manifiesto de migración los IDs de reproducción, la política, las pistas, los metadatos y la configuración de procesamiento de cada asset. Prefiere tus archivos originales conservados cuando necesites los bytes originales. Si Mux posee la única copia, habilita el acceso temporal al master⁠ con master_access: "temporary", espera a master.status: "ready" o video.asset.master.ready, y usa el master.url devuelto para la importación. La URL dura 24 horas; vuelve a solicitar acceso antes de reintentar una importación expirada. Mux describe el master como equivalente en calidad a la entrada, con la resolución controlada por max_resolution_tier, en lugar de prometer los bytes originales. El MP4 incluye el video y la pista de audio principal; conserva el audio alternativo y descarga las pistas de texto por separado⁠. Consulta la guía de descarga de masters de Mux⁠.

Las variantes MP4 estáticas⁠ son archivos de entrega codificados en el nivel de calidad del asset. Usa el acceso al master para el relleno histórico cuando necesites el master de Mux; una variante estática es una elección aparte con sus propias restricciones de calidad y resolución.

Si aún tienes archivos de video fuente en S3, usa 🤖/s3/import. Si tu aplicación almacena URL fuente HTTPS temporales, usa 🤖/http/import. Guarda una variante de relleno histórico del Template: reemplaza el Step de subida :original por un Step de importación llamado imported, y cambia las cuatro referencias a use: ":original" (las tres codificaciones y el póster) por use: "imported". Configura ese Step de importación con una URL fuente o clave de S3 autorizada por Assembly. Para /s3/import, configura sus propios credentials y path de origen; para /http/import, configura url. Por ejemplo, el Step de importación HTTPS puede leer una URL fuente seleccionada por el backend desde fields.source_url de tu solicitud de Assembly firmada:

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.source_url}"
    }
  }
}

Este es el Step de entrada de reemplazo, no el Template de procesamiento completo. Usa solo URL fuente a las que estés autorizado a acceder. Las URL fuente temporales deben permanecer válidas hasta que finalice la importación; renueva las URL expiradas antes de reintentar. Después de una exportación exitosa y una verificación de reproducción, escribe la nueva URL de reproducción en tu base de datos conservando el ID del asset fuente para la reconciliación.

Metadatos, organización y versiones. Copia en tu catálogo meta.title, meta.creator_id y meta.external_id⁠ de Mux, junto con passthrough⁠, si se usa. Conserva en el mismo manifiesto las etiquetas, rutas de carpetas, pertenencias a colecciones e historial de revisiones de tu aplicación. Un Step de importación transfiere el medio, no estas relaciones de catálogo. Asigna nuevas claves de objeto a cada revisión y mantén la correspondencia entre los IDs antiguos de asset y reproducción y las nuevas URL de manifiesto, póster y pista de texto. El ejemplo usa el ID de la Assembly como prefijo de salida, así que los reintentos también necesitan reconciliación antes de publicar una revisión de reemplazo.

Lista de verificación

Widget de subida. Mux Uploader usa las URL de subida directa de Mux⁠. Reemplaza esa interfaz y ese flujo de endpoint con Uppy y su plugin de Transloadit usando la guía de integración por framework⁠. Autoriza al usuario y selecciona el Template permitido en tu servidor antes de devolver opciones de Assembly firmadas de corta duración. Mantén el progreso de subida distinto de la finalización del procesamiento; publica la URL de reproducción solo después de que la exportación tenga éxito.

Webhooks y automatización. El evento video.asset.ready⁠ de Mux indica que la reproducción está lista; no indica que una descarga de master separada o una variante estática estén listas. Mux firma los webhooks en el encabezado mux-signature⁠, y su entrega puede incluir duplicados y reintentos⁠. Implementa la verificación de notificaciones de Transloadit a partir de su propia documentación. Deduplica las actualizaciones de catálogo por revisión de origen e ID de Assembly, maneja los fallos y mantén un registro de reintentos antes de reemplazar tus manejadores de eventos de Mux. No reutilices el verificador de firma de Mux para las Assembly Notifications.

Seguridad. La reproducción firmada de Mux usa JWT generados en tu servidor⁠. Esos tokens no autorizan tu CDN de reemplazo. Reconstruye la autorización del espectador usando el mecanismo de tu CDN de destino, protege los manifiestos HLS, las listas de reproducción, los segmentos, los pósteres y los subtítulos, y prueba las solicitudes permitidas y denegadas. Las firmas de solicitud de Assembly autorizan el procesamiento; no conceden ni restringen el acceso a los archivos exportados. Mantén las políticas de acceso de S3 y los permisos de origen del CDN alineados con la visibilidad de cada asset. Añade 🤖/file/virusscan si tu política de subida requiere un escaneo de malware; el ejemplo anterior no tiene flujo de escaneo ni cuarentena. La moderación de contenido y el escaneo de malware necesitan reglas de aceptación separadas.

Robots de Mux y flujos de IA. Los Robots de Mux⁠ proporcionan flujos de IA alojados que incluyen subtítulos, resúmenes, capítulos y moderación; los Directives⁠ pueden ordenar flujos de trabajo y activarlos cuando los assets están listos. Inventaría los trabajos, las dependencias, las salidas y las decisiones de moderación que usa tu aplicación. El Template de codificación anterior no reemplaza esos flujos. Mantén sus salidas y la automatización existente hasta que hayas probado los idiomas, el esquema, la precisión, los umbrales y el costo de cada reemplazo. Un Template de Transloadit hace que los Steps de procesamiento sean inspeccionables; no hace que las predicciones de IA sean deterministas. Registra la revisión del Template, los IDs de las Assemblies, los fallos y las rutas de exportación, mide el gasto en un piloto y limita los lotes de relleno histórico en consecuencia. Confirma las regiones de procesamiento y almacenamiento y los requisitos de cumplimiento con tu equipo antes de la transición.

Estimación de esfuerzo. Como estimación de planificación, calcula de dos a cinco días de ingeniería para una integración pública de video bajo demanda cuando un desarrollador ya tiene los originales, la entrega S3/CDN y un reproductor HLS compatible implementados. Eso cubre el Template, el flujo de subida/firma, el manejador de notificaciones y una transición piloto de catálogo; excluye el tiempo de transferencia masiva. Los masters exclusivos de Mux, la reproducción privada, los cambios de CMS, los subtítulos, el audio alternativo y los flujos de IA requieren trabajo adicional. Mide el rendimiento de importación, codificación y exportación en archivos representativos para estimar la duración total del relleno histórico.

1. Decide si los videos deben codificarse por adelantado o bajo demanda.
2. Inventaría los archivos fuente, los IDs de asset/reproducción, la visibilidad, las pistas, los metadatos, las opciones de URL y la automatización.
3. Crea y prueba un Template para las variantes, miniaturas y exportaciones que necesites. Planifica el empaquetado de pistas de texto por separado.
4. Configura las credenciales de almacenamiento, el acceso al CDN, CORS para reproducción HLS y los controles de entrega privada donde sea necesario.
5. Reemplaza la herramienta de subida y la integración de webhooks para un piloto, conservando la asignación de entrega anterior para poder revertir.
6. Realiza el relleno histórico en lotes acotados; compara duración, resolución, reproducción, pósteres, permisos y recuentos de catálogo antes de publicar cada asignación.
7. Actualiza los registros de la aplicación y del CMS al manifiesto exportado o a la URL de Smart CDN. Para las URL en un dominio que controlas, configura y prueba las redirecciones allí; actualiza las referencias a las URL alojadas en Mux en tu aplicación.
8. Revisa los reproductores incrustados, los marcadores, los subtítulos y las solicitudes de segmentos del CDN, y luego amplía el despliegue. Mantén los assets antiguos disponibles hasta que hayan pasado tu ventana de reversión y la vida útil de la caché.