Implementação: legendas

Os exemplos a seguir mostram como usar a API de dados do YouTube (v3) para executar funções relacionadas às legendas.

Recuperar uma lista de faixas de legenda de um vídeo

Para recuperar uma lista de faixas de legendas disponíveis para um vídeo específico, chame o método captions.list. Defina o valor do parâmetro videoId para o ID do vídeo do YouTube que identifica exclusivamente o vídeo para o qual você está recuperando legendas. Sua solicitação precisa ser autorizada usando o OAuth 2.0.

A solicitação abaixo recupera uma lista de legendas ocultas para um vídeo no canal do YouTube das histórias do Google:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.list?
part=snippet
&videoId=PRU2ShMzQRg

Consulte a documentação do método captions.list para ver exemplos de código.

Criar uma faixa de legenda

Não é possível testar essa consulta usando o APIs Explorer porque ele não é compatível com o upload de arquivos, que é um requisito desse método.

Você pode usar o método captions.insert da API para enviar uma nova faixa de legenda para um vídeo. Ao fazer upload de uma faixa, é necessário especificar um valor para as seguintes propriedades de recurso caption:

As seguintes opções adicionais estão disponíveis no envio de faixas de legenda:

  • Se você definir o parâmetro sync como true, o YouTube vai ignorar os códigos de tempo que estão no arquivo de legenda enviado e gerar novos códigos de tempo para as legendas.

    Defina o parâmetro sync como true se você estiver fazendo upload de uma transcrição sem códigos de tempo ou se suspeitar que os códigos de arquivo no seu arquivo estão incorretos e quiser que o YouTube tente corrigi-los.

  • Se você definir a propriedade snippet.isDraft do recurso caption como true, a faixa não ficará visível publicamente.

Consulte a documentação do método captions.insert para ver exemplos de código.

Fazer o download de uma faixa de legenda

Não é possível testar esta consulta usando o APIs Explorer porque o APIs Explorer não é compatível com o recurso de download de arquivos.

Para fazer o download de uma faixa de legenda específica, chame o método captions.download. Defina o valor do parâmetro id como o ID da faixa de legenda do YouTube que identifica de forma exclusiva a faixa de legenda que você está baixando. Sua solicitação precisa ser autorizada usando o OAuth 2.0.

A API v3 é compatível com as seguintes opções:

  • Para especificar que uma faixa de legenda precisa ser retornada em um formato específico, defina o valor do parâmetro tfmt para identificar o formato pretendido. A definição do parâmetro lista os valores compatíveis.

  • Para recuperar uma tradução de uma faixa de legenda, defina o valor do parâmetro tlang como um código de idioma de duas letras ISO 639-1 que identifique o idioma da legenda. A tradução é gerada usando uma tradução automática, como o Google Tradutor.

Consulte a documentação do método captions.download para ver exemplos de código.

Atualizar uma faixa de legenda

A API é compatível com a capacidade de alterar o status de rascunho de uma faixa de legenda, fazer upload de uma nova faixa de legenda para um arquivo ou ambas.

Você pode usar o APIs Explorer para testar a capacidade de alterar o status de rascunho de uma faixa. No entanto, não é possível usar o APIs Explorer para atualizar a faixa de legenda real porque a ferramenta não tem suporte à capacidade de upload de arquivos.

A solicitação abaixo recupera uma lista de legendas ocultas para um vídeo no canal do YouTube das histórias do Google:

A solicitação atualiza o status do rascunho de uma faixa de legenda para true, o que significa que a faixa não ficará visível ao público. Para concluir a solicitação no APIs Explorer, você precisa definir o valor da propriedade id para identificar uma faixa de legenda.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.update?
part=snippet

Consulte a documentação do método captions.update para ver exemplos de código.

Excluir uma faixa de legenda

Este exemplo mostra como excluir uma faixa de legenda. O exemplo tem as seguintes etapas: