Controla códecs audio/video con parámetros FFmpeg personalizados

Conclusiones clave

Comienza con un ajuste preestablecido cuando ya coincida con el objetivo de reproducción, y anula solo los ajustes que el producto ha elegido deliberadamente.
Trata el contenedor, el códec de video, el códec de audio, el perfil, el control de tasa, el formato de píxeles y los filtros como decisiones de compatibilidad independientes.
Selecciona ffmpeg_stack deliberadamente y vuelve a probar los datos de prueba antes de cambiarlo, porque el comportamiento del codificador y de los filtros puede variar entre versiones.

El control de códecs rara vez es una decisión de todo o nada entre un ajuste preestablecido fijo y un comando de FFmpeg sin restricciones. Transloadit permite que un Template parta de ajustes preestablecidos de video o audio mantenidos, reemplace opciones individuales compatibles de FFmpeg, o use el ajuste preestablecido vacío cuando el flujo de trabajo deba definir la configuración de salida por sí mismo.

Empieza por el objetivo de compatibilidad, no por un códec favorito

Anota dónde debe reproducirse o editarse el resultado antes de elegir los parámetros. Un archivo de entrega para navegador, un máster de archivo, una descarga de pódcast y un archivo de intercambio tienen requisitos distintos aunque partan de la misma fuente. Registra, para cada destino, los requisitos de contenedor, códecs de video y audio, perfiles, disposición de canales, dimensiones, tasa de fotogramas, frecuencia de muestreo, subtítulos y tamaño máximo de entrega.

Mantén los contenedores y los códecs separados en esa matriz. MP4, WebM, Ogg y MOV describen cómo se empaquetan los streams y los metadatos; H.264, HEVC, VP9, AAC, Opus y FLAC describen cómo se representa cada stream. Un reproductor puede reconocer un contenedor y aun así rechazar uno de sus streams, así que las pruebas basadas únicamente en la extensión no pueden establecer la compatibilidad.

Destino de reproducción

Nombra los navegadores, dispositivos, editores o especificaciones de distribución reales que determinan si una salida es aceptable.

Política de streams

Especifica los requisitos de video y audio de forma independiente para que un contenedor válido no oculte un stream no compatible.

Evidencia de aceptación

Combina la inspección de metadatos con la reproducción en clientes representativos, en lugar de aprobar un archivo solo por su extensión.

Superpón las anulaciones admitidas sobre un ajuste preestablecido mantenido

Un ajuste preestablecido es una colección versionada de configuraciones de codificación para un destino común. /video/encode y /audio/encode combinan las entradas del objeto ffmpeg con el ajuste preestablecido seleccionado, de modo que una opción explícita reemplaza el valor correspondiente del ajuste preestablecido. Esta suele ser la política mantenible más pequeña: heredar la base establecida y registrar solo el códec, el perfil, el control de tasa, el filtro o el comportamiento de contenedor que el producto ha cambiado intencionalmente.

No copies todas las opciones resueltas del ajuste preestablecido en un Template solo para que parezca explícito. Eso crea un ajuste preestablecido privado que la aplicación debe entender y mantener. En su lugar, nombra el ajuste preestablecido, mantén el objeto de anulación enfocado e inspecciona el resultado. Si el flujo de trabajo necesita evitar los valores de FFmpeg predeterminados del ajuste preestablecido, elige preset: "empty", mantén explícito el selector ffmpeg_stack: "v7" recomendado en la documentación, y proporciona el formato y los códecs requeridos.

Ajuste preestablecido base

Ofrece un punto de partida documentado para un resultado común sin requerir que el Template repita cada opción de FFmpeg.

Objeto de anulación

Registra solo los ajustes admitidos que deliberadamente difieren, y esos valores tienen prioridad sobre el ajuste preestablecido.

Ajuste preestablecido vacío

Hace visible para futuros mantenedores la ausencia deliberada de los valores de codificación predeterminados que aporta el ajuste preestablecido, en lugar de depender de un valor predeterminado omitido.

Controla deliberadamente el códec de video y los ajustes de control de tasa

