Outil de manipulation du fichier manifeste pour les flux de vidéo à la demande

L'API Pod Serving permet d'accéder à des séries d'annonces vidéo à débit adaptatif préparées de manière à pouvoir être assemblées directement dans une playlist de contenus multimédias HLS ou MPEG-DASH visible par l'utilisateur.

Ce guide explique comment implémenter un serveur de manipulation de fichiers manifeste de diffusion de séries d'annonces de base pour les flux de vidéo à la demande.

Recevoir des requêtes de fichier manifeste de flux

Votre outil de manipulation du fichier manifeste doit fournir un point de terminaison d'API permettant d'écouter les requêtes de fichier manifeste provenant de l'application cliente du lecteur vidéo. Au minimum, ce point de terminaison doit collecter un ID de flux de l'application du lecteur client. Cet ID de flux permet d'identifier la session de streaming auprès d'Ad Manager dans vos requêtes de séries d'annonces.

Vous devez également collecter d'autres informations pour identifier le flux de contenu approprié, par exemple un Content ID.

Exemple de point de terminaison de requête de fichier manifeste

GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}
Paramètres du chemin d'accès
stream_id ID de flux Ad Manager de l'application de lecteur vidéo cliente.
content_id Un identifiant fictif correspondant au contenu vidéo dans votre système
format Paramètre hypothétique correspondant au format du flux. Au choix:
mpd Pour les flux MPEG-DASH
m3u8 Pour les flux HLS

Récupérer le flux de contenu

Utilisez l'ID de contenu collecté à partir de la requête de fichier manifeste pour sélectionner le flux de contenu à ajouter aux annonces.

Demander des fichiers manifestes de séries d'annonces

Pour demander des annonces à Ad Manager, votre serveur doit envoyer une requête POST au point de terminaison des séries d'annonces, en transmettant les profils d'encodage, le tag d'emplacement publicitaire et les paramètres de ciblage demandés. Cette demande inclut également l'ID de flux que vous avez collecté à l'étape 1.

En retour, vous recevez une liste d'objets de séries d'annonces contenant des fichiers manifestes pour les séries d'annonces demandées par le tag d'emplacement publicitaire de l'éditeur, ainsi que des informations sur le moment et l'endroit où elles doivent être insérées dans votre contenu.

POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json
Paramètres du chemin d'accès
network_code Code de réseau Ad Manager 360 de l'éditeur.
stream_id ID de flux de l'application de lecteur vidéo cliente.

Corps JSON

Paramètres du corps
encoding_profiles Required Liste de représentations JSON des profils d'encodage que vous souhaitez recevoir pour chaque coupure publicitaire. Plus d'informations ci-dessous :

Pour que la lecture soit aussi fluide que possible, elle doit correspondre à l'ensemble des profils d'encodage utilisés dans votre flux de contenu.

ad_tag Required Un tag d'emplacement publicitaire pour demander des annonces VMAP.
cuepoints Optional Liste de points de repère dans le flux de contenu où les coupures publicitaires mid-roll seront insérées. Ils sont mesurés en secondes à virgule flottante.

Obligatoire uniquement pour les réponses VMAP contenant des annonces vidéo mid-roll utilisant des décalages temporels positionnels. C'est rare.

content_duration_seconds Optional Durée du contenu en secondes.

Obligatoire uniquement pour les réponses VMAP qui contiennent des annonces vidéo mid-roll en utilisant des décalages temporels de pourcentage. C'est rare.

manifest_type Optional Format des flux d'annonces demandés (hls ou dash). La valeur par défaut est hls.
dai_options Optional Options supplémentaires contrôlant les aspects de l'affichage des fichiers manifestes. Plus d'informations ci-dessous :
Profil d'encodage
profile_name Required Identifiant de ce profil d'encodage. Cette valeur peut être n'importe quelle chaîne de votre choix, mais vous ne pouvez pas avoir plusieurs profils d'encodage portant le même nom sur le même flux.
type Required Type d'encodage du flux décrit par ce profil d'encodage. Les types de contenus sont les suivants: media, iframe, subtitles.
container_type Required Format de conteneur utilisé par ce profil d'encodage. Les formats de conteneurs sont les suivants : mpeg2ts, fmp4cmaf et hls_packed_audio.
video_settings Optional Obligatoire si le type de profil d'encodage est iframe. Sinon, n'est autorisé que si le type de support contient vidéo. Voir les détails ci-dessous
audio_settings Optional Obligatoire si le profil d'encodage contient de l'audio. Uniquement autorisé si le type est "media". Plus d'informations ci-dessous :
subtitle_settings Optional Obligatoire si le profil d'encodage contient des sous-titres. Plus d'informations ci-dessous :
Paramètres vidéo
codec Required Chaîne de codec RFC6381.

