Diffusion en direct

Le SDK Cast inclut des API intégrées pour la diffusion de contenus en direct. Cela inclut une interface utilisateur flexible et prête à l'emploi, associée à des API qui permettent aux développeurs de créer des expériences en direct riches avec quelques lignes de code. L'API Live prend en charge l'affichage des heures de début et de fin, les métadonnées du programme, les commandes DVR et les fenêtres recherchées.

Ce guide explique comment configurer un flux sur les API Live, y compris des exemples de code et de métadonnées pour la configuration des scénarios de base, ainsi que des captures d'écran illustrant chaque scénario.

Conditions préalables

Vous devez connaître les principes de base de la mise en œuvre d'un récepteur Web avant de consulter ce guide. En outre, pour exécuter les exemples de code, vous devez accéder à un flux en direct conforme à l'un des types de supports compatibles avec Cast. En général, cette fonctionnalité est compatible avec les configurations de streaming en direct classiques pour les supports compatibles.

Les termes suivants sont utilisés tout au long du guide:

  • Période de recherche : plage de diffusions en direct que les utilisateurs peuvent rechercher.
  • Live Edge : partie la plus récente d'une diffusion en direct disponible pour le lecteur.
  • Tête de lecture : horodatage de l'interface utilisateur pour la position de lecture actuelle.

Caster une diffusion en direct

Il existe deux manières de configurer le SDK Récepteur Web pour utiliser l'API Live pour le contenu:

  1. à l'aide de l'intercepteur de messages LOAD dans votre application Web Receiver. (recommandée)
  2. à l'aide d'une requête de chargement générée par l'expéditeur ou le destinataire.

L'intercepteur fournit un objet LoadRequestData contenant toutes les métadonnées importantes concernant une requête de chargement. Pour indiquer qu'une requête de chargement concerne un flux en direct, définissez simplement streamType sur l'objet mediaInformation sur StreamType.LIVE. La propriété MediaInformation.duration doit être définie sur -1, car les instances de lecteur doivent la calculer lorsque le contenu est 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;
});

Ajouter des données du guide des programmes

Les diffusions en direct, en particulier celles de longue durée, comme une chaîne de télévision, peuvent afficher des métadonnées de guide ou de programmation à l'écran en fonction de la position de lecture actuelle. Nous recommandons vivement aux fournisseurs de contenu d'inclure des métadonnées de programmation dans leurs applications Web Receiver pour une meilleure expérience utilisateur.

Vous pouvez configurer les données initiales du guide pour un flux dans l'intercepteur de messages LOAD, de la même manière que nous avons indiqué que le flux était un flux en direct dans l'exemple précédent. Les sections ou les programmes individuels du flux en direct sont représentés sous la forme d'objets MediaMetadata, qui sont ensuite stockés dans une file d'attente. Il existe une classe MediaMetadata différente pour différents types de programmes (par exemple, TvShowMediaMetadata, MovieMediaMetadata, MusicTrackMediaMetadata, etc.).

Dans l'extrait de code suivant, nous utilisons l'objet MediaMetadata pour spécifier l'heure de début de chaque émission avec un horodatage UNIX avec la propriété sectionStartAbsoluteTime. La durée d'un programme est représentée en secondes.

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

Portée visible en direct

Le SDK Cast inclut des commandes et des éléments d'interface utilisateur qui permettent à l'utilisateur de déplacer sa tête de lecture dans le flux à l'aide de la commande étendue ou des commandes tactiles sur les appareils tactiles.

