Captions

Observação:em 13 de março de 2024, o YouTube anunciou que ele vai descontinuar o parâmetro sync para o captions.insert e Endpoints da API captions.update. A sincronização automática de legendas ainda está disponível no YouTube Creator Studio. Consulte a Histórico de revisões da API para mais detalhes.

O 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 legenda associadas a um vídeo específico. A resposta da API não contém as legendas reais e que o método captions.download fornece a capacidade de recuperar uma faixa de legenda. Faça um teste agora.
inserir
Faça upload de uma faixa de legenda.
update
Atualizar uma faixa de legenda. Ao atualizar uma faixa de legenda, é possível mudar o status de rascunho da faixa, fazer upload de um novo arquivo de legenda ou ambos.
delete
Exclui uma faixa de legenda especificada. Faça um teste agora.
fazer 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.

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 de 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
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 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 comum. 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 visa ficar visível para o usuário como uma opção durante a reprodução. O comprimento máximo de nome permitido é 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 adicional.
  • primary – A faixa de legenda corresponde à faixa de áudio principal do vídeo, que é 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 deficientes visuais. O valor padrão é false.
snippet.isEasyReader boolean
Indica se a faixa de legenda está formatada para "fácil de ler", ou seja, está no 3o 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 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 do 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, defina 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 pelo qual o YouTube não conseguiu processar a faixa de legenda. Esta propriedade só vai estar presente se o valor de state for failed.

Os valores válidos para essa propriedade são:
  • processingFailed – O YouTube falhou ao processar a faixa de legenda enviada.
  • unknownFormat – O formato da faixa de legenda não foi reconhecido.
  • unsupportedFormat – O formato da faixa de legenda não é compatível.