Transloadit

Transcodificar, redimensionar ou aplicar marca-d’água em vídeos

🤖/video/encode codifica, redimensiona e aplica marcas-d’água a vídeos e GIFs animados.

Robot /video/encode

O Robot /video/encode é uma ferramenta versátil para processamento de vídeo que realiza transcodificação, redimensionamento e aplicação de marcas-d’água. Ele oferece suporte a vários formatos, incluindo padrões modernos como HEVC (H.265), e fornece recursos como predefinições para dispositivos comuns, parâmetros personalizados do FFmpeg para usuários avançados, posicionamento de marcas-d’água e muito mais.

Áudio espacial do iPhone

Vídeos gravados com áudio espacial do iPhone podem conter uma faixa AAC estéreo junto com uma faixa Apple Positional Audio Codec (APAC). Quando há áudio sem suporte, este Robot mantém por padrão uma faixa de áudio com suporte. O áudio espacial não é preservado nem convertido.

Arquivos que contêm apenas áudio sem suporte continuam falhando. Seleções individuais de faixas de áudio e solicitações de cópia de stream mantêm as faixas que você seleciona; o formato de saída deve oferecer suporte às faixas copiadas.

Ao adicionar marcas-d’água ou desenhar com filtros de vídeo simples do FFmpeg, como drawtext, em vídeos HDR HLG ou PQ, o vídeo passa por mapeamento de tons para SDR BT.709 antes do desenho, para que as cores das sobreposições mantenham os valores RGB pretendidos. As entradas SDR mantêm seu processamento existente. Um ffmpeg.pre:filter:v personalizado que fornece mapeamento de tons controla sua própria conversão de cores. Grafos personalizados de filter_complex com múltiplas entradas devem tratar explicitamente o espaço de cores de cada entrada.

Adição de sobreposições de texto com FFmpeg

Você pode adicionar sobreposições de texto a vídeos usando o filtro drawtext do FFmpeg por meio do parâmetro ffmpeg deste Robot. Aqui estão dois exemplos: um com a fonte padrão e outro com um nome de família de fontes personalizado:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "text_overlay_default": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "empty",
      "ffmpeg_stack": "v7",
      "ffmpeg": {
        "codec:a": "copy",
        "vf": "drawtext=text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
      },
      "result": true
    },
    "text_overlay_custom": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "empty",
      "ffmpeg_stack": "v7",
      "ffmpeg": {
        "codec:a": "copy",
        "vf": "drawtext=font='Times New Roman':text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
      },
      "result": true
    }
  }
}

Observações:

  • Use o atributo font para referenciar uma fonte pelo nome da família com o drawtext do FFmpeg
  • Os nomes de famílias de fontes do FFmpeg normalmente não contêm hífens (por exemplo, Times New Roman), enquanto o ImageMagick usa nomes com hífens (por exemplo, Times-New-Roman).
  • As opções de carregamento de arquivos do drawtext, como textfile e fontfile, não são compatíveis. Use text inline e um nome de família de fontes em vez disso.
  • Preserve o áudio original definindo "codec:a": "copy".
  • Posicione o texto com as expressões x e y. O exemplo acima centraliza o texto.

Veja a demonstração interativa de sobreposição de texto  (English).

Exemplo de uso

Transcodifique o vídeo carregado para HEVC (H.265):

{
  "steps": {
    "hevc_encoded": {
      "preset": "hevc",
      "robot": "/video/encode",
      "use": ":original"
    }
  }
}

