Manifestatore per gli stream VOD

L'API Pod Serving fornisce accesso ai pod di annunci video a velocità in bit adattiva preparati in modo che possano essere unite direttamente a un HLS rivolto all'utente Playlist multimediale MPEG-DASH.

Questa guida è incentrata sull'implementazione di una manipolazione di base del manifest di pubblicazione dei pod per gli stream VOD.

Ricevi richieste di manifest dello stream

Il manipolatore del manifest deve fornire un endpoint API per l'ascolto del manifest dall'app client del video player. Come minimo, questo endpoint deve Raccogliere un ID stream dall'app del player client. Questo ID stream è utilizzato per identificare la sessione di streaming in Ad Manager nelle richieste di pod di annunci.

Devi anche raccogliere altre informazioni per identificare uno stream di contenuti, ad esempio un ID contenuti.

Esempio di endpoint richiesta manifest

GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}
Parametri del percorso
stream_id L'ID stream di Ad Manager dall'app video player del client.
content_id Un ID ipotetico corrispondente al video di contenuti nel tuo sistema.
format Un parametro ipotetico corrispondente al formato dello stream. Uno dei seguenti:
mpd Per stream MPEG-DASH
m3u8 Per flussi HLS

Recupera lo stream di contenuti

Utilizza il Content ID raccolto dalla richiesta del file manifest per selezionare i contenuti uno stream per eseguire lo stitching con gli annunci.

Richiedi manifest dei pod di annunci

Per richiedere annunci ad Ad Manager, il server deve effettuare una richiesta POST all'annuncio endpoint pod, passando i profili di codifica, il tag annuncio e il targeting richiesti parametri. Questa richiesta include anche l'ID stream che hai raccolto nel passaggio 1.

In cambio, ricevi un elenco di oggetti di pod di annunci contenenti file manifest i pod di annunci richiesti dal tag annuncio del publisher, nonché le informazioni su quando e in cui devono essere inseriti nei tuoi contenuti.

POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json
Parametri del percorso
network_code Il codice di rete Ad Manager 360 del publisher.
stream_id L'ID stream dell'app video player client.

Corpo JSON

Parametri corporei
encoding_profiles Required Un elenco di rappresentazioni JSON dei profili di codifica che vuoi ricevere per ogni interruzione pubblicitaria. Consulta i dettagli di seguito

Per semplificare il più possibile la riproduzione, questo deve corrispondere all'insieme di profili di codifica usati nello stream di contenuti.

ad_tag Required Un tag annuncio per richiedere annunci VMAP.
cuepoints Optional Un elenco di cue point all'interno dello stream di contenuti in cui appaiono le interruzioni pubblicitarie mid-roll essere inserite. I cue point sono misurati in secondi con rappresentazione in virgola mobile.

Richiesto solo per le risposte VMAP che contengono mid-roll che usano positional. È raro.

content_duration_seconds Optional La durata dei contenuti in secondi.

Richiesto solo per le risposte VMAP che contengono mid-roll che usano percentage con offset temporali. È raro.

manifest_type Optional Il formato degli stream di annunci richiesti: hls o dash. Il valore predefinito è hls.
dai_options Optional Opzioni aggiuntive che controllano aspetti del rendering dei manifest. Consulta i dettagli di seguito
Profilo di codifica
profile_name Required Un identificatore per questo profilo di codifica. Può trattarsi di qualsiasi stringa scegliere, ma non è possibile avere più profili di codifica con lo stesso nome lo stesso flusso.
type Required Il tipo di codifica del flusso descritto da questo profilo di codifica. Content (Contenuti) sono: media, iframe, subtitles.
container_type Required Il formato del container utilizzato da questo profilo di codifica. I formati contenitore sono: mpeg2ts, fmp4cmaf e hls_packed_audio
video_settings Optional Obbligatorio se il tipo di profilo di codifica è iframe. Altrimenti, consentito solo se il tipo multimediale contiene video. Vedi i dettagli di seguito.
audio_settings Optional Obbligatorio se il profilo di codifica contiene audio. Consentito solo se il tipo è contenuti multimediali. Consulta i dettagli di seguito
subtitle_settings Optional Obbligatorio se il profilo di codifica contiene sottotitoli. Consulta i dettagli di seguito
Impostazioni video
codec Required La stringa del codec RFC6381.

Esempio: avc1.4d000c
bitrate Required Un numero intero che rappresenta la velocità in bit massima del video di questo profilo, espressa in byte per secondo.
frames_per_second Required La voce f/s in virgola mobile del video.
resolution Required Un valore con codifica JSON contenente il video "width" e "height" in pixel.

