Integrar o SDK do Cast ao app de transmissão da Web

Este guia para desenvolvedores descreve como adicionar suporte ao Google Cast ao seu app de transmissão da Web usando o SDK do Cast.

Terminologia

O dispositivo móvel ou navegador é o remetente, que controla a reprodução. O dispositivo com Google Cast é o receptor, que mostra o conteúdo na tela para reprodução.

O SDK de transmissão da Web consiste em duas partes: a API Framework (cast.framework) e a API Base (chrome.cast) Em geral, você faz chamadas na API Framework mais simples e de nível superior, que são processadas pela API Base de nível inferior.

O framework do remetente se refere à API Framework, ao módulo e aos recursos associados que fornecem um wrapper em torno da funcionalidade de nível inferior. O app remetente ou app do Google Cast para Chrome se refere a um app da Web (HTML/JavaScript) em execução em um navegador Chrome em um dispositivo remetente. Um app receptor da Web se refere a um app HTML/JavaScript em execução no Chromecast ou em um dispositivo com Google Cast.

O framework do remetente usa um design de callback assíncrono para informar o app remetente sobre eventos e fazer a transição entre vários estados do ciclo de vida do app Cast.

Carregar a biblioteca

Para que seu app implemente os recursos do Google Cast, ele precisa saber o local do SDK de transmissão da Web do Google Cast, conforme mostrado abaixo. Adicione o parâmetro de consulta de URL loadCastFramework para carregar também a API Framework de transmissão da Web. Todas as páginas do seu app precisam se referir à biblioteca da seguinte maneira:

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Framework

O SDK de transmissão da Web usa o cast.framework.* namespace. O namespace representa o seguinte:

  • Métodos ou funções que invocam operações na API
  • Listeners de eventos para funções de listener na API

O framework consiste nestes componentes principais:

  • O CastContext é um objeto singleton que fornece informações sobre o estado atual do Cast e aciona eventos para mudanças de estado do Cast e da sessão
  • O CastSession objeto gerencia a sessão. Ele fornece informações de estado e aciona eventos, como mudanças no volume do dispositivo, no estado de mudo e nos metadados do app.
  • O elemento do botão "Transmitir", que é um elemento personalizado HTML simples que estende o botão HTML. Se o botão "Transmitir" fornecido não for suficiente, você poderá usar o estado do Cast para implementar um botão.
  • O RemotePlayerController fornece a vinculação de dados para simplificar a implementação do player remoto.

Consulte a referência da API de transmissão da Web do Google Cast para uma descrição completa do namespace.

Botão "Transmitir"

O componente do botão "Transmitir" no seu app é totalmente processado pelo framework. Isso inclui o gerenciamento de visibilidade e o processamento de eventos de clique.

<google-cast-launcher></google-cast-launcher>

Como alternativa, você pode criar o botão de forma programática:

document.createElement("google-cast-launcher");

Você pode aplicar qualquer estilo adicional, como tamanho ou posicionamento, ao elemento conforme necessário. Use o atributo --connected-color para escolher a cor do estado conectado do receptor da Web e --disconnected-color para o estado desconectado.

Inicialização

Depois de carregar a API Framework, o app vai chamar o gerenciador window.__onGCastApiAvailable. Confira se o app define esse gerenciador no window antes de carregar a biblioteca do remetente.

Nesse gerenciador, inicialize a interação do Cast chamando o setOptions(options) método de CastContext.

Exemplo:

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

Em seguida, inicialize a API da seguinte maneira:

initializeCastApi = function() {
  cast.framework.CastContext.getInstance().setOptions({
    receiverApplicationId: applicationId,
    autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
  });
};

Primeiro, o app recupera a instância singleton do CastContext objeto fornecido pelo framework. Em seguida, ele usa setOptions(options) com um CastOptions objeto para definir o applicationID.

Se você estiver usando o receptor de mídia padrão, que não exige registro, use uma constante predefinida pelo SDK de transmissão da Web, conforme mostrado abaixo, em vez do applicationID:

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

Controle de mídia

Depois que o CastContext for inicializado, o app poderá recuperar o CastSession atual a qualquer momento usando getCurrentSession().

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

O CastSession pode ser usado para carregar mídia no dispositivo de transmissão conectado usando loadMedia(loadRequest). Primeiro, crie um MediaInfo, usando o contentId e o contentType, bem como outras informações relacionadas ao conteúdo. Em seguida, crie um LoadRequest e defina todas as informações relevantes para a solicitação. Por fim, chame loadMedia(loadRequest) no seu CastSession.

var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  function() { console.log('Load succeed'); },
  function(errorCode) { console.log('Error code: ' + errorCode); });

O método loadMedia vai retornar uma promessa que pode ser usada para realizar as operações necessárias para um resultado bem-sucedido. Se a promessa for rejeitada, o argumento da função será um chrome.cast.ErrorCode.

