Converter vídeos para HLS, MPEG-Dash e CMAF

🤖/video/adaptive codifica vídeos em formatos compatíveis com HTTP Live Streaming (HLS), MPEG-Dash e CMAF e gera os arquivos de manifesto e playlist necessários.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: *

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": []
  }
]

Exemplo de uso

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded_1080p": {
      "ffmpeg_stack": "v7",
      "preset": "hls/1080p",
      "robot": "/video/encode",
      "use": ":original"
    },
    "encoded_480p": {
      "ffmpeg_stack": "v7",
      "preset": "hls/480p",
      "robot": "/video/encode",
      "use": ":original"
    },
    "encoded_720p": {
      "ffmpeg_stack": "v7",
      "preset": "hls/720p",
      "robot": "/video/encode",
      "use": ":original"
    },
    "hls_bundled": {
      "playlist_name": "my_playlist.m3u8",
      "robot": "/video/adaptive",
      "technique": "hls",
      "use": {
        "bundle_steps": true,
        "steps": [
          "encoded_480p",
          "encoded_720p",
          "encoded_1080p"
        ]
      }
    }
  }
}

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

  Dica

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

• ffmpeg

  object

  Opções personalizadas do FFmpeg são compatíveis com as técnicas "hls" e "cmaf". Opções personalizadas não vazias são rejeitadas para "dash", a técnica padrão.

  Essas opções se aplicam ao comando de empacotamento, que copia os streams de entrada por padrão. Defina as opções de codificação, como intervalos de keyframe, no Step 🤖/video/encode anterior.

• ffmpeg_stack

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

  Seleciona o stack do FFmpeg para o empacotamento. O padrão é "v7.0.0". Este Robot sempre usa pelo menos "v7.0.0"; seleções de stack mais antigas são atualizadas automaticamente.

• width

  string | number | null

  Este parâmetro não tem efeito neste Robot. Defina a largura da representação no Step 🤖/video/encode anterior.

• height

  string | number | null

  Este parâmetro não tem efeito neste Robot. Defina a altura da representação no Step 🤖/video/encode anterior.

• preset

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

  Este parâmetro não tem efeito neste Robot. Defina a predefinição de codificação no Step 🤖/video/encode anterior.

• technique

  dash | hls | cmaf(padrão: "dash")

  Determina qual técnica de streaming deve ser usada. Oferece suporte a "dash" para MPEG-Dash, "hls" para HTTP Live Streaming e "cmaf" para saída CMAF baseada em FFmpeg com manifestos MPEG-Dash e HLS que fazem referência aos mesmos segmentos fMP4.

• playlist_name

  string

  O nome do arquivo de manifesto/playlist gerado. O padrão é "playlist.mpd" se technique for "dash", e "playlist.m3u8" se technique for "hls". Para "cmaf", este valor define o nome do manifesto MPEG-Dash e tem como padrão "playlist.mpd".

• hls_playlist_name

  string

  Usado apenas quando technique é "cmaf". Define o nome do arquivo da playlist mestre HLS gerada. O padrão é "playlist.m3u8".

• segment_duration

  string | number

  A duração de cada segmento, em segundos. Quando omitido, o padrão é 4 segundos para MPEG-Dash e CMAF, e 10 segundos para HLS.

• closed_captions

  boolean(padrão: true)

  Determina se você quer suporte a legendas ocultas ao usar a técnica "hls".

• audio_group

  boolean(padrão: false)

  Quando definido como true e usado com a técnica "hls", os arquivos de entrada somente de áudio são tratados como versões de áudio alternativas em vez de variantes de stream independentes. Isso permite que os players ofereçam seleção de faixa de áudio (por exemplo, para vários idiomas). Os arquivos somente de áudio são listados como entradas #EXT-X-MEDIA:TYPE=AUDIO na playlist multivariante, e as variantes de vídeo fazem referência a eles pelo atributo AUDIO.

  Quando esta opção está ativada, as entradas de vídeo incluem apenas seu stream de vídeo nos segmentos de saída (qualquer áudio multiplexado é excluído). Forneça o áudio separadamente como arquivos de entrada somente de áudio.

  O LANGUAGE de cada versão vem da tag language do primeiro stream de áudio em seu arquivo de entrada somente de áudio, ou é "und" quando a tag está ausente. Defina a tag em 🤖/audio/encode com "ffmpeg": {"metadata:s:a:0": "language=deu"}, por exemplo.

  O primeiro arquivo de entrada somente de áudio na ordem de use.steps torna-se DEFAULT=YES; as demais versões têm DEFAULT=NO. Todas as versões de áudio têm AUTOSELECT=YES. O NAME delas usa a tag title do stream de áudio quando presente; caso contrário, usa o nome do idioma em inglês (por exemplo, "eng" torna-se “English” e "deu" torna-se “German”). O áudio sem tag recebe o nome “Unknown”; códigos de idioma não reconhecidos são usados como nome. Nomes duplicados recebem um sufixo numérico.

  Esta opção só habilita versões de áudio alternativas com a técnica "hls" e não altera o empacotamento com "dash" ou "cmaf". O CMAF coloca todo o áudio em um único conjunto de adaptação rotulado com o primeiro idioma de áudio. Definir audio_group: true com CMAF, ou fornecer entradas CMAF com mais de um idioma de áudio conhecido (incluindo faixas multiplexadas em um único vídeo), adiciona um aviso à Assembly; o empacotamento continua com a saída CMAF existente. Para áudio em vários idiomas, use technique: "hls" com audio_group: true.

Demonstrações

Publicações relacionadas no blog