El ejemplo de video comienza con el ajuste preestablecido web/mp4/1080p, selecciona la línea de stack recomendada v7 y luego anula la restricción level de H.264 más los ajustes de control de tasa específicos del producto en ffmpeg. Las claves JSON omiten el guion de línea de comandos: level, crf, maxrate y bufsize se convierten en opciones de salida de FFmpeg. El ajuste preestablecido sigue aportando su códec de video H.264 (libx264), el perfil high, el formato de píxeles yuv420p, el codificador de audio AAC (libfdk_aac), el contenedor MP4 y movflags: "+faststart"; esos valores heredados no necesitan repetirse.

Los valores son un ejemplo de política, no recomendaciones universales de calidad. El CRF, un límite de tasa de bits, el perfil del codificador, el formato de píxeles, la complejidad de la fuente y las restricciones de reproducción interactúan entre sí. Prueba texto, animación, grano, movimiento, escenas oscuras y material habitual de tipo «talking-head» en la resolución prevista. Inspecciona el resultado tanto en calidad visual como en compatibilidad de decodificación antes de promover la configuración.

Partir de un ajuste preestablecido web y anular opciones específicas de FFmpeg

{
  "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
    }
  }
}

Control de tasa y conformidad

El CRF apunta a un nivel de calidad, mientras que maxrate y bufsize limitan la tasa de bits y suavizan los picos; los valores útiles dependen del codificador y del destino de entrega. level es independiente: establece un techo de conformidad del decodificador H.264 que acota el tamaño de fotograma, la tasa de macrobloques y una tasa de bits máxima, pero no es la tasa de bits objetivo ni el límite establecido mediante CRF, maxrate y bufsize.

Base de compatibilidad del ajuste preestablecido

El ajuste preestablecido seleccionado proporciona el perfil y el formato de píxeles, lo cual puede ser tan importante como el nombre del códec para el hardware más antiguo y los decodificadores de los navegadores.

Inicio rápido heredado

El ajuste preestablecido proporciona la opción movflags de MP4 para la descarga progresiva, pero eso no reemplaza la transmisión adaptativa ni una CDN.

Crea una salida de audio explícita con el ajuste preestablecido vacío

El ejemplo de audio usa preset: "empty" con el selector ffmpeg_stack: "v7" recomendado en la documentación, de modo que el Template aporta su propia configuración de codificación en lugar de heredarla de un ajuste preestablecido. Mantén ese selector explícito en lugar de que el entorno de ejecución recurra de forma implícita a v6. El ejemplo elige el contenedor Ogg, el codificador Opus, una tasa de bits objetivo, una frecuencia de muestreo de 48 kHz, dos canales de salida y un filtro paso alto simple. /audio/encode acepta archivos de audio y archivos de video que contengan un stream de audio, lo que hace que el mismo Step sea útil tanto para subidas de solo audio como para flujos de trabajo de extracción de pista de sonido.

El ajuste preestablecido vacío elimina los valores predeterminados de codificación que aporta el ajuste preestablecido, no todos los argumentos añadidos por el Robot. /audio/encode sigue añadiendo un mapa de streams predeterminado para que la carátula incrustada no se codifique como audio, y deriva el formato o la tasa de bits de la entrada cuando se omite alguno de los dos valores. Este ejemplo indica ambos valores explícitamente en el objeto ffmpeg con f y b:a.

Este ejemplo de audio usa el objeto ffmpeg porque muestra ajustes de codificación explícitos con el ajuste preestablecido vacío. Para conversiones simples que solo cambian la tasa de bits o la frecuencia de muestreo, es preferible usar en su lugar los parámetros de Robot documentados de nivel superior bitrate y sample_rate. Estos aceptan números enteros en bits por segundo y hercios (por ejemplo, 256000 y 48000), mientras que ffmpeg.b:a acepta cadenas como "128k". El Robot Audio Encode aplica los valores de nivel superior después de la combinación con ffmpeg, por lo que sobrescriben los valores conflictivos de b:a o ar. Evita especificar el mismo aspecto en ambos lugares: un único valor autorizado es más fácil de revisar, probar y modificar.

