Esta página foi traduzida pela API Cloud Translation.

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 com a API YouTube Live Streaming e a API YouTube Content ID.

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 Content ID do YouTube. 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 sua transmissão
Reivindicar seu conteúdo
Teste
Removido
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 testes para sua transmissão, em que é possível assistir o 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 quiser criar uma referência da sua transmissão gravada, defina a propriedade contentDetails.recordFromStart da transmissão como true. Se 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. As duas propriedades têm um valor padrão de true.
Você pode atualizar qualquer uma das propriedades contentDetails enquanto o status da transmissão ao vivo for created ou ready.
É possível 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, o status de privacidade e outros campos de metadados da transmissão, que fazem parte do recurso video da transmissão, podem ser atualizados a qualquer momento.

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

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 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 transmitir seu vídeo para o YouTube e descreve o conteúdo que você está transmitindo. Cada transmissão precisa ser associada a exatamente um stream.

Chame o método liveStreams.insert para criar o stream 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 a transmissão é criada. Se você precisar mudar, crie um fluxo diferente repetindo esta etapa. Esse processo é abordado 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 pode ser atualizada depois que a transmissão é criada. Nem o título nem a descrição ficam visíveis para os usuários do YouTube.
contentDetails.isReusable: indica se o stream é reutilizável, ou seja, se pode ser vinculado a várias transmissões. O valor dessa propriedade determina se um canal tem uma relação de muitos para um ou de um para um entre os recursos liveBroadcast e liveStream:
- Se você usar o valor padrão da propriedade true, 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, basta reutilizar o ID do fluxo para transmissões subsequentes.
- Se você definir o valor da propriedade como false, será necessário criar um novo stream para cada transmissão.

Depois de emitir a solicitação de API para o stream, a resposta da API vai conter o recurso liveStream que você criou. O código precisa extrair e armazenar o id desse recurso. Você vai precisar desse valor para identificar o fluxo em futuras solicitações de 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 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 da transmissão ao vivo obtido na etapa 1.2.

Fase 2: reivindicar o conteúdo

Se quiser mostrar anúncios durante a transmissão, reivindique o vídeo dela 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 obra de 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 esse valor será necessário 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 detêm a propriedade. 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 um poderá definir políticas diferentes para o vídeo da transmissão e para os vídeos enviados pelos usuários que correspondem a ele. 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 corresponde à 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 usar essa referência para identificar vídeos enviados por usuários que correspondam à 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 atuais, chame o método policies.list. Para definir uma nova política, chame o método policies.insert. Em qualquer caso, você precisa capturar o id da política que 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ê cria 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 sua transmissão. (Os vídeos enviados por usuários que correspondem ao seu vídeo de transmissão ao vivo 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

Ao inserir a reivindicação, a resposta da API vai conter o recurso claim que você criou. O código precisa extrair e armazenar o id desse recurso. Você vai usar esse valor mais tarde para criar uma referência do seu 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 prerrol quando os espectadores começarem a assistir sua transmissão ou veicular anúncios durante pausas na transmissão.

Se você ativar os anúncios prerrol para sua transmissão, todos os espectadores vão ver um anúncio quando começarem a assistir, mesmo que entrem no meio da transmissão.
Se você ativar os anúncios intermediários na sua 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

Nessa etapa, você incorpora um player que mostra o stream do monitor da sua transmissão para testar a experiência de visualização. O monitoramento é uma transmissão particular que permite pré-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 a 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 o stream do monitor.

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 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 "Em 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 período, faça uma pesquisa na 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 foi tranquilo, siga para a etapa 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 fluxo de vídeo não estiver configurado corretamente, desvincule (e exclua) o fluxo atual e crie um novo. Por exemplo, um stream pode não estar configurado corretamente se especificar o formato de vídeo errado.

Para desvincular o fluxo 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 obtido 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 obtido na etapa 1.2.
Repita a etapa 1.2 para criar um novo recurso liveStream configurado corretamente. Depois, repita a etapa 1.3 para vincular o novo stream à sua 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 a fase de testes, 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 começasse.

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: mudar o status da transmissão para "Ao vivo"

Importante:esta etapa torna seu 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, aguarde 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 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 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 da 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 da transmissão, que é 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 sinalizaçã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 marcador de anúncio foi inserido. A veiculação de um anúncio depende de vários fatores, como a disponibilidade dele e o histórico de visualização de anúncios do espectador. Os espectadores que recebem um intervalo comercial voltam à sua transmissão quando ele termina, enquanto os espectadores que não recebem um anúncio continuam assistindo a transmissão durante o intervalo.

O guia Como começar oferece 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: parar 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 quiser parar de transmitir, 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 ao vivo 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 o 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 ter definido 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 com base nele. Para determinar se o vídeo terminou de ser processado, faça uma pesquisa no 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, siga 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 armazenado na etapa 2.4.

Fornecimento do Content ID para conteúdo ao vivo

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, e não é possível desativar a gravação 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 conta de parceiro não for aprovada para criar uma referência para uma transmissão ao vivo antes da transmissão, 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.