Lire des diffusions en direct enregistrées avec l'API Google Cloud Video Stitcher
Ce guide explique comment utiliser le SDK IMA DAI pour les récepteurs Web CAF afin de demander et de lire une diffusion en direct pour un événement enregistré avec l'API Google Cloud Video Stitcher, et d'insérer une coupure publicitaire pendant la lecture.
Ce guide développe l'exemple de base de l'insertion dynamique d'annonces (DAI) avec service complet, en ajoutant la prise en charge des flux enregistrés avec l'API Google Cloud Video Stitcher.
Avant de continuer, assurez-vous que votre format de streaming est compatible avec les récepteurs Web CAF.
Pour savoir comment intégrer d'autres plates-formes ou utiliser les SDK IMA côté client, consultez SDK Interactive Media Ads.
Arrière-plan
Avant d'utiliser ce guide, familiarisez-vous avec le protocole Web Receiver du framework d'application Chromecast.
Ce guide suppose que vous connaissez les concepts de base du récepteur CAF, tels que les intercepteurs de messages, les objets MediaInformation et l'utilisation de l'outil de commande et de contrôle Cast pour émuler un émetteur CAF.
Composants et architecture de l'application
L'implémentation de la lecture de diffusions en direct avec l'API Google Cloud Video Stitcher avec le SDK IMA CAF DAI implique deux composants principaux, comme indiqué dans ce guide :
VideoStitcherLiveStreamRequest: objet qui définit une requête de flux vers les serveurs Google. La requête spécifie une instance de l'API Cloud Video Stitcher, un ID de configuration en direct et d'autres paramètres facultatifs.StreamManager: objet qui gère la communication entre le flux vidéo et le SDK IMA DAI, par exemple en déclenchant des pings de suivi et en transmettant les événements de flux à l'éditeur.
Prérequis
Vous avez besoin des variables suivantes pour le SDK IMA :
ID de configuration pour le direct : ID de configuration pour le direct que vous avez spécifié lors de la création de votre configuration pour le direct de l'API Video Stitcher.
LIVE_CONFIG_IDEmplacement : région Google Cloud dans laquelle votre configuration en direct a été créée.
LOCATIONNuméro du projet : numéro du projet Google Cloud utilisant l'API Video Stitcher.
PROJECT_NUMBERJeton OAuth : jeton OAuth de courte durée d'un compte de service avec le rôle utilisateur Video Stitcher. Pour en savoir plus sur la création d'identifiants éphémères pour les comptes de service, consultez la page correspondante.
OAUTH_TOKENNetwork Code : code de réseau Google Ad Manager pour demander des annonces.
NETWORK_CODEClé d'asset personnalisée : clé d'asset personnalisée Google Ad Manager générée lors de la création d'une configuration pour un événement en direct avec l'API Video Stitcher.
CUSTOM_ASSET_KEY
Pour créer un récepteur Cast personnalisé, vous avez besoin des éléments suivants :
Un compte Cast Developer Console avec des appareils de test dans une liste d'autorisation.
Une application Web Receiver hébergée et enregistrée dans votre Cast Developer Console, qui peut être modifiée pour héberger le code fourni par ce guide.
Une application émettrice configurée pour utiliser votre application Web Receiver. Pour cet exemple, ce guide utilise l'outil de commande et de contrôle Cast comme émetteur.
Préparer un expéditeur pour transmettre des données de flux au destinataire
Tout d'abord, configurez votre application émettrice pour qu'elle envoie une requête de chargement à votre récepteur Web, contenant les champs suivants dans l'objet MediaInformation de votre plate-forme.
| Champ | Sommaire | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
contentId
|
Identifiant unique de cet élément multimédia, tel que défini dans la documentation de référence Cast. Cet ID ne doit pas être réutilisé pour plusieurs éléments de la même file d'attente multimédia.
|
||||||||||||||
contentUrl
|
URL de la diffusion de sauvegarde facultative à lire si la diffusion DAI ne parvient pas à se charger.
|
||||||||||||||
contentType
|
Type MIME facultatif de l'URL de la diffusion de sauvegarde à lire si la diffusion DAI ne se charge pas.
|
||||||||||||||
streamType
|
Le littéral de chaîne ou la constante utilisés pour cette valeur varient en fonction de la plate-forme de l'expéditeur.
|
||||||||||||||
customData
|
Le champ
|
Voici quelques exemples de code pour vous aider à vous lancer :
Web
Pour configurer ces valeurs dans un émetteur Web Cast, commencez par créer un objet MediaInfo avec les données requises, puis envoyez une requête de chargement au récepteur Web.
// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "BACKUP_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
liveConfigID: "LIVE_CONFIG_ID",
region: "LOCATION",
projectNumber: "PROJECT_NUMBER",
oAuthToken: "OAUTH_TOKEN",
networkCode: "NETWORK_CODE",
customAssetKey: "CUSTOM_ASSET_KEY"
};
// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
() => { console.log('Load succeed'); },
(errorCode) => { console.log('Error code: ' + errorCode); });
Android
Pour configurer ces valeurs dans un émetteur Web Cast, commencez par créer un objet MediaInfo avec les données requises, puis envoyez une requête de chargement au récepteur Web.
JSONObject customData = new JSONObject()
.put("liveConfigID", "LIVE_CONFIG_ID")
.put("region", "LOCATION")
.put("projectNumber", "PROJECT_NUMBER")
.put("oAuthToken", "OAUTH_TOKEN")
.put("networkCode", "NETWORK_CODE")
.put("customAssetKey", "CUSTOM_ASSET_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
.setContentUrl("BACKUP_STREAM_URL")
.setContentType("BACKUP_STREAM_MIMETYPE")
.setStreamType(MediaInfo.STREAM_TYPE_LIVE)
.setCustomData(customData)
.build();
RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());
iOS (Obj-C)
Pour configurer ces valeurs dans un émetteur Web Cast, commencez par créer un objet GCKMediaInformation avec les données requises, puis envoyez une requête de chargement au récepteur Web.
NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
@"liveConfigID": @"LIVE_CONFIG_ID",
@"region": @"LOCATION",
@"projectNumber": @"PROJECT_NUMBER",
@"oAuthToken": @"OAUTH_TOKEN",
@"networkCode": @"NETWORK_CODE",
@"customAssetKey": @"CUSTOM_ASSET_KEY"
};
GCKMediaInformationBuilder *mediaInfoBuilder =
[[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"BACKUP_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];
GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
request.delegate = self;
}
iOS (Swift)
Pour configurer ces valeurs dans un émetteur Web Cast, commencez par créer un objet GCKMediaInformation avec les données requises, puis envoyez une requête de chargement au récepteur Web.
let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
print("invalid mediaURL")
return
}
let customData = [
"liveConfigID": "LIVE_CONFIG_ID",
"region": "LOCATION",
"projectNumber": "PROJECT_NUMBER",
"oAuthToken": "OAUTH_TOKEN",
"networkCode": "NETWORK_CODE",
"customAssetKey": "CUSTOM_ASSET_KEY"
]
let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = "BACKUP_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()
guard let mediaInfo = mediaInformation else {
print("invalid mediaInformation")
return
}
if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia(mediaInfo) {
request.delegate = self
}
Outil CAC
Pour configurer ces valeurs dans l'outil de commande et de contrôle Cast, cliquez sur l'onglet "Load Media" (Charger le contenu multimédia), puis définissez le type de requête de chargement personnalisé sur LOAD. Remplacez ensuite les données JSON dans la zone de texte par ce code JSON :
{
"media": {
"contentId": "CONTENT_ID",
"contentUrl": "BACKUP_STREAM_URL",
"contentType": "BACKUP_STREAM_MIMETYPE",
"streamType": "LIVE",
"customData": {
"liveConfigID": "LIVE_CONFIG_ID",
"region": "LOCATION",
"projectNumber": "PROJECT_NUMBER",
"oAuthToken": "OAUTH_TOKEN",
"networkCode": "NETWORK_CODE",
"customAssetKey": "CUSTOM_ASSET_KEY"
}
}
}
Cette demande de charge personnalisée peut être envoyée au récepteur pour tester le reste des étapes.
Créer un récepteur Web CAF personnalisé
Créez un récepteur Web personnalisé, comme indiqué dans le Guide du récepteur Web personnalisé du SDK CAF.
Le code du destinataire doit ressembler à ce qui suit :
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
</script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance()
castContext.start();
</script>
</body>
</html>
Importer le SDK IMA DAI et obtenir le gestionnaire de lecteur
Ajoutez une balise de script pour importer le SDK IMA DAI pour CAF à votre récepteur Web, juste après le script de chargement CAF. Ensuite, dans la balise de script qui suit, stockez le contexte du récepteur et le gestionnaire de lecteur en tant que constantes avant de démarrer le récepteur.
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
castContext.start();
</script>
</body>
</html>
Initialiser le gestionnaire de flux IMA
Initialisez le gestionnaire de flux IMA.
<html>
<head>
<script type="text/javascript"
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
castContext.start();
</script>
</body>
</html>
Créer l'intercepteur de charge Stream Manager
Avant que vos éléments multimédias ne soient transmis à CAF, créez votre demande de flux dans un intercepteur de message LOAD.
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
/**
* Creates a livestream request object for the Video Stitcher API.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => { /* ... */};
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithStreamData) => {
console.log('Successfully made DAI stream request.');
return castRequestWithStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, createDAICastRequest);
castContext.start();
Créer la requête de flux
Complétez la fonction createStreamRequest pour créer une requête de diffusion en direct de l'API Video Stitcher, basée sur la requête de chargement CAF.
/**
* Creates a livestream request object for the Video Stitcher API.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => {
const streamRequest = new google.ima.cast.dai.api.VideoStitcherLiveStreamRequest();
const customData = castRequest.media.customData;
streamRequest.liveStreamEventId = customData.liveConfigID;
streamRequest.region = customData.region;
streamRequest.projectNumber = customData.projectNumber;
streamRequest.oAuthToken = customData.oAuthToken;
streamRequest.networkCode = customData.networkCode;
streamRequest.customAssetKey = customData.customAssetKey;
return streamRequest;
};
(Facultatif) Ajouter des options de session de streaming
Personnalisez votre demande de flux en ajoutant des options de session pour remplacer la configuration par défaut de l'API Cloud Video Stitcher à l'aide de VideoStitcherLiveStreamRequest.videoStitcherSessionOptions.
Si vous fournissez une option non reconnue, l'API Cloud Video Stitcher répondra avec une erreur HTTP 400. Pour obtenir de l'aide, consultez le guide de dépannage.
Par exemple, vous pouvez remplacer les options du fichier manifeste avec l'extrait de code suivant, qui demande deux fichiers manifestes de flux avec des rendus classés du débit le plus faible au plus élevé.
...
// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
"manifestOptions": {
"bitrateOrder": "ascending"
}
};
streamManager.requestStream(streamRequest);