Manipulator pliku manifestu w przypadku strumieni VOD

Interfejs Pod Serving API zapewnia dostęp do bloków reklam wideo o adaptacyjnej szybkości transmisji danych przygotowanych w taki sposób, aby można je było bezpośrednio zszywać do playlisty multimediów HLS lub MPEG-DASH przeznaczonej dla użytkowników.

Ten przewodnik skupia się na wdrożeniu podstawowego serwera manipulującego plikiem manifestu bloku reklamowego w przypadku strumieni VOD.

Odbieranie żądań pliku manifestu strumienia

Manipulator pliku manifestu musi udostępnić punkt końcowy interfejsu API, który będzie nasłuchiwać żądań pliku manifestu z aplikacji klienta odtwarzacza. Punkt końcowy musi co najmniej zbierać identyfikator strumienia z aplikacji klienta odtwarzacza. Ten identyfikator strumienia jest używany do identyfikowania sesji strumieniowania w usłudze Ad Manager w żądaniach modułów reklamowych.

Musisz też zebrać inne informacje, aby zidentyfikować odpowiedni strumień treści, na przykład identyfikator treści.

Przykład punktu końcowego żądania pliku manifestu

GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}

Pobieranie strumienia treści

Użyj identyfikatora treści zebranego z żądania pliku manifestu, aby wybrać strumień treści, który ma być zszyty z reklamami.

Prośba o pliki manifestu bloków reklamowych

Aby żądać reklam z Ad Managera, serwer musi wysłać żądanie POST do punktu końcowego adpods, przekazując żądane profile kodowania i tag reklamy. To żądanie zawiera również identyfikator strumienia zebrany w kroku 1.

W zamian otrzymasz listę obiektów modułów reklamowych zawierających pliki manifestu modułów reklamowych żądanych przez tag reklamowy wydawcy oraz informacje o tym, kiedy i gdzie należy je wstawić do treści.

POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json

Treść w formacie JSON

Odpowiedź

