Esta página foi traduzida pela API Cloud Translation.

Vida de uma transmissão

Introdução

Este documento orienta você pela duração de uma transmissão ao vivo no YouTube que é criada e gerenciada usando a API de transmissão ao vivo do YouTube e a API Content ID do YouTube.

Recursos e tipos de recursos

Conforme explicado no guia de primeiros passos, um recurso é uma entidade de dados individual com um identificador exclusivo. Para criar e gerenciar eventos ao vivo no YouTube, você usará vários tipos diferentes de recursos que são definidos como parte da API de dados do YouTube ou da API do Content ID do YouTube. Os recursos listados no cabeçalho da API YouTube Live Streaming são tecnicamente definidos nessas outras APIs, mas são listados separadamente porque são usados apenas para transmissões ao vivo.

Recursos da API YouTube Live Streaming

Recursos da API YouTube Data

video

Recursos da API Content ID do YouTube

Criar e gerenciar uma transmissão ao vivo

As etapas a seguir explicam como criar e gerenciar um evento ao vivo no YouTube. As etapas são divididas nas seguintes fases:

Configurar sua transmissão
Reivindicar seu conteúdo
Teste
Removido
Conclua sua transmissão
Criar uma referência

Fase 1: configurar sua transmissão

Etapa 1.1: criar sua transmissão

Chame o método liveBroadcasts.insert para adicionar sua transmissão à programação de eventos ao vivo do YouTube. O recurso liveBroadcast inserido precisa definir valores para as propriedades listadas abaixo.

Leve em conta as seguintes diretrizes ao configurar sua transmissão:

Se você quiser ter uma fase de teste para sua transmissão, quando puder ver sua transmissão de vídeo sem que outros espectadores também possam vê-la, defina a propriedade contentDetails.monitorStream.enableMonitorStream como true e a propriedade contentDetails.enableAutoStart como false. Esses são os valores padrão para ambas as propriedades.
Se você quiser criar uma referência da transmissão gravada, defina a propriedade contentDetails.recordFromStart da transmissão como true. Se você quiser disponibilizar o vídeo gravado para reprodução imediatamente após o término da transmissão, defina a propriedade contentDetails.enableDvr como true. Ambas as propriedades têm o valor padrão true.
Você pode atualizar qualquer propriedade contentDetails, desde que o status da transmissão ainda seja created ou ready.
É possível atualizar os horários de início e término programados da transmissão, desde que o status dela seja created, ready ou testing.
O título, a descrição, o status de privacidade e outros campos de metadados que fazem parte do recurso video da transmissão podem ser atualizados a qualquer momento.

Observação:se você quiser que o vídeo esteja disponível apenas para usuários específicos do YouTube, defina o valor da propriedade status.privacyStatus como unlisted ou private conforme necessário.

Como processar a resposta da API

Quando você chama o método liveBroadcasts.insert, a resposta da API contém o recurso liveBroadcast que você criou. Seu código precisa extrair e armazenar o id desse recurso. Você vai precisar desse valor para identificar a transmissão em futuras solicitações da API. Também é possível identificar o recurso video que corresponde ao recurso liveBroadcast usando o mesmo ID.

Etapa 1.2: criar um fluxo

Um recurso liveStream permite que você transmita seu vídeo para o YouTube e descreve o conteúdo que você está transmitindo. Cada transmissão precisa estar associada a exatamente um stream.

Chame o método liveStreams.insert para criar o stream de vídeo do evento. Ao criar o stream, é preciso definir valores para as propriedades listadas abaixo:

Com exceção do título do stream, esses valores não podem ser atualizados após a criação do stream. Se precisar mudá-los, repita esta etapa para criar um stream diferente. Esse processo é discutido em mais detalhes na etapa 3.5 mais adiante neste documento.

Também é possível definir valores para as seguintes propriedades:

snippet.description: como o título do stream, a descrição dele pode ser atualizada após a criação do stream. Nem o título nem a descrição ficam visíveis para usuários do YouTube.
contentDetails.isReusable: indica se o stream é reutilizável, o que significa que pode ser vinculado a várias transmissões. O valor dessa propriedade determina efetivamente se um canal tem um relacionamento de muitos para um ou um para um entre os recursos liveBroadcast e liveStream:
- Se você usar o valor padrão de true da propriedade, poderá usar o mesmo recurso liveStream para todas as transmissões de um canal. Isso significa que você não precisa repetir essa etapa (1.2) para cada transmissão. Em vez disso, é possível reutilizar o ID de stream para transmissões subsequentes.
- Se você definir o valor da propriedade como false, será necessário criar um novo fluxo para cada transmissão.

