Manipulator manifes untuk streaming VOD

Pod Serving API menyediakan akses ke pod iklan video dengan kecepatan bit adaptif yang disiapkan sehingga dapat digabungkan langsung ke playlist media HLS atau MPEG-DASH yang ditampilkan kepada pengguna.

Panduan ini berfokus pada penerapan server manipulasi manifes Pod Serving dasar untuk streaming VOD.

Menerima permintaan manifes streaming

Manipulator manifes Anda harus menyediakan endpoint API untuk memproses permintaan manifes dari aplikasi klien pemutar video. Minimal, endpoint ini harus mengumpulkan ID streaming dari aplikasi pemutar klien. ID streaming ini digunakan untuk mengidentifikasi sesi streaming ke Ad Manager dalam permintaan pod iklan Anda.

Anda juga perlu mengumpulkan beberapa informasi lain untuk mengidentifikasi streaming konten yang sesuai, misalnya, Content ID.

Contoh endpoint permintaan manifes

GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}
Parameter jalur
stream_id ID streaming Ad Manager dari aplikasi pemutar video klien.
content_id ID hipotetis yang sesuai dengan video konten di sistem Anda.
format Parameter hipotetis yang sesuai dengan format streaming. Salah satu dari:
mpd Untuk streaming MPEG-DASH
m3u8 Untuk streaming HLS

Mengambil streaming konten

Gunakan Content ID yang dikumpulkan dari permintaan manifes untuk memilih streaming konten yang akan digabungkan dengan iklan.

Meminta manifes pod iklan

Untuk meminta iklan dari Ad Manager, server Anda harus membuat permintaan POST ke endpoint pod iklan, yang meneruskan profil encoding dan tag iklan yang diminta. Permintaan ini juga menyertakan ID streaming yang Anda kumpulkan di Langkah 1.

Sebagai gantinya, Anda akan menerima daftar objek pod iklan yang berisi file manifes untuk pod iklan yang diminta oleh tag iklan penayang dan informasi tentang waktu dan tempat pod iklan tersebut harus disisipkan ke dalam konten Anda.

POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json
Parameter jalur
network_code Kode jaringan Ad Manager 360 penayang.
stream_id ID streaming dari aplikasi pemutar video klien.

Isi JSON

Parameter isi
encoding_profiles Required Daftar representasi JSON profil encoding yang ingin Anda terima untuk setiap jeda iklan. Lihat detail di bawah

Agar pemutaran berjalan selancar mungkin, profil ini harus cocok dengan kumpulan profil encoding yang digunakan di streaming konten Anda.

ad_tag Required Tag iklan untuk meminta iklan VMAP.
cuepoints Optional Daftar titik tanda dalam streaming konten tempat jeda iklan midroll akan disisipkan. Titik tanda diukur dalam detik floating point.

Hanya diperlukan untuk respons VMAP yang berisi mid-roll menggunakan selisih waktu posisional. Hal ini jarang terjadi.

content_duration_seconds Optional Durasi konten dalam detik.

Hanya diperlukan untuk respons VMAP yang berisi mid-roll menggunakan selisih waktu persentase. Hal ini jarang terjadi.

manifest_type Optional Format streaming iklan yang diminta, baik hls maupun dash. Nilai defaultnya adalah hls.
dai_options Optional Opsi tambahan yang mengontrol aspek cara manifes dirender. Lihat detail di bawah
Profil encoding
profile_name Required ID untuk Profil Encoding ini. Nilai ini dapat berupa string apa pun yang Anda pilih, tetapi Anda tidak dapat memiliki beberapa profil encoding dengan nama yang sama di streaming yang sama.
type Required Jenis encoding streaming yang dijelaskan oleh profil encoding ini. Jenis konten adalah: media, iframe, subtitles.
container_type Required Format penampung yang digunakan oleh profil encoding ini. Format penampung adalah: mpeg2ts, fmp4cmaf, hls_packed_audio
video_settings Optional Wajib diisi jika jenis profil encoding adalah iframe. Jika tidak, hanya diizinkan jika jenis media berisi video. Lihat detailnya di bawah
audio_settings Optional Wajib diisi jika profil encoding berisi audio. Hanya diizinkan jika jenisnya media. Lihat detail di bawah
subtitle_settings Optional Diperlukan jika profil encoding berisi subtitel. Lihat detail di bawah
Setelan Video
codec Required String codec RFC6381.

Contoh: avc1.4d000c

bitrate Required Bilangan bulat yang mewakili kecepatan bit video maksimum profil ini dalam byte per detik.
frames_per_second Required FPS floating point video.
resolution Required Nilai yang dienkode JSON yang berisi `lebar` dan `tinggi` video dalam piksel.