Esempio: {"width": 640, "height": 320}
Impostazioni audio
codec Required La stringa del codec RFC6381.

Esempio: mp4a.40.5
bitrate Required Un numero intero che rappresenta la velocità in bit audio massima di questo profilo in byte per secondo.

Esempio: 300000
channels Required Un numero intero che rappresenta il numero di canali audio, inclusa la frequenza bassa canali.
sample_rate Required Un numero intero che rappresenta la frequenza di campionamento audio in Hertz.

Esempio: 4800
Impostazioni sottotitoli
format Required Il formato file utilizzato dai sottotitoli in banda. I valori supportati sono webvtt o ttml.
language Optional La lingua dei sottotitoli come stringa di lingua RFC5646. Se fornito, questo valore viene utilizzato solo per il rendering DASH.

Esempio: en-us
Opzioni DAI
dash_profile Optional Il profilo MPEG-DASH da applicare ai manifest dei pod di annunci. Questa impostazione viene utilizzata Solo manifest DASH. I valori consentiti sono live o on-demand. Il valore predefinito è on-demand.

Il valore live corrisponde al profilo MPEG-DASH "urn:mpeg:dash:profile:isoff-live:2011".

Il valore on-demand corrisponde al profilo MPEG-DASH urn:mpeg:dash:profile:isoff-on-demand:2011.
ad_pod_timeout Optional Il tempo massimo da dedicare alla selezione degli annunci e alla creazione di pod di annunci in floating secondo punto. Una volta trascorso questo tempo, Ad Manager restituisce qualsiasi annunci già selezionati nella risposta ad_pods e interrompe l'operazione e l'elaborazione dei dati.
sam_id Optional Specifica una chiave di debug alternativa che può essere utilizzata per cercare sessioni nei attività di streaming monitor.

Risposta

Parametri di risposta
valid_for Durata della quale le playlist di pod di annunci sono valide in dhms (giorni, ore, minuti, secondi).
valid_until La data e l'ora di validità di queste playlist di pod di annunci come file ISO8601 stringa data/ora, in yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm formato.
ad_pods Un elenco di pod di annunci selezionati per questo stream.
Pod di annunci
manifest_uris Solo per flussi HLS. Mappa della codifica degli ID profilo negli URI del manifest HLS.
mpd_uri Solo per stream DASH. L'URI dell'MPD DASH.
type Il tipo di pod di annunci. I tipi di pod di annunci sono: pre, mid o post.
start Solo per pod di annunci mid-roll. La posizione nello stream in cui il pod di annunci è deve essere inserito in secondi con rappresentazione in virgola mobile.
duration La durata di questo pod di annunci in secondi con rappresentazione in virgola mobile.
midroll_index Solo per pod di annunci mid-roll. L'indice dell'attuale pod di annunci mid-roll. Indicizzazione inizia con 1.

Richiesta di esempio (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

Corpo della richiesta di esempio

Questi sono i contenuti di request-body.json a cui viene fatto riferimento nella chiamata cURL precedente.

{
  "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"
}

Esempio di risposta

{
  "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
    }
  ]
}

Integra i pod di annunci nei contenuti

Il processo di unione dei pod di annunci negli stream di contenuti varia a seconda la tua implementazione, il formato dello stream e le funzionalità che scegli implementare dalle specifiche del formato. Di seguito sono riportati i flussi di lavoro suggerimenti su come gestire questo processo. I dettagli precisi del tuo l'implementazione può variare in base alle esigenze aziendali e ai contenuti i flussi di dati.

Flussi HLS

Se esegui lo stitching di uno stream in formato HLS, lo stream di contenuti sarà una multivariante una playlist di link a manifest di streaming separati, uno per ogni profilo di codifica. Il tuo annuncio i pod devono essere inseriti in ognuno di questi manifest delle varianti. Sola andata in questo modo preparare tutti i manifest delle varianti e trasmetterli a un Delivery Network (CDN) per hosting. La playlist multivariante finale è un insieme di link a questi e i file manifest.

Esegui l'iterazione sui profili di codifica

Per ogni profilo di codifica, raccogli tutti i file manifest dei pod di annunci associati La risposta di Ad Manager, insieme alle relative ore di inizio. Per annuncio pre-roll impostare l'ora di inizio su 0. Per i post-roll, utilizza la durata dei contenuti come all'ora di inizio del pod di annunci. Identificare il flusso della variante nella variante multivariante che corrisponde alle impostazioni audio e video di ciascun profilo di codifica.

Array di pod di annunci di esempio
"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
    }
  ]
Esempio di playlist di contenuti multivariante
#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
Esempio di dati sulle varianti raccolti
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