Depois de emitir a solicitação de API para o stream, a resposta da API conterá o recurso liveStream que você criou. Seu código precisa extrair e armazenar o id desse recurso. Você vai precisar desse valor para identificar o fluxo em futuras solicitações da API.

Etapa 1.3: vincular a transmissão ao fluxo

Depois de criar os recursos liveBroadcast e liveStream, você precisa associar os dois usando o método liveBroadcasts.bind. Essa ação vincula os bits de vídeo que você vai transmitir para o YouTube com a transmissão do evento desse vídeo.

Ao chamar o método liveBroadcasts.bind, defina o parâmetro id como o ID de transmissão recebido na etapa 1.1 e o parâmetro streamId como o ID de fluxo recebido na etapa 1.2.

Fase 2: reivindicar o conteúdo

Se quiser mostrar anúncios durante a transmissão, reivindique o vídeo de transmissão antes do início do evento. As etapas a seguir explicam esse processo. Todas as chamadas de API discutidas nesta etapa são definidas na API Content ID do YouTube.

Etapa 2.1: criar um ativo

Um recurso asset representa uma parte da propriedade intelectual. Neste caso, o ativo é sua transmissão. Chame o método assets.insert para criar seu recurso.

A resposta da API vai conter o recurso asset que você criou. Seu código precisa extrair e armazenar o id desse recurso, já que você vai precisar desse valor para identificar o recurso em solicitações futuras da API.

Etapa 2.2: defina a propriedade do ativo

Os dados de propriedade de um recurso identificam os proprietários dele, bem como os territórios em que ele é proprietário. O YouTube usa esses dados para determinar onde um proprietário pode definir a política para um vídeo reivindicado.

Por exemplo, se você tiver o direito de transmitir um evento nos Estados Unidos e outra emissora tiver os mesmos direitos para o Canadá, será possível definir políticas diferentes para o vídeo de transmissão e para vídeos enviados pelo usuário que correspondam ao vídeo de transmissão. Sua política de correspondência será aplicada aos vídeos enviados pelo usuário nos Estados Unidos, enquanto a política do outro proprietário será aplicada aos vídeos no Canadá.

Para definir os territórios de propriedade do recurso, chame o método ownership.update. Nessa solicitação, defina o parâmetro assetId como o id armazenado na etapa 2.1.

Etapa 2.3: definir política de correspondência do ativo

A política de correspondência de um recurso explica o que o YouTube deve fazer quando um usuário envia um vídeo que corresponde a uma referência associada ao recurso. Nesse caso, a política de correspondência indicará como o YouTube deve lidar com um vídeo enviado que corresponde à sua transmissão ao vivo.

Observação:você deve definir uma política de correspondência se planeja criar uma referênciacom seu vídeo de transmissão e usá-la para identificar vídeos enviados pelo usuário que correspondam à transmissão. Caso contrário, pule esta etapa.

Para definir a política de correspondência, primeiro você precisa identificar a política que quer aplicar. Para recuperar uma lista das políticas existentes, chame o método policies.list. Para definir uma nova política, chame o método policies.insert. Em qualquer um dos casos, é necessário capturar o id da política que você quer aplicar.

Depois de identificar a política, chame o método assetMatchPolicy.update. Nessa solicitação, defina o parâmetro assetId como o id armazenado na etapa 2.1.

Etapa 2.4: reivindicar seu vídeo

Nesta etapa, você cria uma reivindicação que vincula o vídeo que você transmitirá ao recurso criado na etapa 2.1. A reivindicação define uma política que se aplica apenas ao seu vídeo de transmissão. Os vídeos enviados pelo usuário que correspondem ao seu vídeo de transmissão são cobertos pela política de correspondência definida na etapa anterior.

Para criar uma reivindicação, chame o método claims.insert. No recurso claim inserido, é necessário definir valores para as seguintes propriedades:

assetId: você recebeu esse valor na etapa 2.1.
videoId: é o ID de transmissão que você recebeu na etapa 1.1.
policy: este é um recurso de policy. Para aplicar uma política, defina a propriedade id do recurso com o ID da política atual. A etapa anterior explica como recuperar o ID de uma política atual.
contentType: defina esse valor como audiovisual.

Como processar a resposta da API

Quando você insere a declaração, a resposta da API contém o recurso claim criado. Seu código precisa extrair e armazenar o id desse recurso. Você usará esse valor posteriormente para criar uma referência a partir do vídeo processado.

Etapa 2.5: atualizar as configurações de anúncios para a transmissão

Defina as opções de publicidade para seu vídeo se você quiser exibir um anúncio precedente quando os espectadores começarem a assistir à transmissão ou exibir anúncios durante os intervalos.

