Visão geral da API YouTube Live Streaming

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 da API YouTube Data e da API YouTube Content ID. A API Data permite que os usuários do YouTube gerenciem as contas da plataforma, enquanto a 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 Live Streaming são usados apenas 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

Transmissões

Uma transmissão representa um evento que pode ser assistido no YouTube enquanto 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.

de aplicativos.

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.

Marcadores

Um cuepoint 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 os transmissores definam informações sobre uma transmissão e o vídeo dela (usando a API YouTube Data) ao mesmo tempo.

• Simplifique as transições entre estados de transmissão (por exemplo, testing ou live) e permita que os usuários insiram marcadores.

Antes de começar

1. Você precisa de uma Conta do Google para acessar o Google Cloud console, solicitar uma chave de API e registrar seu aplicativo.

2. Registre seu aplicativo no Google para que ele possa enviar solicitações de API.

3. Depois de registrar o aplicativo, selecione a YouTube Data API como um dos serviços usados por ele:

   1. Acesse o Cloud console e selecione o projeto que você acabou de registrar.
   2. Acesse a página APIs ativadas. Na lista de APIs, verifique se o status está ATIVADO para a API YouTube Data v3 e, se você for um parceiro de conteúdo do YouTube, a API YouTube Content ID.

4. Familiarize-se com os conceitos básicos do formato de dados JavaScript Object Notation (JSON). JSON é um formato de dados comum e independente de linguagem que oferece uma representação de texto simples das estruturas de dados arbitrárias. Para mais informações, acesse json.org (em inglês).

Como autorizar solicitações de API

Como observado acima, a API Live Streaming usa funcionalidades que fazem parte tecnicamente da API YouTube Data ou da API YouTube Content ID. Você pode usar a API Content ID para fornecer ao YouTube metadados, informações de propriedade e informações de política para 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 da Content ID API, que são diferentes dos requisitos para autorizar outras solicitações da Live Streaming API.

Como chamar a Data API

A solicitação de API precisa ser autorizada pela Conta do Google que é proprietária do canal do YouTube de transmissão.

Como chamar a 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 do YouTube de transmissão.

Recursos e tipos de recursos

Um recurso é uma entidade de dados individual com um identificador exclusivo. A tabela abaixo descreve os diferentes tipos de recursos com que você vai interagir usando a Live Streaming API. Tecnicamente, todos esses recursos são definidos como parte da YouTube Data API ou da YouTube Content ID API. No entanto, os recursos liveBroadcast, liveStream e cuepoint são usados apenas para criar e gerenciar eventos ao vivo.

Operações suportadas

A tabela a seguir mostra os diferentes métodos que a API suporta:

A tabela a seguir 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 oferecem suporte a solicitações autorizadas e não autorizadas. As solicitações não autorizadas só recuperam dados públicos, enquanto as solicitações autorizadas também podem recuperar informações restritas ao usuário autenticado.

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 recupere ou retorne 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 aninhadas, e você pode pensar nesses objetos como grupos de campos de metadados que o servidor de API pode (ou não pode) recuperar. Assim, o parâmetro part exige que você selecione os componentes de recursos que seu aplicativo realmente usa. Esse requisito tem dois propósitos importantes:

• Reduz a latência, impedindo que o servidor de API gaste tempo recuperando campos de metadados que seu aplicativo não usa.
• 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 que participa do programa Content ID.