Inserire annunci nel manifest di ogni variante

Per ogni live streaming delle varianti, esamina i segmenti del file manifest dei contenuti, mantenendo un valore totale del tempo di contenuti trascorso. Quando arrivi alla posizione iniziale di un pod di annunci, estrai l'elenco di segmenti dal file manifest del pod di annunci, aggrega la l'elenco dei segmenti in due tag #EXT-X-DISCONTINUITY e inserisci l'elenco in posizione corrente nel file manifest dei contenuti. Continua questa procedura finché tutti gli annunci sono stati elaborati pod e flussi di varianti.

I manifest risultanti devono essere conformi allo standard HLS. Pertanto, a seconda sulle funzionalità della specifica incluse nel file manifest dei contenuti, potresti dover eseguire un passaggio finale sul manifest combinato per correggere numeri di sequenza, durata dei contenuti, numeri di sequenza di discontinuità e qualsiasi altri tag che devono essere aggiornati per tenere conto dei nuovi segmenti di annunci. Una volta risolte eventuali discrepanze con lo standard, un manifest specifico per l'utente alla rete CDN per l'hosting.

Se il manifest dei contenuti è criptato, devi archiviare l'ultima crittografia trovata prima dell'inizio del pod di annunci corrente in un tag #EXT-X-KEY. Poi, devi aggiungere il tag #EXT-X-KEY:METHOD=NONE per rimuovere la crittografia prima nel primo segmento di ogni pod di annunci. Infine, devi aggiungere una copia del file #EXT-X-KEY prima del primo segmento di contenuti dopo ogni pod di annunci, per per ripristinare la crittografia dei contenuti.

Esempio di dati sulle varianti raccolti
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
File manifest dei contenuti di esempio

Questi sono i contenuti del file manifest https://{...}/1080p.m3u8 elencato nel raccolto i dati delle varianti.

#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
{...}
Esempio di file manifest dei pod di annunci

Questi sono i contenuti Manifest di https://dai.google.com/{...}/pod/1/profile/1080p.m3u8 elencato nei dati delle varianti raccolti.

#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
Esempio di file manifest della variante unita

ovvero il manifest risultante della variante unita, passato alla CDN e ospitato presso 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
{...}

Crea una playlist multivariante

Raccogli gli indirizzi CDN per ogni manifest della variante completata, insieme ai corrispondenti ai dettagli del profilo di codifica e assemblare i risultati in un nuovo manifest multivariante. Questo manifest specifico dell'utente viene restituito come risposta. alla richiesta del file manifest ricevuta nel passaggio 1.

Esempio di playlist multivariante 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

Stream MPEG DASH

Se stai eseguendo lo stitching di uno stream nel formato MPEG DASH, devi produrre solo un singolo file. In questo modo è più facile unire gli stream DASH rispetto a quelli HLS.

Deve essere preparato un file MPD (Media Presenta descrizione) MPEG DASH sono composte da più punti, ciascuno contenente più rappresentazioni. Ciascuna deve corrispondere a uno dei tuoi profili di codifica. Viene restituito ogni pod di annunci di Ad Manager è anche un file MPD contenente una sequenza di punti con rappresentazioni corrispondenti.

Per unire questi file MPD, inizia prendendo nota del momento di inizio per ogni pod di annunci. Per pre-roll, inserisci i periodi dei pod di annunci pre-roll prima di qualsiasi contenuto punto. Per i post-roll, inserisci i periodi dei pod di annunci post-roll dopo tutti i contenuti cicli. Esegui l'iterazione sui periodi del file MPD dei contenuti, tenendo traccia dei il tempo di riproduzione trascorso per tutti i periodi di contenuti elaborati. Quando raggiungi un confine tra i periodi che corrispondono all'ora di inizio di un pod di annunci, inserisci i periodi dal file MPD del pod di annunci mid-roll corrispondente al limite.

Il file MPD finale unito deve essere completamente conforme alle specifiche MPEG_DASH. potresti dover ripetere il file finale ancora una volta correggendo le ore di inizio del periodo, correggendo la durata della presentazione multimediale per tenere conto i periodi di annuncio appena inseriti e risolvendo eventuali altri conflitti che potrebbero derivanti dal processo di unione.

MPD dei contenuti di esempio

<?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>

Esempio JSON di pod di annunci

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

Esempio di MPD del pod di annunci

Questi sono i contenuti di mpd_uri dal file JSON del pod di annunci riportato sopra.

<?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>

Esempio di file MPD unito

Serviti come risposta alla richiesta iniziale del manifest dello stream.

<?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>

Risorse aggiuntive