Definir una salida Ogg Opus sin opciones de ajuste preestablecido heredadas

{
  "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
    }
  }
}

Contenedor explícito

La opción f selecciona el formato del contenedor de salida a través de su muxer, de forma independiente de codec:a, por lo que el contenedor y el códec de audio se eligen por separado.

Política de canales

La opción ac hace visible el número de canales de salida solicitado, en lugar de heredar una configuración de origen inesperada.

Filtro de audio

Una cadena af puede aplicar filtros de FFmpeg compatibles, pero cada filtro sigue necesitando comprobaciones de escucha y de nivel representativas.

Usa la flexibilidad de FFmpeg dentro del límite de seguridad gestionado

El valor ffmpeg es un objeto de opciones estructurado, no un comando de shell. Transloadit convierte sus claves y valores en argumentos para el stack de FFmpeg gestionado seleccionado. Ese límite ofrece un control sustancial sin exponer el host de procesamiento. También significa que un Template no puede instalar una compilación distinta de FFmpeg, agregar una biblioteca de codificadores no disponible, ni asumir que todas las opciones de la documentación oficial más reciente existen en cada stack.

Las opciones controladas por el usuario pasan por controles de seguridad. Los scripts de filtro y las directivas de filtro que leen archivos locales se rechazan, incluidas las entradas de subtítulos, fuentes y texto basadas en archivos. Usa parámetros de Robot dedicados y Robots dedicados cuando estén disponibles, como watermark_url, /video/subtitle o texto drawtext en línea con una familia de fuentes disponible. Trata un rechazo como un límite en torno al cual rediseñar, no como un motivo para ocultar otro comando dentro de una cadena de filtro.

Sin sintaxis de shell

Pasa los nombres y valores de las opciones como JSON para que el entrecomillado, la interpolación y la validación se mantengan dentro de las Assembly Instructions.

Capacidades del stack

Un codificador, multiplexor o filtro debe estar compilado en el stack gestionado seleccionado antes de que una opción, aunque válida, pueda funcionar.

Manejo seguro de archivos

Usa entradas declaradas y parámetros de Robot diseñados para ese fin, en lugar de pedirle a un filtro de FFmpeg que abra rutas locales del host de procesamiento.

Crea variantes de códec como Assembly Steps independientes

Un Step de origen puede alimentar varios Steps de codificación independientes. El ejemplo crea variantes de video H.264/MP4 y VP9/WebM, además de salidas de audio AAC y Opus. Estas ramas no necesitan bucles del lado de la aplicación ni subidas repetidas: su valor use compartido declara la dependencia, y cada codificación puede ejecutarse en cuanto el archivo de origen esté disponible.

Dale a cada Step un nombre que describa el contrato de salida en lugar de un detalle de implementación que probablemente cambie. A una aplicación puede importarle más browser_fallback y modern_web que los nombres de codificadores actuales. Marca como resultados solo las salidas intencionales, exporta cada variante duradera y conserva el ID de la Assembly para que un operador pueda vincular un archivo rechazado con el Step y la configuración exactos que lo produjeron.

Crear cuatro salidas de códec independientes a partir de una fuente

{
  "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
    }
  }
}

Fuente compartida

Los Steps hermanos leen el mismo archivo subido o importado sin que la aplicación tenga que transferirlo de nuevo.

Resultados independientes

Cada rama de códec tiene sus propias entradas de estado, metadatos, error y resultado para un manejo preciso por parte de la aplicación.

Nombres basados en el propósito

Los nombres de contrato estables permiten que la política de códecs subyacente evolucione sin obligar a cada consumidor a renombrar su campo.

Versiona el Template y prueba el contenido multimedia producido

