本頁說明如何使用 Live Stream API,從直播內容建立隨選影片 (VOD) 短片。VOD 短片由 HLS 資訊清單檔案和從直播儲存的區段檔案組成。僅支援 HLS 資訊清單。
VOD 短片和 DVR 工作階段的差異
VOD 短片 (也稱為頻道短片) 與 DVR 工作階段類似,但有以下主要差異:
- DVR 工作階段:
- API 會將 DVR 資訊清單儲存在與直播串流片段相同的位置,因此不會再將資料複製到 Cloud Storage。DVR 資訊清單與直播資訊清單類似,但長度較長。當保留時間結束時,系統會刪除資訊清單和片段檔案。
- 你可以為過去、現在和未來的內容建立 DVR 工作階段。舉例來說,DVR 工作階段可以追蹤直播,或是安排 DVR 工作階段在未來的某個時間開始和停止。
- DVR 工作階段的一般用途是支援直播活動的 DVR 功能。舉例來說,觀眾可以在直播開始後一小時加入,並以一小時的延遲時間 (或略過部分內容) 觀看內容。
- 頻道短片:
- Live Stream API 會將短片資訊清單和相關的片段檔案複製到使用者指定的目錄,以便在保留期間結束時不刪除。你可以完全掌控短片。
- 只能剪輯過往的內容。不支援直播短片和排定日後的短片。
- 剪輯片段的常見用途是封存直播內容,讓直播內容可無限期做為 VOD 檔案使用。
如要進一步瞭解 DVR 工作階段,請參閱「建立 DVR 工作階段」。
設定 Google Cloud 專案和驗證
如果您尚未建立 Google Cloud 專案和憑證,請參閱「開始前」一節。建立輸入端點
如要建立輸入端點,請使用 projects.locations.inputs.create
方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:您的 Google Cloud 專案編號,位於 IAM 設定頁面上的「專案編號」欄位LOCATION
:建立輸入端點的位置;請使用支援的地區之一顯示地區us-central1
us-east1
us-east4
us-west1
us-west2
northamerica-northeast1
southamerica-east1
asia-east1
asia-east2
asia-south1
asia-northeast1
asia-southeast1
australia-southeast1
europe-north1
europe-west1
europe-west2
europe-west3
europe-west4
INPUT_ID
:使用者定義的識別碼,用於建立新的輸入端點 (您會將輸入串流傳送至此)。這個值的長度必須介於 1 至 63 個半形字元之間,開頭和結尾須為[a-z0-9]
,字元之間可以包含破折號 (-)。例如:my-input
。
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.video.livestream.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_NUMBER/locations/LOCATION/inputs/INPUT_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
這個指令會建立長期執行作業 (LRO),您可以使用該作業追蹤要求的進度。詳情請參閱「管理長時間執行的作業 」。
取得輸入端點詳細資料
如要取得輸入端點的詳細資料,請使用 projects.locations.inputs.get
方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:您的 Google Cloud 專案編號,位於 IAM 設定頁面上的「專案編號」欄位LOCATION
:輸入端點的位置;請使用其中一個支援的地區顯示地區us-central1
us-east1
us-east4
us-west1
us-west2
northamerica-northeast1
southamerica-east1
asia-east1
asia-east2
asia-south1
asia-northeast1
asia-southeast1
australia-southeast1
europe-north1
europe-west1
europe-west2
europe-west3
europe-west4
INPUT_ID
:輸入端點的使用者定義 ID
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/inputs/INPUT_ID", "createTime": CREATE_TIME, "updateTime": UPDATE_TIME, "type": "RTMP_PUSH", "uri": "INPUT_STREAM_URI", # For example, "rtmp://1.2.3.4/live/b8ebdd94-c8d9-4d88-a16e-b963c43a953b", "tier": "HD" }
找出 uri
欄位,並複製傳回的 INPUT_STREAM_URI,以便稍後在「傳送輸入串流」一節中使用。
建立管道
如要建立管道,請使用 projects.locations.channels.create
方法。以下範例會建立可產生 HLS 直播的頻道。直播內容包含單一高畫質 (1280x720) 呈現方式。
如要啟用 VOD 短片建立功能,請將 retentionConfig
物件新增至頻道設定。
"retentionConfig": {
"retentionWindowDuration": {
"seconds": 86400
}
},
為直播頻道啟用保留功能後,系統會保留直播串流片段和資訊清單,以便建立 VOD 短片。retentionWindowDuration
物件會指定直播輸出內容上傳至 Cloud Storage 後的儲存時間長度。保留期間是從在 Cloud Storage 中建立區隔時起算。
保留期限上限為 30 天。在保留期限過後,系統會自動從 Cloud Storage 刪除直播串流區段檔案和資訊清單檔案。(VOD 短片資訊清單及其相關的片段檔案不會自動刪除)。你無法使用已刪除的片段建立 VOD 短片。刪除程序為非同步作業,最多可能需要 24 小時才能完成。
指定資訊清單的索引鍵,即可啟用 VOD 短片建立功能。您可以在實際建立短片時參考這個鍵。僅支援 HLS 資訊清單。
"manifests": [
{
...
"key": "manifest_hls"
}
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:您的 Google Cloud 專案編號,位於 IAM 設定頁面上的「專案編號」欄位LOCATION
:建立管道的所在位置;請使用支援的區域之一顯示地區us-central1
us-east1
us-east4
us-west1
us-west2
northamerica-northeast1
southamerica-east1
asia-east1
asia-east2
asia-south1
asia-northeast1
asia-southeast1
australia-southeast1
europe-north1
europe-west1
europe-west2
europe-west3
europe-west4
CHANNEL_ID
:要建立的管道使用者定義的 ID,這個值必須介於 1 至 63 個半形字元之間,開頭和結尾須為[a-z0-9]
,字元之間可包含破折號 (-)INPUT_ID
:輸入端點的使用者定義 IDBUCKET_NAME
:您建立的 Cloud Storage 值區名稱,用於保存即時串流資訊清單和區段檔案
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.video.livestream.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
這個指令會建立長期執行作業 (LRO),您可以使用該作業追蹤要求的進度。詳情請參閱「管理長時間執行的作業 」。
啟動管道
如要啟動管道,請使用 projects.locations.channels.start
方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:您的 Google Cloud 專案編號,位於 IAM 設定頁面上的「專案編號」欄位LOCATION
:頻道所在位置;請使用支援的區域之一顯示地區us-central1
us-east1
us-east4
us-west1
us-west2
northamerica-northeast1
southamerica-east1
asia-east1
asia-east2
asia-south1
asia-northeast1
asia-southeast1
australia-southeast1
europe-north1
europe-west1
europe-west2
europe-west3
europe-west4
CHANNEL_ID
:管道的使用者定義 ID
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.video.livestream.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID", "verb": "start", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
這個指令會建立長期執行作業 (LRO),您可以使用該作業追蹤要求的進度。詳情請參閱「管理長時間執行的作業 」。
傳送輸入串流
開啟新的終端機視窗。使用「取得輸入端點詳細資料」一節中的 INPUT_STREAM_URI 執行下列指令:
ffmpeg -re -f lavfi -i "testsrc=size=1280x720 [out0]; sine=frequency=500 [out1]" \
-acodec aac -vcodec h264 -f flv INPUT_STREAM_URI
建立 VOD 短片
如要建立 VOD 短片,請使用 projects.locations.channels.clips.create
方法。
使用 outputUri
欄位,指定在 Cloud Storage 中儲存短片和短片資訊清單檔案的位置。您可以使用為直播資訊清單建立的值區,也可以使用其他值區。您也可以在值區名稱後方加上目錄名稱 (例如 my-bucket/vod-clip
)。
請使用 clipManifests
陣列中的 manifestKey
欄位,指定要儲存短片的資訊清單。在本頁的管道設定範例中,這個鍵設為 manifest_hls
。
使用 outputType
欄位指定所支援的其中一種短片輸出格式:MANIFEST
(預設) 或 MP4
。在本頁的示例頻道設定中,這個欄位會設為 MANIFEST
,產生與頻道輸出內容類似的 VOD 資訊清單。
您可以將直播的多個時間段合併為單一短片,方法是將 timeSlice
物件新增至 slices
陣列。
"outputUri": "gs://my-bucket",
"clipManifests":[
{
"manifestKey": "manifest_hls"
}
],
"slices":[
{
"timeSlice": {
"markinTime": "2022-07-08T23:03:20.000Z",
"markoutTime": "2022-07-08T23:04:20.000Z"
}
},
{
"timeSlice": {
"markinTime": "2022-07-08T23:05:20.000Z",
"markoutTime": "2022-07-08T23:06:20.000Z"
}
}
]
注意事項:
- 每個短片都必須在
slices
中包含至少一個timeSlice
。 clipManifests.manifestKey
欄位必須參照短片父項頻道中定義的 HLS 資訊清單。如果短片工作建立要求成功,系統會在clipManifests.outputUri
欄位中傳回產生的短片資訊清單 URI。這個 URI 位於剪輯片段的outputUri
欄位所指定的路徑中。clipManifests
陣列僅支援每個要求一個資訊清單。如果您想為同一個短片工作產生多個資訊清單,就必須將資訊清單分割成多個短片工作要求。- 剪輯片段必須是同質的,每個元素都必須是
timeSlice
類型。 timeSlice
物件集合不得重疊,且必須按照時間順序排列。markinTime
必須早於每個timeSlice
中的markoutTime
。- 如果片段的最新
markinTime
早於頻道開始時間或保留期間的開始時間,則系統會將標記時間設為兩者中較晚的時間。 - 如果片段的最新
markoutTime
晚於頻道停止時間,則會設為頻道停止時間。如果短片的最新markoutTime
晚於目前的系統時鐘時間,則會設為 API 實際啟動剪輯任務的時間。 - 使用
MANIFEST
輸出類型的短片,最長時間為 24 小時。使用MP4
輸出類型的短片,長度上限為 6 小時。
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:您的 Google Cloud 專案編號,位於 IAM 設定頁面上的「專案編號」欄位LOCATION
:頻道所在位置;請使用支援的區域之一顯示地區us-central1
us-east1
us-east4
us-west1
us-west2
northamerica-northeast1
southamerica-east1
asia-east1
asia-east2
asia-south1
asia-northeast1
asia-southeast1
australia-southeast1
europe-north1
europe-west1
europe-west2
europe-west3
europe-west4
CHANNEL_ID
:管道的使用者定義 IDCLIP_ID
:隨選影片短片的使用者定義 IDMARK_IN_TIME
:原始直播資訊清單中的 Unix Epoch 紀元時間;使用 RFC3339 世界標準時間「Zulu」格式的時間戳記 (例如2014-10-02T15:01:23Z
)MARK_OUT_TIME
:原始直播資訊清單中的 Mark-out Unix Epoch 時間;使用 RFC3339 世界標準時間「Zulu」格式的時間戳記 (例如2014-10-02T15:01:23Z
)BUCKET_NAME
:您建立用於儲存 VOD 短片資訊清單和片段檔案的 Cloud Storage 值區名稱;您可以使用建立直播資訊清單時建立的值區,也可以使用其他值區;您也可以在值區名稱後方加上目錄名稱 (例如my-bucket/vod-clip
)
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.video.livestream.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/clips/CLIP_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
這個指令會建立長期執行作業 (LRO),您可以使用該作業追蹤要求的進度。詳情請參閱「管理長時間執行的作業 」。
取得 VOD 短片
如要取得 VOD 短片,請使用 projects.locations.channels.clips.get
方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_NUMBER
:您的 Google Cloud 專案編號,位於 IAM 設定頁面上的「專案編號」欄位LOCATION
:頻道所在位置;請使用支援的區域之一顯示地區us-central1
us-east1
us-east4
us-west1
us-west2
northamerica-northeast1
southamerica-east1
asia-east1
asia-east2
asia-south1
asia-northeast1
asia-southeast1
australia-southeast1
europe-north1
europe-west1
europe-west2
europe-west3
europe-west4
CHANNEL_ID
:管道的使用者定義 IDCLIP_ID
:隨選影片短片的使用者定義 ID
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/clips/CLIP_ID", "createTime": CREATE_TIME, "startTime": START_TIME, "updateTime": UPDATE_TIME, "state": "SUCCEEDED", "outputUri": "gs://BUCKET_NAME", "slices": [ { "timeSlice": { "markinTime": "MARK_IN_TIME", "markoutTime": "MARK_OUT_TIME" } } ], "features": {}, "clipManifests": [ { "manifestKey": "manifest_hls", "outputUri": "gs://BUCKET_NAME/main.m3u8" } ] }
產生的資訊清單位於 clipManifests.outputUri
欄位中指定的 URI。資訊清單檔案名稱與父項管道的 manifests.fileName
欄位值相同。
回應應包含下列內容:
{
...
"state": "SUCCEEDED"
...
}
使用 projects.locations.channels.clips.get
方法時,系統只會提供每個頻道最近的 1000 個短片工作記錄。系統會移除超過上限的所有短片工作記錄。您必須管理由 outputUri
指定的產生短片檔案;Live Stream API 不會從 Cloud Storage 刪除這些檔案。
驗證值區內容
開啟剪輯片段的 outputUri
欄位中指定的 Cloud Storage 值區。確認該資料夾包含下列檔案和目錄:
- 剪輯片段的頂層資訊清單,名稱與管道設定中指定的
manifests.fileName
相同 (例如main.m3u8
);你可以使用線上媒體播放器播放這個資訊清單 - 通道中指定的每個
muxStreams.key
的資料夾 (例如mux_video_ts
)- 短片的播放清單 (例如
index-1.m3u8
) - 使用
YYYYMMDDTHHMMSSZ
格式命名的目錄 (例如20220708T203309Z/
);這個目錄會儲存 VOD 短片片段- 組成 VOD 短片的多個片段
segment-number.ts
檔案
- 組成 VOD 短片的多個片段
- 短片的播放清單 (例如
播放 VOD 短片
如要在 Shaka Player 中播放產生的媒體檔案,請完成下列步驟:
- 將您建立的 Cloud Storage bucket 設為可公開讀取。
- 如要在 Cloud Storage 值區中啟用跨來源資源共享 (CORS),請按照下列步驟操作:
- 建立包含下列內容的 JSON 檔案:
[ { "origin": ["https://shaka-player-demo.appspot.com/"], "responseHeader": ["Content-Type", "Range"], "method": ["GET", "HEAD"], "maxAgeSeconds": 3600 } ]
-
將
JSON_FILE_NAME
替換為您在前一個步驟建立的 JSON 檔案名稱後,執行下列指令:gcloud storage buckets update gs://BUCKET_NAME --cors-file=JSON_FILE_NAME.json
- 建立包含下列內容的 JSON 檔案:
- 在 Cloud Storage 值區中,找出系統產生的檔案。在該檔案的「Public access」(公開存取權) 資料欄中,按一下「Copy URL」(複製網址)。
- 前往 Shaka Player (這是一個線上即時串流播放器)。
- 按一下頂端導覽列中的「Custom Content」(自訂內容)。
- 按一下「+」按鈕。
將檔案的公開網址貼到「Manifest URL」(資訊清單網址) 方塊中。
在「Name」(名稱) 方塊中輸入名稱。
按一下「Save」(儲存)。
按一下「Play」(播放)。
這時候應該就會看到即時串流內容以測試模式播放。
廣告插播和廣告板事件
如果您為直播建立廣告插播事件,隨選影片片段就不會包含廣告。API 會產生播放清單,並將廣告中斷點替換為下列標記:
#EXT-X-CUE-OUT: AD_BREAK_DURATION
#EXT-X-CUE-IN
VOD 短片開頭或結尾出現的標題卡會自動移除。在串流中顯示的資訊板 (夾在直播內容之間) 會保留在產生的 VOD 短片中。