O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Vida de uma transmissão

Introdução

Este documento mostra o ciclo de vida de uma transmissão ao vivo no YouTube criada e gerenciada usando a API YouTube Live Streaming e a API Content ID do YouTube.

Recursos e tipos de recursos

Conforme explicado no guia Como começar, um recurso é uma entidade de dados individual com um identificador exclusivo. Para criar e gerenciar eventos ao vivo no YouTube, você vai usar vários tipos de recursos definidos como parte da API YouTube Data ou da API YouTube Content ID. Os recursos listados no cabeçalho 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 a transmissão
Reivindicar seu conteúdo
Teste
Transmissão
Concluir a 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 que você está inserindo 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, em que é possível assistir ao vídeo sem que outros espectadores também possam ver a transmissão, 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 com base na 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 também a propriedade contentDetails.enableDvr como true. As duas propriedades têm um valor padrão de true.
Se quiser restringir as regiões em que sua transmissão pode ser assistida, defina a propriedade contentDetails.availabilityConfig. Com ela, é possível bloquear regiões específicas ou limitar a disponibilidade a uma lista definida de regiões. Também é possível especificar períodos para disponibilidade regional.
Se quiser, especifique a categoria do vídeo para a transmissão usando a propriedade snippet.categoryId. Se não for especificado, a categoria será Entertainment por padrão.
Você pode atualizar qualquer uma das propriedades contentDetails enquanto o status da transmissão ao vivo for created ou ready.
Você pode atualizar o horário de início e término programados da transmissão enquanto o status dela for created, ready ou testing.
O título, a descrição, a categoria, 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 seu 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 apropriado para suas necessidades.

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 solicitações futuras de 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 está sendo transmitido. Cada transmissão precisa estar associada a exatamente um stream.

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

Com exceção do título da transmissão, esses valores não podem ser atualizados depois que ela é criada. Se você precisar alterá-las, será necessário criar um stream diferente repetindo esta etapa. Esse processo é discutido em mais detalhes na etapa 3.5 mais adiante neste documento.

Você também pode definir valores para as seguintes propriedades:

