Controle codecs de vídeo e áudio com a Transloadit

Comece pelo alvo de compatibilidade, não por um codec favorito

Antes de escolher parâmetros, anote onde o resultado precisa ser reproduzido ou editado. Um arquivo para entrega no navegador, um master de arquivamento, um download de podcast e um arquivo de intercâmbio têm requisitos diferentes, mesmo quando partem da mesma origem. Registre, para cada alvo, o contêiner, os codecs de vídeo e áudio, os perfis, o layout de canais, as dimensões, a taxa de quadros, a taxa de amostragem, as legendas e o tamanho máximo de entrega exigidos.

Mantenha contêineres e codecs separados nessa matriz. MP4, WebM, Ogg e MOV descrevem como os streams e os metadados são empacotados; H.264, HEVC, VP9, AAC, Opus e FLAC descrevem como cada stream é representado. Um player pode reconhecer um contêiner e ainda assim rejeitar um de seus streams, portanto testes baseados apenas na extensão não conseguem comprovar a compatibilidade.

Aplique substituições suportadas sobre uma predefinição mantida

Uma predefinição é um conjunto versionado de configurações de codificação para um alvo comum. /video/encode e /audio/encode mesclam as entradas do objeto ffmpeg sobre a predefinição selecionada, de modo que uma opção explícita substitui o valor correspondente da predefinição. Essa costuma ser a política sustentável mais enxuta: herde a base estabelecida e registre apenas o comportamento de codec, perfil, controle de taxa, filtro ou contêiner que o produto alterou intencionalmente.

Não copie todas as opções resolvidas da predefinição para um Template só para torná-lo explícito. Isso cria uma predefinição privada que a aplicação precisa entender e manter. Em vez disso, nomeie a predefinição, mantenha o objeto de substituição focado e inspecione o resultado. Se o fluxo de trabalho precisar evitar os padrões do FFmpeg fornecidos pela predefinição, escolha preset: "empty", mantenha explícito o seletor ffmpeg_stack: "v7" recomendado pela documentação e forneça o formato e os codecs necessários.

Controle deliberadamente as configurações de codec de vídeo e de controle de taxa

O exemplo de vídeo começa com a predefinição web/mp4/1080p, seleciona a linha de stack recomendada v7 e, em seguida, substitui a restrição level do H.264, além das configurações de controle de taxa específicas do produto em ffmpeg. As chaves JSON omitem o hífen da linha de comando: level, crf, maxrate e bufsize se tornam opções de saída do FFmpeg. A predefinição continua fornecendo seu codec de vídeo H.264 (libx264), o perfil high, o formato de pixel yuv420p, o codificador de áudio AAC (libfdk_aac), o contêiner MP4 e movflags: "+faststart"; esses valores herdados não precisam ser repetidos.

Os valores são um exemplo de política, não recomendações universais de qualidade. O CRF, um limite de taxa de bits, o perfil do codificador, o formato de pixel, a complexidade do conteúdo de origem e as restrições de reprodução interagem entre si. Teste textos, animações, granulação, movimento, cenas escuras e material comum de pessoas falando para a câmera na resolução pretendida. Inspecione a saída quanto à qualidade visual e à compatibilidade com decodificadores antes de promover as configurações.

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

Crie uma saída de áudio explícita com a predefinição vazia

O exemplo de áudio usa preset: "empty" com o seletor ffmpeg_stack: "v7" recomendado pela documentação, de modo que o Template fornece suas próprias configurações de codificação em vez de herdá-las de uma predefinição. Mantenha esse seletor explícito em vez de depender da alternativa implícita em tempo de execução v6. O exemplo escolhe o contêiner Ogg, o codificador Opus, uma taxa de bits alvo, uma taxa de amostragem de 48 kHz, dois canais de saída e um filtro passa-alta simples. /audio/encode aceita arquivos de áudio e arquivos de vídeo que contenham um stream de áudio, o que torna o mesmo Step útil para uploads somente de áudio e para fluxos de trabalho de extração de trilha sonora.

