Contrôler les codecs vidéo et audio avec Transloadit

Commencer par la cible de compatibilité, pas par un codec préféré

Consignez où le résultat doit être lu ou monté avant de choisir les paramètres. Un fichier destiné à être diffusé dans un navigateur, un master d’archivage, un podcast à télécharger et un fichier d’échange ont des exigences différentes, même s’ils partent de la même source. Consignez pour chaque cible le conteneur requis, les codecs vidéo et audio, les profils, la disposition des canaux, les dimensions, la fréquence d’images, la fréquence d’échantillonnage, les sous-titres et la taille maximale de diffusion.

Distinguez les conteneurs des codecs dans cette matrice. MP4, WebM, Ogg et MOV décrivent la manière dont les flux et les métadonnées sont regroupés ; H.264, HEVC, VP9, AAC, Opus et FLAC décrivent la représentation de chaque flux. Un lecteur peut reconnaître un conteneur tout en rejetant l’un de ses flux ; des tests fondés uniquement sur l’extension ne peuvent donc pas établir la compatibilité.

Appliquer des surcharges prises en charge à un préréglage maintenu

Un préréglage est un ensemble versionné de paramètres d’encodage pour une cible courante. /video/encode et /audio/encode fusionnent les entrées de l’objet ffmpeg avec le préréglage sélectionné en leur donnant priorité, de sorte qu’une option explicite remplace la valeur correspondante du préréglage. C’est généralement la politique la plus restreinte qui reste maintenable : hériter du socle établi et consigner uniquement les choix de codec, de profil, de contrôle du débit, de filtre ou de comportement du conteneur délibérément modifiés pour le produit.

Ne copiez pas toutes les options résolues du préréglage dans un Template simplement pour donner l’impression que tout est explicite. Cela crée un préréglage privé que l’application doit comprendre et maintenir. Nommez plutôt le préréglage, limitez l’objet de surcharge aux options nécessaires et inspectez le résultat. Si le flux de travail doit éviter les valeurs FFmpeg par défaut fournies par le préréglage, choisissez preset: "empty", conservez explicitement le sélecteur ffmpeg_stack: "v7" recommandé par la documentation et fournissez le format et les codecs requis.

Contrôler délibérément le codec vidéo et les paramètres de contrôle du débit

L’exemple vidéo part du préréglage web/mp4/1080p, sélectionne la branche recommandée v7 de la pile, puis surcharge la contrainte level de H.264 ainsi que les paramètres de contrôle du débit propres au produit dans ffmpeg. Les clés JSON omettent le tiret de la ligne de commande : level, crf, maxrate et bufsize deviennent des options de sortie FFmpeg. Le préréglage continue de fournir son codec vidéo H.264 (libx264), son profil high, son format de pixels yuv420p, son encodeur audio AAC (libfdk_aac), son conteneur MP4 et movflags: "+faststart" ; ces valeurs héritées n’ont pas besoin d’être redéfinies.

Ces valeurs illustrent une politique, sans constituer des recommandations universelles de qualité. Le facteur de débit constant (CRF), le plafond de débit, le profil de l’encodeur, le format de pixels, la complexité de la source et les contraintes de lecture interagissent. Testez du texte, des animations, du grain, du mouvement, des scènes sombres et des vidéos ordinaires de personnes parlant face à la caméra à la résolution prévue. Vérifiez à la fois la qualité visuelle de la sortie et sa compatibilité avec les décodeurs avant d’adopter les paramètres.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "web_video": {
      "use": ":original",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/1080p",
      "ffmpeg": {
        "level": "4.1",
        "crf": 21,
        "maxrate": "5M",
        "bufsize": "10M"
      },
      "result": true
    }
  }
}

Configurer explicitement une sortie audio avec le préréglage vide

L’exemple audio utilise preset: "empty" avec le sélecteur ffmpeg_stack: "v7" recommandé par la documentation ; le Template fournit donc ses paramètres d’encodage au lieu de les hériter d’un préréglage. Conservez ce sélecteur explicite plutôt que de vous fier à la valeur de repli implicite v6 de l’environnement d’exécution. L’exemple choisit le conteneur Ogg, l’encodeur Opus, un débit cible, une fréquence d’échantillonnage de 48 kHz, deux canaux de sortie et un simple filtre passe-haut. Le Robot /audio/encode accepte les fichiers audio et les fichiers vidéo contenant un flux audio, ce qui rend le même Step utile pour les téléversements de fichiers exclusivement audio et les flux de travail d’extraction de bandes-son.

Le préréglage vide supprime les valeurs d’encodage par défaut fournies par les préréglages, mais pas tous les arguments ajoutés par le Robot. Le Robot /audio/encode ajoute toujours une sélection de flux par défaut afin que les pochettes intégrées ne soient pas encodées comme de l’audio, et déduit le format ou le débit de l’entrée lorsque l’une de ces valeurs est omise. Cet exemple indique explicitement les deux valeurs dans l’objet ffmpeg avec f et b:a.