Se você ativar os anúncios precedentes para transmissão, todos os espectadores vão ver um anúncio quando começarem a assistir, mesmo que comecem a assistir no meio da transmissão.
Se você ativar os anúncios intermediários na transmissão, vai poder inserir marcadores de anúncios durante a transmissão.

Para ativar anúncios, chame o método videoAdvertisingOptions.update. Na solicitação, defina o parâmetro videoId como a transmissão id recebida na etapa 1.1. Use a propriedade adFormats[] do recurso videoAdvertisingOption para identificar os formatos de anúncio (preroll, midroll ou postroll) que você quer ativar.

Fase 3: testar

Durante esse estágio, você incorpora um player que mostra o stream de monitoramento da sua transmissão para testar a experiência de visualização. O stream de monitor é um stream particular que permite visualizar o vídeo de transmissão como ele será exibido para os espectadores do YouTube.

Só é possível testar a transmissão de vídeos se o stream do monitor estiver ativado. Por padrão, os fluxos de monitoramento da transmissão ficam ativados. É possível desativar o fluxo de monitoramento de uma transmissão ao definir a propriedade contentDetails.monitorStream.enableMonitorStream como false ao criar ou atualizar essa transmissão.

Etapa 3.1: incorporar player de fluxo de monitoramento

Recupere a transmissão usando o método liveBroadcasts.list e extraia o valor da propriedade contentDetails.streamDetails.monitorStreamEmbedHtml. Esse valor contém o HTML necessário para incorporar um player do YouTube que mostra o fluxo de monitoramento.

Etapa 3.2: começar seu vídeo

Comece a transmitir vídeos em seu fluxo.

Etapa 3.3: confirmar se seu fluxo de vídeo está ativo

Chame o método liveStreams.list para extrair o recurso liveStream associado à transmissão. Confirme se o valor da propriedade status.streamStatus é active, o que indica que os servidores do YouTube estão recebendo dados do seu codificador corretamente.

Etapa 3.4: fazer a transição do status da transmissão para testes

Chame o método liveBroadcasts.transition para atualizar o status da transmissão. Defina o valor do parâmetro id como o ID de transmissão recebido na etapa 1.1 e o valor broadcastStatus como testing.

Depois de chamar o método liveBroadcasts.transition, pode levar vários segundos ou até um minuto para que a transição seja concluída. Durante esse período, você precisa pesquisar a API para verificar o status da transmissão. Até que a transição seja concluída, o status da transmissão será testStarting. O status será testing quando a transição for concluída.

Etapa 3.5: concluir o teste

Se o teste tiver corrido bem, siga para a fase 4. No entanto, em alguns casos, pode ser necessário fazer mais testes. Por exemplo, se os testes revelarem que o stream de vídeo não está configurado corretamente, você precisará resolver esse problema antes de continuar com a transmissão.

Se o stream de vídeo não estiver configurado corretamente, será necessário desvincular (e excluir) o stream existente e criar um novo. Por exemplo, um stream pode não ser configurado corretamente se ele especificar o formato de vídeo errado.

Para desvincular o stream de vídeo, chame o método liveBroadcasts.bind da etapa 1.3. Na solicitação da API, defina o parâmetro id como o id recebido na etapa 1.1. Não inclua o parâmetro streamId na solicitação.
Para excluir o stream de vídeo, chame o método liveStreams.delete. Na solicitação, defina o parâmetro id como o id recebido na etapa 1.2.
Repita a etapa 1.2 para criar um novo recurso de liveStream configurado corretamente. Em seguida, repita as etapas de 1.3 para vincular o novo stream à sua transmissão e as etapas de 3.1 a 3.3 para testar o novo stream.

Etapa 3.6: ativar as propriedades `autoStart` e `autoStop`

Depois de concluir o estágio de teste, você tem a opção de definir as propriedades contentDetails.enableAutoStart e contentDetails.enableAutoStop da transmissão como true antes do início da transmissão real. Essas propriedades não podem ser definidas como true antes do estágio de teste porque o teste faria com que a transmissão fosse iniciada.

Etapa 4: transmitir

Durante esta fase, o vídeo de transmissão é visível para o público.

Etapa 4.1: iniciar o vídeo

Comece a transmitir vídeos em seu fluxo.

Etapa 4.2: confirmar se o stream de vídeo está ativo

Etapa 4.3: transição do status de sua transmissão para ao vivo

Importante:nesta etapa, o vídeo fica visível para o público.

Se você definir a propriedade contentDetails.enableAutoStart do recurso liveBroadcast como true, não precisará chamar o método liveBroadcasts.transition.