A predefinição vazia remove os padrões de codificação fornecidos pela predefinição, e não todos os argumentos adicionados pelo Robot. O Robot /audio/encode ainda adiciona um mapeamento de streams padrão para que a capa incorporada não seja codificada como áudio, e deriva o formato ou a taxa de bits da entrada quando qualquer um desses valores é omitido. Este exemplo declara ambos os valores explicitamente no objeto ffmpeg com f e b:a.

Este exemplo de áudio usa o objeto ffmpeg porque demonstra configurações de codificação explícitas com a predefinição vazia. Para conversões simples que alteram apenas a taxa de bits ou a taxa de amostragem, prefira os parâmetros de Robot documentados de nível superior bitrate e sample_rate. Eles recebem inteiros em bits/s e hertz, por exemplo, 256000 e 48000, enquanto ffmpeg.b:a aceita strings como "128k". O Robot Audio Encode aplica os valores de nível superior após a mesclagem de ffmpeg, portanto eles substituem valores conflitantes de b:a ou ar. Evite especificar a mesma questão em ambos os lugares: um único valor de referência é mais fácil de revisar, testar e alterar.

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

Use a flexibilidade do FFmpeg dentro do limite de segurança gerenciado

O valor ffmpeg é um objeto de opções estruturado, não um comando de shell. A Transloadit transforma suas chaves e valores em argumentos para o stack gerenciado do FFmpeg selecionado. Esse limite oferece um controle substancial sem expor a máquina de processamento. Também significa que um Template não pode instalar um build diferente do FFmpeg, adicionar uma biblioteca de codificador indisponível nem presumir que todas as opções da documentação upstream mais recente existem em todos os stacks.

As opções controladas pelo usuário passam por verificações de segurança. Scripts de filtro e diretivas de filtro que leem arquivos locais são rejeitados, incluindo entradas de legenda, fonte e texto baseadas em arquivos. Use parâmetros de Robot e Robots dedicados quando disponíveis, como watermark_url, /video/subtitle ou texto inline em drawtext com uma família de fontes disponível. Trate uma rejeição como um limite que exige redesenhar a solução, e não como um motivo para esconder outro comando dentro de uma string de filtro.

Crie variantes de codec como Assembly Steps independentes

Um único Step de origem pode alimentar vários Steps de codificação independentes. O exemplo cria variantes de mídia de vídeo H.264/MP4 e VP9/WebM, além de saídas de áudio AAC e Opus. Essas ramificações não precisam de loops no lado da aplicação nem de uploads repetidos: o valor use compartilhado declara a dependência, e cada codificação pode ser executada depois que o arquivo de origem estiver disponível.

Dê a cada Step um nome que descreva o contrato de saída, e não um detalhe de implementação que provavelmente mudará. Uma aplicação pode se importar mais com browser_fallback e modern_web do que com os nomes dos codificadores atuais. Marque como resultados apenas as saídas intencionais, exporte todas as variantes de mídia duráveis e guarde o Assembly ID para que um operador possa relacionar um arquivo rejeitado ao Step e às configurações exatas que o produziram.

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

Versione o Template e teste a mídia produzida

Mantenha a predefinição, as substituições do FFmpeg e ffmpeg_stack em um Template salvo para que os Jobs de produção usem uma única política revisável. A documentação do Robot em produção recomenda o seletor de versão principal v7, enquanto uma requisição que chega ao runtime da API sem seletor usa a alternativa implícita v6; por isso, os exemplos salvam v7 explicitamente. Um seletor de versão principal resolve para o build mais alto disponível dentro dessa versão principal. Por exemplo, v7 resolve para um build v7, e não v8. O seletor descontinuado v5 não é mais um stack válido e agora resolve para v6. Teste mudanças de stack, predefinição ou substituição em paralelo à política atual antes de direcionar todos os novos Jobs para elas.

Uma Assembly bem-sucedida comprova que o comando foi concluído, não que a saída atende ao contrato do produto. Leia os metadados do resultado para verificar codecs, dimensões, duração, taxa de quadros, número de canais e taxa de amostragem e, em seguida, reproduza os arquivos em clientes representativos. Mantenha arquivos de teste reconhecidamente bons e arquivos de teste difíceis, compare o tamanho dos arquivos e o custo de processamento, verifique a sincronização de áudio e vídeo e a navegação na linha do tempo, e mantenha uma alternativa enquanto uma política alterada é implantada.