Présentation de Transloadify : Transloadit en ligne de commande
Le 14 février 2017, nous avons annoncé la bêta de Transloadify, un outil en ligne de commande permettant d’accéder à la plateforme d’encodage de Transloadit. Il permettait d’automatiser le traitement de médias sans devoir d’abord écrire une intégration avec un SDK. Ce tutoriel d’Adrian a initialement été publié sur transloadify.io.
Transloadify est depuis déprécié. Sa CLI a été intégrée au SDK
Node.js, désormais publié sous le nom @transloadit/node. Les exemples ci-dessous utilisent la version 4.12.0
de ce paquet. La motivation d’origine et le flux de travail de filigrane vidéo restent valables,
contrairement aux anciennes commandes d’inscription à la bêta et aux anciennes instructions
d’installation du paquet.
Introduction
Imaginez un Raspberry Pi qui enregistre des vidéos pour un projet d’Internet des objets. Vous souhaitez ajouter un filigrane à chaque vidéo avant de la publier sur YouTube, tout en laissant le processeur de l’appareil disponible pour ses autres tâches. En téléversant l’enregistrement terminé sur Transloadit, vous pouvez effectuer cet encodage à distance.
La même approche peut être utile pour une grande médiathèque sur une machine plus puissante. Les préréglages et les Robots de traitement de Transloadit vous permettent de décrire le résultat souhaité, tandis qu’un script CLI gère les fichiers locaux. Les durées de téléversement et de traitement dépendent toujours de vos fichiers, de votre connexion et de vos Instructions.
Nous allons d’abord traiter une vidéo, puis surveiller un répertoire, et enfin exporter le résultat directement vers YouTube. Les commandes qui créent des Assemblies utilisent votre compte et peuvent entraîner des frais de traitement.
Installation
Installez Node.js 24 ou une version plus récente pour suivre ce tutoriel. Exécutez la CLI à version fixée sans installation globale :
npx -y @transloadit/node@4.12.0 --help
npx -y @transloadit/node@4.12.0 assemblies create --help
Autres sources
L’annonce originale mentionnait un paquet AUR pour Arch Linux et une image Docker prévue. Il s’agissait de notes historiques sur la distribution, et non de prérequis pour ce tutoriel actualisé. Utilisez le SDK Node.js officiel pour le contrat de CLI présenté ici.
Inscription et authentification
Créez un compte sur le site web de Transloadit et obtenez une Auth Key et un Auth Secret
depuis votre compte. Faites fournir TRANSLOADIT_KEY et TRANSLOADIT_SECRET au processus de la CLI par votre
gestionnaire de secrets. Ne placez pas leurs valeurs dans l’historique du shell, dans le contrôle de
version ni dans une application cliente.
La CLI lit également un fichier .env dans son répertoire courant ainsi que ~/.transloadit/credentials au
format dotenv ; les variables d’environnement du shell sont prioritaires. Gardez vos fichiers
d’identifiants privés. Les anciens noms transloadify register et transloadify authenticate, le fichier .transloadify et
les variables TRANSLOADIT_AUTH_* ne correspondent pas à la configuration utilisée par ces commandes.
N’exécutez la CLI que sur une machine à laquelle vous confiez votre Auth Secret. Les Templates conservent les identifiants de stockage chez Transloadit, mais ne rendent pas sûre la distribution d’un Auth Secret à des appareils non fiables. Les intégrations pour navigateur et mobiles devraient obtenir des Instructions signées de courte durée auprès d’un serveur authentifié.
Définir les Assembly Instructions
Enregistrez cet objet steps sous le nom steps.json. Avant de traiter une vidéo, remplacez l’URL
du filigrane par une image HTTPS publiquement accessible que vous contrôlez :
{
"video_encode": {
"robot": "/video/encode",
"use": ":original",
"preset": "webm",
"watermark_url": "https://example.org/watermark.png",
"result": true
}
}
--steps accepte cet objet. Le préréglage WebM explicite correspond au nom du fichier de sortie
ci-dessous. Consultez la documentation de /video/encode pour le positionnement du
filigrane et les autres paramètres de sortie, et les Assembly Instructions pour
composer des Steps.
Traiter une vidéo
Créez le répertoire de sortie et traitez un enregistrement terminé :
mkdir -p watermarked
npx -y @transloadit/node@4.12.0 assemblies create \
--steps steps.json -i originals/recording.webm -o watermarked/recording.webm
La commande téléverse le fichier d’entrée, attend la fin de l’Assembly et télécharge le résultat sélectionné. Vérifiez son code de sortie et toute sortie de diagnostic ; l’absence de message n’est pas le critère de réussite. Ce Template produit un résultat par fichier d’entrée, un seul nom de fichier de sortie convient donc. Pour plusieurs fichiers de résultat, utilisez un répertoire de sortie et consultez les options de sortie de la CLI.
Automatisation
L’intégration la plus prévisible consiste à appeler la commande une fois que votre enregistreur a fermé son fichier de sortie. Vous pouvez aussi surveiller un répertoire existant :
mkdir -p originals watermarked
npx -y @transloadit/node@4.12.0 assemblies create \
--watch --steps steps.json -i originals/ -o watermarked/
La surveillance inclut les fichiers d’entrée existants et les modifications ultérieures. Enregistrez en dehors du répertoire surveillé, puis déplacez l’enregistrement terminé dans celui-ci sur le même système de fichiers. Un événement du système de fichiers ne prouve pas à lui seul qu’un enregistrement est terminé. Gardez les sorties en dehors du répertoire d’entrée pour éviter de traiter vos propres résultats, et arrêtez le processus de surveillance avec Ctrl+C une fois terminé.
Cette approche peut aussi s’intégrer à un flux de travail avec dossier partagé, comme Dropbox : une personne y dépose des enregistrements terminés, tandis qu’une machine de confiance les traite vers un dossier de sortie distinct. Tenez compte du comportement du client de synchronisation vis-à-vis des fichiers partiels avant d’activer un processus de surveillance. Un processus de surveillance n’est pas une file d’attente de tâches durable ; des redémarrages ou des modifications de fichiers peuvent déclencher une autre Assembly. Pour des nouvelles tentatives et un audit fiables, suivez les tâches et les identifiants d’Assembly dans votre application. Les SDK Ruby et Go constituent des alternatives lorsque vous avez besoin d’une intégration plus étroite.
Templates
Un fichier steps local est pratique pour une seule machine. Un Template permet à plusieurs nœuds de traitement de confiance de partager des Instructions gérées de manière centralisée. Créez-en un dans l’interface web ou avec :
npx -y @transloadit/node@4.12.0 templates create watermarker steps.json
La commande affiche l’identifiant du nouveau Template. Définissez TEMPLATE_ID sur cet identifiant dans
votre shell ; le nom du Template est un libellé lisible par un humain, pas son identifiant.
Remplacez ensuite --steps par --template :
npx -y @transloadit/node@4.12.0 assemblies create \
--watch --template "$TEMPLATE_ID" -i originals/ -o watermarked/
Les Templates peuvent référencer des informations d’identification de Template afin que les secrets de stockage restent dans votre compte Transloadit. Gardez également privés les identifiants de compte de la CLI elle-même.
Tirer le meilleur parti de Transloadit
Si la destination finale est YouTube, Transloadit peut y exporter directement la vidéo filigranée. Cela évite de la télécharger sur le Raspberry Pi puis de la téléverser à nouveau. Cela ne supprime pas le téléversement initial et ne garantit pas une vitesse de transfert particulière.
Autorisez YouTube via l’interface des informations d’identification de Template,
puis référencez dans votre Template le nom de cet ensemble d’informations d’identification. Consultez
/youtube/store pour les exigences liées au compte et les options d’exportation.
Remplacez steps.json par :
{
"video_encode": {
"robot": "/video/encode",
"use": ":original",
"preset": "webm",
"watermark_url": "https://example.org/watermark.png"
},
"youtube": {
"robot": "/youtube/store",
"use": "video_encode",
"credentials": "my_youtube_credentials",
"title": "Watermarked Raspberry Pi recording",
"description": "A recording processed with Transloadit.",
"category": "science & technology",
"keywords": "raspberry pi, transloadit",
"visibility": "private"
}
}
L’exemple exporte en mode privé afin que vous puissiez examiner le résultat avant de le publier. Personnalisez le titre, la description, la catégorie, les mots-clés et la visibilité selon votre flux de travail. Mettez à jour le Template par son identifiant, en conservant explicitement son nom :
npx -y @transloadit/node@4.12.0 templates modify "$TEMPLATE_ID" steps.json --name watermarker
Omettez ensuite -o pour éviter de télécharger les résultats en local :
npx -y @transloadit/node@4.12.0 assemblies create \
--watch --template "$TEMPLATE_ID" -i originals/
Vous disposez maintenant du flux de travail que l’annonce originale de Transloadify entendait démontrer : enregistrement local, filigrane appliqué à distance et publication directe, le tout coordonné depuis la ligne de commande. Vérifiez le statut de l’Assembly obtenue et le résultat sur YouTube avant de laisser une automatisation fonctionner sans surveillance.
Ce tutoriel a d’abord été publié sur transloadify.io. Les commandes ci-dessus ont été mises à jour pour la CLI du SDK Node.js.