Exemple : avc1.4d000c
bitrate Required Entier représentant le débit vidéo maximal de ce profil en octets par seconde.
frames_per_second Required FPS à virgule flottante de la vidéo.
resolution Required Valeur encodée au format JSON contenant les valeurs "width" et "height" de la vidéo en pixels.

Exemple : {"width": 640, "height": 320}
Paramètres audio
codec Required Chaîne de codec RFC6381.

Exemple : mp4a.40.5
bitrate Required Entier représentant le débit audio maximal de ce profil en octets par seconde.

Exemple : 300000
channels Required Entier représentant le nombre de canaux audio, y compris les canaux basse fréquence.
sample_rate Required Entier représentant le taux d'échantillonnage audio en hertz.

Exemple : 4800
Paramètres des sous-titres
format Required Format de fichier utilisé par les sous-titres intégrés au groupe. Les valeurs acceptées sont webvtt ou ttml.
language Optional Langue de sous-titres sous forme de chaîne de langue RFC5646. Si cette valeur est fournie, elle n'est utilisée que pour l'affichage DASH.

Exemple : en-us
Options d'insertion dynamique d'annonce
dash_profile Optional Profil MPEG-DASH à appliquer aux fichiers manifestes de séries d'annonces. Ce paramètre n'est utilisé que pour les fichiers manifestes DASH. Les valeurs autorisées sont live ou on-demand. La valeur par défaut est on-demand.

La valeur live correspond au profil MPEG-DASH "urn:mpeg:dash:profile:isoff-live:2011".

La valeur on-demand correspond au profil MPEG-DASH urn:mpeg:dash:profile:isoff-on-demand:2011.
ad_pod_timeout Optional Temps maximal à consacrer à la sélection des annonces et à la création de séries d'annonces, en secondes à virgule flottante. Une fois ce délai écoulé, Ad Manager affiche toutes les annonces déjà sélectionnées dans la réponse ad_pods et arrête le traitement.
sam_id Optional Spécifie une autre clé de débogage pouvant être utilisée pour rechercher des sessions dans l'outil de contrôle de l'activité des flux.

Réponse

Paramètres de réponse
valid_for Durée de validité de ces playlists de séries d'annonces au format dhms (jours, heures, minutes, secondes).
valid_until Date et heure jusqu'à laquelle ces playlists de séries d'annonces sont valides en tant que chaîne de date et heure ISO 8601, au format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.
ad_pods Liste des séries d'annonces sélectionnées pour ce flux.
Série d'annonces
manifest_uris Pour les flux HLS uniquement. Mappage des ID de profil d'encodage avec les URI du fichier manifeste HLS.
mpd_uri Pour les flux DASH uniquement. URI de la description de la présentation du média DASH.
type Type de série d'annonces. Les types de séries d'annonces sont les suivants: pre, mid ou post.
start Pour les séries d'annonces mid-roll uniquement. Position dans le flux où cette série d'annonces doit être insérée, en secondes à virgule flottante.
duration Durée de cette série d'annonces, en secondes à virgule flottante.
midroll_index Pour les séries d'annonces mid-roll uniquement. Indice de la série d'annonces mid-roll actuelle. L'indexation commence par 1.

Exemple de requête (cURL)

curl -X POST \
     -d '@request-body.json' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/streams/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/adpods

Exemple de corps de requête

Il s'agit du contenu de request_body.json référencé dans l'appel cURL ci-dessus.

{
  "encoding_profiles": [
   {
     "profile_name": "1080p",
     "type": "media",
     "container_type": "mpeg2ts",
     "video_settings": {
       "codec": "avc1.4d000c",
       "bitrate": 5000000,
       "frames_per_second": 30.0,
       "resolution": {
         "width": 1920,
         "height": 1080
       }
     },
     "audio_settings": {
       "codec": "mp4a.40.5",
       "bitrate": 300000,
       "channels": 2,
       "sample_rate": 48000
     }
   },
   {
     "profile_name": "360p",
     "type": "media",
     "container_type": "mpeg2ts",
     "video_settings": {
       "codec": "avc1.4d000d",
       "bitrate": 1000000,
       "frames_per_second": 30.0,
       "resolution": {
         "width": 640,
         "height": 360
       }
     },
     "audio_settings": {
       "codec": "mp4a.40.5",
       "bitrate": 64000,
       "channels": 2,
       "sample_rate": 48000
     }
   },
   {
     "profile_name": "subtitles-webvtt",
     "type": "subtitles",
     "subtitle_settings": {
       "format": "webvtt"
     }
   }
 ],
 "ad_tag": "https://pubads.g.doubleclick.net/gampad/ads?...",
 "manifest_type": "hls"
}

