Manipulador de manifiestos para transmisiones de VOD

La API de Pod Serving proporciona acceso a los grupos de anuncios de video con tasa de bits adaptable preparados de manera que puedan unirse directamente a un servidor HLS orientado al usuario Playlist de contenido multimedia MPEG-DASH.

Esta guía se enfoca en implementar una manipulación básica del manifiesto de Publicación de grupos de anuncios para transmisiones de VOD.

Cómo recibir solicitudes de manifiesto de transmisión

Tu manipulador de manifiestos debe proporcionar un extremo de API para escuchar el manifiesto de la app cliente del reproductor de video. Como mínimo, este extremo debe recopilar un ID de transmisión de la app de reproductor cliente Este ID de transmisión se usa para identificar la sesión de transmisión a Ad Manager en tus solicitudes de grupos de anuncios.

También debe recopilar otra información para identificar la la transmisión de contenido, por ejemplo, un ID de contenido.

Ejemplo de extremo de solicitud de manifiesto

GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}
Parámetros de ruta
stream_id Es el ID de transmisión de Ad Manager de la app del reproductor de video del cliente.
content_id Un ID hipotético que corresponde al video de contenido en tu sistema.
format Es un parámetro hipotético que corresponde al formato de transmisión. Uno de los siguientes:
mpd Para transmisiones MPEG-DASH
m3u8 Para transmisiones HLS

Recupera la transmisión de contenido

Usa el ID de contenido recopilado de la solicitud del manifiesto para seleccionar el contenido transmitir para unir anuncios.

Solicitar manifiestos de grupos de anuncios

Para solicitar anuncios de Ad Manager, su servidor debe enviar una solicitud POST al anuncio extremo de grupos de anuncios, pasando los perfiles de codificación, la etiqueta de anuncios y la segmentación solicitados. parámetros. Esta solicitud también incluye el ID de transmisión que recopilaste en el paso 1)

A cambio, recibe una lista de objetos de grupos de anuncios que contienen archivos de manifiesto de los grupos de anuncios solicitados por la etiqueta de anuncio del publicador y la información dónde deberían insertarse en tu contenido.

POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json
Parámetros de ruta
network_code Es el código de red de Ad Manager 360 del publicador.
stream_id El ID de transmisión de la app de reproductor de video del cliente.

Cuerpo JSON

Parámetros corporales
encoding_profiles Required Una lista de representaciones JSON de los perfiles de codificación que quieres recibir para cada pausa publicitaria. Sigue leyendo para conocer más detalles

Para que la reproducción sea lo más fluida posible, esto debe coincidir con el conjunto de los perfiles de codificación utilizados en la transmisión de contenido.

ad_tag Required Una etiqueta de anuncio para solicitar anuncios de VMAP.
cuepoints Optional Una lista de puntos de inserción dentro de la transmisión de contenido donde se mostrarán las pausas publicitarias durante el video. insertar. Los puntos de inserción se miden en segundos de punto flotante.

Obligatorio solo para las respuestas de VMAP que contienen anuncios durante el video con posicionales. Esto es poco común.

content_duration_seconds Optional Es la duración del contenido en segundos.

Obligatorio solo para las respuestas de VMAP que contienen anuncios durante el video con percentage. Esto es poco común.

manifest_type Optional El formato de los flujos de anuncios que se solicitan, ya sea hls o dash El valor predeterminado es hls.
dai_options Optional Son opciones adicionales que controlan aspectos de la manera en que se representan los manifiestos. Sigue leyendo para conocer más detalles
Perfil de codificación
profile_name Required Es un identificador para este perfil de codificación. Este valor puede ser cualquier cadena que pero no puedes tener varios perfiles de codificación con el mismo nombre en la misma transmisión.
type Required El tipo de codificación de la transmisión que describe este perfil de codificación. Contenido Los tipos son media, iframe y subtitles.
container_type Required El formato de contenedor que usa este perfil de codificación. Los formatos de contenedor son los siguientes: mpeg2ts, fmp4cmaf y hls_packed_audio
video_settings Optional Obligatorio si el tipo de perfil de codificación es iframe. De lo contrario, solo se permite si el tipo de medio contiene video. Consulta a continuación
audio_settings Optional Obligatorio si el perfil de codificación contiene audio. Solo se permite si el tipo es medios de comunicación. Sigue leyendo para conocer más detalles
subtitle_settings Optional Obligatorio si el perfil de codificación contiene subtítulos. Sigue leyendo para conocer más detalles
Configuración de video
codec Required La cadena del códec RFC6381.

Ejemplo: avc1.4d000c.

bitrate Required Un número entero que representa la tasa de bits de video máxima de este perfil en bytes por por segundo.
frames_per_second Required Es el valor de FPS de punto flotante del video.
resolution Required Un valor codificado en JSON que contiene el valor "width" y "height" del video en píxeles.

