Intégrer le SDK Cast à votre application d'envoi Web

Ce guide du développeur explique comment ajouter la compatibilité avec Google Cast à votre application Web émettrice à l'aide du SDK Cast.

Remarque : Nous vous recommandons d'essayer les solutions suivantes :

• Tutoriel de l'atelier de programmation Cast Web Sender : découvrez comment modifier une application vidéo Web existante pour lire du contenu sur un appareil Google Cast.
• Exemple d'application CastVideos-chrome (GitHub) : exécutez, parcourez et affichez cet exemple d'application de référence conforme aux consignes d'expérience utilisateur et à la checklist de conception.

Terminologie

L'appareil mobile ou le navigateur est l'émetteur, qui contrôle la lecture. L'appareil Google Cast est le récepteur, qui affiche le contenu à l'écran pour la lecture.

Le SDK Web Sender se compose de deux parties : l'API Framework (cast.framework) et l'API de base (chrome.cast). En général, vous effectuez des appels sur l'API Framework, plus simple et de niveau supérieur, qui sont ensuite traités par l'API de base, de niveau inférieur.

Le framework de l'expéditeur fait référence à l'API Framework, au module et aux ressources associées qui fournissent un wrapper autour des fonctionnalités de niveau inférieur. L'application émettrice ou l'application Google Cast pour Chrome désigne une application Web (HTML/JavaScript) exécutée dans un navigateur Chrome sur un appareil émetteur. Une application réceptrice Web désigne une application HTML/JavaScript exécutée sur un appareil Chromecast ou Google Cast.

Le framework de l'expéditeur utilise une conception de rappel asynchrone pour informer l'application émettrice des événements et pour passer d'un état à un autre du cycle de vie de l'application Cast.

Charger la bibliothèque

Pour que votre application puisse implémenter les fonctionnalités de Google Cast, elle doit connaître l'emplacement du SDK Google Cast Web Sender, comme indiqué ci-dessous. Ajoutez le paramètre de requête d'URL loadCastFramework pour charger également l'API Web Sender Framework. Toutes les pages de votre application doivent faire référence à la bibliothèque comme suit :

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

Framework

Le SDK Web Sender utilise l'espace de noms cast.framework.*. L'espace de noms représente les éléments suivants :

• Méthodes ou fonctions qui appellent des opérations sur l'API
• Écouteurs d'événements pour les fonctions d'écouteur dans l'API

Le framework se compose des principaux éléments suivants :

• CastContext est un objet singleton qui fournit des informations sur l'état actuel de Cast et déclenche des événements pour les changements d'état de Cast et de session Cast.
• L'objet CastSession gère la session. Il fournit des informations sur l'état et déclenche des événements, tels que des modifications du volume de l'appareil, de l'état de coupure du son et des métadonnées de l'application.
• L'élément du bouton Cast, qui est un élément HTML personnalisé simple qui étend le bouton HTML. Si l'icône Cast fournie ne suffit pas, vous pouvez utiliser l'état Cast pour implémenter une icône Cast.
• RemotePlayerController fournit la liaison de données pour simplifier l'implémentation du lecteur distant.

Pour obtenir une description complète de l'espace de noms, consultez la documentation de référence de l'API Google Cast Web Sender.

Icône Cast

Le composant du bouton Cast de votre application est entièrement géré par le framework. Cela inclut la gestion de la visibilité, ainsi que la gestion des événements de clic.

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

Vous pouvez également créer le bouton de manière programmatique :

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

Vous pouvez appliquer tout style supplémentaire, tel que la taille ou le positionnement, à l'élément si nécessaire. Utilisez l'attribut --connected-color pour choisir la couleur de l'état du récepteur Web connecté et --disconnected-color pour l'état déconnecté.

Initialisation

Après avoir chargé l'API du framework, l'application appelle le gestionnaire window.__onGCastApiAvailable. Vous devez vous assurer que l'application définit ce gestionnaire sur window avant de charger la bibliothèque de l'émetteur.

Dans ce gestionnaire, vous initialisez l'interaction Cast en appelant la méthode setOptions(options) de CastContext.

Exemple :

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

Ensuite, vous initialisez l'API comme suit :

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

L'application récupère d'abord l'instance singleton de l'objet CastContext fourni par le framework. Il utilise ensuite setOptions(options) à l'aide d'un objet CastOptions pour définir applicationID.

Si vous utilisez le récepteur multimédia par défaut, qui ne nécessite pas d'enregistrement, vous utilisez une constante prédéfinie par le SDK Web Sender, comme indiqué ci-dessous, au lieu de applicationID :

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

Commande multimédia