O processo para reivindicar sua transmissão 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 a isso, e o ciclo de vida de uma transmissão explica as YouTube Content ID API chamadas que permitem criar sua 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ó é possível fazer a transição de uma transmissão para a fase testing se o stream de monitor dela estiver ativado. O stream do monitor não exibe intervalos de 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 ou unlisted. (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.

Como veicular anúncios intermediários durante um stream de transmissão

Durante uma transmissão, você pode inserir um cuepoint para indicar que um intervalo de anúncio deve começar em a transmissão o mais rápido possível ou em um horário especificado. O intervalo de anúncio permite que o YouTube veicule anúncios intermediários durante a transmissão.

Os intervalos de anúncio têm as seguintes características:

1. Ele tem um período predefinido, que você define usando a propriedade do recurso cuepoint durationSecs. Após a conclusão do intervalo de anúncio, os espectadores retornam à transmissão ao vivo.

2. Quando um intervalo de anúncio acontece, um anúncio só é veiculado no player de vídeo para os espectadores que estão assistindo a transmissão quando o marcador é inserido. Um anúncio não é veiculado quando os espectadores atualizam a página onde a transmissão está sendo reproduzida ou quando os visitantes começam a assistir a 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 de anúncio durante sua transmissão:

Definir ajustes de tempo

Ao inserir um marcador, você pode especificar que ele seja inserido imediatamente ou que ele seja inserido em um ponto específico da transmissão. Suas opções dependem de o stream de transmissão do vídeo estar atrasado.

• Se o stream de transmissão não estiver atrasado, você poderá inserir o marcador imediatamente ou usar a walltimeMs propriedade para que o intervalo de anúncio comece em um horário específico.

  • Para iniciar o intervalo de anúncio imediatamente, chame o método liveBroadcasts.cuepoint. No recurso no corpo da solicitação, defina o valor da propriedade insertionOffsetTimeMs como 0 ou não especifique um valor para essa propriedade e não especifique um valor para a propriedade walltimeMs.

    Importante: os espectadores 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, o stream de transmissão ainda estará visível para os espectadores, e você precisará assistir o stream de transmissão para determinar quando o conteúdo do anúncio será exibido em vez do stream de monitor.

  • Para iniciar o intervalo de anúncio em um horário específico, chame o liveBroadcasts.cuepoint método e use a walltimeMs propriedade para especificar o horário desejado. O valor da propriedade é um número inteiro que representa um carimbo de data/hora da época.

• Se o stream de transmissão estiver atrasado, você poderá inserir o marcador imediatamente, conforme descrito acima, especificar um horário de relógio conforme descrito acima ou especificar um ajuste de tempo para determinar quando o intervalo de anúncio será iniciado. O ajuste de tempo especifica um ponto na transmissão em que os espectadores devem ver um anúncio.

  O valor do ajuste é medido em milissegundos desde o início do stream de monitor da transmissão para seu broadcast. Se a transmissão tiver uma fase de teste, o stream de monitor será iniciado quando a transmissão fizer a transição para o status testing. Caso contrário, o stream de monitor será iniciado quando a transmissão fizer a transição para o status live.

  Ao inserir um marcador, defina a propriedade insertionOffsetTimeMs do recurso cuepoint como o ajuste desejado.

Calcular o valor do ajuste de tempo

Para recuperar o valor do ajuste, chame a função getCurrentTime da API YouTube Player para o player que está reproduzindo o stream de monitor. 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 tempo quando o YouTube não pode inserir um marcador com precisão. 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.
• O transmissor está inserindo o marcador quatro minutos após a transição da transmissão para o live status. (isso corresponde a três minutos depois de o stream de transmissão ficar visível).

Nesse caso, o intervalo possível de ajustes de tempo é [(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 monitor foi executado por nove minutos (540 segundos, 540.000 milissegundos) quando o método liveBroadcasts.cuepoint é chamado.
• broadcast_delay=60000: o stream de transmissão está atrasado em 60 segundos ou 60.000 milissegundos.
• Δ=5000 – o buffer de cinco segundos quando o marcador não pode ser inserido de forma confiável.

Solução de problemas e tratamento de erros

As seguintes diretrizes explicam como solucionar problemas específicos que possam surgir. Para conferir as listas de erros que cada método de API pode retornar, consulte API YouTube Live Streaming - Erros.

• 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 de ready para testing, o YouTube vai definir o status da transmissão como testStarting e concluir as ações associadas à mudança de status. Quando todas essas ações forem concluídas, o YouTube vai atualizar o status da transmissão para testing, indicando que a transição está concluída.

  Se uma transmissão ficar presa com um status testStarting ou liveStarting, você precisará chamar o método liveBroadcasts.delete e excluir a transmissão. Em seguida, crie uma nova transmissão, vincule-a à transmissão ao vivo e continue com o processo de teste.

  Conforme observado na documentação do método liveBroadcasts.transition, confirme se o valor da propriedade status.streamStatus para o stream vinculado à transmissão é active antes de chamar esse método.