La colonne LiveSeekableRange représente la période d'un flux que l'utilisateur peut rechercher. Sur le récepteur Web, vous pouvez accéder aux informations sur la plage recherchée via PlayerManager.getLiveSeekableRange(), qui renvoie un objet LiveSeekableRange. Voici les principales propriétés à connaître sur l'objet:

  • start : heure de début (en secondes) de la plage par rapport au début du flux, en secondes.
  • end : durée maximale (en secondes) pendant laquelle le joueur peut chercher, en fonction des segments disponibles, par rapport au début du flux.
  • isMoveWindow : valeur booléenne indiquant si les plages recherchées (c'est-à-dire les segments plus anciens sont supprimés du fichier manifeste) avec le flux, la valeur doit être true pour tous les flux en direct.
  • isLiveDone : valeur booléenne indiquant si la diffusion en direct est terminée (ce qui signifie qu'aucun nouveau segment n'est généré).

La taille de la plage recherchée, représentée par le temps entre start et end, est déterminée par le nombre de segments disponibles dans le flux et se déplace avec le flux. Par exemple, si, au début du flux, la plage recherchée est {start:0, end: 600, isMovingWindow: false, isLiveDone: false}, dix secondes après le démarrage du flux, elle peut devenir {start: 10, end: 610, isMovingWindow: true, isLiveDone: false}. Il est important de noter que les heures de début et de fin de la plage recherchée sont mises à jour en fonction du temps nécessaire pour générer un nouveau segment. Ainsi, si la durée habituelle d'un segment pour votre flux est de 10 secondes, les heures de début et de fin sont également mises à jour toutes les 10 secondes également.

Désactiver la recherche

Pour désactiver la recherche dans un flux, vous devez supprimer la fonctionnalité de recherche des commandes multimédias compatibles sur le récepteur Web:

// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);

Si vous supprimez la commande multimédia compatible avec SEEK pour les signaux d'application et que les écrans tactiles sont désactivés pour désactiver la recherche, mais ne désactive pas les commandes vocales telles que "Ok Google, revenir en arrière de 30 secondes". Consultez le guide Commandes multimédias compatibles avec commande vocale pour savoir comment désactiver les commandes multimédias pour la commande vocale.

Événements du framework en direct

Deux événements, LIVE_ENDED et LIVE_IS_MOVING_WINDOW_CHANGED, sont inclus dans l'API Live. Les deux événements reçoivent un objet LiveStatusEvent contenant la plage actuelle active.

Événement Description
LIVE_ENDED Déclenché à la fin d'une diffusion en direct. À ce stade, la valeur end dans LiveSeekableRange ne sera plus mise à jour. Les utilisateurs pourront toujours voir le contenu se trouvant dans la plage accessible en direct.
LIVE_IS_MOVING_WINDOW_CHANGED Déclenchement lorsque la plage recherchée d'un flux en direct passe d'une fenêtre fixe à une fenêtre mobile, ou inversement. Pour un flux en direct, cela se produit lorsque le lecteur détecte que le fichier manifeste supprime des segments précédents.

Scénarios de diffusion en direct

Il existe huit types de scénarios possibles pour la diffusion en direct, chacun étant configuré en définissant trois paramètres de base:

  • L'heure de début du flux
  • La diffusion a une heure de fin
  • Les utilisateurs sont autorisés à rechercher des contenus dans la fenêtre visible du flux en direct.

Pour savoir comment configurer ces valeurs, consultez Ajouter les données du guide des programmes.

Vous trouverez ci-dessous des descriptions et des captures d'écran des scénarios compatibles avec l'API Live. Les variables T1 et T2 sont utilisées pour représenter l'horodatage à gauche et à droite de l'interface utilisateur.

Heure de début Heure de fin Recherche facile T1 T2
Scénario 1 Non Non Non Tête de lecture Non affiché
Scénario 2 No No Yes Tête de lecture Non diffusée
Scénario 3 No Oui No Tête de lecture Non diffusée
Scénario 4 No Oui Yes Tête de lecture Non diffusée
Scénario 5 Yes No No Afficher la phase de démarrage Tête de lecture
Scénario 6 Yes No Yes Afficher la phase de démarrage Tête de lecture
Scénario 7 Oui Oui Non Afficher l'heure de début Afficher l'heure de fin
Scénario 8 Oui Yes Oui Afficher l'heure de début Afficher l'heure de fin

Premier scénario

Heure de début Heure de fin Recherche facile T1 T2
Non Non Non Tête de lecture Non affiché

Le scénario 1 n'a pas d'heure de début ni de fin, et les utilisateurs ne peuvent pas effectuer de recherches dans le flux. Lorsqu'un utilisateur arrête un flux, la lecture reprend à partir du bord de la vidéo, et non là où le flux a été mis en pause.

Scénario 7

Un téléviseur montrant l'interface utilisateur en direct de Chromecast pour le scénario 7 avec l'heure de l'horloge Téléphone mobile montrant l'interface utilisateur en direct du scénario 7 avec l'heure de l'horloge

Heure de début Heure de fin Recherche facile T1 T2
Oui Oui Non Tête de lecture Durée du programme

L'heure de début et l'heure de fin du scénario 7 ne sont pas disponibles. Les deux horodatages de l'interface utilisateur, T1 et T2, représentent respectivement la tête de lecture actuelle et la durée totale du programme. Si un utilisateur interrompt ou reprend la lecture, la diffusion reprend au niveau de la diffusion en direct. Dans l'exemple ci-dessus, la section rouge de la barre de recherche représente la partie du flux depuis que l'utilisateur a commencé à regarder la vidéo.

Scénario 8

Un téléviseur affichant l'interface utilisateur en direct de Chromecast pour le scénario 8 avec l'heure de l'horloge Téléphone mobile montrant l'interface utilisateur en direct pour le scénario 8 avec l'heure de l'horloge

Heure de début Heure de fin Recherche facile T1 T2
Oui Yes Oui Tête de lecture Durée du programme

Le scénario 7 comprend des heures de début et de fin, et est recherché. Dans l'interface utilisateur, les deux horodatages T1 et T2 représentent respectivement la tête de lecture actuelle et la durée totale du programme. Si un utilisateur interrompt ou reprend la lecture, le flux reprendra au moment où il s'arrête s'il se trouve dans la fenêtre de recherche. La zone en rouge sur la barre de recherche représente l'endroit où l'utilisateur peut revenir et la zone en blanc représente l'endroit où il peut revenir.

Configurer un scénario

La configuration d'un flux en tant que scénario en direct spécifique s'effectue en trois parties:

  1. Set Stream Type (Définir le type de flux) : marquez le flux comme diffusion en direct.
  2. Ajouter les données du guide des programmes : définissez une heure de début et une durée dans l'objet MediaMetadata.
  3. Configurer la fonctionnalité de recherche : activez ou désactivez la recherche.

Comportement de lecture

Pendant la mise en pause, les métadonnées de lecture de l'interface utilisateur continueront d'être mises à jour, y compris les temps de tête de lecture et de diffusion en direct. À la reprise du flux, plusieurs comportements à prendre en compte dépendent de la configuration du flux.

Flux consultables

À la reprise d'un flux recherché:

  • Le bord réel doit être mis à jour en fonction de l'emplacement réel, et la plage recherchée sera ajustée en conséquence.
  • Si la tête de lecture dépasse l'émission en cours, la barre de lecture est mise à jour avec les métadonnées de la nouvelle émission (y compris l'heure de début et de fin, le cas échéant).
  • Si la fenêtre recherchée a une longueur de "X", la plage de recherche s'étendra au maximum à "X" ou au début de l'émission, selon la valeur la plus petite.
  • Si l'utilisateur a été mis en veille suffisamment longtemps pour que l'heure actuelle ne soit plus dans la fenêtre de recherche, le flux reprend au début (tout à gauche) de la fenêtre de recherche.