Une fois que CastContext a été initialisé, l'application peut récupérer l'élément CastSession actuel à tout moment à l'aide de getCurrentSession().

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

CastSession peut être utilisé pour charger des contenus multimédias sur l'appareil Cast connecté à l'aide de loadMedia(loadRequest). Commencez par créer un MediaInfo à l'aide de contentId et contentType, ainsi que de toute autre information liée au contenu. Créez ensuite un LoadRequest à partir de celui-ci, en définissant toutes les informations pertinentes pour la requête. Enfin, appelez loadMedia(loadRequest) sur votre 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); });

La méthode loadMedia renvoie une promesse qui peut être utilisée pour effectuer toutes les opérations nécessaires à l'obtention d'un résultat positif. Si la promesse est rejetée, l'argument de la fonction sera un chrome.cast.ErrorCode.

Vous pouvez accéder aux variables d'état du lecteur dans RemotePlayer. Toutes les interactions avec RemotePlayer, y compris les rappels et les commandes d'événements multimédias, sont gérées avec RemotePlayerController.

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

RemotePlayerController donne à l'application un contrôle multimédia total sur les commandes PLAY, PAUSE, STOP et SEEK pour le contenu multimédia chargé.

• LECTURE/PAUSE : playerController.playOrPause();
• ARRÊT : playerController.stop();
• SEEK : playerController.seek();

RemotePlayer et RemotePlayerController peuvent être utilisés avec des frameworks de liaison de données, tels que Polymer ou Angular, pour implémenter un lecteur distant.

Voici un extrait de code pour 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>

État du contenu multimédia

Pendant la lecture d'un contenu multimédia, divers événements se produisent. Ils peuvent être capturés en définissant des écouteurs pour différents événements cast.framework.RemotePlayerEventType sur l'objet RemotePlayerController.

Pour obtenir les informations sur l'état du contenu multimédia, utilisez l'événement cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, qui se déclenche lorsque la lecture change et lorsque CastSession.getMediaSession().media change.

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;
  });

Lorsque des événements tels que la mise en pause, la lecture, la reprise ou la recherche se produisent, l'application doit agir en conséquence et se synchroniser avec l'application Web Receiver sur l'appareil Cast. Pour en savoir plus, consultez Mises à jour d'état.

Fonctionnement de la gestion des sessions

Le SDK Cast introduit le concept de session Cast, dont l'établissement combine les étapes de connexion à un appareil, de lancement (ou de participation) d'une application Web Receiver, de connexion à cette application et d'initialisation d'un canal de contrôle multimédia. Pour en savoir plus sur les sessions Cast et le cycle de vie du récepteur Web, consultez le guide sur le cycle de vie des applications du récepteur Web.

Les sessions sont gérées par la classe CastContext, que votre application peut récupérer via cast.framework.CastContext.getInstance(). Les sessions individuelles sont représentées par des sous-classes de la classe Session. Par exemple, CastSession représente les sessions avec des appareils Cast. Votre application peut accéder à la session Cast actuellement active via CastContext.getCurrentSession().

Pour surveiller l'état de la session, ajoutez un écouteur à CastContext pour le type d'événement CastContextEventType.SESSION_STATE_CHANGED.

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;
    }
  })

Pour la déconnexion, par exemple lorsque l'utilisateur clique sur le bouton "Arrêter la diffusion" dans la boîte de dialogue Cast, vous pouvez ajouter un écouteur pour le type d'événement RemotePlayerEventType.IS_CONNECTED_CHANGED dans votre écouteur. Dans votre écouteur, vérifiez si RemotePlayer est déconnecté. Si tel est le cas, mettez à jour l'état du lecteur local si nécessaire. Exemple :

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

Bien que l'utilisateur puisse contrôler directement l'arrêt de la diffusion via l'icône Cast du framework, l'expéditeur peut arrêter la diffusion à l'aide de l'objet CastSession actuel.

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);
}

Transfert de diffusion

La préservation de l'état de la session est à la base du transfert de diffusion, qui permet aux utilisateurs de déplacer des flux audio et vidéo existants d'un appareil à l'autre à l'aide de commandes vocales, de l'application Google Home ou d'écrans connectés. La lecture du contenu multimédia s'arrête sur un appareil (la source) et se poursuit sur un autre (la destination). Tout appareil Cast équipé du dernier micrologiciel peut servir de source ou de destination dans un transfert de diffusion.

Pour obtenir le nouvel appareil de destination pendant le transfert de diffusion, appelez CastSession#getCastDevice() lorsque l'événement cast.framework.SessionState.SESSION_RESUMED est appelé.

Pour en savoir plus, consultez Transfert de diffusion sur le récepteur Web.