Captions

Observação:em 13 de março de 2024, o YouTube anunciou que o parâmetro sync para os endpoints da API captions.insert e captions.update será descontinuado. A sincronização automática de legendas ainda está disponível no YouTube Studio. 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 é associada a exatamente um vídeo do YouTube.

Métodos

A API oferece suporte aos seguintes métodos para recursos captions:

list
Recuperar uma lista de faixas de legenda associadas a um vídeo específico. A resposta da API não contém as legendas reais, e o método captions.download permite recuperar uma faixa de legenda. Teste agora.
inserir
Faça upload de uma faixa de legenda. Faça um teste agora.
update
Atualizar uma faixa de legenda. Ao atualizar uma faixa de legenda, você pode mudar o status de rascunho dela, fazer upload de um novo arquivo de legenda ou fazer as duas coisas. Teste agora.
download
Faça 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. Teste agora.
delete
Excluir uma faixa de legenda específica. Faça um teste agora.

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 exclusivamente 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
A data e a hora em que a faixa de legenda foi atualizada pela última vez. O valor é especificado no formato ISO 8601.
snippet.trackKind string
O tipo da faixa de legenda.

Os valores válidos para essa propriedade são:
  • ASR: uma faixa de legenda gerada usando o reconhecimento automático de fala.
  • 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 uma língua 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
O 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 deve ser visível para o usuário como uma opção durante a reprodução. O comprimento máximo do nome é de 150 caracteres.
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ários, como comentários de diretório.
  • descriptive: a faixa de legenda corresponde a uma faixa de áudio alternativa que inclui áudio descritivo extra.
  • primary: a faixa de legenda corresponde à faixa de áudio principal do vídeo, que é a faixa de áudio normalmente associada ao vídeo.
  • unknown: é 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", ou seja, se está no nível do terceiro ano para estudantes 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 vai ficar 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 tiver sido 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 vai usar os códigos de tempo na faixa de legendas enviada para determinar quando mostrar 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 pelo qual o YouTube não conseguiu processar a faixa de legenda. Essa propriedade só vai estar presente se o valor da propriedade state for failed.

Os valores válidos para essa 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.