A API YouTube Live Streaming permite criar, atualizar e gerenciar eventos ao vivo no YouTube. Usando a API, você pode agendar eventos (transmissões) e associá-los a streams de vídeo, que representam o conteúdo da transmissão real.
A API Live Streaming é composta por componentes das APIs de dados do YouTube e do Content ID. A API Data permite que os usuários gerenciem as contas do YouTube, enquanto o YouTube Content ID API permite interações com o sistema de gerenciamento de direitos do YouTube. No entanto, todos os recursos que compõem a API de transmissão ao vivo são usados somente para criar e gerenciar eventos ao vivo.
Este documento é destinado a desenvolvedores que querem criar aplicativos para facilitar a transmissão ao vivo no YouTube. Ele explica os conceitos básicos do YouTube e da própria API. Também fornece uma visão geral das diferentes funções que a API suporta.
Principais conceitos
- transmite
- Uma transmissão representa um evento que pode ser visto no YouTube no momento em que ele acontece. As transmissões também podem ser gravadas e salvas como vídeos do YouTube para que os usuários possam assisti-los depois que acontecem.
- córregos
- Um stream identifica o conteúdo de áudio e vídeo que está sendo comunicado ao YouTube. Cada transmissão está associada a um stream de vídeo.
- pontos de inserção
- Um ponto de inserção representa um intervalo de anúncio que pode ser inserido em uma transmissão ao vivo.
Casos de uso da API
A lista abaixo sugere várias maneiras de usar a API em seu aplicativo:
-
Agende transmissões e defina configurações de transmissão. Seu aplicativo pode permitir que os usuários predefinam configurações de transmissão e selecionem as configurações que serão aplicadas a uma determinada transmissão.
-
Associe streams de vídeo e transmissões.
-
Permita que as emissoras definam informações sobre uma transmissão e seu vídeo (usando a API de dados do YouTube) ao mesmo tempo.
-
Simplifique as transições entre estados de transmissão (
testing
,live
etc.) e permita que os usuários insiram marcadores.
Antes de começar
-
Você precisa de uma Conta do Google para acessar o Google API Console, solicitar uma chave de API e registrar o aplicativo.
-
Registre seu aplicativo no Google para que ele possa enviar solicitações de API.
-
Depois de registrar seu aplicativo, selecione o YouTube Data API como um dos serviços que seu aplicativo usa:
- Acesse o API Console e selecione o projeto que você acabou de registrar.
- Acesse a página APIs ativadas. Na lista de APIs, verifique se o status está ATIVADO na API YouTube Data v3 e, se você for um parceiro de conteúdo, na API Content ID.
-
Familiarize-se com os conceitos fundamentais do formato de dados JSON (JavaScript Object Notation, Notação de objeto do JavaScript). JSON é um formato de dados comum e independente de linguagem que fornece uma representação de texto simples de estruturas de dados arbitrárias. Para mais informações, acesse json.org.
Como autorizar solicitações de API
Conforme mencionado acima, a API Live Streaming usa funcionalidades que, tecnicamente, fazem parte da API de dados do YouTube ou da API do Content ID do YouTube. Você pode usar a API Content ID para fornecer ao YouTube metadados, informações de propriedade e informações sobre a política de seus recursos. (a transmissão de vídeo ao vivo é um exemplo de recurso). A API também permite que você reivindique vídeos e defina políticas de anúncios para seus vídeos.
Esta seção explica os requisitos de autorização para solicitações para o Content ID API, que são diferentes dos requisitos para autorizar outras solicitações Live Streaming API.
- Chamando o Data API
- A solicitação de API precisa ser autorizada pela Conta do Google proprietária do canal de transmissão do YouTube.
- Chamando o Content ID API
- A solicitação de API precisa ser autorizada por uma Conta do Google vinculada ao proprietário do conteúdo que é proprietário do canal de transmissão do YouTube.
Recursos e tipos de recursos
Um recurso é uma entidade individual de dados com um identificador exclusivo. A tabela abaixo descreve os
diferentes tipos de recursos com que você vai interagir usando o
Live Streaming API. Tecnicamente, todos esses recursos são
definidos como parte de YouTube Data API
ou YouTube Content ID API. No entanto, os
recursos liveBroadcast
,
liveStream
e
cuepoint
são usados apenas para
criar e gerenciar eventos ao vivo.
Recursos | |
---|---|
liveBroadcast |
Contém informações sobre um evento que você está transmitindo no YouTube. Um recurso liveBroadcast é uma extensão de um recurso de vídeo do YouTube e define metadados de vídeo que seriam pertinentes para uma transmissão ao vivo, mas não para outros vídeos do YouTube.Sendo assim, um recurso liveBroadcast corresponde exatamente a um recurso de vídeo do YouTube.
Na verdade, os recursos liveBroadcast
e video compartilham o
mesmo ID. Além disso, depois de criar a transmissão com a API Live Streaming, você poderá usar a
API YouTube Data para fornecer metadados adicionais sobre o vídeo. |
liveStream |
Contém informações sobre o stream de vídeo que você está transmitindo para o YouTube. O stream fornece o conteúdo que será transmitido para os usuários do YouTube. Depois de criado, o recurso liveStream pode ser vinculado a exatamente um recurso liveBroadcast . Da mesma forma, o recurso liveBroadcast só pode ser vinculado a um recurso liveStream . |
cuepoint |
Insere um marcador no stream de vídeo de transmissão, o que pode acionar um intervalo comercial. Use o método
liveBroadcasts.cuepoint
para inserir um marcador durante uma transmissão.
|
video |
Representa um vídeo simples do YouTube. Como observado acima, um recurso liveBroadcast é uma extensão de um recurso video . Você pode usar a API de dados do YouTube para atualizar metadados sobre o vídeo, como o local da gravação ou as regiões em que a transmissão será vista. |
videoAdvertisingOptions |
Define as configurações de publicidade para um vídeo (ou transmissão). Use YouTube Content ID API para definir as opções de publicidade. |
asset |
Representa uma parte da propriedade intelectual, como um filme ou episódio de um show. Neste caso, a transmissão de vídeo é o recurso. Você vai usar o YouTube Content ID API para criar e gerenciar recursos do asset . |
claim |
Vincula um vídeo a um recurso correspondente ao vídeo. Você cria uma reivindicação usando YouTube Content ID API para se identificar como o proprietário do vídeo de transmissão. |
policy |
Define regras que especificam as circunstâncias nas quais você deseja que seu conteúdo seja visualizado no YouTube ou impedido de ser exibido no YouTube. Você precisa aplicar uma política para sua transmissão de vídeo e também pode especificar uma política que o YouTube aplicará a vídeos enviados por usuários que correspondam à sua transmissão de vídeo. |
Operações suportadas
A tabela a seguir mostra os diferentes métodos que a API suporta:
Operações | |
---|---|
list |
Recupera (GET ) uma lista vazia ou com recursos. |
insert |
Cria (POST ) um novo recurso. |
update |
Modifica (PUT ) um recurso existente para propagar os dados em sua solicitação. |
bind |
Vincula um recurso liveBroadcast a um recurso liveStream ou remove esse vínculo. |
transition |
Muda o status de um recurso liveBroadcast e inicia todos os processos associados ao novo status. Por exemplo, quando você faz a transição de um status da transmissão para testing , o YouTube começa a transmitir vídeo para o stream de monitoramento da transmissão. |
delete |
Remove (DELETE ) um recurso específico. |
A tabela abaixo identifica as operações que são compatíveis com diferentes tipos de recursos. Operações que inserem, atualizam ou excluem recursos sempre precisam de autorização do usuário. Em alguns casos, os métodos list
aceitam solicitações autorizadas e não autorizadas, em que as solicitações não autorizadas apenas recuperam dados públicos, enquanto as solicitações autorizadas também podem recuperar informações restritas ao usuário autenticado no momento.
Operações suportadas | |||||||
---|---|---|---|---|---|---|---|
list | insert | update | bind | transition | cuepoint | delete | |
transmissão ao vivo | |||||||
transmissão ao vivo |
Recursos parciais
A API permite e, na prática, requer a recuperação de recursos parciais para que os aplicativos evitem a transferência, a análise e o armazenamento de dados desnecessários. Esta abordagem também garante que a API use a rede, a CPU e os recursos da memória de modo mais eficiente.
O parâmetro part
é obrigatório para qualquer solicitação de API que recupera ou retorna um recurso YouTube Data API. O parâmetro identifica uma ou mais propriedades do recurso de alto nível (não testadas) que devem ser incluídas em uma resposta da API. Por exemplo, um recurso liveStream
tem as seguintes partes:
snippet
cdn
status
Todas essas partes são objetos que contêm propriedades agrupadas, e esses objetos são considerados grupos de campos de metadados que podem (ou não) ser recuperados pelo servidor da API. Por isso, o parâmetro part
exige que você selecione os componentes do recurso que seu aplicativo realmente usa. Esse requisito tem duas finalidades importantes:
- Reduz a latência evitando que o servidor da API perca tempo recuperando campos de metadados que não são usados por seu aplicativo.
- Reduz o uso de largura de banda diminuindo (ou eliminando) a quantidade de dados desnecessários que seu aplicativo pode recuperar.
Com o passar do tempo, à medida que os recursos adicionam mais partes, esses benefícios só irão aumentar, uma vez que seu aplicativo não solicitará propriedades recém-introduzidas não suportadas por ele.
Dicas e práticas recomendadas
Reivindicar seu conteúdo
Caso queira exibir anúncios durante sua transmissão, reivindique a transmissão de vídeo antes do início do evento. Para reivindicar conteúdo, você precisa ser um Parceiro de conteúdo do YouTube participante do programa Content ID.
O processo para reivindicar sua transmissão de vídeo ao vivo é diferente do processo normal para reivindicar um vídeo. Crie a reivindicação de um vídeo ao vivo antes mesmo de ele existir para reivindicá-lo. A API oferece suporte para isso, e o documento life of a broadcast explica as chamadas de YouTube Content ID API que permitem criar a reivindicação.
Visualizar e testar seu conteúdo
Ao receber seu stream de vídeo de entrada, o YouTube pode transmitir esse vídeo em dois streams de saída diferentes:
-
O stream de monitor permite que você visualize (e teste) sua transmissão de vídeo. Ele constitui um stream particular que somente você pode acessar. Só será possível fazer a transição de uma transmissão para a fase
testing
se o stream de monitoramento da transmissão estiver ativado. O stream do monitor não exibe intervalos no anúncio. -
O stream de transmissão é o stream que seu público pode visualizarco. Você pode definir o status de privacidade da transmissão como
public
,private
ouunlisted
. (a transmissão particular fica visível apenas aos usuários que foram explicitamente convidados a assisti-la, enquanto uma transmissão não listada fica visível a qualquer pessoa que possui um link para visualizá-la).Você pode optar por atrasar o stream de transmissão de modo que ele não seja executado simultaneamente com o stream de monitor. Ao atrasar o stream de transmissão, você pode ter maior controle do tempo que você insere marcadores na transmissão.
No entanto, quando você atrasa o stream de transmissão, seus apresentadores ao vivo podem enfrentar dificuldades para interagirem com seu público. Além disso, o atraso da transmissão aumenta a probabilidade de que os espectadores descubram detalhes importantes sobre o evento a partir de outras fontes de sua transmissão. Por exemplo, se você estiver transmitindo um evento esportivo com um atraso de 60 segundos, os espectadores poderão ver momentos críticos do evento de outras fontes de notícias em tempo real antes de realmente vê-los na transmissão.
O YouTube recomenda que você ative o stream de monitor para sua transmissão para que consiga testar seu conteúdo. Você deve escolher se também atrasará sua transmissão porque deseja controlar o tempo dos marcadores ou porque deseja interagir com seu público ou fornecer cobertura de um evento em tempo real.
Exibição de anúncios intermediários durante uma transmissão
Durante uma transmissão, é possível inserir um marcador para indicar que um intervalo de anúncio precisa começar na transmissão assim que possível ou em um horário especificado. O intervalo de anúncio permite que o YouTube exiba anúncios intermediários durante a transmissão.
Os intervalos de anúncio têm as características abaixo:
-
Ele tem um período predefinido, que você define usando a propriedade
durationSecs
do recursocuepoint
. Após a conclusão do intervalo de anúncio, os espectadores retornam à transmissão ao vivo. -
Quando ocorre um intervalo no anúncio, um anúncio só é exibido no player de vídeo para os espectadores que estão assistindo à transmissão quando o marcador é inserido. Um anúncio não é exibido quando os espectadores atualizam a página em que a transmissão está sendo veiculada ou quando os visitantes começam a assistir à transmissão depois que o marcador é inserido.
A sequência de passos abaixo reflete a prática recomendada para a inserção de um intervalo no anúncio durante sua transmissão:
Definir ajustes de horário
Ao inserir um marcador, você pode especificar que ele seja inserido imediatamente ou que seja inserido em um ponto específico da transmissão. Suas opções dependem de o stream de transmissão do seu vídeo atrasar.
-
Se o stream de transmissão não estiver atrasado, você poderá inserir o ponto de inserção imediatamente ou usar a propriedade
walltimeMs
para que o intervalo comercial seja iniciado em um momento específico.-
Para iniciar o intervalo comercial imediatamente, chame o método
liveBroadcasts.cuepoint
. No recurso no corpo da solicitação, defina o valor da propriedadeinsertionOffsetTimeMs
como0
ou não especifique um valor para essa propriedade e não especifique um valor para a propriedadewalltimeMs
.Importante: os usuários não veem o conteúdo do anúncio resultante imediatamente. Pode haver um atraso de cerca de 30 segundos antes que o conteúdo do anúncio fique visível para os usuários. Durante esse atraso, seu stream de transmissão ainda estará visível para seus espectadores, e você precisa assistir ao stream de transmissão para determinar quando o conteúdo do anúncio realmente é exibido em vez de seu stream de monitor.
-
Para iniciar o intervalo de anúncio em um momento específico, chame o método
liveBroadcasts.cuepoint
e use a propriedadewalltimeMs
para especificar o horário desejado. O valor da propriedade é um número inteiro que representa um carimbo de data/hora de época.
-
Para iniciar o intervalo comercial imediatamente, chame o método
-
Se o stream de transmissão estiver atrasado, insira o marcador imediatamente, conforme descrito acima, especifique uma hora no formato de relógio conforme descrito acima ou especifique um ajuste de horário para determinar quando o intervalo de anúncio começará. O ajuste de horário especifica um ponto na transmissão em que os espectadores precisam ver um anúncio.
O valor do deslocamento é medido em milissegundos desde o início do stream do monitor para a transmissão. Se a transmissão tiver uma fase de teste, o stream do monitor será iniciado quando ela mudar para o status
testing
. Caso contrário, o fluxo de monitoramento será iniciado quando a transmissão passar para o statuslive
.Ao inserir um marcador, defina a propriedade
insertionOffsetTimeMs
do recursocuepoint
com o deslocamento desejado.
Calcular o valor do ajuste de horário
Para recuperar o valor do deslocamento, chame a função getCurrentTime
da API do Player do YouTube para o player que está reproduzindo o stream de monitoramento. Use o valor recuperado para inserir o marcador no stream de transmissão nesse momento.
Os valores possíveis para o ajuste de horário podem ser calculados como o seguinte intervalo:
[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]
O Δ
é um buffer de cinco segundos no início e no fim dos possíveis ajustes de horário quando o YouTube não consegue inserir com precisão um marcador. Exemplo:
- Uma transmissão tem uma fase de teste de cinco minutos.
- O stream de transmissão está atrasado em 60 segundos após o stream de monitor.
- A emissora está inserindo o marcador quatro minutos após a transição para o status
live
. (isso corresponde a três minutos depois de o stream de transmissão ficar visível).
Nesse caso, o intervalo possível de deslocamento é [(485,000), (535,000)]
.
Esses horários são especificados em milissegundos e são calculados com base nos seguintes valores:
elapsed_time=540000
: o stream de monitoramento é executado por nove minutos (540 segundos, 540.000 milissegundos) quando o métodoliveBroadcasts.cuepoint
é chamado.broadcast_delay=60000
: o stream de transmissão está atrasado por 60 segundos ou 60 mil milissegundos.Δ=5000
: o buffer de cinco segundos quando o marcador não pode ser inserido de maneira confiável.
Solucionar problemas e erros
As seguintes diretrizes explicam como solucionar problemas específicos que possam surgir. Consulte também a documentação de erros para ver as listas de erros que cada método de API pode retornar.
-
Quando uma transmissão muda de um status para outro, ela pode ser temporariamente transferida com outro status enquanto o YouTube conclui as ações associadas à transição. Por exemplo, se você enviar uma solicitação
liveBroadcasts.transition
para mudar o status de uma transmissão deready
paratesting
, o YouTube definirá o status da transmissão comotestStarting
e, em seguida, concluirá as ações associadas à mudança de status. Quando todas essas ações forem concluídas, o YouTube atualizará o status da transmissão paratesting
, indicando que a transição foi concluída.Se uma transmissão ficar presa com um status
testStarting
ouliveStarting
, vai ser necessário chamar o métodoliveBroadcasts.delete
e excluir a transmissão. Crie uma nova transmissão, vincule-a a seu stream ao vivo e continue com o processo de teste.Conforme observado na documentação do método
liveBroadcasts.transition
, você precisa confirmar se o valor da propriedadestatus.streamStatus
para o stream vinculado à transmissão éactive
antes de chamar esse método.