Cet exemple audio utilise l’objet ffmpeg pour illustrer des paramètres d’encodage explicites avec un préréglage vide. Pour les conversions simples qui ne modifient que le débit ou la fréquence d’échantillonnage, préférez les paramètres documentés bitrate et sample_rate du Robot, au niveau supérieur. Ils acceptent des entiers en bits par seconde et en hertz, par exemple 256000 et 48000, tandis que ffmpeg.b:a accepte des chaînes telles que "128k". Le Robot d’encodage audio applique les valeurs de niveau supérieur après la fusion de ffmpeg ; elles remplacent donc les valeurs contradictoires de b:a ou de ar. Évitez de définir le même réglage à la fois dans l’objet et au niveau supérieur : une valeur de référence est plus facile à examiner, à tester et à modifier.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "podcast_audio": {
      "use": ":original",
      "robot": "/audio/encode",
      "ffmpeg_stack": "v7",
      "preset": "empty",
      "ffmpeg": {
        "f": "ogg",
        "codec:a": "libopus",
        "b:a": "128k",
        "ar": 48000,
        "ac": 2,
        "af": "highpass=f=80"
      },
      "result": true
    }
  }
}

Utiliser la souplesse de FFmpeg dans le périmètre de sécurité géré

La valeur ffmpeg est un objet d’options structuré, pas une commande shell. Transloadit transforme ses clés et ses valeurs en arguments pour la pile FFmpeg gérée sélectionnée. Ce périmètre offre un contrôle étendu sans exposer la machine hôte du processus de traitement. Cela signifie aussi qu’un Template ne peut pas installer une autre compilation de FFmpeg, ajouter une bibliothèque d’encodage indisponible ni supposer que chaque option de la documentation amont la plus récente existe dans toutes les piles.

Les options contrôlées par l’utilisateur font l’objet de contrôles de sécurité. Les scripts et directives de filtrage qui lisent des fichiers locaux sont rejetés, y compris les entrées de sous-titres, de polices et de texte provenant de fichiers. Utilisez les paramètres de Robot et les Robots dédiés lorsqu’ils sont disponibles, tels que watermark_url, /video/subtitle ou du texte drawtext fourni directement avec une famille de polices disponible. Considérez un rejet comme une limite qui impose de revoir la conception, et non comme une raison de dissimuler une autre commande dans une chaîne de filtre.

Créer des variantes de codecs sous forme d’Assembly Steps indépendants

Un Step source peut alimenter plusieurs Steps d’encodage indépendants. L’exemple crée des variantes vidéo H.264/MP4 et VP9/WebM ainsi que des sorties audio AAC et Opus. Ces branches ne nécessitent ni boucles côté application ni téléversements répétés : leur valeur use commune déclare la dépendance, et chaque encodage peut s’exécuter après la mise à disposition du fichier source.

Donnez à chaque Step un nom qui décrit le contrat de sortie plutôt qu’un détail d’implémentation susceptible de changer. Une application peut accorder plus d’importance à browser_fallback et à modern_web qu’aux noms actuels des encodeurs. Ne marquez comme résultats que les sorties voulues, exportez chaque variante multimédia destinée à être conservée durablement et conservez l’identifiant de l’Assembly pour qu’un opérateur puisse relier un fichier rejeté au Step exact et aux paramètres qui l’ont produit.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "browser_fallback": {
      "use": ":original",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/720p",
      "result": true
    },
    "modern_web": {
      "use": ":original",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/webm/720p",
      "result": true
    },
    "download_aac": {
      "use": ":original",
      "robot": "/audio/encode",
      "ffmpeg_stack": "v7",
      "preset": "aac",
      "result": true
    },
    "download_opus": {
      "use": ":original",
      "robot": "/audio/encode",
      "ffmpeg_stack": "v7",
      "preset": "opus",
      "result": true
    }
  }
}

Versionner le Template et tester les médias produits

Conservez le préréglage, les surcharges FFmpeg et ffmpeg_stack dans un Template enregistré afin que les Jobs de production utilisent une politique unique qui puisse être examinée. La documentation des Robots en production recommande le sélecteur de version majeure v7, tandis qu’une requête qui atteint l’environnement d’exécution de l’API sans sélecteur utilise sa valeur de repli implicite v6 ; les exemples enregistrent donc explicitement v7. Un sélecteur de version majeure choisit la compilation disponible la plus récente au sein de cette version majeure ; par exemple, v7 sélectionne une compilation v7 plutôt que v8. Le sélecteur obsolescent v5 ne correspond plus à une pile valide et sélectionne désormais v6. Testez les changements de pile, de préréglage ou de surcharge en parallèle de la politique actuelle avant de leur acheminer tous les nouveaux Jobs.

Une Assembly réussie prouve que la commande s’est terminée, pas que la sortie respecte le contrat du produit. Consultez les métadonnées des résultats pour connaître les codecs, les dimensions, la durée, la fréquence d’images, le nombre de canaux et la fréquence d’échantillonnage, puis lisez les fichiers sur des clients représentatifs. Conservez des fichiers de test connus pour fonctionner et des fichiers de test difficiles, comparez la taille des fichiers et le coût du traitement, vérifiez la synchronisation audio/vidéo et le déplacement dans la lecture, et gardez une solution de repli pendant le déploiement d’une politique modifiée.