O SDK do Cast inclui APIs integradas para oferecer suporte a conteúdo ao vivo. Isso inclui uma IU flexível e pronta para uso, além de APIs que permitem aos desenvolvedores criar experiências avançadas de vida com apenas algumas linhas de código. A API Live permite exibir horários de início e término, metadados do programa, controles de DVR e janelas pesquisáveis.
Este guia demonstra como configurar um stream para as APIs ao vivo, incluindo amostras de código e metadados para configurar os principais cenários ao vivo, além de capturas de tela que demonstram a aparência de cada cenário.
Pré-requisitos
É necessário conhecer os princípios básicos da implementação de um Web Receiver antes de ler este guia. Além disso, para executar os exemplos de código, você precisa de acesso a uma transmissão ao vivo que esteja em conformidade com um dos tipos de mídia compatíveis com o Cast. Em geral, o recurso "Ao vivo" oferece suporte a configurações típicas de transmissão ao vivo para a mídia compatível.
Os termos a seguir são usados ao longo do guia:
- Janela pesquisável: o intervalo de uma transmissão ao vivo que os usuários podem procurar.
- Live Edge: a parte mais recente de uma transmissão ao vivo disponível para o jogador.
- Play Head: é um carimbo de data/hora de IU da posição de reprodução atual.
Transmitir uma transmissão ao vivo
Há duas maneiras de configurar o SDK do receptor da Web para usar a API Live para conteúdo:
- usando o interceptador de mensagens
LOADno aplicativo receptor da Web. (recomendado) - usando uma solicitação de carga gerada pelo remetente ou pelo receptor.
O interceptador fornece um objeto
LoadRequestData
que contém todos os metadados importantes sobre uma solicitação de carregamento. Para
indicar que uma solicitação de carregamento é de uma transmissão ao vivo, basta definir
streamType
no objeto
mediaInformation
como
StreamType.LIVE.
MediaInformation.duration precisa ser -1, porque as instâncias do jogador são
responsáveis por calcular quando o conteúdo é LIVE.
/*
* This interceptor is called before your content is loaded by a Cast device
*/
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD,
request => { /* cast.framework.messages.LoadRequestData */
request.media.streamType = cast.framework.messages.StreamType.LIVE;
return request;
});
Adicionar dados do guia de programação
As transmissões ao vivo, especialmente de longa duração, como um canal de TV, podem exibir metadados de programação/guia na tela com base na posição de reprodução atual em uma transmissão ao vivo. Recomendamos que os provedores de conteúdo incluam metadados de programação nos aplicativos Web Receiver para melhorar a experiência do usuário final.
É possível configurar os dados iniciais do guia para um stream no interceptador da mensagem
LOAD, da mesma forma que indicamos que era um stream ao vivo no
exemplo anterior. Seções ou programas individuais na transmissão ao vivo são
representados como objetos
MediaMetadata
armazenados em uma
fila.
Há uma classe MediaMetadata diferente para diferentes tipos de programas, por exemplo,
TvShowMediaMetadata,
MovieMediaMetadata,
MusicTrackMediaMetadata
etc.
No snippet de código a seguir, usamos o objeto MediaMetadata para especificar o
horário de início de cada programa com um
carimbo de data/hora UNIX com a
propriedade
sectionStartAbsoluteTime. A duração de um programa é representada em segundos.
// The metadata for a single TV show
const currentShow = new cast.framework.messages.TvShowMediaMetadata();
currentShow.episode = 15;
currentShow.seriesTitle = 'The Odyssey';
currentShow.title = 'Scylla and Charybdis';
currentShow.sectionStartAbsoluteTime = toUnixTimestamp('9:00 PM');
currentShow.sectionDuration = HOUR_IN_SECONDS;
const previousShow = new ...;
const nextShow = new ...;
const containerMetadata = new cast.framework.messages.ContainerMetadata();
containerMetadata.title = 'My TV Channel';
containerMetadata.sections = [previousShow, currentShow, nextShow];
playerManager.getQueueManager().setContainerMetadata(containerMetadata);
Intervalo pesquisável ao vivo
O SDK do Cast inclui controles e elementos da IU que permitem ao usuário mover o marcador dentro do stream usando o controlador expandido ou controles de toque em dispositivos com recurso de toque.
O
LiveSeekableRange
representa o intervalo de tempo em um stream em que um usuário pode procurar. No
Receptor da Web, é possível acessar informações sobre o intervalo pesquisável por meio de
PlayerManager.getLiveSeekableRange(),
que retorna um objeto
LiveSeekableRange. As principais propriedades do objeto que você precisa conhecer são:
- start: o horário de início (em segundos) do intervalo em relação ao início do stream em segundos.
- end: o tempo máximo (em segundos) que o jogador pode procurar, com base nos segmentos disponíveis em relação ao início do stream.
- isMoveWindow: um valor booleano que indica se o intervalo pesquisável se move (ou seja, segmentos mais antigos foram removidos do manifesto) com o stream. Esse valor precisa ser true para todas as transmissões ao vivo.
- isLiveDone: um valor booleano que indica se a transmissão ao vivo foi concluída, o que significa que nenhum segmento novo está sendo gerado.
O tamanho do intervalo pesquisável, representado como o tempo entre start e
end, é determinado pelo número de segmentos disponíveis no stream e vai
ser movido com ele. Por exemplo, se, no início do stream, o intervalo pesquisável for {start:0, end: 600, isMovingWindow: false, isLiveDone: false}, dez segundos após o início do stream, ele poderá se tornar {start: 10, end: 610,
isMovingWindow: true, isLiveDone: false}. É importante observar que os horários de início e
término no intervalo pesquisável são atualizados com base no tempo necessário para
gerar um novo segmento. Assim, se a duração típica de um segmento para o stream
for 10 segundos, os horários de início e término também serão atualizados a cada 10 segundos.
Desativar busca
Para desativar a busca em um stream, você precisa remover a funcionalidade de busca dos comandos de mídia com suporte no receptor da Web:
// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);
A remoção do comando de mídia compatível para indicadores de SEEK para aplicativos de remetente
e touchscreens para desativar a busca, mas não desativa os comandos de voz,
como "Ok Google, busque 30 segundos para trás". Consulte o
guia de comandos de mídia compatíveis com a voz
para ver detalhes sobre como desativar os comandos de mídia para voz.
Eventos de framework em tempo real
Dois eventos, LIVE_ENDED e LIVE_IS_MOVING_WINDOW_CHANGED, estão incluídos na
API Live. Os dois eventos recebem um objeto
LiveStatusEvent, que contém o intervalo atual pesquisável.
| Evento | Descrição |
|---|---|
LIVE_ENDED |
Acionado quando uma transmissão ao vivo termina. A partir de agora, o valor de end no LiveSeekableRange deixará de ser atualizado. Os usuários ainda poderão ver o conteúdo dentro do intervalo pesquisável. |
LIVE_IS_MOVING_WINDOW_CHANGED |
Acionado quando o intervalo pesquisável de uma transmissão ao vivo muda de uma janela fixa para uma janela móvel ou vice-versa. Isso acontece quando o player detecta que o manifesto está removendo segmentos anteriores. |
Cenários de transmissão ao vivo
Existem oito tipos possíveis de cenário para transmissões ao vivo, cada um definido com três configurações principais:
- O horário de início do stream está em andamento
- A transmissão tem um horário de término
- Os usuários podem buscar na janela pesquisável da transmissão ao vivo
Consulte Como adicionar dados de guia de programação para saber como configurar esses valores.
Veja abaixo as descrições e capturas de tela dos cenários com suporte da API Live. As variáveis T1 e T2 são usadas para representar o carimbo de data/hora à esquerda e à direita da IU, respectivamente.
| Horário de início | Horário de término | Procurável | T1 | T2 (em inglês) | |
|---|---|---|---|---|---|
| Cenário 1 | Não | Não | Não | Cabeça do Google Play | Não exibido |
| Cenário 7 | Sim | Sim | Não | Mostrar horário de início | Mostrar horário de término |
| Cenário 8 | Sim | Yes | Sim | Mostrar horário de início | Mostrar horário de término |
Cenário um
| Horário de início | Horário de término | Procurável | T1 | T2 (em inglês) |
|---|---|---|---|---|
| Não | Não | Não | Reproduzir cabeça | Não exibido |
O cenário um não tem horário de início ou de término e os usuários não podem fazer buscas no stream. Quando um usuário interrompe um stream, a reprodução é retomada da borda ao vivo, em vez de onde o stream foi pausado.
Situação 7
| Horário de início | Horário de término | Procurável | T1 | T2 (em inglês) |
|---|---|---|---|---|
| Sim | Sim | Não | Cabeça do Google Play | Duração do programa |
O cenário 7 tem um horário de início e de término, mas não é pesquisável. Os dois carimbos de data/hora na IU, T1 e T2, representam o tempo de reprodução atual e a duração total do programa, respectivamente. Se um usuário pausar/retomar a reprodução, o stream vai ser retomado na borda ao vivo. No exemplo acima, a seção vermelha da barra de busca representa a parte do stream desde que o usuário começou a assistir.
Cenário oito
| Horário de início | Horário de término | Procurável | T1 | T2 (em inglês) |
|---|---|---|---|---|
| Sim | Yes | Sim | Cabeça do Google Play | Duração do programa |
O cenário 7 tem um horário de início e de término e é pesquisável. Os dois carimbos de data/hora na IU, T1 e T2, representam o tempo de reprodução atual e a duração total do programa, respectivamente. Se um usuário pausar/retomar a reprodução, o stream vai ser retomado no momento em que estiver pausado, se estiver dentro da janela pesquisável. A área em vermelho na barra de busca representa onde um usuário pode voltar e a área em branco representa onde ele pode avançar.
Como configurar um cenário
A configuração de um stream como um cenário ao vivo específico é feita em três partes:
- Defina o tipo de transmissão: marque o stream como uma transmissão ao vivo.
- Adicionar dados do guia de programação: defina um horário de início
e uma duração no objeto
MediaMetadata. - Configurar a funcionalidade de busca: ative ou desative a busca.
Comportamento de reprodução
Enquanto estiver pausada, os metadados de reprodução da IU vão continuar sendo atualizados. Isso inclui os tempos de início da reprodução e de borda em tempo real. Após a retomada do stream, há alguns comportamentos que variam de acordo com a configuração do stream.
Streams pesquisáveis
Após a retomada de uma transmissão pesquisável:
- A borda ativa será atualizada para o local ativo e o intervalo pesquisável vai ser ajustado de acordo.
- Se o marcador passar do programa atual, a barra de reprodução será atualizada com os metadados do novo programa (incluindo os horários de início e término, se disponíveis).
- Se uma janela pesquisável tem a extensão "X", o intervalo pesquisável se estende até o máximo de "X" ou até o início do programa, o que for menor.
- Se o usuário estiver pausado por tempo suficiente para que a hora atual não esteja mais na janela pesquisável, o stream será retomado no ponto mais cedo (à esquerda) da janela pesquisável.
Tente
LiveSeekableRange.end
para retomar a reprodução na borda ativa depois de retomar.
let playerManager = cast.framework.CastReceiverContext.getInstance().getPlayerManager();
// Intercept the message to PLAY
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.PLAY, (requestData) => {
...
if (playerManager.getLiveSeekableRange()) {
// Resume playback at the live edge
playerManager.seek(playerManager.getLiveSeekableRange().end);
} else {
return requestData;
}
...
});
Transmissões não perceptíveis
Após a retomada de uma transmissão não pesquisável:
- Nesse caso, a reprodução vai ser retomada na borda ativa.
- Se a borda ativa passar do programa atual, a barra de reprodução vai ser atualizada com os metadados do novo programa (incluindo os horários de início e término, se disponíveis).
Mudanças na superfície da API e personalização da IU em tempo real
O SDK do Cast tem suporte integrado para criar interfaces do usuário personalizadas em vez de usar a IU pronta para uso. No entanto, é importante seguir a Lista de verificação de design da UX do Google Cast ao personalizar a interface.
Receptor da Web
No receptor da Web, o
PlayerData
inclui os campos a seguir para permitir que os desenvolvedores estendam as interfaces
personalizadas para transmissões ao vivo:
- isLive: uma sinalização que indica se a transmissão atual é uma transmissão ao vivo, em vez de VOD.
- liveSeekableRange: o intervalo pesquisável a ser exibido na tela demarcando a janela de DVR.
- mediaStartAbsoluteTime: quando a seção começou no tempo absoluto (Época UNIX).
- sectionStartTimeInMedia: horário de início da seção em segundos em relação ao horário de início da mídia.
- sectionDuration: duração da seção em segundos.
Além disso, considere os dois eventos ao vivo ao personalizar a IU.
SDK do Android
Como parte da funcionalidade "Ao vivo", o uso do widget de busca da Android no
UIMediaController foi descontinuado. Use a CastSeekBar.