VOD 串流資訊清單操控器

Pod Serving API 可讓您存取準備的自動調整位元率影片廣告連播，以便他們可以直接將這類廣告連播拼接成面向使用者的 HLS 或 MPEG-DASH 媒體播放清單。

本指南著重於為 VOD 串流實作基本的 Pod 服務資訊清單操控伺服器。

接收串流資訊清單要求

資訊清單操控程式必須提供 API 端點，以監聽影片播放器用戶端應用程式的資訊清單要求。這個端點至少會從用戶端播放器應用程式收集串流 ID。這個串流 ID 可用來在廣告連播請求中，識別向 Ad Manager 發出的串流工作階段。

您還需要收集其他資訊才能識別適當的內容串流，例如內容 ID。

資訊清單要求端點範例

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

路徑參數
stream_id	用戶端影片播放器應用程式的 Ad Manager 串流 ID。
content_id	與系統中內容影片對應的假設 ID。
format	與串流格式對應的假設參數。下列其中一個選項： mpd MPEG-DASH 串流 m3u8 HTTP 即時串流串流

擷取內容串流

使用從資訊清單要求收集的內容 ID，選取要與廣告組合的內容串流。

請求廣告連播資訊清單

如要從 Ad Manager 請求廣告，您的伺服器必須向廣告連播端點發出 POST 要求，並傳遞要求的編碼設定檔、廣告代碼和指定參數。這項要求也包含您在步驟 1 中收集的串流 ID。

系統會傳回一份廣告連播物件清單，其中包含發布商廣告代碼要求的廣告連播資訊清單檔案，以及這些物件應插入內容的時間點和位置相關資訊。

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

路徑參數
network_code	發布商的 Ad Manager 360 聯播網代碼。
stream_id	用戶端影片播放器應用程式的串流 ID。

JSON 主體

內文參數
encoding_profiles	Required	一份 JSON 表示法清單，其中代表您希望每個廣告插播接收的編碼設定檔。詳情請見下文 為了盡可能提供順暢的播放體驗，這個值應符合內容串流中使用的編碼設定檔組合。
ad_tag	Required	用來請求 VMAP 廣告的廣告代碼。
cuepoints	Optional	內容串流中要插入片中廣告的提示點清單。提示點的測量單位為浮點秒數。 只有使用位置時間偏移，包含片中廣告的 VMAP 回應才需要。這種情況很罕見，
content_duration_seconds	Optional	內容時間長度 (以秒為單位)。 只有包含使用百分比時間偏移的片中廣告的 VMAP 回應時，才需要填寫。這種情況很罕見，
manifest_type	Optional	所請求的廣告放送格式：hls 或 dash。預設值為 hls。
dai_options	Optional	可控制資訊清單轉譯方式的其他選項。詳情請見下文
編碼設定檔
profile_name	Required	這個編碼設定檔的 ID。這個值可以是任何您選擇的字串，但同一個串流中不能有多個名稱相同的編碼設定檔。
type	Required	這個編碼設定檔描述的串流編碼類型。內容類型如下：media、iframe、subtitles。
container_type	Required	這個編碼設定檔使用的容器格式。容器格式包括：mpeg2ts、fmp4cmaf、hls_packed_audio
video_settings	Optional	如果編碼設定檔類型為 iframe，則為必要欄位。否則，只有當媒體類型包含影片時才能允許放送。詳情請參閱下文
audio_settings	Optional	如果編碼設定檔含有音訊，則為必填。只有在類型為媒體時才能允許。詳情請見下文
subtitle_settings	Optional	如果編碼設定檔含有字幕，則為必填屬性。詳情請見下文
影片設定
codec	Required	RFC6381 轉碼器字串。 範例：avc1.4d000c
bitrate	Required	整數，代表此設定檔的影片位元率上限 (以每秒位元組為單位)。
frames_per_second	Required	影片的浮點 FPS。
resolution	Required	包含影片「寬度」和「高度」影片的 JSON 編碼值，以像素為單位。 範例：{"width": 640, "height": 320}
音訊設定
codec	Required	RFC6381 轉碼器字串。 範例：mp4a.40.5
bitrate	Required	整數，代表此設定檔的音訊位元率上限，以每秒位元組為單位。 範例：300000
channels	Required	一個整數，代表音訊聲道數量，包括低頻率聲道。
sample_rate	Required	代表赫茲語音訊取樣率的整數。 範例：4800
字幕設定
format	Required	頻內字幕使用的檔案格式。支援的值為 webvtt 或 ttml。
language	Optional	字幕語言，以 RFC5646 語言字串表示。如有提供，這個值只會用於 DASH 算繪。 範例：en-us
動態廣告插播選項
dash_profile	Optional	要套用至廣告連播資訊清單的 MPEG-DASH 設定檔。這項設定僅適用於 DASH 資訊清單。允許的值為 live 或 on-demand。預設值為 on-demand。 live 值對應 MPEG-DASH 設定檔 "urn:mpeg:dash:profile:isoff-live:2011"。 on-demand 值對應 MPEG-DASH 設定檔 urn:mpeg:dash:profile:isoff-on-demand:2011。
ad_pod_timeout	Optional	花費在浮點秒內選取廣告及建構廣告連播的時間上限。這段時間過後，Ad Manager 會傳回 ad_pods 回應中已選取的所有廣告，並停止處理。
sam_id	Optional	指定替代偵錯鍵，用於在串流活動監控器中查詢工作階段。

回應