Parâmetros

  • interpolate

    boolean | Record<string, boolean>

    Controla se as Assembly Variables são interpoladas em campos individuais de instruções.

    Por padrão, a maioria dos campos de instruções dos Robots interpola Assembly Variables. Defina isso como false para tratar todos os campos de instruções como texto literal, ou defina o caminho de um campo individual como false para tratar apenas esse campo como texto literal. Para campos específicos de um Robot que são literais por padrão, defina isso como true ou defina o caminho desse campo como true para voltar a usar a interpolação.

    Use nomes de campos como path ou caminhos com pontos como ffmpeg.vf para objetos aninhados.

  • output_meta

    Record<string, boolean> | boolean | Array<string>

    Permite especificar um conjunto de metadados cujo cálculo é mais custoso para a CPU e que, por isso, vem desativado por padrão para manter o processamento das suas Assemblies rápido.

    Para imagens, você pode adicionar "has_transparency": true neste objeto para extrair se a imagem contém partes transparentes e "dominant_colors": true para extrair um array de códigos de cores hexadecimais da imagem.

    Para imagens, você também pode adicionar "blurhash": true para extrair uma string BlurHash, uma representação compacta de um placeholder da imagem, útil para exibir uma prévia desfocada enquanto a imagem completa carrega.

    Para imagens, "thumbhash": true em vez disso extrai um ThumbHash codificado em base64 em meta.thumbhash, junto com meta.has_alpha (se existe um canal alfa, mesmo quando totalmente opaco). Ele descreve pixels orientados por EXIF e usa o primeiro quadro de imagens animadas. A extração é feita em regime de melhor esforço: imagens acima de 40 megapixels, formatos não suportados ou uma decodificação com falha/limitada não geram placeholder. Uma extração bem-sucedida adiciona uma cobrança de metadados equivalente a 20% dos bytes desse arquivo. Nenhuma sobretaxa de ThumbHash se aplica quando desativado ou quando nenhum hash é gerado.

    Defina essa opção no Step que produz a imagem, como /upload/handle para originais enviados por upload ou /image/resize para saídas processadas. Defini-la apenas em /transloadit/store não solicita a extração: o armazenamento preserva os metadados do produtor. O Transloadit Storage persiste um hash gerado com sua versão imutável e o retorna em resultados armazenados e em leituras nativas de ativos. Uploads diretos para o S3 não geram placeholders. Um placeholder contém informações da imagem, portanto proteja-o com os mesmos controles de acesso da imagem completa.

    Para vídeos, você pode adicionar o parâmetro "colorspace": true para extrair o espaço de cores do vídeo de saída.

    Para vídeos, você também pode adicionar "interlaced": true para detectar se o vídeo é entrelaçado. Isso combina a flag barata do ffprobe field_order com uma passagem de amostragem idet limitada sobre os primeiros quadros da origem, expondo interlaced, field_order e um objeto de diagnóstico interlace_detection em file.meta. Isso é computacionalmente caro e cobrado de acordo.

    Para áudio, você pode adicionar "mean_volume": true para obter um único valor que representa o volume médio do arquivo de áudio.

    Você também pode definir isso como false para pular a extração de metadados e acelerar a transcodificação.

  • user_meta

    Record<string, any>(padrão: {})

    Adiciona metadados JSON personalizados a cada arquivo emitido sem modificar seu conteúdo. Objetos e arrays aninhados são suportados.

    A herança depende do Robot. Os valores são mesclados com o user_meta existente no arquivo de saída; o Step atual substitui as chaves de nível superior com o mesmo nome. Atribua explicitamente as chaves necessárias quando um Robot criar novas saídas.

    Nos Steps de processamento, ${file.*} se refere à primeira entrada e ${result.*} ao arquivo emitido. Os valores são avaliados para cada saída após a execução do Robot, antes da extração subsequente de metadados e do armazenamento temporário. Em :original, os valores são avaliados para cada upload antes da extração de metadados.

    Os Steps subsequentes leem ${file.user_meta.key}. Consulte Metadados personalizados para ver um exemplo completo e as regras de herança.

  • result

    boolean(padrão: false)

    Se os resultados deste Step devem estar presentes no Assembly Status JSON

  • queue

    batch

    Definir a fila como “batch” rebaixa manualmente a prioridade dos Jobs deste Step, para evitar o consumo de vagas prioritárias de Jobs em Jobs que não precisam de tempo zero de espera na fila

  • force_accept

    boolean(padrão: false)

    Forçar um Robot a aceitar um tipo de arquivo que ele teria ignorado.

    Por padrão, os Robots ignoram arquivos que não conhecem. O 🤖/video/encode, por exemplo, ignora tranquilamente imagens de entrada.

    Com o parâmetro force_accept definido como true, você pode forçar os Robots a aceitar todos os arquivos enviados a eles. Isso normalmente leva a erros e só deve ser usado para depuração ou para lidar com casos extremos.

  • ignore_errors

    boolean | Array<meta | execute>(padrão: [])

    Ignorar erros durante fases específicas do processamento.

    Definir isso como ["meta"] fará com que o Robot ignore erros durante a extração de metadados.

    Definir isso como ["execute"] fará com que o Robot ignore erros durante a fase principal de execução.

    Definir isso como true equivale a ["meta", "execute"] e fará com que erros sejam ignorados nas duas fases.

  • use

    string | Array<string> | Array<object> | object

    Especifica quais Steps usar como entrada.

    • Você pode escolher qualquer nome para os Steps, exceto ":original" (reservado para uploads de usuários tratados pela Transloadit)
    • Você pode fornecer vários Steps como entrada usando arrays: 
      {
  "use": [
    ":original",
    "encoded",
    "resized"
  ]
}
    • Você também pode marcar os Steps de entrada com as para transmitir intenção semântica aos Robots: 
      {
  "use": [
    {
      "name": ":original",
      "as": "image"
    },
    {
      "name": ":original",
      "as": "mask"
    }
  ]
}

  • ffmpeg

    object

    Um objeto de parâmetros a ser passado para o FFmpeg. Se uma predefinição for usada, as opções especificadas são mescladas sobre as da predefinição. Para ver as opções disponíveis, consulte a documentação do FFmpeg. As opções especificadas aqui têm precedência sobre as opções da predefinição.

  • ffmpeg_stack

    v6 | v7 | v8 | string(padrão: "v6.0.0")

    Seleciona a versão do stack do FFmpeg a ser usada na codificação. Atualmente, recomendamos usar “v7”. As versões exatas “v6.0.0”, “v7.0.0” e “v8.0.0” são valores legados que continuam sendo aceitos por compatibilidade retroativa. Valores “v5.x” descontinuados também são aceitos.

  • width

    string | number | null

    Largura do novo vídeo, em pixels.

    Se o valor não for especificado e o parâmetro preset estiver disponível, será aplicada a largura fornecida por preset.

  • height

    string | number | null

    Altura do novo vídeo, em pixels.

    Se o valor não for especificado e o parâmetro preset estiver disponível, será aplicada a altura fornecida por preset.

  • preset

    android | android-high | android-low | android_high | android_low | dash-1080p-video | dash-1080p_video |

    Converte um vídeo de acordo com configurações predefinidas.

    Você pode usar o valor 'empty' aqui se especificar seus próprios parâmetros do FFmpeg usando o Robot ou se não quiser que a Transloadit defina nenhuma configuração de codificação.

  • resize_strategy

    crop | fit | fillcrop | min_fit | pad | stretch(padrão: "pad")

    Veja as estratégias de redimensionamento disponíveis.

  • zoom

    boolean(padrão: true)

    Se este parâmetro estiver definido como false, vídeos menores não serão esticados até a largura e a altura desejadas. Para saber mais sobre o impacto do zoom na sua estratégia de redimensionamento preferida, consulte a lista de estratégias de redimensionamento disponíveis.

  • crop

    object | string

    Especifique um objeto contendo as coordenadas dos cantos superior esquerdo e inferior direito do retângulo a ser recortado dos vídeos originais. Os valores podem ser números inteiros para valores absolutos em pixels ou strings para valores percentuais.

    Por exemplo:

    {
  "x1": 80,
  "y1": 100,
  "x2": "60%",
  "y2": "80%"
}

    Isso recortará a área de (80, 100) a (600, 800) de um vídeo de 1000×1000 pixels, resultando em um retângulo com largura de 520px e altura de 700px. Se crop estiver definido, os parâmetros de largura e altura serão ignorados, e resize_strategy será definido como crop automaticamente.

    Você também pode usar uma string JSON desse tipo de objeto com coordenadas de forma semelhante:

    "{\"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer>}"

  • background

    string(padrão: "#00000000")

    A cor de fundo do vídeo resultante no formato "rrggbbaa" (vermelho, verde, azul, alfa) quando usado com a estratégia de redimensionamento "pad". A cor padrão é preto.

  • rotate

    0 | 90 | 180 | 270 | 360 | false

    Força a rotação do vídeo pelo número inteiro de graus especificado. Atualmente, apenas múltiplos de 90 são compatíveis. Corrigimos automaticamente a orientação de muitos vídeos quando ela é fornecida pela câmera. Esta opção só é útil para vídeos que precisam de rotação porque a orientação não foi detectada pela câmera. Se você definir rotate como false, nenhuma rotação será realizada, mesmo que os metadados contenham essas instruções.

  • hint

    boolean(padrão: false)

    Habilita o hinting em arquivos mp4 para streaming RTP/RTSP.

  • turbo

    boolean(padrão: false)

    Divide o vídeo em vários trechos para que cada um possa ser codificado em paralelo antes que todos os trechos codificados sejam reunidos para formar o vídeo resultante. Isso consome vagas prioritárias de Jobs adicionais e pode ser contraproducente para arquivos de vídeo muito pequenos.

    A saída VP8 e expressões de codec de vídeo não resolvidas usam a codificação normal mesmo quando turbo é true.

  • chunk_duration

    string | number

    Permite especificar a duração de cada trecho quando turbo está definido como true. Isso significa que você pode aproveitar esse recurso usando menos vagas prioritárias de Jobs. Por exemplo, quanto maior a duração de cada trecho, menos Jobs de codificação precisarão ser usados.

    Durações solicitadas abaixo de 5 segundos são tratadas como 5 segundos.

  • watermark_url

    "" | string(padrão: "")

    Uma URL que indica uma imagem PNG a ser sobreposta a esta imagem. Você também pode fornecer a marca-d’água por meio de outro Assembly Step.

  • watermark_position

    bottom | bottom-left | bottom-right | center | left | right | top | | Array<bottom | bottom-left | bottom-right | center | left | right | top | >(padrão: "center")

    A posição em que a marca-d’água é colocada.

    Também é possível especificar um array de valores possíveis, como [ "center", "left", "bottom-left", "bottom-right" ], caso em que um valor será selecionado aleatoriamente.

    Esta configuração coloca a marca-d’água no canto especificado. Para usar um deslocamento específico em pixels para a marca-d’água, você precisará adicionar o preenchimento à própria imagem.

  • watermark_x_offset

    string | number(padrão: 0)

    O deslocamento no eixo x, em número de pixels, no qual a marca-d’água será colocada em relação à posição determinada por watermark_position.

    Os valores podem ser positivos ou negativos e produzem resultados diferentes dependendo do parâmetro watermark_position. Valores positivos aproximam a marca-d’água do ponto central da imagem, enquanto valores negativos a afastam do ponto central da imagem.

  • watermark_y_offset

    string | number(padrão: 0)

    O deslocamento no eixo y, em número de pixels, no qual a marca-d’água será colocada em relação à posição determinada por watermark_position.

    Os valores podem ser positivos ou negativos e produzem resultados diferentes dependendo do parâmetro watermark_position. Valores positivos aproximam a marca-d’água do ponto central da imagem, enquanto valores negativos a afastam do ponto central da imagem.

  • watermark_size

    string

    O tamanho da marca-d’água, em porcentagem, como "50%". A forma como a marca-d’água é redimensionada depende bastante de watermark_resize_strategy.

  • watermark_resize_strategy

    area | fit | stretch(padrão: "fit")

    Para explicar como as estratégias de redimensionamento funcionam, vamos supor que o tamanho de destino do vídeo seja de 800×800 pixels e que a imagem da marca-d’água tenha 400×300 pixels. Vamos supor também que o parâmetro watermark_size esteja definido como "25%".

    Na estratégia de redimensionamento "fit", a marca-d’água é redimensionada para que seu lado maior ocupe 25% do lado correspondente do vídeo. O outro lado é redimensionado de acordo com a proporção da imagem da marca-d’água. Assim, na nossa marca-d’água, a largura é o lado maior, e 25% do tamanho do vídeo seria 200px. Portanto, a marca-d’água seria redimensionada para 200×150 pixels. Se watermark_size estivesse definido como "50%", ela seria redimensionada para 400×300 pixels (ou seja, permaneceria no tamanho original).

    Na estratégia de redimensionamento "stretch", a imagem da marca-d’água é esticada (ou seja, redimensionada sem preservar sua proporção) para que ambos os lados ocupem 25% do lado correspondente do vídeo. Como nosso vídeo tem 800×800 pixels, para um tamanho de marca-d’água de 25%, a marca-d’água seria redimensionada para 200×200 pixels. Sua altura pareceria esticada, pois, se a proporção fosse preservada, ela seria redimensionada para 200×150 pixels.

    Na estratégia de redimensionamento "area", a marca-d’água é redimensionada (preservando sua proporção) para cobrir "xx%" da área da superfície do vídeo. O valor de watermark_size é usado como percentual da área.

  • watermark_start_time

    string | number(padrão: 0)

    O atraso em segundos desde o início do vídeo até a marca-d’água aparecer. Por padrão, a marca-d’água é exibida imediatamente.

  • watermark_duration

    string | number(padrão: -1)

    A duração em segundos da exibição da marca-d’água. Pode ser usada junto com watermark_start_time para criar efeitos interessantes. O valor padrão é -1.0, o que significa que a marca-d’água é exibida durante toda a duração do vídeo.

  • watermark_opacity

    string | number(padrão: 1)

    A opacidade da marca-d’água. Os valores válidos estão entre 0 (invisível) e 1.0 (visibilidade total).

  • segment

    boolean(padrão: false)

    Divide o arquivo em várias partes para uso com o HTTP Live Streaming da Apple.

  • segment_duration

    string | number(padrão: 10)

    Especifica a duração de cada segmento HTTP. Este parâmetro é opcional, e o valor padrão recomendado pela Apple é 10. Não altere esse valor sem um bom motivo.

  • segment_prefix

    string(padrão: "")

    O prefixo usado na nomenclatura. Por exemplo, o prefixo "segment_" produziria arquivos chamados "segment_0.ts", "segment_1.ts" e assim por diante. Este parâmetro é opcional e usa por padrão o nome base do arquivo de entrada. Veja também o parâmetro relacionado segment_name.

  • segment_name

    string(padrão: "")

    O nome usado para o segmento final. As variáveis disponíveis são ${segment_prefix}, ${segment_number} e ${segment_id} (que é um UUIDv4 sem hífens).

  • segment_time_delta

    string | number

    Delta a ser aplicado à duração do segmento. Este parâmetro é opcional e permite o ajuste fino dos limites dos segmentos.

Demonstrações

Publicações relacionadas no blog