Migrer de Mux vers Transloadit

Mux ingère la vidéo, l’encode et la conditionne pour la lecture HLS⁠. Transloadit est une plateforme de traitement multimédia plus polyvalente : vous pouvez téléverser ou importer des fichiers, générer plusieurs rendus, créer des sorties HLS ou MPEG-DASH, produire des miniatures, ajouter des sous-titres, transcrire de l’audio et enregistrer les résultats dans votre propre stockage.

Ce guide couvre un catalogue de vidéos à la demande : ingestion, encodage, miniatures, export vers votre propre stockage et modifications associées dans l’application. Il précise les décisions à prendre pour les métadonnées, les téléversements, les webhooks et la sécurité. L’implémentation du SDK du lecteur, les statistiques de lecture, la diffusion en direct, les DRM, le conditionnement des pistes multilingues et la reconstruction des processus d’IA sortent du cadre de cet exemple.

Périmètre du stockage et du DAM. Le processus ci-dessous exporte vers votre bucket S3 et votre CDN. La migration d’un DAM hébergé, l’import des dossiers et des métadonnées, le basculement de la diffusion tlcdn.com, les essais à blanc et les manifestes de migration, les rôles Media Library, les widgets et les intégrations aux CMS et aux éditeurs nécessitent un plan de migration distinct. Ce guide ne fournit pas d’outil d’import pour un DAM hébergé.

Correspondances pour la migration

Une Assembly ne recrée pas une ressource Mux, ses identifiants de lecture, ses politiques d’accès ou son historique de statistiques. Déterminez quelle application assume chacune de ces responsabilités avant de transférer les données des médias.

Choisir l’encodage à l’avance ou à la demande

Migration des préréglages et des URL. Mux nomme actuellement ses niveaux de qualité basic, plus et premium ; plus utilise un encodage propre à chaque vidéo. L’échelle fixe de trois rendus ci-dessous ne reproduit pas ce comportement. Comparez la qualité, la taille des fichiers, le rapport d’aspect, la fréquence d’images et la résolution maximale requise sur des vidéos représentatives avant de choisir vos propres préréglages. Consultez le guide des niveaux de qualité de Mux⁠. Recensez les options des URL de miniatures⁠, comme l’instant de l’image, les dimensions et le mode d’ajustement, et générez explicitement les sorties correspondantes ; reporter ces paramètres de requête sur une image exportée n’applique aucune transformation.

Pour les catalogues prévisibles, encodez les variantes de débit à l’avance avec /video/encode et /video/adaptive. Pour les grands catalogues dont seule une fraction des vidéos est regardée, évaluez /video/ondemand avec le Smart CDN afin que les ressources HLS soient générées à la demande des spectateurs. Ce Robot nécessite un Template Smart CDN compatible distinct, dont la branche de réponse se termine par /file/serve. Signez les URL sur votre backend pour protéger votre budget d’encodage contre les abus. Le Template de téléversement et d’export ci-dessous est destiné à l’encodage à l’avance, et non au Smart CDN.

Exemple de Template de vidéo adaptative

Ce Template reçoit une vidéo, encode trois rendus, les segmente, écrit des listes de lecture de variantes de débit et une liste de lecture multivariante, crée une miniature et stocke le tout sur S3. Cet exemple nécessite une seule vidéo source par Assembly ; choisissez des rendus adaptés à sa résolution. Les trois préréglages n’ajoutent pas les détails absents d’une source de faible résolution :