Mantén el ajuste preestablecido, las anulaciones de FFmpeg y ffmpeg_stack en un Template guardado para que los trabajos de producción usen una sola política revisable. La documentación de Robots en producción recomienda el selector de versión mayor v7, mientras que una solicitud que llega al entorno de ejecución de la API sin selector recurre de forma implícita a v6, por lo que los ejemplos guardan v7 explícitamente. Un selector de versión mayor se resuelve a la compilación disponible más alta dentro de esa versión mayor; por ejemplo, v7 se resuelve a una compilación v7 en lugar de v8. El selector obsoleto v5 ya no es un stack válido y ahora se resuelve a v6. Prueba los cambios de stack, ajuste preestablecido o anulaciones junto a la política actual antes de dirigir hacia ellos todos los trabajos nuevos.

Una Assembly exitosa demuestra que el comando se completó, no que el resultado cumple con el contrato del producto. Lee los metadatos del resultado para conocer códecs, dimensiones, duración, tasa de fotogramas, número de canales y frecuencia de muestreo, y luego reproduce los archivos en clientes representativos. Conserva datos de prueba ya verificados y otros difíciles, compara el tamaño de archivo y el costo de procesamiento, revisa la sincronización audio/video y el desplazamiento por la línea de tiempo, y mantén un respaldo mientras se implementa una política modificada.

Template controlado

Mantiene unida la política de códecs y evita que llamadas individuales deriven en combinaciones no documentadas.

Matriz de datos de prueba

Abarca los códecs de origen, las resoluciones, las tasas de fotogramas, los canales, los metadatos y las entradas dañadas que producción realmente recibe.

Comprobaciones de reproducción

Comprueba la decodificación, el desplazamiento por la línea de tiempo, la sincronización y la calidad en los clientes objetivo, en lugar de basarte en el estado de salida del codificador.

Detalles técnicos que conviene conocer

El parámetro ffmpeg es un objeto cuyas entradas se combinan sobre el ajuste preestablecido seleccionado; los valores proporcionados en ese objeto tienen prioridad sobre las opciones correspondientes del ajuste preestablecido.
Cuando quien llama proporciona un objeto ffmpeg sin indicar un ajuste preestablecido, no se aplica el ajuste preestablecido predeterminado de video o audio, lo que evita heredar configuraciones que luego habría que sobrescribir.
El ajuste preestablecido explícito empty elimina los valores de codificación predeterminados que aporta el ajuste preestablecido, pero el Robot puede seguir añadiendo respaldos de selección de stream o derivados de la entrada cuando faltan los valores requeridos.
El selector de versión mayor ffmpeg_stack se resuelve dentro de la versión mayor solicitada: v7 selecciona la compilación v7 más alta disponible y nunca pasa a v8. Las versiones mayores admitidas son v6, v7 y v8.
La documentación de Robots en producción recomienda actualmente v7, por lo que todos los ejemplos configuran ffmpeg_stack: "v7" explícitamente; una solicitud que llega al entorno de ejecución de la API sin selector recurre de forma implícita a v6.
El selector obsoleto v5 se acepta por compatibilidad con versiones anteriores, pero ya no es un stack en tiempo de ejecución, por lo que una solicitud que lo indique se actualiza de forma transparente a v6; v6, v7 y v8 se ejecutan cada uno dentro de su versión mayor solicitada.
Una opción de contenedor como f: "mp4" o f: "ogg" no elige todos los códecs de stream; los códecs de video y audio se controlan de forma independiente. Las opciones de códec de stream aceptan tanto la forma larga (codec:v, codec:a) como los alias cortos equivalentes de FFmpeg (c:v, c:a); los ajustes preestablecidos mantenidos usan las formas cortas, y el Robot trata ambas grafías como intercambiables.
El Robot Audio Encode también expone los parámetros enteros de nivel superior bitrate y sample_rate, medidos en bits por segundo y en hercios. El objeto ffmpeg abarca opciones de códec, formato, canal, filtro y otras opciones admitidas, y acepta valores como "128k" para b:a.
Los nombres de las opciones de FFmpeg son claves JSON sin un guion inicial, de modo que la opción de línea de comandos -movflags +faststart se representa como "movflags": "+faststart" dentro del objeto.
Transloadit valida las opciones de FFmpeg controladas por el usuario frente a una política de seguridad gestionada; el stack seleccionado también debe contener el codificador, el multiplexor y el filtro solicitados.
Los Steps independientes que usan el mismo archivo subido o importado pueden codificar diferentes variantes de códec sin otra subida, y cada Step aparece por separado en Assembly Status y en los resultados.