Ejemplo: {"width": 640, "height": 320}.

Configuración de audio
codec Required La cadena del códec RFC6381.

Ejemplo: mp4a.40.5.

bitrate Required Un número entero que representa la tasa de bits de audio máxima de este perfil en bytes por por segundo.

Ejemplo: 300000.

channels Required Un número entero que representa la cantidad de canales de audio, incluida la frecuencia baja canales.
sample_rate Required Es un número entero que representa la tasa de muestreo de audio en hercios.

Ejemplo: 4800.

Configuración de subtítulos
format Required Formato de archivo que usan los subtítulos en banda. Valores admitidos: webvtt o ttml.
language Optional El idioma de subtítulos como una cadena de idioma RFC5646. Si se proporciona, este valor solo se usa para el procesamiento DASH.

Ejemplo: en-us.

Opciones de DAI
dash_profile Optional Es el perfil de MPEG-DASH que se aplicará a los manifiestos de grupos de anuncios. Este parámetro de configuración se usa para Solo manifiestos de DASH. Los valores permitidos son live o on-demand El valor predeterminado es on-demand.

El valor live corresponde al perfil de MPEG-DASH. "urn:mpeg:dash:profile:isoff-live:2011"

El valor on-demand corresponde al perfil de MPEG-DASH. urn:mpeg:dash:profile:isoff-on-demand:2011

ad_pod_timeout Optional El tiempo máximo que se debe dedicar a seleccionar anuncios y crear grupos de anuncios en anuncios flotantes punto y segundos. Una vez transcurrido ese tiempo, Ad Manager mostrará los anuncios ya seleccionados en la respuesta ad_pods y se detienen el procesamiento de datos.
sam_id Optional Especifica una clave de depuración alternativa que se puede usar para buscar sesiones en el actividad de transmisión supervisión.

Respuesta

Parámetros de respuesta
valid_for Duración de la validez de estas playlists de grupos de anuncios en dhms (días, horas, minutos, segundos).
valid_until La fecha y hora hasta la que estas playlists de grupos de anuncios son válidas como norma ISO8601 String de fecha y hora, en yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm de un conjunto de datos tengan un formato común.
ad_pods Es una lista de grupos de anuncios seleccionados para esta transmisión.
Grupo de anuncios
manifest_uris Solo para transmisiones HLS. Es una asignación de los IDs de perfiles de codificación a los URI de manifiesto de HLS.
mpd_uri Solo para transmisiones DASH. El URI de la MPD de DASH.
type Es el tipo de grupo de anuncios. Los tipos de grupos de anuncios son: pre, mid o post
start Solo para grupos de anuncios durante el video. Es la posición en la transmisión en la que este grupo de anuncios. debe insertarse en segundos de punto flotante.
duration Es la duración de este grupo de anuncios en segundos de punto flotante.
midroll_index Solo para grupos de anuncios durante el video. Es el índice del grupo de anuncios durante el video actual. Indexación comienza con 1.

Solicitud de ejemplo (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

Cuerpo de la solicitud de ejemplo

Este es el contenido de request-body.json al que se hace referencia en la llamada cURL anterior.

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

Ejemplo de respuesta

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

Unir grupos de anuncios en el contenido

El proceso de unir grupos de anuncios a sus transmisiones de contenido varía según sobre tu implementación, el formato de transmisión y las funciones que elijas implementar a partir de las especificaciones del formato. Los siguientes flujos de trabajo son sugerencias sobre cómo manejar este proceso. Los detalles precisos de tus de implementación puede variar según las necesidades de tu empresa y tu contenido transmisiones continuas.

Transmisiones HLS

Si quieres unir una transmisión en el formato HLS, la transmisión de contenido será una multivariante playlist de vínculos a manifiestos de transmisión separados, uno para cada perfil de codificación. Su anuncio Pods deben insertarse en cada uno de estos manifiestos de variantes. Una forma de hacer esto es preparar todos los manifiestos de variantes y pasarlos a una de distribución (CDN) para web. La última playlist de múltiples variantes es un conjunto de vínculos a estas manifiestos.

Cómo iterar en perfiles de codificación

Para cada perfil de codificación, recopile todos los manifiestos de grupos de anuncios asociados de Es la respuesta de Ad Manager, junto con sus horas de inicio asociadas. Para anuncios previos al video Pods, establece la hora de inicio en 0. Para los anuncios al final del video, usa la duración del contenido como la hora de inicio del grupo de anuncios. Identifica el flujo de variantes en la multivariante playlist que coincida con la configuración de audio y video de cada perfil de codificación.

Ejemplo de array de grupos de anuncios
"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
    }
  ]