Contoh: {"width": 640, "height": 320}

Setelan audio
codec Required String codec RFC6381.

Contoh: mp4a.40.5

bitrate Required Bilangan bulat yang mewakili kecepatan bit audio maksimum profil ini dalam byte per detik.

Contoh: 300000

channels Required Bilangan bulat yang mewakili jumlah saluran audio termasuk saluran frekuensi rendah.
sample_rate Required Bilangan bulat yang mewakili frekuensi sampling audio dalam hertz.

Contoh: 4800

Setelan subtitel
format Required Format file yang digunakan oleh subtitel dalam band. Nilai yang didukung adalah webvtt atau ttml.
language Optional Bahasa subtitel sebagai string bahasa RFC5646. Jika diberikan, nilai ini hanya digunakan untuk rendering DASH.

Contoh: en-us

Opsi DAI
dash_profile Optional Profil MPEG-DASH yang akan diterapkan ke manifes pod iklan. Setelan ini hanya digunakan untuk manifes DASH. Nilai yang diizinkan adalah live atau on-demand. Nilai defaultnya adalah on-demand.

Nilai live sesuai dengan profil MPEG-DASH "urn:mpeg:dash:profile:isoff-live:2011".

Nilai on-demand sesuai dengan profil MPEG-DASH urn:mpeg:dash:profile:isoff-on-demand:2011.

ad_pod_timeout Optional Waktu maksimum yang dihabiskan untuk memilih iklan dan membuat pod iklan, dalam detik floating point. Setelah waktu ini berlalu, Ad Manager akan menampilkan iklan apa pun yang sudah dipilih dalam respons ad_pods dan berhenti memproses.
sam_id Optional Menentukan kunci debug alternatif yang dapat digunakan untuk mencari sesi di pemantauan aktivitas streaming.

Respons

Parameter respons
valid_for Durasi validasi playlist pod iklan ini dalam format dhms (hari, jam, menit, detik).
valid_until Tanggal dan waktu hingga playlist pod iklan ini valid sebagai string tanggal & waktu ISO8601, dalam format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.
ad_pods Daftar pod iklan yang dipilih untuk streaming ini.
Pod iklan
manifest_uris Hanya untuk streaming HLS. Peta ID profil encoding ke URI manifes HLS.
mpd_uri Hanya untuk streaming DASH. URI MPD DASH.
type Jenis pod iklan. Jenis pod iklan adalah: pre, mid, atau post.
start Khusus untuk pod iklan mid-roll. Posisi dalam streaming tempat pod iklan ini harus disisipkan, dalam detik floating point.
duration Durasi pod iklan ini dalam detik floating point.
midroll_index Khusus untuk pod iklan mid-roll. Indeks pod iklan mid-roll saat ini. Pengindeksan dimulai dengan 1.

Contoh permintaan (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

Contoh isi permintaan

Ini adalah konten request-body.json yang dirujuk dalam panggilan cURL di atas.

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

Contoh respons

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

Menyatukan pod iklan ke dalam konten

Proses penyambungan pod iklan ke aliran konten bervariasi bergantung pada penerapan, format streaming, dan fitur yang Anda pilih untuk diterapkan dari spesifikasi format. Alur kerja berikut adalah saran untuk menangani proses ini. Detail penerapan yang tepat mungkin bervariasi, berdasarkan kebutuhan bisnis dan streaming konten Anda.

Streaming HLS

Jika Anda menggabungkan streaming dalam format HLS, streaming konten Anda akan berupa playlist multivarian dari link ke manifes streaming terpisah, satu untuk setiap profil encoding. Pod iklan Anda harus disisipkan ke dalam setiap manifes varian ini. Salah satu cara untuk melakukannya adalah dengan menyiapkan semua manifes varian dan meneruskannya ke Jaringan Penayangan Konten (CDN) untuk hosting. Playlist multivarian akhir adalah kumpulan link ke manifes yang dihosting CDN ini.

Melakukan iterasi pada profil encoding

Untuk setiap profil encoding, kumpulkan semua manifes pod iklan terkait dari respons Ad Manager, beserta waktu mulai terkait. Untuk pod iklan pre-roll, tetapkan waktu mulai ke 0. Untuk post-roll, gunakan durasi konten sebagai waktu mulai pod iklan. Identifikasi aliran varian dalam playlist multivarian yang cocok dengan setelan audio dan video setiap profil encoding.

Contoh array pod iklan
"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
    }
  ]
Contoh playlist konten multi-varian
#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
Contoh data varian yang dikumpulkan
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

