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:
|
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: |
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: |
Impostazioni audio | ||
codec |
Required |
La stringa del codec RFC6381.
Esempio: |
bitrate |
Required |
Un numero intero che rappresenta la velocità in bit audio massima di questo profilo in byte per
secondo.
Esempio: |
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: |
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: |
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
Il valore |
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
- Riproduzione con la pubblicazione dei pod con l'SDK IMA:
- Il pod che gestisce la riproduzione con l'inserimento di annunci dinamici dell'API