Adicionar legendas a vídeos

🤖/video/subtitle adiciona legendas e legendas ocultas a vídeos.

Exemplo de uso

{
  "steps": {
    "captioned": {
      "ffmpeg_stack": "v7",
      "preset": "empty",
      "robot": "/video/subtitle",
      "style": "social",
      "subtitles_type": "burned",
      "use": {
        "steps": [
          {
            "as": "video",
            "name": ":original"
          },
          {
            "as": "subtitles",
            "name": "transcript"
          }
        ]
      }
    },
    "transcript": {
      "format": "json",
      "provider": "aws",
      "robot": "/speech/transcribe",
      "source_language": "en-US",
      "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"
        }
      ]
    }
    

  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 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 | mais 195 ↓

  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.

• subtitles_type

  burned | external | burn(padrão: "external")

  Determina se as legendas são adicionadas ao vídeo como um fluxo separado (valor "external"), que pode ser ativado e desativado no seu player de vídeo, ou se devem ser gravadas diretamente no vídeo (valor "burned" ou "burn"), tornando-se parte do fluxo de vídeo.

• style

  social

  Aplica uma aparência pronta para legendas gravadas no vídeo: texto em Poppins com peso alto, contorno espesso e sombra preta suave. As legendas JSON são renderizadas em maiúsculas no terço inferior. Por padrão, o dimensionamento da fonte das legendas JSON usa o lado menor do vídeo e ajusta cada legenda à largura segura, dando preferência a uma linha e usando no máximo duas. As palavras nunca são divididas. Cada legenda cresce de 85% até o tamanho completo ao longo de 120 milissegundos; depois, suas palavras permanecem no lugar enquanto o destaque muda de cor. O arquivo de transcrição é preservado. Os parâmetros de estilo existentes substituem a predefinição; um valor explícito de font_size desativa o ajuste automático. Arquivos ASS mantêm seus próprios estilos. Com JSON com marcações de tempo de /speech/transcribe, a palavra ativa fica destacada até o início da próxima palavra ou legenda; as outras palavras usam font_color. Vírgulas e pontos finais no fim das legendas JSON com estilo social são omitidos; pontos de interrogação e de exclamação são preservados. O destaque e o agrupamento de palavras exigem entrada JSON.

• highlight_color

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

  A cor de destaque da palavra ativa nas legendas JSON. Aplica-se apenas a legendas JSON gravadas no vídeo. Com "style": "social", a palavra anterior permanece destacada durante intervalos curtos até o início da próxima palavra ou legenda. Sem o estilo social, os intervalos usam font_color para toda a legenda.

  Use o formato "rgb", "rrggbb" ou "aarrggbb", opcionalmente com o prefixo #. Cores de três dígitos são expandidas para seis dígitos. Cores sem alfa são totalmente opacas. Em cores de oito dígitos, os dois primeiros dígitos especificam a transparência ("00" é totalmente opaco, "ff" é totalmente transparente).

• max_words_per_caption

  string | number(padrão: 3)

  O número máximo desejado de palavras do JSON com marcações de tempo exibidas em uma legenda. As legendas terminam antes desse limite em pontuações de fim de frase ou pausas superiores a 0,4 segundos. Com "style": "social", uma palavra funcional do inglês no final da legenda, como “by”, “to” ou “the”, é movida para a próxima legenda quando possível. Expressões curtas como “line of code” podem permanecer juntas, e uma palavra isolada no fim de uma frase pode ser incorporada à legenda anterior. Esses ajustes permitem no máximo uma palavra extra por legenda, sem ultrapassar finais de frase ou pausas longas. Legendas de uma única palavra são preservadas quando o limite é 1. Uma legenda permanece visível até o início da próxima quando a pausa é de no máximo 0,4 segundos, e desaparece ao término de sua última palavra durante pausas mais longas. Não altera os blocos de legenda SRT, VTT ou ASS.

• border_style

  box | outline | shadow(padrão: "outline")

  Especifica o estilo da legenda. Use o parâmetro border_color para especificar a cor da borda.