Recherchez LiveSeekableRange.end pour reprendre la lecture sur le bord du direct après sa réactivation.

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

Flux non recherchés

À la reprise d'un flux non consultable:

  • Dans ce cas, la lecture reprendra en direct.
  • Si la bordure en direct dépasse l'émission en cours, la barre de lecture doit être mise à jour avec les métadonnées de la nouvelle émission (y compris l'heure de début et de fin, si elles sont disponibles).

Modifications de la surface de l'API et personnalisation de l'UI en direct

Le SDK Cast permet de créer des interfaces utilisateur personnalisées au lieu d'utiliser l'interface utilisateur prête à l'emploi. Cependant, il est important de suivre la checklist de conception de l'expérience utilisateur Cast lorsque vous personnalisez l'interface.

Récepteur Web

Sur le récepteur Web, le PlayerData inclut les champs suivants pour permettre aux développeurs d'étendre leurs interfaces personnalisées pour les diffusions en direct:

  • isLive : option indiquant si le flux en cours est en direct et non VOD.
  • liveSeekableRange : plage pouvant être affichée à l'écran et délimitant la fenêtre DVR.
  • mediaStartabsoluteTime : date et heure de début de la section en temps absolu (UNIX Epoch).
  • sectionStartTimeInMedia : heure de début de la section, en secondes, par rapport à l'heure de début du support
  • sectionDuration : durée de la section en secondes.

Veillez également à tenir compte des deux événements en direct lorsque vous personnalisez l'UI.

SDK Android

Dans le cadre de la fonctionnalité Live, l'utilisation du widget Seekbar d'Android dans UIMediaController a été abandonnée à la place de CastSeekBar.