Exemple de réponse

{
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00",
  "ad_pods": [
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/0/profile/1080p.m3u8",
        "360p": "https://{...}/pod/0/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt"
      },
      "type": "pre",
      "duration": 10.0
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/1/profile/1080p.m3u8",
        "360p": "https://{...}/pod/1/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/1/profile/subtitles-en.vtt"
      },
      "type": "mid",
      "start": 15.0,
      "duration": 15.0,
      "midroll_index": 1
    },
    {
      "manifest_urls":{
        ]"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
        "360p": "https://{...}/pod/2/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt""
      },
      "type": "post",
      "duration": 10.0
    }
  ]
}

Assembler les séries d'annonces dans le contenu

Le processus d'intégration des séries d'annonces dans vos flux de contenu varie en fonction de votre implémentation, du format de flux et des fonctionnalités que vous choisissez d'implémenter selon les spécifications du format. Les workflows suivants sont des suggestions pour gérer ce processus. Les détails précis de votre implémentation peuvent varier en fonction des besoins de votre entreprise et de vos flux de contenu.

Flux HLS

Si vous assemblez un flux au format HLS, votre flux de contenu constitue une playlist multivariante de liens vers des fichiers manifestes de flux distincts, un pour chaque profil d'encodage. Vous devez insérer vos séries d'annonces dans chacun de ces fichiers manifestes de variantes. Pour ce faire, vous pouvez préparer tous les fichiers manifestes des variantes et les transmettre à un réseau de diffusion de contenu (CDN) pour l'hébergement. La playlist de multivariantes finale est un ensemble de liens vers ces fichiers manifestes hébergés par CDN.

Itérer des profils d'encodage

Pour chaque profil d'encodage, rassemblez tous les fichiers manifestes de séries d'annonces associés à partir de la réponse d'Ad Manager, ainsi que les heures de début associées. Pour les séries d'annonces pré-roll, définissez l'heure de début sur 0. Pour les annonces vidéo post-roll, utilisez la durée du contenu comme heure de début de la série d'annonces. Dans la playlist de multivariantes, identifiez le flux de variantes qui correspond aux paramètres audio et vidéo de chaque profil d'encodage.

Tableau des exemples de séries d'annonces
"ad_pods": [
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/0/profile/1080p.m3u8",
        "360p": "https://{...}/pod/0/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/0/profile/subitles-en.vtt"
      },
      "type": "pre",
      "duration": 10.0
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/1/profile/1080p.m3u8",
        "360p": "https://{...}/pod/1/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/1/profile/subitles-en.vtt"
      },
      "type": "mid",
      "start": 15.0,
      "duration": 15.0,
      "midroll_index": 1
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/2/profile/1080p.m3u8",
        "360p": "https://{...}/pod/2/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/2/profile/subitles-en.vtt"
      },
      "type": "post",
      "duration": 10.0
    }
  ]
Exemple de playlist de contenus multivariantes
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://{...}/subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://{...}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://{...}/360p.m3u8
Exemple de données de variantes collectées
Encoding profile: "1080p"
Profile settings: {...}
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
    0 -> https://{...}/pod/0/profile/1080p.m3u8
   15 -> https://{...}/pod/1/profile/1080p.m3u8
  600 -> https://{...}/pod/2/profile/1080p.m3u8

Insérer des annonces dans chaque fichier manifeste de variante

Pour chaque flux de variantes, parcourez les segments du fichier manifeste de contenu, en conservant le total cumulé de la durée écoulée pour le contenu. Lorsque vous atteignez la position de départ d'une série d'annonces, extrayez la liste des segments à partir du fichier manifeste de la série d'annonces, encapsulez-la dans deux balises #EXT-X-DISCONTINUITY, puis insérez la liste à l'emplacement actuel dans le fichier manifeste de contenu. Continuez jusqu'à ce que toutes les séries d'annonces et flux de variantes aient été traités.

Les fichiers manifestes obtenus doivent être conformes à la norme HLS. Par conséquent, en fonction des caractéristiques de la spécification que votre fichier manifeste de contenu intègre, vous devrez peut-être effectuer un dernier transfert sur le fichier manifeste combiné pour corriger les numéros de séquence multimédia, la durée du contenu, les numéros de séquence de discontinuité et toute autre balise qui doit être mise à jour pour prendre en compte les nouveaux segments d'annonces. Une fois les écarts par rapport à la norme corrigés, transférez chaque fichier manifeste de variante spécifique à l'utilisateur vers votre CDN pour l'hébergement.

