Mesclar vídeo, áudio e imagens em um único vídeo

🤖/video/merge compõe um novo vídeo adicionando uma faixa de áudio a uma ou mais imagens estáticas ou a um vídeo existente.

Exemplo de uso

{
  "steps": {
    "merged": {
      "duration": 12,
      "framerate": "1/4",
      "height": 720,
      "resize_strategy": "pad",
      "robot": "/video/merge",
      "use": [
        {
          "as": "image",
          "name": ":original"
        },
        {
          "as": "audio",
          "name": ":original"
        }
      ],
      "width": 1280
    }
  }
}

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")

  Se os parâmetros de largura/altura fornecidos forem maiores que as dimensões da imagem de entrada, resize_strategy determinará como a imagem será redimensionada para corresponder à largura/altura fornecida. Veja as estratégias de redimensionamento disponíveis.

• 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.

• framerate

  string | number | string(padrão: "1/5")

  Ao combinar imagens para gerar um vídeo, esta é a taxa de quadros de entrada. Um valor de “1/5” significa que cada imagem é exibida por 5 segundos antes de o próximo quadro aparecer (o inverso de uma taxa de quadros de “5”). O mesmo vale para “1/10”, “1/20”, etc. Um valor de “5” significa que há 5 quadros por segundo.

• image_durations

  Array<string | number>(padrão: [])

  Ao combinar imagens para gerar um vídeo, este parâmetro permite definir por quanto tempo (em segundos) cada imagem será exibida no vídeo. Assim, se você passar 3 imagens e definir [2.4, 5.6, 9], a primeira imagem será exibida por 2,4 s, a segunda por 5,6 s e a última por 9 s. O parâmetro duration será definido automaticamente como a soma de image_durations, ou seja, 17 no nosso exemplo. Esse valor ainda pode ser sobrescrito; nesse caso, a última imagem será exibida até que a duração definida seja atingida.

• duration

  string | number | null(padrão: null)

  Ao combinar imagens para gerar um vídeo ou ao combinar áudio e vídeo, esta é a duração de destino desejada em segundos. O valor de ponto flutuante pode ter uma casa decimal. Se você quiser que todas as imagens sejam exibidas exatamente uma vez, poderá definir a duração de acordo com esta fórmula: duration = numberOfImages / framerate. Isso também funciona para valores inversos de taxa de quadros, como 1/5.

  Se você definir este valor como null (padrão), a duração do arquivo de áudio de entrada será usada ao combinar imagens com um arquivo de áudio.

  Ao combinar arquivos de áudio e de vídeo, a duração do arquivo de vídeo ou de áudio mais longo é usada por padrão.

• audio_delay

  string | number(padrão: 0)

  Ao combinar um vídeo e um arquivo de áudio, ou imagens e um arquivo de áudio para gerar um vídeo, este é o atraso desejado em segundos para o arquivo de áudio começar a tocar. Imagine que você combine um arquivo de vídeo sem som e um arquivo de áudio, mas queira que o áudio comece a tocar após 5 segundos, e não imediatamente. Este é o parâmetro a ser usado nesse caso.

• loop

  boolean(padrão: false)

  Determina se o arquivo de mídia mais curto deve ser repetido em loop para corresponder à duração do mais longo. Por exemplo, se você combinar um vídeo de 1 minuto com um arquivo de áudio de 3 minutos e ativar esta opção, o vídeo será reproduzido três vezes seguidas para corresponder à duração do áudio.

• replace_audio

  boolean(padrão: false)

  Determina se o áudio do vídeo deve ser substituído por um arquivo de áudio fornecido.

• vstack

  boolean(padrão: false)

  Empilha a mídia de entrada verticalmente. Todos os fluxos precisam ter o mesmo formato de pixel e a mesma largura, portanto, considere usar um Step com /video/encode antes de usar este parâmetro para garantir isso.

• image_url

  string

  A URL de uma imagem a ser combinada com o áudio ou vídeo. Quando este parâmetro é fornecido, o Robot baixa a imagem da URL e a combina com as outras mídias.

• sort_by

  auto | basename | import_order(padrão: "basename")

  Controla como as entradas agrupadas são ordenadas quando nenhum alias numerado explícito para o tipo de entrada é usado. Aliases numerados terminam com um sufixo numérico, como _1.

  O padrão "basename" mantém o comportamento legado de ordenação natural por basename.

  Defina como "import_order" para preservar a ordem dos Steps de importação baseados em array quando todos os arquivos de entrada carregarem metadados completos de ordem de importação. "auto" tem a mesma preferência de ordem de importação, com ordenação natural por basename como fallback.

• transition

  none | crossfade | fade_to_black(padrão: "none")

  O tipo de efeito de transição a aplicar entre clipes de vídeo concatenados. Aplica-se apenas ao concatenar vários vídeos (usando video_1, video_2, etc. ou entradas pre_roll/post_roll).

  • "none" — Sem efeito de transição. Os vídeos são unidos em sequência.
  • "crossfade" — Uma mesclagem gradual de um clipe para o próximo (tanto de vídeo quanto de áudio).
  • "fade_to_black" — O clipe atual desaparece gradualmente até o preto, e então o próximo clipe aparece gradualmente a partir do preto.

• transition_duration

  string | number(padrão: 1)

  A duração do efeito de transição em segundos. Aplica-se apenas quando transition não é "none". Aceita valores de ponto flutuante (por exemplo, 0.5 para uma transição de 500 ms) e deve ser maior que 0 sempre que as transições estiverem habilitadas. A transição aplicada é automaticamente limitada à metade da duração do clipe mais curto em cada par de transição para evitar transições sobrepostas.

Demonstrações

Publicações relacionadas no blog