Extrair miniaturas de vídeos

🤖/video/thumbs extrai qualquer quantidade de imagens de vídeos para uso como prévias.

Exemplo de uso

{
  "steps": {
    "thumbnailed": {
      "count": 3,
      "ffmpeg_stack": "v7",
      "robot": "/video/thumbs",
      "smart": true,
      "smart_max_candidates": 12,
      "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.

• count

  string | number(padrão: 8)

  O número de miniaturas a extrair. Como alguns vídeos têm durações incorretas, o número real de miniaturas geradas pode ser menor em casos raros. O número máximo de miniaturas que permitimos atualmente é 999.

  As miniaturas são extraídas em intervalos regulares, determinados pela divisão da duração do vídeo pela quantidade. Por exemplo, uma quantidade de 3 produzirá miniaturas em 25%, 50% e 75% ao longo do vídeo.

  Para extrair miniaturas em instantes específicos, use o parâmetro offsets.

• offsets

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

  Um array de deslocamentos que representam segundos da duração do arquivo, como [ 2, 45, 120 ]. Também é possível usar durações em milissegundos com valores decimais. Por exemplo, um deslocamento de 1250 milissegundos seria representado por 1.25. Os deslocamentos também podem ser valores percentuais, como [ "2%", "50%", "75%" ].

  Esta opção não pode ser usada com o parâmetro count e tem precedência se ambos forem especificados. Deslocamentos fora do intervalo são ignorados silenciosamente.

  Quando smart é true, a seleção inteligente ignora offsets e usa count para selecionar entre seus próprios instantes candidatos. Se nenhum candidato da seleção inteligente puder ser extraído, o Robot recorre à extração padrão, na qual offsets tem precedência. Use smart: false para extrair consistentemente os instantes especificados.

• format

  jpeg | jpg | png(padrão: "jpeg")

  O formato da miniatura extraída. Os valores aceitos são "jpg", "jpeg" e "png". Mesmo que você especifique o formato como "jpeg", as miniaturas resultantes terão a extensão de arquivo "jpg".

• width

  string | number

  A largura da miniatura, em pixels. O padrão é a largura original do vídeo.

• height

  string | number

  A altura da miniatura, em pixels. Por padrão, usa a altura original do vídeo.

• resize_strategy

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

  Uma das estratégias de redimensionamento disponíveis.

• background

  string(padrão: "#00000000")

  A cor de fundo das miniaturas resultantes no formato "rrggbbaa" (vermelho, verde, azul, alfa) quando usada com a estratégia de redimensionamento "pad". A cor padrão é preta.

• rotate

  0 | 90 | 180 | 270 | 360(padrão: 0)

  Força a rotação do vídeo pelo número inteiro de graus especificado. Atualmente, apenas múltiplos de 90 são aceitos. 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.

• input_codec

  string

  Especifica o codec de entrada a usar ao decodificar o vídeo. Isso é útil para vídeos com codecs especiais que exigem decodificadores específicos.

• smart

  boolean(padrão: false)

  Quando definido como true, habilita a seleção inteligente de miniaturas com IA. Em vez de retornar miniaturas em intervalos regulares, o Robot analisará quadros candidatos e selecionará os mais atraentes visualmente.

  A IA avalia os quadros com base em:

  • Nitidez visual (evitando quadros desfocados ou escuros)
  • Qualidade da composição
  • Presença de rostos e expressões
  • Ação e movimento (evitando quadros de transição)
  • Interesse visual geral

  As cobranças normais de processamento de /video/thumbs continuam sendo aplicadas. A análise de quadros por IA é cobrada separadamente pelo custo do provedor utilizado mais um acréscimo de 50% da Transloadit. Você não precisa fornecer credenciais de IA.

  O modo inteligente gera seus próprios instantes candidatos em intervalos regulares; use smart: false com offsets quando precisar de instantes especificados. As miniaturas escolhidas pela seleção inteligente são retornadas em ordem cronológica, não por pontuação. Inspecione meta.thumb_offset, meta.smart_score e meta.smart_reasons ao avaliar a seleção.

  Se a pontuação por IA falhar, o Robot seleciona entre os candidatos extraídos em ordem cronológica e registra o motivo de ter recorrido à alternativa. Se nenhum candidato puder ser extraído, ele tenta a extração padrão de miniaturas. Uma Assembly concluída não garante uma imagem de pôster representativa ou segura para publicação; verifique se existem arquivos de saída e aplique a política de revisão da sua aplicação.

• smart_max_candidates

  string | number(padrão: 20)

  O tamanho máximo do conjunto de candidatos quando smart é true. O Robot analisa até três candidatos por miniatura solicitada, limitado por este valor, mas nunca analisa menos candidatos do que o valor solicitado de count.

  Um número maior pode gerar resultados melhores, mas aumenta o tempo de processamento e o custo de IA. Com os valores padrão de count: 8 e smart_max_candidates: 20, o Robot analisa 20 quadros e retorna os melhores 8 em ordem cronológica.

  Este parâmetro só é usado quando smart é true.

Demonstrações

Publicações relacionadas no blog