Presentamos Transloadify: usa Transloadit por línea de comandos
El 14 de febrero de 2017 anunciamos la versión beta de Transloadify, una herramienta de línea de comandos para acceder a la plataforma de codificación de Transloadit. Permitía automatizar el procesamiento multimedia sin tener que escribir primero una integración con un SDK. Esta guía de Adrian se publicó originalmente en transloadify.io.
Transloadify ha quedado obsoleto desde entonces. Su CLI se incorporó
al SDK de Node.js, que ahora se publica como @transloadit/node. Los ejemplos siguientes
usan la versión 4.12.0 de ese paquete. La motivación original y el flujo de trabajo para añadir
marcas de agua a videos siguen siendo válidos; los antiguos comandos de registro en la beta y las
instrucciones de instalación del paquete ya no lo son.
Introducción
Imagina una Raspberry Pi que graba videos para un proyecto de Internet de las cosas. Quieres añadir una marca de agua a cada video antes de publicarlo en YouTube, dejando la CPU del dispositivo disponible para sus otras tareas. Subir la grabación terminada a Transloadit te permite realizar esa codificación de forma remota.
El mismo enfoque puede ayudarte con una biblioteca multimedia grande en una máquina más potente. Los ajustes preestablecidos y los Robots de procesamiento de Transloadit te permiten describir el resultado que necesitas, mientras un script de CLI gestiona los archivos locales. Los tiempos de subida y procesamiento siguen dependiendo de tus archivos, tu conexión y las Instructions.
Primero procesaremos un video, luego supervisaremos un directorio y, por último, exportaremos el resultado directamente a YouTube. Los comandos que crean Assemblies usan tu cuenta y pueden generar cargos por procesamiento.
Instalación
Instala Node.js 24 o una versión posterior para seguir esta guía. Ejecuta la versión fijada de la CLI sin instalarla globalmente:
npx -y @transloadit/node@4.12.0 --help
npx -y @transloadit/node@4.12.0 assemblies create --help
Otras fuentes
El anuncio original mencionaba un paquete de Arch Linux AUR y una imagen de Docker prevista. Eran notas históricas sobre la distribución, no requisitos para esta guía actualizada. Usa el SDK oficial de Node.js para la interfaz de CLI que se muestra aquí.
Registro y autenticación
Crea una cuenta en el sitio web de Transloadit y obtén una Auth Key y
un Auth Secret desde tu cuenta. Configura tu gestor de secretos para que proporcione
TRANSLOADIT_KEY y TRANSLOADIT_SECRET al proceso de la CLI. No incluyas sus
valores en el historial del shell, en el control de versiones ni en una aplicación cliente.
La CLI también lee un archivo .env en su directorio actual y
~/.transloadit/credentials en formato dotenv; las variables de entorno del shell tienen
prioridad. Mantén privados los archivos de credenciales. Los nombres originales
transloadify register, transloadify authenticate, el archivo
.transloadify y la variable TRANSLOADIT_AUTH_* no forman parte de la
configuración que usan estos comandos.
Ejecuta la CLI solo en una máquina a la que puedas confiar tu Auth Secret. Los Templates mantienen las credenciales de almacenamiento en Transloadit, pero no hacen que sea seguro distribuir un Auth Secret a dispositivos que no sean de confianza. Las integraciones web y móviles deben obtener Instructions firmadas de corta duración desde un servidor autenticado.
Especificar las Assembly Instructions
Guarda este objeto de Steps como steps.json. Antes de procesar un video,
sustituye la URL de la marca de agua por la de una imagen bajo tu control, accesible públicamente
mediante HTTPS:
{
"video_encode": {
"robot": "/video/encode",
"use": ":original",
"preset": "webm",
"watermark_url": "https://example.org/watermark.png",
"result": true
}
}
--steps acepta este objeto. El ajuste preestablecido explícito de WebM
coincide con el nombre del archivo de salida que aparece a continuación. Consulta la
documentación de /video/encode para conocer las opciones de ubicación
de la marca de agua y otros ajustes de salida, y las
Assembly Instructions para combinar Steps.
Procesar un video
Crea el directorio de salida y procesa una grabación terminada:
mkdir -p watermarked
npx -y @transloadit/node@4.12.0 assemblies create \
--steps steps.json -i originals/recording.webm -o watermarked/recording.webm
El comando sube el archivo de entrada, espera a que termine la Assembly y descarga el resultado seleccionado. Revisa su estado de salida y cualquier información de diagnóstico; la ausencia de mensajes no garantiza el éxito. Este Template produce un resultado por cada entrada, por lo que es adecuado usar un solo nombre de archivo de salida. Para varios archivos de resultados, usa un directorio de salida y consulta las opciones de salida de la CLI.
Automatización
La integración más predecible consiste en invocar el comando después de que tu grabador cierre su archivo de salida. Como alternativa, supervisa un directorio existente:
mkdir -p originals watermarked
npx -y @transloadit/node@4.12.0 assemblies create \
--watch --steps steps.json -i originals/ -o watermarked/
La supervisión incluye las entradas existentes y los cambios posteriores. Graba fuera del directorio supervisado y luego mueve la grabación terminada a ese directorio dentro del mismo sistema de archivos. Un evento del sistema de archivos por sí solo no demuestra que una grabación haya terminado. Mantén los archivos de salida fuera del directorio de entrada para evitar procesar tus propios resultados y detén la supervisión con Ctrl+C cuando termines.
Esto también puede encajar en un flujo de trabajo con una carpeta compartida, como Dropbox: una persona aporta grabaciones terminadas mientras una máquina de confianza las procesa en una carpeta de salida separada. Ten en cuenta cómo gestiona el cliente de sincronización los archivos parciales antes de activar la supervisión. Un proceso de supervisión no es una cola persistente de Jobs; los reinicios o los cambios en los archivos pueden provocar otra Assembly. Para contar con reintentos y auditorías fiables, lleva un registro de los Jobs y los ID de las Assemblies en tu aplicación. Los SDK de Ruby y Go son alternativas cuando necesitas una integración más estrecha.
Templates
Un archivo local de Steps resulta práctico para una sola máquina. Un Template permite que varios procesos de trabajo de confianza compartan Instructions gestionadas de forma centralizada. Crea uno en la interfaz web o con:
npx -y @transloadit/node@4.12.0 templates create watermarker steps.json
El comando muestra el nuevo Template ID. Asigna ese ID a TEMPLATE_ID en tu shell;
el nombre del Template es una etiqueta legible para las personas, no su identificador. Luego
sustituye --steps por --template:
npx -y @transloadit/node@4.12.0 assemblies create \
--watch --template "$TEMPLATE_ID" -i originals/ -o watermarked/
Los Templates pueden hacer referencia a credenciales de Template para que los secretos de almacenamiento permanezcan en tu cuenta de Transloadit. Mantén también privadas las credenciales de cuenta de la propia CLI.
Aprovechar Transloadit al máximo
Si el destino final es YouTube, Transloadit puede exportar directamente el video con la marca de agua. Así evitas descargarlo a la Raspberry Pi y volver a subirlo. Esto no elimina la subida original ni garantiza una velocidad de transferencia determinada.
Autoriza YouTube mediante la
interfaz de credenciales de Template y luego haz referencia al nombre
de esa credencial en tu Template. Consulta /youtube/store para
conocer los requisitos de la cuenta y las opciones de exportación. Sustituye
steps.json por:
{
"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"
}
}
El ejemplo exporta el video como privado para que puedas revisar el resultado antes de publicarlo. Personaliza el título, la descripción, la categoría, las palabras clave y la visibilidad según tu flujo de trabajo. Actualiza el Template por su ID, conservando su nombre explícitamente:
npx -y @transloadit/node@4.12.0 templates modify "$TEMPLATE_ID" steps.json --name watermarker
Luego omite -o para evitar descargar los resultados localmente:
npx -y @transloadit/node@4.12.0 assemblies create \
--watch --template "$TEMPLATE_ID" -i originals/
Ahora tienes el flujo de trabajo que el anuncio original de Transloadify se proponía demostrar: grabación local, incorporación remota de marcas de agua y publicación directa, coordinadas desde la línea de comandos. Revisa el estado de la Assembly resultante y el video en YouTube antes de dejar una automatización sin supervisión.
La guía original se publicó primero en transloadify.io. Los comandos anteriores se han actualizado para la CLI del SDK de Node.js.