Si le fichier manifeste de votre contenu est chiffré, vous devez stocker la dernière clé de chiffrement détectée avant le début de la série d'annonces actuelle dans une balise #EXT-X-KEY. Vous devez ensuite ajouter le tag #EXT-X-KEY:METHOD=NONE pour supprimer le chiffrement avant le premier segment de chaque série d'annonces. Enfin, vous devez ajouter une copie de la balise #EXT-X-KEY stockée avant le premier segment de contenu après chaque série d'annonces afin de restaurer le chiffrement du contenu.

Exemple de données de variantes collectées
Encoding profile: "1080p"
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
    0 -> https://dai.google.com/{...}pod/0/profile/1080p.m3u8
   15 -> https://dai.google.com/{...}pod/1/profile/1080p.m3u8
  600 -> https://dai.google.com/{...}pod/2/profile/1080p.m3u8
Exemple de fichier manifeste de contenu

Il s'agit du contenu du fichier manifeste https://{...}/1080p.m3u8 indiqué dans les données de variantes collectées.

#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}
Exemple de fichier manifeste de séries d'annonces

Il s'agit du contenu du fichier manifeste https://dai.google.com/{...}/pod/1/profile/1080p.m3u8 listé dans les données de variantes collectées.

#EXTM3U
{...}
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
Exemple de fichier manifeste de variantes assemblées

Il s'agit du fichier manifeste de variante assemblée résultant, transmis au CDN et hébergé à https://cdn.{...}/{userid}/1080p.m3u8.

#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}

Créer une playlist de multivariantes

Collectez les adresses CDN de chaque fichier manifeste de variante terminé, ainsi que les détails du profil d'encodage correspondant, puis assemblez les résultats dans un nouveau fichier manifeste de multivariantes. Ce fichier manifeste spécifique à l'utilisateur est renvoyé en tant que réponse à la requête de fichier manifeste reçue à l'étape 1.

Exemple de playlist de multivariantes finale
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://cdn.{...}-subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://cdn.{...}/{userid}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://cdn.{...}/{userid}/360p.m3u8

Flux MPEG DASH

Si vous assemblez un flux au format MPEG DASH, il vous suffit de produire un seul fichier. Les flux DASH sont ainsi plus faciles à assembler que HLS.

Un fichier MPEG DASH Media présentation Description (MPD) doit comporter plusieurs périodes, chacune contenant plusieurs représentations. Chaque représentation doit correspondre à l'un de vos profils d'encodage. Chaque série d'annonces renvoyée par Ad Manager est également un fichier MPD contenant une séquence de points avec des représentations correspondantes.

Pour assembler ces fichiers MPD, commencez par noter les heures de début de chaque série d'annonces. Pour une annonce vidéo pré-roll, insérez les périodes de série d'annonces pré-roll avant toute période de contenu. Pour les annonces vidéo post-roll, insérez les périodes de série d'annonces post-roll après toutes les périodes de contenu. Itérez les périodes de la description de la présentation du média pour le contenu, en effectuant le suivi du temps de lecture écoulé pour toutes les périodes de contenu traité. Lorsque vous atteignez une limite entre les périodes correspondant à l'heure de début d'une série d'annonces, insérez les périodes du fichier MPD de la série d'annonces mid-roll correspondante à cette limite.

Le fichier MPD final assemblé doit être entièrement conforme aux spécifications MPEG_DASH. Vous devrez donc peut-être itérer une nouvelle fois le fichier final en corrigeant les heures de début des périodes, en corrigeant la durée de présentation du média en fonction des périodes d'annonce nouvellement insérées et en résolvant tout autre conflit susceptible de provenir du processus d'assemblage.

Exemple de description de la présentation du média pour le contenu

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M00.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Example Stream</Title>
  </ProgramInformation>
  <Period duration="PT0H0M15.000S" id="content-period-1">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-2">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-3">
    ...
  </Period>
  ...
</MPD>

Exemple de fichier JSON de série d'annonces

[{
  "mpd_uri": "https://{...}pod/1.mpd",
  "type": "mid",
  "start": 15.0,
  "duration": 15.0,
  "midroll_index": 1
}]

Exemple de description de la présentation du média pour une série d'annonces

Il s'agit du contenu de mpd_uri du fichier JSON de série d'annonces ci-dessus.

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H0M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Ad Pod 1</Title>
  </ProgramInformation>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
    ...
  </Period>
  ...
</MPD>

Exemple de description de la présentation du média assemblé

Utilisez ce message en tant que réponse à la requête initiale de fichier manifeste de flux.

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Example Stream</Title>
  </ProgramInformation>
  <Period duration="PT0H0M15.000S" id="content-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-2">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-3">
    ...
  </Period>
  ...
</MPD>

Ressources supplémentaires