Un enfoque práctico

1
Define los reproductores, dispositivos, editores o sistemas de distribución que toda salida debe admitir.
2
Elige el ajuste preestablecido más cercano y registra solo las anulaciones de FFmpeg admitidas necesarias para ese destino.
3
Ejecuta una matriz de datos de prueba que cubra códecs de entrada reales, canales, tasas de fotogramas, dimensiones y archivos dañados.
4
Guarda el Template, la elección de stack, las verificaciones de aceptación y las salidas aprobadas como una versión controlada.

Un flujo de trabajo multimedia de cuatro etapas

Cuándo resulta útil Transloadit

Usa /video/encode y /audio/encode cuando un flujo de trabajo necesite un ajuste preestablecido documentado, controles de códec y contenedor seleccionados, filtros o varias variantes a partir de una sola fuente. Ejecuta la lógica de autorización y aprobación de salida en tu aplicación, no dentro del Step de codificación, y exporta los resultados aprobados a un almacenamiento duradero.

Límite de la arquitectura

El parámetro ffmpeg expone las opciones de FFmpeg admitidas dentro de los Robots de codificación gestionada; no es acceso a la shell, ni una forma de instalar otra compilación del codificador, ni una garantía de que esté disponible cada opción de cada versión de FFmpeg. Las opciones fuera del límite de seguridad gestionado se rechazan.

Preguntas frecuentes

¿Puedo pasar cualquier opción de FFmpeg a través del objeto `ffmpeg`?

No. El objeto acepta las opciones de FFmpeg admitidas, pero Transloadit las valida antes de la ejecución y bloquea las formas que quedan fuera del límite de seguridad gestionado. El stack seleccionado también debe contener el codificador, el multiplexor y el filtro solicitados. Prueba el conjunto exacto de opciones con entradas representativas, en lugar de suponer que un ejemplo válido para otra compilación de FFmpeg se transferirá sin cambios.

¿Cuándo debería usar un ajuste preestablecido en lugar de `preset: "empty"`?

Usa un ajuste preestablecido con nombre cuando proporcione el contenedor, la familia de códecs, las dimensiones y la base de compatibilidad deseados. Añade un pequeño objeto ffmpeg cuando solo difieran unas pocas opciones. Usa preset: "empty" cuando heredar el comportamiento del ajuste preestablecido pueda ocultar o entrar en conflicto con una política de codificación explícita, y mantén explícito el selector ffmpeg_stack: "v7" recomendado en la documentación.

¿Cómo debo elegir un `ffmpeg_stack`?

Usa el stack recomendado actual, salvo que el flujo de trabajo requiera otro selector de versión mayor admitido, y conserva esa elección en el Template guardado. La documentación de Robots en producción recomienda v7, de modo que los ejemplos lo seleccionan explícitamente en lugar de depender de que el entorno de ejecución de la API recurra de forma implícita a v6. Antes de trasladar un flujo de trabajo de producción a otro stack, ejecuta los mismos datos de prueba de origen, compara los metadatos de salida y la reproducción, y despliega el Template modificado como una versión controlada.

¿Elegir MP4 u Ogg también elige los códecs?

No. Un contenedor empaqueta streams, mientras que los códecs definen cómo se codifican esos streams de video y audio. Un archivo MP4 puede aun así contener un códec que un reproductor de destino no admite. Especifica e inspecciona el códec de video, el códec de audio, el perfil, el formato de píxel y otros requisitos de reproducción por separado del contenedor.

¿Cómo creo varias variantes de códec a partir de una sola entrada?

Crea Steps hermanos de /video/encode o /audio/encode que usen todos el mismo Step de origen. Dale a cada Step un nombre estable basado en su propósito, marca las salidas seleccionadas como resultados o expórtalas, y valida cada variante independiente contra su propio objetivo de reproducción.

Controla los códecs de video y audio con Transloadit