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.

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

Exemplo de uso

{
  "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 exige mais 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 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 computacionalmente barata field_order do ffprobe 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"
        }
      ]
    }
    

  Dica

  Provavelmente é tudo o que você precisa saber sobre use, mas você pode ver os casos de uso avançados.

• 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 EN (English) 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 EN (English) por preset.

• preset

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

  Converte um vídeo de acordo com configurações predefinidas EN (English).

  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 quadrado 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 para Jobs adicionais e pode ser contraproducente para arquivos de vídeo muito pequenos.

• 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 para Jobs. Por exemplo, quanto maior a duração de cada trecho, menos Jobs de codificação precisarão ser usados.

• 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 | mais 2 ↓ | Array<bottom | bottom-left | bottom-right | center | left | right | top | mais 2 ↓>(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