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
kindstring
Identifica o tipo do recurso da API. O valor será youtube#caption.
etagetag
A Etag deste recurso.
idstring
O ID que o YouTube usa para identificar exclusivamente a faixa de legenda.
snippetobject
O objeto snippet contém detalhes básicos sobre a legenda.
snippet.videoIdstring
O ID que o YouTube usa para identificar de forma exclusiva o vídeo associado à faixa de legenda.
snippet.lastUpdateddatetime
A data e a hora em que a faixa de legenda foi atualizada pela última vez. O valor é especificado no formato ISO 8601.
snippet.trackKindstring
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.languagestring
O idioma da faixa de legenda. O valor da propriedade é uma tag de idioma BCP-47.
snippet.namestring
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.audioTrackTypestring
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.isCCboolean
Indica se a faixa contém legendas para pessoas surdas e com perda auditiva. O valor padrão é false.
snippet.isLargeboolean
Indica se a faixa de legenda usa texto grande para pessoas com deficiência visual. O valor padrão é false.
snippet.isEasyReaderboolean
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.isDraftboolean
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.isAutoSyncedboolean
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.statusstring
O status da faixa de legenda.

Os valores válidos para essa propriedade são:
  • failed
  • serving
  • syncing
snippet.failureReasonstring
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.