Captions

Observação:em 5 de agosto de 2022, o YouTube anunciou que mudou a forma como os IDs de legendas são gerados e, como parte dessa mudança, está atribuindo novos IDs a todas as faixas de legenda. Consulte o histórico de revisões da API para mais detalhes.

Um recurso caption representa uma faixa de legenda do YouTube. Uma faixa de legenda está associada a exatamente um vídeo do YouTube.

Métodos

A API é compatível com os seguintes métodos para recursos captions:

list
Recuperar uma lista de faixas de legendas associadas a um vídeo especificado. A resposta da API não contém as legendas reais e o método captions.download fornece a capacidade de recuperar uma faixa de legenda. Faça um teste.
inserir
Faça upload de uma faixa de legenda.
update
Atualizar uma faixa de legenda. Ao atualizar uma faixa de legenda, é possível alterar o status de rascunho da faixa, fazer upload de um novo arquivo de legenda para a faixa ou ambos.
delete
Excluir uma faixa de legenda especificada. Faça um teste agora.
fazer download
Fazer o download de uma faixa de legenda. A faixa de legenda é retornada no formato original, a menos que a solicitação especifique um valor para o parâmetro tfmt e no idioma original, a menos que a solicitação especifique um valor para o parâmetro tlang.

Representação de recurso

A estrutura JSON a seguir mostra o formato de um recurso captions:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

Propriedades

A tabela a seguir define as propriedades que aparecem neste recurso:

Propriedades
kind string
Identifica o tipo do recurso da API. O valor será youtube#caption.
etag etag
A ETag deste recurso.
id string
O ID que o YouTube usa para identificar de forma exclusiva a faixa de legenda.
snippet object
O objeto snippet contém detalhes básicos sobre a legenda.
snippet.videoId string
O ID que o YouTube usa para identificar de forma exclusiva o vídeo associado à faixa de legenda.
snippet.lastUpdated datetime
Data e hora em que a faixa de legenda foi atualizada pela última vez. O valor é especificado no formato ISO 8601.
snippet.trackKind string
O tipo de faixa de legenda.

Os valores válidos para essa propriedade são:
  • ASR: uma faixa de legenda gerada usando o reconhecimento de fala automático.
  • forced: uma faixa de legenda que é reproduzida quando nenhuma outra faixa está selecionada no player. Por exemplo, um vídeo que mostra alienígenas falando em um idioma alienígena pode ter uma faixa de legenda forçada para mostrar apenas legendas nesse idioma.
  • standard: uma faixa de legenda normal. Esse é o valor padrão.
snippet.language string
Idioma da faixa de legenda. O valor da propriedade é uma tag de idioma BCP-47.
snippet.name string
O nome da faixa de legenda. O nome precisa ficar visível para o usuário como uma opção durante a reprodução.
snippet.audioTrackType string
O tipo de faixa de áudio associada à faixa de legenda.

Os valores válidos para essa propriedade são:
  • commentary: a faixa de legenda corresponde a uma faixa de áudio alternativa que inclui comentário, como o comentário no diretório.
  • descriptive – A faixa de legenda corresponde a uma faixa de áudio alternativa que inclui áudio descritivo adicional.
  • primary – A faixa de legenda corresponde à faixa de áudio principal do vídeo, que é normalmente a faixa de áudio normalmente associada ao vídeo.
  • unknown: esse é o valor padrão.
snippet.isCC boolean
Indica se a faixa contém legendas para pessoas surdas e com perda auditiva. O valor padrão é false.
snippet.isLarge boolean
Indica se a faixa de legenda usa texto grande para pessoas com deficiência visual. O valor padrão é false.
snippet.isEasyReader boolean
Indica se a faixa de legenda está formatada para "leitor fácil", o que significa que ela está no nível secundário para alunos de idiomas. O valor padrão é false.
snippet.isDraft boolean
Indica se a faixa de legenda é um rascunho. Se o valor for true, a faixa não está visível publicamente. O valor padrão é false.
snippet.isAutoSynced boolean
Indica se o YouTube sincronizou a faixa de legenda com a faixa de áudio no vídeo. O valor será true se uma sincronização foi solicitada explicitamente quando a faixa de legenda foi enviada. Por exemplo, ao chamar os métodos captions.insert ou captions.update, você pode definir o parâmetro sync como true para instruir o YouTube a sincronizar a faixa enviada com o vídeo. Se o valor for false, o YouTube usará os códigos de tempo na faixa de legenda enviada para determinar quando exibir as legendas.
snippet.status string
O status da faixa de legenda.

Os valores válidos para essa propriedade são:
  • failed
  • serving
  • syncing
snippet.failureReason string
O motivo da falha do YouTube ao processar a faixa de legenda. Esta propriedade só estará presente se o valor da propriedade state for failed.

Os valores válidos dessa propriedade são:
  • processingFailed – O YouTube não conseguiu processar a faixa de legenda enviada.
  • unknownFormat: o formato da faixa de legenda não foi reconhecido.
  • unsupportedFormat: não há suporte para o formato da faixa de legenda.