Menyisipkan iklan ke dalam setiap manifes varian

Untuk setiap streaming varian, periksa segmen manifes konten, dengan mempertahankan total waktu konten yang telah berlalu. Saat Anda berada di posisi awal pod iklan, ekstrak daftar segmen dari manifes pod iklan, gabungkan daftar segmen dalam dua tag #EXT-X-DISCONTINUITY, dan sisipkan daftar di lokasi saat ini dalam manifes konten. Lanjutkan proses ini hingga semua pod iklan dan aliran varian telah diproses.

Manifes yang dihasilkan harus sesuai dengan standar HLS. Oleh karena itu, bergantung pada fitur spesifikasi yang disertakan dalam manifes konten, Anda mungkin perlu melakukan pemeriksaan akhir pada manifes gabungan untuk memperbaiki nomor urutan media, durasi konten, nomor urutan ketidakberlanjutan, dan tag lainnya yang perlu diperbarui untuk mempertimbangkan segmen iklan baru. Setelah perbedaan dengan standar diperbaiki, kirim setiap manifes varian khusus pengguna ke CDN Anda untuk dihosting.

Jika manifes konten dienkripsi, Anda harus menyimpan kunci enkripsi terakhir yang ditemukan sebelum awal pod iklan saat ini di tag #EXT-X-KEY. Kemudian, Anda perlu menambahkan tag #EXT-X-KEY:METHOD=NONE untuk menghapus enkripsi sebelum segmen pertama setiap pod iklan. Terakhir, Anda harus menambahkan salinan tag #EXT-X-KEY yang disimpan sebelum segmen konten pertama setelah setiap pod iklan, untuk memulihkan enkripsi konten.

Contoh data varian yang dikumpulkan
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
Contoh manifes konten

Ini adalah konten manifes https://{...}/1080p.m3u8 yang tercantum dalam data varian yang dikumpulkan.

#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
{...}
Contoh manifes pod iklan

Ini adalah konten manifes https://dai.google.com/{...}/pod/1/profile/1080p.m3u8 yang tercantum dalam data varian yang dikumpulkan.

#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
Contoh manifes varian yang digabungkan

Ini akan menjadi manifes varian yang dijahit, yang diteruskan ke CDN dan dihosting di 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
{...}

Membuat playlist multi-varian

Kumpulkan alamat CDN untuk setiap manifes varian yang telah selesai, beserta detail profil encoding yang cocok, dan gabungkan hasilnya ke dalam manifes multivarian baru. Manifes khusus pengguna ini ditampilkan sebagai respons terhadap permintaan manifes yang Anda terima di Langkah 1.

Contoh playlist multi-varian akhir
#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

Streaming MPEG DASH

Jika Anda menggabungkan streaming dalam format MPEG DASH, Anda hanya perlu membuat satu file. Hal ini dapat membuat streaming DASH lebih mudah digabungkan daripada HLS.

File deskripsi presentasi media (MPD) MPEG DASH yang disiapkan dengan benar harus terdiri dari beberapa periode, yang masing-masing berisi beberapa representasi. Setiap representasi harus cocok dengan salah satu profil encoding Anda. Setiap pod iklan yang ditampilkan dari Ad Manager juga merupakan file MPD yang berisi urutan periode dengan representasi yang cocok.

Untuk menggabungkan file MPD ini, mulailah dengan mencatat waktu mulai untuk setiap pod iklan. Untuk pre-roll, masukkan periode pod iklan pre-roll sebelum periode konten apa pun. Untuk post-roll, masukkan periode pod iklan post-roll setelah semua periode konten. Lakukan iterasi pada periode dalam MPD konten, dengan melacak waktu pemutaran yang telah berlalu untuk semua periode konten yang diproses. Saat Anda mencapai batas antara periode yang sesuai dengan waktu mulai pod iklan, masukkan periode dari file MPD pod iklan mid-roll yang cocok di batas tersebut.

File MPD akhir yang dijahit harus sepenuhnya sesuai dengan spesifikasi MPEG_DASH, sehingga Anda mungkin perlu melakukan iterasi pada file akhir sekali lagi untuk memperbaiki waktu mulai periode, memperbaiki durasi presentasi media untuk memperhitungkan periode iklan yang baru disisipkan, dan menyelesaikan konflik lain yang mungkin terjadi dari proses penyambungan.

Contoh MPD konten

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

Contoh JSON pod iklan

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

Contoh MPD pod iklan

Ini adalah konten mpd_uri dari JSON pod iklan di atas.

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

Contoh MPD yang dijahit

Tampilkan ini sebagai respons Anda terhadap permintaan manifes streaming awal.

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

Referensi lainnya