{
  "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 définit relative_path sur ses sorties. Conservez cette valeur dans le chemin d’export pour que les références des listes de lecture soient résolues. Configurez les Informations d’identification pour les services tiers et un CDN pouvant lire la racine du bucket ; url_prefix ne configure pas la diffusion et n’accorde pas d’accès. acl: "bucket-default" EN (English) n’envoie aucune ACL d’objet ; configurez l’accès via la politique de votre bucket et les autorisations d’accès du CDN à l’origine.

Définissez notify_url dans votre requête d’Assembly signée, vérifiez les signatures des notifications et exigez ASSEMBLY_COMPLETED. L’export met à jour les URL sous les Steps qui produisent les fichiers : results.hls répertorie les segments et les listes de lecture ; sélectionnez l’entrée nommée playlist.m3u8 dont meta.relative_path est vide. Récupérez la miniature depuis results.poster en vérifiant is_temp_url: false avant d’enregistrer durablement son URL. Les URL Transloadit temporaires expirent après 24 heures et ne doivent pas être utilisées pour la lecture ; consultez Enregistrer les fichiers de résultat. Testez le manifeste exporté, les listes de lecture de variantes de débit et les segments via votre CDN dans le lecteur HLS prévu avant de basculer le trafic.

Importer les fichiers sources Mux existants

Exporter depuis Mux. Listez les ressources de chaque environnement⁠ en parcourant toutes les pages. Conservez les identifiants de lecture, la politique, les pistes, les métadonnées et les paramètres de traitement de chaque ressource dans un manifeste de migration. Privilégiez les fichiers originaux que vous avez conservés lorsque vous avez besoin des données d’origine. Si Mux détient la seule copie, activez l’accès temporaire au fichier maître⁠ avec master_access: "temporary", attendez master.status: "ready" ou video.asset.master.ready, puis utilisez la valeur renvoyée dans master.url pour l’import. L’URL reste valide pendant 24 heures ; demandez à nouveau l’accès avant de réessayer un import dont l’URL a expiré. Mux décrit le fichier maître comme équivalent à l’entrée en matière de qualité, avec une résolution contrôlée par max_resolution_tier, sans promettre les données d’origine. Le MP4 comprend la vidéo et la piste audio principale ; conservez les pistes audio alternatives et téléchargez les pistes de texte séparément⁠. Consultez le guide de téléchargement des fichiers maîtres de Mux⁠.

Les rendus MP4 statiques⁠ sont des fichiers de diffusion encodés au niveau de qualité de la ressource. Utilisez l’accès au fichier maître pour l’import de l’existant lorsque vous avez besoin du fichier maître de Mux ; un rendu statique constitue un choix distinct, avec ses propres contraintes de qualité et de résolution.

Si vous avez encore les fichiers vidéo sources dans S3, utilisez 🤖/s3/import EN (English). Si votre application stocke des URL HTTPS sources temporaires, utilisez 🤖/http/import. Enregistrez une variante du Template pour l’import de l’existant : remplacez le Step de téléversement :original par un Step d’import nommé imported et remplacez les quatre références à use: ":original" (trois encodages et l’image d’affiche) par use: "imported". Configurez ce Step d’import avec une seule URL source ou clé S3 autorisée par Assembly. Pour /s3/import, configurez ses propres credentials et path pour la source ; pour /http/import, configurez url. Par exemple, le Step d’import HTTPS peut lire une URL source sélectionnée par le backend dans fields.source_url de votre requête d’Assembly signée :

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

Il s’agit du Step d’entrée de remplacement, et non du Template de traitement complet. Utilisez uniquement des URL sources auxquelles vous êtes autorisé à accéder. Les URL sources temporaires doivent rester valides jusqu’à la fin de l’import ; renouvelez les URL expirées avant de réessayer. Après un export réussi et une vérification de la lecture, enregistrez la nouvelle URL de lecture dans votre base de données tout en conservant l’identifiant de la ressource source pour la réconciliation.

Métadonnées, organisation et versions. Copiez les valeurs Mux meta.title, meta.creator_id et meta.external_id⁠ dans votre catalogue, ainsi que passthrough⁠, si cette valeur est utilisée. Conservez les étiquettes, les chemins de dossiers, l’appartenance aux collections et l’historique des révisions de votre application dans le même manifeste. Un Step d’import transfère les médias, mais pas ces relations de catalogue. Attribuez de nouvelles clés d’objet à chaque révision et conservez la correspondance entre les anciens identifiants de ressource et de lecture et les nouvelles URL de manifeste, d’image d’affiche et de pistes de texte. L’exemple utilise l’identifiant d’Assembly comme préfixe de sortie : les nouvelles tentatives nécessitent donc elles aussi une réconciliation avant de publier une révision de remplacement.

Liste de vérification

Widget de téléversement. Mux Uploader utilise les URL de téléversement direct de Mux⁠. Remplacez cette interface et le processus associé aux points de terminaison par Uppy et son plugin Transloadit en suivant le guide d’intégration par framework⁠. Autorisez l’utilisateur et sélectionnez le Template permis sur votre serveur avant de renvoyer des options d’Assembly signées à durée de validité courte. Distinguez la progression du téléversement de la fin du traitement ; ne publiez l’URL de lecture qu’après la réussite de l’export.

Webhooks et automatisation. L’événement video.asset.ready⁠ de Mux signale que la ressource est prête pour la lecture ; il ne signale pas qu’un téléchargement distinct du fichier maître ou qu’un rendu statique est prêt. Mux signe les webhooks dans l’en-tête mux-signature⁠, et leur livraison peut comporter des doublons et de nouvelles tentatives⁠. Implémentez la vérification des notifications Transloadit à partir de sa propre documentation. Dédupliquez les mises à jour du catalogue par révision source et identifiant d’Assembly, gérez les échecs et conservez un journal des nouvelles tentatives avant de remplacer vos gestionnaires d’événements Mux. Ne réutilisez pas le vérificateur de signatures Mux pour les Assembly Notifications.

Sécurité. La lecture signée de Mux utilise des JWT générés sur votre serveur⁠. Ces jetons n’autorisent pas l’accès à votre CDN de remplacement. Reconstruisez l’autorisation des spectateurs avec le mécanisme de votre CDN de destination, protégez les manifestes HLS, les listes de lecture, les segments, les images d’affiche et les sous-titres, puis testez les requêtes autorisées et refusées. Les signatures des requêtes d’Assembly autorisent le traitement ; elles n’accordent ni ne restreignent l’accès aux fichiers exportés. Alignez les politiques d’accès S3 et les autorisations d’accès du CDN à l’origine sur la visibilité de chaque ressource. Ajoutez 🤖/file/virusscan si votre politique de téléversement exige une analyse antimalware ; l’exemple ci-dessus ne comporte aucun processus d’analyse ou de mise en quarantaine. La modération de contenu et l’analyse antimalware nécessitent des règles d’acceptation distinctes.

Mux Robots et processus d’IA. Mux Robots⁠ propose des processus d’IA hébergés, notamment pour les sous-titres, les résumés, les chapitres et la modération ; Directives⁠ peut ordonner les processus et les déclencher lorsque les ressources sont prêtes. Recensez les tâches, les dépendances, les sorties et les décisions de modération utilisées par votre application. Le Template d’encodage ci-dessus ne remplace pas ces processus. Conservez leurs sorties et l’automatisation existante jusqu’à ce que vous ayez testé les langues, le schéma, la précision, les seuils et le coût de chaque solution de remplacement. Un Template Transloadit rend les Steps de traitement inspectables ; il ne rend pas les prédictions d’IA déterministes. Suivez la révision du Template, les identifiants d’Assembly, les échecs et les chemins d’export, mesurez les dépenses sur un pilote et limitez en conséquence la taille des lots d’import de l’existant. Confirmez les régions de traitement et de stockage ainsi que les exigences de conformité avec votre équipe avant le basculement.

Estimation de l’effort. Pour la planification, prévoyez deux à cinq jours de développement pour une intégration de vidéo à la demande avec accès public lorsqu’un développeur dispose déjà des originaux, d’une diffusion S3/CDN et d’un lecteur HLS compatible. Cette estimation couvre le Template, le processus de téléversement et de signature, le gestionnaire de notifications et le basculement d’un catalogue pilote ; elle exclut le temps de transfert en masse. Les fichiers maîtres détenus uniquement par Mux, la lecture privée, les modifications du CMS, les sous-titres, les pistes audio alternatives et les processus d’IA nécessitent du travail supplémentaire. Mesurez les débits d’import, d’encodage et d’export sur des fichiers représentatifs pour estimer la durée totale de l’import de l’existant.

1. Décidez si les vidéos doivent être encodées à l’avance ou à la demande.
2. Recensez les fichiers sources, les identifiants de ressource et de lecture, la visibilité, les pistes, les métadonnées, les options d’URL et l’automatisation.
3. Créez et testez un Template pour les rendus, les miniatures et les exports requis. Planifiez séparément le conditionnement des pistes de texte.
4. Configurez les informations d’identification du stockage, l’accès au CDN, les paramètres CORS pour la lecture HLS et les contrôles de diffusion privée si nécessaire.
5. Remplacez l’outil de téléversement et l’intégration des webhooks pour un pilote, en conservant l’ancienne correspondance de diffusion pour un retour arrière.
6. Importez l’existant par lots de taille limitée ; comparez la durée, la résolution, la lecture, les images d’affiche, les autorisations et le nombre d’entrées du catalogue avant de publier chaque correspondance.
7. Mettez à jour les entrées de l’application et du CMS pour qu’elles pointent vers le manifeste exporté ou l’URL du Smart CDN. Pour les URL sur un domaine que vous contrôlez, configurez et testez les redirections sur ce domaine ; mettez à jour les références aux URL hébergées par Mux dans votre application.
8. Vérifiez les lecteurs intégrés, les favoris, les sous-titres et les requêtes de segments au CDN, puis élargissez le déploiement. Gardez les anciennes ressources disponibles jusqu’à la fin de votre période de retour arrière et à l’expiration des caches.