Przykładowe żądanie (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

Przykładowa treść żądania

To jest zawartość request-body.json, do której odwołuje się wywołanie cURL powyżej.

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

Przykładowa odpowiedź

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

Wplatanie modułów reklamowych w treści

Proces łączenia modułów reklamowych ze strumieniami treści różni się w zależności od implementacji, formatu strumienia i funkcji, które chcesz zaimplementować zgodnie ze specyfikacją formatu. Poniższe przepływy pracy to sugestie dotyczące sposobu postępowania w tym przypadku. Szczegóły wdrożenia mogą się różnić w zależności od potrzeb firmy i strumieni treści.

strumienie HLS,

Jeśli zszywać będziesz strumień w formacie HLS, strumień treści będzie playlistą wielowariantową zawierającą linki do osobnych plików manifestu strumienia, po jednym dla każdego profilu kodowania. Twoje podzbiory reklam muszą zostać wstawione do każdego z tych plików manifestu wariantów. Jednym ze sposobów jest przygotowanie wszystkich plików manifestu wariantów i przekazanie ich do sieci dystrybucji treści (CDN) na potrzeby hostingu. Ostateczna playlista z wieloma wariantami to zestaw linków do tych plików manifestu hostowanych przez sieć CDN.

Przechodzenie przez profile kodowania

W przypadku każdego profilu kodowania pobierz wszystkie powiązane manifesty bloków reklam z odpowiedzi Ad Managera wraz z ich czasami rozpoczęcia. W przypadku podkładów reklam przed filmem ustaw czas rozpoczęcia na 0. W przypadku reklam końcowych użyj czasu trwania treści jako czasu rozpoczęcia podgrupy reklam. Określ strumień wariantu w multiwariantowej playliście, który pasuje do ustawień dźwięku i obrazu każdego profilu kodowania.

Przykładowa tablica bloków reklamowych

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

Przykładowa playlista z wieloma wariantami

#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

Przykład zebranych danych wariantów

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

Wstawianie reklam w każdym pliku manifestu wariantu

W przypadku każdego strumienia wariantu przejrzyj segmenty pliku manifestu treści, zwracając uwagę na łączny upływ czasu trwania treści. Gdy dojdziesz do pozycji początkowej bloku reklamowego, wyodrębnij listę segmentów z pliku manifestu bloku reklamowego, ułóż listę segmentów w ramach dwóch tagów #EXT-X-DISCONTINUITY i wstaw ją w bieżącej lokalizacji w pliku manifestu treści. Kontynuuj ten proces, aż przetworzone zostaną wszystkie podgrupy reklam i warianty.

Wygenerowane pliki manifestu muszą być zgodne ze standardem HLS. Dlatego w zależności od tego, które funkcje specyfikacji zawiera manifest treści, konieczne może być wykonanie ostatniego przejścia przez połączony plik manifestu w celu poprawienia numerów sekwencji multimediów, czasu trwania treści, numerów sekwencji przerwania i innych tagów, które należy zaktualizować, aby uwzględnić nowe segmenty reklam. Gdy usuniesz wszelkie rozbieżności ze standardem, prześlij do sieci CDN manifesty wariantów dla poszczególnych użytkowników, aby je hostować.

Jeśli manifest treści jest zaszyfrowany, musisz przechowywać ostatni klucz szyfrowania znaleziony przed rozpoczęciem bieżącego podgrupy reklam w tagu #EXT-X-KEY. Następnie musisz dodać tag #EXT-X-KEY:METHOD=NONE, aby usunąć szyfrowanie przed pierwszym segmentem każdego podzbioru reklam. Na koniec musisz dodać kopię zapisanego tagu #EXT-X-KEY przed pierwszym segmentem treści po każdym podzbiorze reklam, aby przywrócić szyfrowanie treści.

Przykład zebranych danych wariantów

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

Przykładowy plik manifestu treści

To zawartość pliku manifestu https://{...}/1080p.m3u8 wymienionego w zbieranych danych wersji.

#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
{...}

Przykładowy blok reklamowy z plikiem manifestu

To zawartość pliku https://dai.google.com/{...}/pod/1/profile/1080p.m3u8manifestu wymienionego w zbieranych danych wersji.

#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

Przykład pliku manifestu złączonych wariantów

Jest to wynikowy zszyty manifest wersji, przekazany do CDN i hostowany na 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
{...}

Tworzenie playlisty z wieloma wariantami

Pobierz adresy CDN dla każdego ukończonego pliku manifestu wersji wraz z odpowiadającymi im szczegółami profilu kodowania i zmontuj wyniki w nowym pliku manifestu wersji. Ten plik manifestu dotyczący konkretnego użytkownika jest zwracany jako odpowiedź na żądanie pliku manifestu otrzymane w kroku 1.

Przykład końcowej playlisty z wieloma wariantami

#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

strumienie MPEG DASH,

Jeśli zszywać strumień w formacie MPEG DASH, wystarczy wygenerować jeden plik. Dzięki temu strumienie DASH można łatwiej łączyć niż strumienie HLS.

Odpowiednio przygotowany plik opisu prezentacji multimedialnej MPEG DASH (MPD) powinien składać się z kilku okresów, z których każdy zawiera wiele reprezentacji. Każde z nich powinno odpowiadać jednemu z Twoich profili kodowania. Każdy blok reklamowy zwrócony przez Ad Managera jest też plikiem MPD zawierającym sekwencję okresów z odpowiadającymi sobie reprezentacjami.

Aby połączyć te pliki MPD, zacznij od zapisania czasów rozpoczęcia poszczególnych podgrup reklam. W przypadku reklam przed filmem wstaw okresy reklamy przed filmem przed każdym okresem treści. W przypadku reklam po filmie wstaw okresy reklamy po filmie po wszystkich okresach treści. Przetwarzanie wszystkich okresów w MPD treści z uwzględnieniem upływu czasu odtwarzania wszystkich przetworzonych okresów treści. Gdy dojdziesz do granicy między okresami odpowiadającą czasowi rozpoczęcia bloku reklamowego, wstaw w tym miejscu okresy z pliku MPD pasującego bloku reklamowego w trakcie filmu.

Ostateczny połączony plik MPD musi w pełni odpowiadać specyfikacji MPEG_DASH, więc może być konieczne jeszcze raz przejrzenie końcowego pliku w celu poprawienia czasów rozpoczęcia okresów, skorygowania czasu trwania prezentacji multimediów, aby uwzględnić nowo wstawione okresy reklamowe, oraz rozwiązania wszelkich innych konfliktów, które mogły wystąpić podczas procesu łączenia.

Przykładowy opis MPD

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

Przykładowy kod reklamy w formacie JSON

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

Przykład bloku reklamowego w plikach MPD

To jest zawartość elementu mpd_uri z pliku JSON pod reklamą podanego powyżej.

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

Przykład połączonego pliku MPD

Prześlij go jako odpowiedź na początkowe żądanie manifestu strumienia.

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

Dodatkowe materiały

• Odtwarzanie bloków reklamowych za pomocą pakietu IMA SDK:
  • Android
  • HTML5.
  • iOS
  • tvOS
• Odtwarzanie bloków reklamowych w ramach dynamicznego wstawiania reklam za pomocą interfejsu API