Captions

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

Métodos

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

list
Recupera uma lista de faixas de legendas associadas a um vídeo especificado. 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. Teste agora mesmo.
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 do rascunho, fazer upload de um novo arquivo de legenda ou ambos.
excluir
Exclua 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 desse 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 de fala automático.
  • forced: uma faixa de legenda que é tocada 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 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 precisa ficar visível para o usuário como uma opção durante a reprodução. O nome máximo aceito é 150 caracteres.
snippet.audioTrackType string
O tipo de faixa de áudio associado à 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.
  • primary – A faixa de legenda corresponde à faixa de áudio principal do vídeo, que é normalmente associada ao vídeo.
  • unknown: esse é o valor padrão.
snippet.isCC boolean
Indica se a faixa contém legendas para surdos e pessoas 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 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 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 vai 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 usa 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 processou a faixa de legenda. Essa propriedade só estará presente se o valor da propriedade state for failed.

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