Você pode acessar variáveis de estado do player em RemotePlayer. Todas as interações com o RemotePlayer, incluindo callbacks e comandos de eventos de mídia, são processadas com o RemotePlayerController.

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

O RemotePlayerController oferece ao app controle total de mídia de REPRODUZIR, PAUSAR, PARAR e PROCURAR a mídia carregada.

  • REPRODUZIR/PAUSAR: playerController.playOrPause();
  • PARAR: playerController.stop();
  • PROCURAR: playerController.seek();

O RemotePlayer e o RemotePlayerController podem ser usados com frameworks de vinculação de dados, como Polymer ou Angular, para implementar um player remoto.

Confira um snippet de código para Angular:

<button id="playPauseButton" class="playerButton"
  ng-disabled="!player.canPause"
  ng-click="controller.playOrPause()">
    {{player.isPaused ? 'Play' : 'Pause'}}
</button>
<script>
var player = new cast.framework.RemotePlayer();
var controller = new cast.framework.RemotePlayerController(player);
// Listen to any player update, and trigger angular data binding
update.controller.addEventListener(
  cast.framework.RemotePlayerEventType.ANY_CHANGE,
  function(event) {
    if (!$scope.$$phase) $scope.$apply();
  });
</script>

Status da mídia

Durante a reprodução de mídia, vários eventos ocorrem e podem ser capturados definindo listeners para vários cast.framework.RemotePlayerEventType eventos no RemotePlayerControllerobjeto.

Para receber as informações de status da mídia, use o cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED evento, que é acionado quando a reprodução muda e quando o CastSession.getMediaSession().media muda.

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
    // Use the current session to get an up to date media status.
    let session = cast.framework.CastContext.getInstance().getCurrentSession();

    if (!session) {
        return;
    }

    // Contains information about the playing media including currentTime.
    let mediaStatus = session.getMediaSession();
    if (!mediaStatus) {
        return;
    }

    // mediaStatus also contains the mediaInfo containing metadata and other
    // information about the in progress content.
    let mediaInfo = mediaStatus.media;
  });

Quando eventos como pausar, reproduzir, retomar ou procurar ocorrem, o app precisa agir neles e sincronizar entre si e o app receptor da Web no dispositivo Cast. Consulte Atualizações de status para mais informações.

Como o gerenciamento de sessões funciona

O SDK do Cast apresenta o conceito de uma sessão do Cast, cuja criação combina as etapas de conexão a um dispositivo, inicialização (ou participação) de um app receptor da Web, conexão a esse app e inicialização de um canal de controle de mídia. Consulte o guia do ciclo de vida do aplicativo receptor da Web para mais informações sobre as sessões do Cast e o ciclo de vida do receptor da Web.

As sessões são gerenciadas pela classe CastContext, que seu app pode recuperar usando cast.framework.CastContext.getInstance(). As sessões individuais são representadas por subclasses da classe Session. Por exemplo, CastSession representa sessões com dispositivos Cast. Seu app pode acessar a sessão do Cast ativa no momento usando CastContext.getCurrentSession().

Para monitorar o estado da sessão, adicione um listener ao CastContext para o CastContextEventType.SESSION_STATE_CHANGED tipo de evento.

var context = cast.framework.CastContext.getInstance();
context.addEventListener(
  cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
  function(event) {
    switch (event.sessionState) {
      case cast.framework.SessionState.SESSION_STARTED:
      case cast.framework.SessionState.SESSION_RESUMED:
        break;
      case cast.framework.SessionState.SESSION_ENDED:
        console.log('CastContext: CastSession disconnected');
        // Update locally as necessary
        break;
    }
  })

Para a desconexão, como quando o usuário clica no botão "Parar transmissão" na caixa de diálogo do Cast, você pode adicionar um listener para o RemotePlayerEventType.IS_CONNECTED_CHANGED tipo de evento no listener. No listener, verifique se RemotePlayer está desconectado. Se estiver, atualize o estado do player local conforme necessário. Exemplo:

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

Embora o usuário possa controlar diretamente o encerramento do Cast pelo botão do framework, o remetente em si pode parar a transmissão usando o objeto atual CastSession.

function stopCasting() {
  var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
  // End the session and pass 'true' to indicate
  // that Web Receiver app should be stopped.
  castSession.endSession(true);
}

Transferência de stream

A preservação do estado da sessão é a base da transferência de stream, em que os usuários podem mover streams de áudio e vídeo entre dispositivos usando comandos de voz, o app Google Home ou Smart Displays. A mídia para de ser reproduzida em um dispositivo (a origem) e continua em outro (o destino). Qualquer dispositivo Cast com o firmware mais recente pode servir como origem ou destino em uma transferência de stream.

Para receber o novo dispositivo de destino durante a transferência de stream, chame CastSession#getCastDevice() quando o evento cast.framework.SessionState.SESSION_RESUMED for chamado.

Consulte Transferência de stream no receptor da Web para mais informações.

Anterior
Configuração
Avançar
Adicionar recursos avançados