Ejemplo de playlist de contenido de múltiples variantes
#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
Ejemplo de datos de variantes recopilados
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

Inserta anuncios en el manifiesto de cada variante

Para cada transmisión de variantes, revisa los segmentos del manifiesto de contenido y mantén un el total de tiempo del contenido transcurrido. Cuando llegues a la posición inicial de un grupo de anuncios, extraer la lista de segmentos del manifiesto del grupo de anuncios, unir una lista de segmentos en dos etiquetas #EXT-X-DISCONTINUITY y, luego, inserta la lista en el la ubicación actual en el manifiesto de contenido. Continúa este proceso hasta que se muestren los Pods y las transmisiones de variantes.

Los manifiestos resultantes deben cumplir con el estándar HLS. Por lo tanto, dependiendo sobre las funciones de la especificación que incorpora tu manifiesto de contenido, quizás debas hacer un repaso final del manifiesto combinado para corregir el contenido multimedia de secuencia, la duración del contenido, los números de secuencia de discontinuidad y cualquier otras etiquetas que deben actualizarse para tener en cuenta los nuevos segmentos de anuncios. Cuando se hayan corregido las discrepancias con el estándar, envía cada del manifiesto de la variante específica del usuario a tu CDN para el hosting.

Si tu manifiesto de contenido está encriptado, debes almacenar el último archivo que se encuentra antes del inicio del grupo de anuncios actual en una etiqueta #EXT-X-KEY. Luego, debes agregar la etiqueta #EXT-X-KEY:METHOD=NONE para quitar la encriptación antes el primer segmento de cada grupo de anuncios. Por último, debes agregar una copia del archivo Etiqueta #EXT-X-KEY antes del primer segmento de contenido después de cada grupo de anuncios para restablecer la encriptación de contenido.

Ejemplo de datos de variantes recopilados
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
Ejemplo de manifiesto de contenido

Este es el contenido del manifiesto https://{...}/1080p.m3u8 que se menciona en el datos de variantes recopilados.

#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
{...}
Ejemplo de manifiesto de grupo de anuncios

Este es el contenido del Manifiesto de https://dai.google.com/{...}/pod/1/profile/1080p.m3u8 que se enumeran en los datos recopilados de las variantes.

#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
Ejemplo de manifiesto de variante unida

Este sería el manifiesto de la variante unida resultante, que se pasa a la CDN y alojado en 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 playlists de múltiples variantes

Recopila las direcciones de la CDN de cada manifiesto de variante completado, junto con los hacer coincidir los detalles del perfil de codificación y reunir los resultados en una nueva manifiesto de múltiples variantes. Este manifiesto específico del usuario se muestra como respuesta a la solicitud de manifiesto que recibiste en el paso 1.

Ejemplo de playlist final de múltiples variantes
#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

Transmisiones MPEG DASH

Si vas a unir una transmisión en formato MPEG DASH, solo debes producir un solo archivo. Esto puede hacer que las transmisiones DASH sean más fáciles de unir que las HLS.

Un archivo de descripción de presentación multimedia (MPD) MPEG DASH preparado correctamente debe constan de varios períodos, cada uno de los cuales contiene múltiples representaciones. Cada la representación debe coincidir con uno de tus perfiles de codificación. Cada grupo de anuncios devuelto de Ad Manager también es un archivo MPD que contiene una secuencia de puntos con representaciones coincidentes.

Para unir estos archivos MPD, comienza por tomar nota de las horas de inicio de para cada grupo de anuncios. Para los anuncios previos al video, inserte los puntos del grupo de anuncios previos al video antes de cualquier anuncio. período. Para los anuncios al final del video, inserte los puntos del grupo de anuncios al final del video después de todo el contenido. en los períodos de prueba. Iterar en los períodos de la MPD de contenido y hacer un seguimiento del tiempo de reproducción transcurrido para todos los períodos de contenido procesado. Cuando alcances un límite entre los períodos que corresponden a la hora de inicio de un grupo de anuncios, inserte los puntos del archivo MPD del grupo de anuncios durante el video coincidente en ese límite.

El archivo MPD unido final debe cumplir por completo con las especificaciones MPEG_DASH, por lo que quizás debas iterar sobre el archivo final una vez más y corregir de inicio del período y corregir la duración de la presentación en los medios para dar cuenta del los períodos publicitarios insertados recientemente y la resolución de cualquier otro conflicto que podría haber surgen del proceso de costura.

Ejemplo de MPD de contenido

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

Ejemplo de JSON de grupo de anuncios

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

Ejemplo de MPD de grupo de anuncios

Este es el contenido de mpd_uri del JSON del grupo de anuncios anterior.

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

Ejemplo de MPD unida

Úsala como respuesta a la solicitud inicial del manifiesto de transmisión.

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

Recursos adicionales