Depois de fazer essa chamada de API, ou se você tiver definido a propriedade contentDetails.enableAutoStart como true, depois de iniciar o streaming, normalmente é necessário esperar de 5 a 10 segundos para que a transição seja concluída. A transição pode levar até um minuto. Durante esse período, você precisa pesquisar a API para verificar o status da transmissão. Até que a transição seja concluída, o status da transmissão será liveStarting. O status será live quando a transição for concluída e os espectadores puderem assistir à transmissão a partir desse ponto no stream do monitor.

Observe os seguintes efeitos desse comando:

Se você ativou o stream de monitoramento para sua transmissão (consulte a etapa 3.1), você poderá ver o fluxo de monitoramento em um player incorporado.
Se você tiver definido um valor para a propriedade contentDetails.streamDetails.broadcastStreamDelayMs da transmissão, o stream de transmissão, que fica visível para outros espectadores, será atrasado por esse tempo.

Etapa 4.4: inserir intervalos de anúncio na sua transmissão

Chame o método liveBroadcasts.cuepoint para inserir um marcador. O marcador pode acionar um intervalo de anúncio. No recurso cuepoint fornecido no corpo da solicitação, defina a propriedade durationSecs com a duração desejada do intervalo (em segundos) que você quer mostrar. O valor padrão é 30.

No momento, o YouTube tenta exibir um anúncio no player de vídeo para qualquer espectador que estava assistindo a transmissão quando o marcador foi inserido. A exibição de um anúncio depende de vários fatores, como disponibilidade de anúncio e histórico de visualização de anúncios do espectador. Os espectadores que recebem um intervalo de anúncio retornam à sua transmissão quando ele termina. Os espectadores que não veem um anúncio continuam vendo o fluxo de transmissão durante o intervalo.

O guia Primeiros passos fornece mais informações sobre a experiência de visualização durante um intervalo comercial de uma transmissão ao vivo.

Etapa 5: concluir a transmissão

Etapa 5.1: interromper a transmissão

Isso conclui o teste do sistema de transmissão ao vivo do YouTube.

Etapa 5.2: transição do status da transmissão para concluído

Quando estiver tudo pronto para interromper a transmissão, chame o método liveBroadcasts.transition da API para atualizar o status da transmissão. Defina o valor do parâmetro id como o ID de transmissão recebido na etapa 1.1 e defina o valor do parâmetro broadcastStatus como complete.

Se você tiver definido as propriedades contentDetails.recordFromStart e contentDetails.enableDvr da transmissão como true, quando o evento ao vivo terminar, seu público vai poder assistir imediatamente à reprodução do evento.

Fase 6: criar uma referência

Quando a gravação ao vivo for concluída, você pode criar uma referência do vídeo gravado. Essa ação instrui o YouTube a procurar vídeos enviados pelo usuário que correspondam à transmissão e processá-los de acordo com a política de correspondência definida na etapa 2.3.

Importante: para criar a referência, é necessário definir a propriedade contentDetails.recordFromStart da transmissão como true.

Etapa 6.1: pesquisar API de dados referente ao status do vídeo

O YouTube precisa terminar de processar uma transmissão ou um vídeo enviado antes que você possa criar uma referência a partir desse vídeo. Para determinar se o processamento do vídeo foi concluído, pesquise o método videos.list da API YouTube Data, definindo o parâmetro part como status e o parâmetro id como o ID de transmissão que você armazenou na etapa 1.1.

A resposta da API para a solicitação de pesquisa conterá um recurso video. Quando o valor da propriedade status.uploadStatus desse recurso for processed, prossiga para a etapa 6.2.

Etapa 6.2: criar uma referência a partir do vídeo processado

Para criar sua referência, chame o método references.insert da API Content ID e defina o parâmetro claimId como o ID da declaração armazenado na etapa 2.4.

Envio de Content ID em tempo real

Alguns parceiros do YouTube podem criar uma referência antes da transição de transmissão para o estado testing, mas esse recurso não está disponível para todos os parceiros. Nesse fluxo, o YouTube gera e atualiza continuamente a referência do stream de evento ao vivo enquanto a transmissão está em andamento. Além disso, o YouTube procura corresponder a vídeos enviados por usuários enquanto a transmissão ainda está em andamento. Observe que criar uma referência antes de uma transmissão começar automaticamente ativa a gravação para a transmissão, e a gravação não pode ser desativada após a criação da referência.

Para ativar sua transmissão para envio ao vivo do Content ID, tente realizar as ações descritas na etapa 6.2 depois de reivindicar seu vídeo na etapa 2.4. Se a conta do parceiro não tiver sido aprovada para criar uma referência para uma transmissão ao vivo antes que ela ocorra, a API retornará um erro fingerprintingNotAllowed. Nesse caso, é necessário aguardar até que a transmissão seja concluída, conforme descrito nas etapas 6.1 e 6.2 acima, antes de criar a referência.