回應參數
valid_for	這些廣告連播播放清單的時間長度，格式為 dhms (天、小時、分鐘、秒)。
valid_until	這些廣告連播播放清單的有效期限為 ISO8601 日期時間字串，採用 yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 格式。
ad_pods	為這個串流選取的廣告連播清單。
廣告連播
manifest_uris	僅適用於 HLS 串流。將設定檔 ID 編碼與 HLS 資訊清單 URI 的對應。
mpd_uri	僅適用於 DASH 串流。DASH MPD 的 URI。
type	廣告連播的類型。廣告連播類型為：pre、mid 或 post。
start	僅適用於片中廣告連播。應插入這個廣告連播在串流中的位置 (以浮點秒數表示)。
duration	這個廣告連播的時間長度 (以浮點秒為單位)。
midroll_index	僅適用於片中廣告連播。目前片中廣告連播的索引。系統會從 1 開始建立索引。

要求範例 (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

要求主體示例

這是上述 cURL 呼叫中參照的 request_body.json 內容。

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

回應範例

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

將廣告連播拼接成內容

將廣告連播拼接至內容串流的程序，取決於您的實作方式、串流格式，以及您根據格式規格選擇實作的功能。下列工作流程建議如何處理此程序。根據業務需求和內容串流，導入實作的具體細節可能會有所不同。

HTTP 即時串流串流

如果您是以 HLS 格式拼接串流，內容串流會是其他串流資訊清單連結的多變化版本播放清單，每個編碼設定檔都有一個連結。您必須將廣告連播插入每個變化版本資訊清單。其中一個方法是準備所有變數資訊清單，並傳送至內容傳遞聯播網 (CDN) 以進行託管。最終的多變化版本播放清單是這些 CDN 託管資訊清單的連結組合。

疊代編碼設定檔

針對每個編碼設定檔，從 Ad Manager 回應中收集所有相關聯的廣告連播資訊清單，以及相關的開始時間。針對片頭廣告連播，請將開始時間設為 0。如果是片尾廣告，請將內容的時間長度做為廣告連播的開始時間。找出多變化版本播放清單中符合每個編碼設定檔的音訊和影片設定的變化版本串流。

廣告連播陣列範例

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

多變化版本內容播放清單範例

#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

收集的變化版本資料範例

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

在每個變化版本資訊清單中插入廣告

檢查每個變化版本串流，檢查內容資訊清單的區段，保留經過的總內容時間。當您前往廣告連播的開始位置時，請從廣告連播的資訊清單中擷取區隔清單，將區隔清單納入兩個 #EXT-X-DISCONTINUITY 標記中，然後在內容資訊清單中的目前位置插入清單。請繼續進行這項程序，直到所有廣告連播和變化版本串流都處理完畢。

產生的資訊清單必須符合 HLS 標準。因此，視內容資訊清單納入的規格特徵而定，您可能需要最終傳遞合併的資訊清單，以修正媒體序列編號、內容時間長度、中斷序號，以及任何需要更新以將新廣告區隔納入考量的標記。修復與標準之間的任何差異後，請將每個使用者專屬的變化版本資訊清單推送至 CDN 進行託管。

如果內容資訊清單已加密，您需要將最後找到的加密金鑰，儲存在目前廣告連播開始之前的 #EXT-X-KEY 標記中。接著，您需要在每個廣告連播的第一個區隔之前新增 #EXT-X-KEY:METHOD=NONE 代碼，藉此移除加密功能。最後，您必須在每個廣告連播後方的內容區段之前，新增已儲存的 #EXT-X-KEY 標記副本，才能還原內容加密。

收集的變化版本資料範例

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

內容資訊清單範例

這是收集的變化版本資料中列出的 https://{...}/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
#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
{...}

廣告連播資訊清單範例

這是在收集的變化版本資料中列出的 https://dai.google.com/{...}/pod/1/profile/1080p.m3u8 資訊清單內容。

#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

拼接變化版本資訊清單範例

這會產生拼接的變化版本資訊清單，會傳遞至 CDN 並在 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
{...}

建構多變化版本播放清單

收集每個已完成變化版本資訊清單的 CDN 位址，以及相符的編碼設定檔詳細資料，然後將結果組合成新的多變數資訊清單。系統會傳回這份使用者專屬的資訊清單，做為您在步驟 1 中收到的資訊清單要求回應。

最終多變化版本播放清單範例

#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

MPEG DASH 串流

如果您是以 MPEG DASH 格式拼接串流，則只需產生單一檔案。因此，DASH 串流可以比 HTTP 即時串流更容易拼接。

妥善準備的 MPEG DASH 媒體顯示說明 (MPD) 檔案應含有多個半形句號，且每個半形句號包含多種表示法。每個表示法都應與您的其中一個編碼設定檔相符。每個從 Ad Manager 傳回的廣告連播也是 MPD 檔案，內含一組符合表示法的句點。

如要拼接這些 MPD 檔案，請先記下每個廣告連播的開始時間。如果是片頭廣告，請在內容時段之前插入片頭廣告連播時段。如果是片尾廣告，請在所有內容時段結束後插入片尾廣告連播時段。按照內容 MPD 中的時段進行疊代，追蹤所有處理的內容時段的播放時間。達到廣告廣告連播開始時間的時段之間的邊界時，請在該邊界插入相符片中廣告廣告連播 MPD 檔案中的句點。

最終拼接的 MPD 檔案必須完全符合 MPEG_DASH 規格，因此您可能需要再逐一修正最終檔案，修正任何週期的開始時間、修正媒體顯示時間長度，以考慮新插入的廣告時段，並解決拼接程序中可能引發的任何其他衝突。

內容 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>

廣告連播 JSON 範例

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

廣告連播 MPD 範例

這是上方廣告連播 JSON 中的 mpd_uri 內容。

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

拼接的 MPD 範例

請在回應初始串流資訊清單要求時提供這個回應。

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

其他資源

• 透過 IMA SDK 放送廣告連播：
  • Android
  • HTML5
  • iOS
  • tvOS
• 使用 DAI API 進行廣告連播放送