snippet.description - assim como o título, a descrição da transmissão pode ser atualizada depois que ela é criada. Nem o título nem a descrição ficam visíveis para os usuários do YouTube.
[contentDetails.isReusable](

/youtube/data/live/reference/rest/v3/liveStreams#contentDetails.isReusable)

Indica se a transmissão é reutilizável, ou seja, se pode ser vinculada a várias transmissões. O valor dessa propriedade determina se um canal tem uma relação de muitos para um ou um para um entre os recursos liveBroadcast e liveStream:
- Se você usar o valor padrão da propriedade de true, poderá usar o mesmo recurso liveStream para todas as transmissões de um canal. Isso significa que não é necessário repetir essa etapa (1.2) para cada transmissão. Em vez disso, basta reutilizar o ID do stream para as transmissões seguintes.
- 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, a resposta dela vai 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 stream em solicitações de API futuras.

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 ao YouTube com a transmissão do evento para esse vídeo.

Ao chamar o método liveBroadcasts.bind, defina o parâmetro id como o ID da transmissão obtido na etapa 1.1 e o parâmetro streamId como o ID do stream obtido na etapa 1.2.

Fase 2: reivindicar o conteúdo

Se você quiser mostrar anúncios durante a transmissão, reivindique o vídeo antes do início do evento. Siga as etapas abaixo para configurar a transmissão, o vídeo e os anúncios. O canal do proprietário da transmissão precisa estar qualificado para veicular anúncios.

Todas as chamadas de API discutidas nesta etapa estã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 e os territórios em que eles têm direitos sobre o recurso. O YouTube usa esses dados para determinar onde um proprietário pode definir a política de 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 no Canadá, cada uma poderá definir políticas diferentes para o vídeo transmitido e para os vídeos enviados por usuários que correspondam ao vídeo transmitido. Sua política de correspondência será aplicada aos vídeos enviados por usuários nos Estados Unidos, enquanto a política do outro proprietário será aplicada aos vídeos correspondentes 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 que você armazenou 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 vai indicar como o YouTube deve lidar com um vídeo enviado que corresponda à sua transmissão ao vivo.

Observação:defina uma política de correspondência se você planeja criar uma referência do seu vídeo de transmissão e usá-la para identificar vídeos enviados por usuários que correspondem à sua transmissão. Caso contrário, pule esta etapa.

Para definir a política de correspondência, primeiro identifique a política que você quer aplicar. Para recuperar uma lista de políticas, chame o método policies.list. Para definir uma nova política, chame o método policies.insert. Em qualquer caso, é 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 que você armazenou na etapa 2.1.

Etapa 2.4: reivindicar seu vídeo

Nesta etapa, você vai criar uma reivindicação que vincula o vídeo que será transmitido ao recurso criado na etapa 2.1. A reivindicação define uma política que se aplica apenas ao vídeo da transmissão. Os vídeos enviados por usuários 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 que você inserir, defina valores para as seguintes propriedades:

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

Processar a resposta da API

Quando você inserir a reivindicação, a resposta da API vai conter o recurso claim que você criou. Seu código precisa extrair e armazenar o id desse recurso. Você vai usar esse valor mais tarde para criar uma referência do vídeo processado.

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

Você precisa definir as opções de publicidade do seu vídeo se quiser veicular um anúncio prerrolagem quando os espectadores começarem a assistir sua transmissão ou veicular anúncios durante intervalos na transmissão.

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

Para ativar os anúncios, chame o método videoAdvertisingOptions.update. Na sua solicitação, defina o parâmetro videoId como a transmissão id que você recebeu 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

Nesta etapa, você incorpora um player que mostra o stream de monitoramento da sua transmissão para testar a experiência de visualização. A transmissão de monitoramento é uma transmissão privada que permite visualizar o vídeo da transmissão como ele apareceria para os espectadores do YouTube.

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

Etapa 3.1: incorporar player de fluxo de monitoramento

Recupere sua 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 sua transmissão de monitoramento.

Etapa 3.2: começar seu vídeo

Comece a transmitir vídeo no seu stream de vídeo.

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

Chame o método liveStreams.list para recuperar o recurso liveStream associado à sua 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: mudar o status da transmissão para "teste"

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

Depois de chamar o método liveBroadcasts.transition, a transição pode levar vários segundos ou até um minuto para ser concluída. Durante esse tempo, você precisa consultar 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 correu bem, avance para a fase 4. No entanto, em alguns casos, pode ser necessário fazer mais testes. Por exemplo, se o teste revelar que o stream de vídeo não está configurado corretamente, corrija isso antes de continuar com a transmissão.

Se o stream de vídeo não estiver configurado corretamente, desvincule (e exclua) o stream atual e crie um novo. Por exemplo, uma transmissão pode não estar configurada corretamente se 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 de 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 fluxo 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 liveStream configurado corretamente. Em seguida, repita a etapa 1.3 para vincular o novo stream à transmissão e as etapas 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ê pode 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 da fase de teste, porque o teste faria com que a transmissão fosse iniciada.

Etapa 4: transmissão

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ídeo no seu fluxo de vídeo.

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

Etapa 4.3: mudar o status da transmissão para "Ao vivo"

Importante:essa etapa torna o vídeo visível para o público.

Se você definir a propriedade contentDetails.enableAutoStart do recurso liveBroadcast como true, não será necessário 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 aguardar de 5 a 10 segundos para que essa transição seja concluída. A transição pode levar até um minuto. Durante esse período, você precisa consultar 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 sua transmissão a partir desse ponto no stream do monitor.

Observe os seguintes efeitos desse comando:

Se você tiver ativado o stream de monitoramento para sua transmissão (consulte a etapa 3.1), ele vai aparecer em um player incorporado.
Se você tiver definido um valor para a propriedade contentDetails.streamDetails.broadcastStreamDelayMs da transmissão, o stream dela, que fica visível para outros espectadores, será atrasado por esse período.

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

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

Nesse momento, o YouTube tenta veicular um anúncio no player de vídeo para todos os espectadores que estavam assistindo a transmissão quando o ponto de inserção de anúncio foi inserido. A reprodução de um anúncio depende de vários fatores, como a disponibilidade de anúncios e o histórico de visualização do espectador. Os espectadores que recebem um intervalo de anúncio voltam para sua transmissão quando ele termina. Já os espectadores que não recebem um anúncio continuam assistindo a transmissão durante o intervalo.

O guia Introdução oferece mais informações sobre a experiência de visualização durante o intervalo de anúncio de uma transmissão ao vivo.

Etapa 5: concluir a transmissão

Etapa 5.1: interromper o streaming

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

Etapa 5.2: mudar o status da transmissão para concluída

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 da transmissão obtido na etapa 1.1 e 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 poderá assistir imediatamente à reprodução dele.

Fase 6: criar uma referência

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

Importante:para criar a referência, você precisa definir a propriedade contentDetails.recordFromStart da transmissão como true.

Etapa 6.1: sondar a API Data para verificar o status do vídeo

O YouTube precisa concluir o processamento de uma transmissão ou de um vídeo enviado antes que você possa criar uma referência com base nele. Para determinar se o vídeo terminou de ser processado, faça uma pesquisa com o método videos.list da API YouTube Data, definindo o parâmetro part como status e o parâmetro id como o ID da transmissão que você armazenou na etapa 1.1.

A resposta da API à sua solicitação de sondagem vai 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 reivindicação que você armazenou na etapa 2.4.

Envio de conteúdo ao vivo do Content ID

Alguns parceiros do YouTube podem criar uma referência antes que a transmissão passe 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 transmissão do seu evento ao vivo enquanto a transmissão está em andamento. Além disso, o YouTube procura vídeos enviados por usuários que correspondam ao conteúdo enquanto a transmissão ainda está em andamento. Criar uma referência antes do início de uma transmissão ativa automaticamente a gravação dela, que não pode ser desativada depois que a referência é criada.

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