• border_color

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

  A cor da borda da legenda. O padrão é preto opaco. Aplica-se apenas a legendas gravadas no vídeo.

  Use o formato "rgb", "rrggbb" ou "aarrggbb", opcionalmente com o prefixo #. Cores de três dígitos são expandidas para seis dígitos. Cores sem alfa são totalmente opacas. Em cores de oito dígitos, os dois primeiros dígitos especificam a transparência ("00" é totalmente opaco, "ff" é totalmente transparente).

• font

  string

  A família de fontes a usar. Também inclui o peso e o estilo da fonte. O padrão é Arial. Com "style": "social", o padrão é Poppins, usando seu peso ExtraBold para legendas JSON. Uma fonte explícita substitui o estilo.

  Aqui está uma lista de todas as fontes compatíveis.

• font_color

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

  A cor do texto da legenda. Aplica-se apenas a legendas gravadas no vídeo.

  Use o formato "rgb", "rrggbb" ou "aarrggbb", opcionalmente com o prefixo #. Cores de três dígitos são expandidas para seis dígitos. Cores sem alfa são totalmente opacas. Em cores de oito dígitos, os dois primeiros dígitos especificam a transparência ("00" é totalmente opaco, "ff" é totalmente transparente).

• font_size

  string | number

  Especifica o tamanho do texto no espaço de coordenadas das legendas de 288 pixels, dimensionado conforme a altura do vídeo. O padrão é 16. Com "style": "social", o padrão é 54. Para legendas JSON com estilo social, quando o valor é omitido, esse padrão é dimensionado conforme o lado menor do vídeo, aumentado em 18% para vídeos na orientação retrato, e as legendas são reduzidas conforme necessário para caber em no máximo duas linhas. As letras maiúsculas de Poppins medem cerca de 7,5% do lado menor antes do ajuste, ou cerca de 9% para vídeos na orientação retrato. Um valor explícito mantém o dimensionamento relativo à altura e desativa o ajuste automático.

• bold

  boolean

  Especifica se o texto da legenda deve ficar em negrito. Aplica-se apenas a legendas gravadas diretamente no vídeo. O padrão é false. Com "style": "social", o padrão é true; um valor explícito de false substitui o estilo.

• italic

  boolean(padrão: false)

  Especifica se o texto da legenda deve ficar em itálico. Aplica-se apenas a legendas gravadas diretamente no vídeo.

• outline_width

  string | number | null

  Especifica a largura do contorno do texto no espaço de coordenadas das legendas de 288 pixels, dimensionado conforme a altura do vídeo. Strings numéricas como "4" também são aceitas. Aplica-se apenas a legendas gravadas no vídeo com os estilos de borda "outline" ou "box". Se for omitido ou null, será usada a largura padrão (2 com "style": "social", proporcional ao tamanho final ajustado da fonte para legendas JSON com estilo social).

• position

  bottom | bottom-left | bottom-right | center | left | right | top | mais 2 ↓(padrão: "bottom")

  Especifica a posição das legendas. Com "style": "social", a posição inferior padrão coloca as legendas JSON no terço inferior, com espaço livre adicional na parte inferior em vídeos na orientação retrato. Um valor explícito substitui o estilo.

• language

  string | null

  Especifica o idioma do fluxo de legenda usando um código de idioma de três letras (por exemplo, "eng", "deu", "spa"). Usado apenas se as legendas forem externas. Ao adicionar vários fluxos de legenda, defina um idioma diferente para cada fluxo para que os players de vídeo possam oferecer a seleção de idioma.

• name

  string | null

  Especifica um nome legível para a faixa de legenda (por exemplo, "English", "Deutsch", "Español"). Usado apenas se as legendas forem externas. Esse nome é exibido nos menus de legendas dos players de vídeo junto ao idioma.

• keep_subtitles

  boolean(padrão: false)

  Especifica se as legendas existentes no arquivo de entrada devem ser mantidas ou substituídas pela nova legenda. Usado apenas se as legendas forem externas. Defina este parâmetro como true ao encadear vários Steps com /video/subtitle para adicionar vários fluxos de legenda (por exemplo, em idiomas diferentes) ao mesmo vídeo.

Demonstrações

Publicações relacionadas no blog