使用GenerateVideoPlaylist產生邊轉邊播m3u8播放清單-Intelligent Media Management-阿里雲 - Intelligent Media Management

建立邊轉邊播播放清單能夠將影片檔案產生 m3u8 檔案，產生播放清單後即時播放，並根據播放進度實施隨需轉碼，相比離線轉碼能極大減少轉碼等待時間並大幅降低轉碼和儲存開銷。

介面說明

請確保在使用該介面前，已充分了解智慧媒體管理產品的收費方式和價格。
呼叫該介面前，請確保目前 Region 已經存在可用的專案（Project），詳見專案管理。
使用該介面時，預設只處理一路影片/音訊/字幕串流，同時支援設定處理的影片/音訊/字幕串流數量。
重要 Targets 下面的 Video、Audio、Subtitle 參數不能同時為空，為空時則表示停用該處理，例如：Video 為空表示停用影片處理，輸出 ts 檔案中將不包含影片串流。
該介面限制原影片的時長最小為 0.x 秒，根據輸出影格率不同會有一些差異。
該介面同時能支援產生 Media Playlist 和 Master Playlist，請注意文件參數說明。
該介面為同步介面。播放或預轉時才會觸發同步或非同步轉碼。可以透過設定 Notification 訊息通知參數，透過訊息通知獲取轉碼任務結果。
該介面的功能說明參見邊轉邊播。
OSS 的資料處理能力也提供了產生播放清單功能，但只提供產生 Media Playlist 且參數進行了簡化。詳情參見 OSS 資料處理能力產生播放清單。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

imm:GenerateVideoPlaylist

none

*Project

acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}

無

請求參數

名稱	類型	必填	描述	樣本值
ProjectName	string	是	專案名稱，取得方式請參見建立專案。	immtest
UserData	string	否	使用者自訂資訊，在非同步訊息通知中會返回，方便您在系統內對訊息通知進行關聯處理。最大長度為 2048 位元組。	{"ID": "user1","Name": "test-user1","Avatar": "http://example.com?id=user1"}
SourceURI	string	是	影片的 OSS 位址。 OSS 位址規則為 oss://${Bucket}/${Object}，其中 ${Bucket} 為和目前專案處於同一區域 (Region) 的 OSS Bucket 名稱，${Object} 為包含副檔名的檔案完整路徑。說明只支援 OSS 標準儲存 Bucket。不支援設定了防盜鏈白名單存取 Bucket。	oss://test-bucket/test-source-object/video.mp4
SourceStartTime	number	否	產生播放清單的起始時間點，單位為秒（s）。取值範圍如下： 0（預設）或不填表示從來源影片起始時間點開始。大於 0 表示從來源影片所設定的時間點開始。說明透過與參數 SourceDuration 一同設定可以對來源影片的部分內容產生播放清單。	0
SourceDuration	number	否	產生播放清單的持續時間。單位為秒（s），取值範圍如下： 0（預設）或不填表示持續到來源影片結尾。大於 0 表示從產生播放清單的起始時間點持續所設定的時長。說明當設定參數所對應的時間點超過來源影片結尾時按預設值處理。	0
SourceSubtitles	array<object>	否	新增字幕清單，預設為空。最大支援 2 個。
	object	否	字幕資訊。
URI	string	是	被嵌入字幕的 OSS 位址。 OSS 位址規則為 oss://${Bucket}/${Object}，其中 ${Bucket} 為和目前專案處於同一區域 (Region) 的 OSS Bucket 名稱，${Object} 為檔案的完整路徑。說明參數 MasterURI 必須不為空，並且被嵌入字幕的 OSS 位址 `oss://${Bucket}/${Object}` 必須處於參數 MasterURI 所在目錄或其子目錄。	oss://test-bucket/test-object/subtitle/eng.vtt
Language	string	否	字幕語言，參考標準為 ISO 639-2，預設為空。	eng
MasterURI	string	否	Master Playlist 的 OSS 位址。 OSS 位址規則為 oss://${Bucket}/${Object}，其中 ${Bucket} 為和目前專案處於同一區域 (Region) 的 OSS Bucket 名稱，${Object} 為帶 ".m3u8" 副檔名的檔案完整路徑。說明如果 Playlist 有字幕輸入或有多 Target 輸出，MasterURI 為必填，並且字幕 URI 或 Target URI 必須處於 MasterURI 所在目錄或子目錄。	oss://test-bucket/test-object/master.m3u8
Targets	array<object>	是	邊轉邊播播放清單陣列，陣列長度最大為 6。每個 Target 對應至多一個影片 Media Playlist 和一個或多個字幕 Media Playlist。說明如果設定了大於一個 Target，參數 MasterURI 必須不為空。
	array<object>	否	邊轉邊播任務詳細資訊。
URI	string	否	邊轉邊播輸出檔案的 OSS 位址前綴，輸出檔案包括 m3u8 檔案和 ts 檔案。 OSS 位址規則為 oss://${Bucket}/${Object}，其中 ${Bucket} 為和目前專案處於同一區域的 OSS Bucket 名稱，${Object} 為不包含副檔名的檔案完整路徑前綴。範例：URI 為 oss://test-bucket/test-object/output-video，則將產生一個 oss://test-bucket/test-object/output-video.m3u8 檔案以及多個 oss://test-bucket/test-object/output-video-${token}-${index}.ts 檔案，其中 ${token} 為根據轉碼參數產生的唯一字串，在 API 返回結果中包含了 ${token} 參數。${index} 為產生的從 0 開始編號的 ts 檔案序號。說明如果參數 MasterURI 不為空，URI 位址必須處於參數 MasterURI 所在目錄或其子目錄。	oss://test-bucket/test-object/output-video
Container	string	否
Video	TargetVideo	否	影片處理參數設定，空值（預設）表示停用影片處理，輸出 ts 檔案中將不包含影片串流。說明同一 Target 內的 Video 和 Subtitle 欄位互斥。如果設定了 Video 欄位會忽略 Subtitle 欄位。
Audio	TargetAudio	否	音訊處理參數設定，空值（預設）表示停用音訊處理，輸出 ts 檔案中將不包含音訊串流。說明同一 Target 內的 Audio 和 Subtitle 欄位互斥。如果設定了 Audio 欄位會忽略 Subtitle 欄位。Audio 和 Video 可以同時設定，Audio 表示輸出影片中的音訊資訊。也可以只設定 Audio，只產生音訊資訊。
Subtitle	TargetSubtitle	否	字幕處理參數設定。說明同一 Target 內的 Subtitle 和 Video 或 Audio 欄位互斥，只有單獨設定 Subtitle 才能產生字幕。
TranscodeAhead	integer	否	觸發邊轉邊播時向前轉碼的 ts 檔案數量。預設向前轉碼 2 分鐘時長的影片。範例：Duration 為 10，則 TranscodeAhead 預設為 12。您可以指定該參數控制非同步向前轉碼的數量，取值範圍為 [10,30]。	12
Duration	number	否	單個 ts 檔案的播放時長。單位為秒（s），預設為 10，取值範圍為 [5,15]。	10
InitialTranscode	number	否	初始轉碼時長，單位為秒（s），預設值為 30。當所設定的時長為 0 時，不預轉。當所設定的時長小於 0 或超過來源影片長度時，將初始轉碼整段影片。當所設定的時長位於 ts 檔案中間時，將持續轉碼到 ts 檔案結束位置。說明該參數主要用於加快影片初次播放的等待時間，提升播放體驗。若您需要替換傳統 VOD 業務場景則可嘗試初始轉碼整段影片。	30
InitialSegments	array	否	初始轉碼 ts 檔案時長陣列，陣列長度最大為 6，預設為空，與參數 Duration 獨立。
	number	否	初始轉碼 ts 檔案時長，取值範圍為 [1,Duration]。範例：初始轉碼 ts 時長陣列為 `[2, 2, 4, 4, 8, 8]`，則序號為 0 的 ts 時長為 2，序號為 1 的 ts 時長為 2，序號為 2 的 ts 時長為 4，序號為 3 的 ts 時長為 4，序號為 4 的 ts 時長為 8，序號為 5 的 ts 時長為 8。說明自訂更小的初始轉碼 ts 檔案時長可以讓影片載入更加流暢。	2
Tags	object	否	為產生的 ts 檔案新增 OSS 物件標籤。可以使用 OSS 標籤來控制 OSS 檔案的生命週期。說明目前標籤值與上一級中定義的 Tags 取聯集作為目前 Target 的標籤值。如有同名，取目前值。
	string	否	標籤值。	{\"key1\":\"value1\"}
Tags	object	否	為產生的 ts 檔案新增 OSS 物件標籤。可以使用標籤來控制 OSS 檔案的生命週期。	{"key1": "value1", "key2": "value2"}
	string	否	標籤值。	{"key1": "value1", "key2": "value2"}
CredentialConfig	CredentialConfig	否	如無特殊需求，請保持留空即可。鏈式授權設定，非必填。更多資訊，請參見使用鏈式授權存取其他實體資源。
Notification	Notification	否	訊息通知設定，詳細內容請按一下 Notification 檢視，非同步通知訊息格式請參見非同步通知訊息格式。
OverwritePolicy	string	否	當 Media Playlist 存在時的覆蓋策略，取值範圍： overwrite（預設）：覆蓋已經存在的 Media Playlist。 skip-existing：跳過產生，保留已經存在的 Media Playlist。	overwrite

返回參數

名稱	類型	描述	樣本值
	object	Schema of Response
RequestId	string	請求 ID。	CA995EFD-083D-4F40-BE8A-BDF75FFF*****
Duration	number	輸出影片總時長。	1082
Token	string	Master Playlist 的 Token。	92376fbb-171f-4259-913f-705f7ee0****
MasterURI	string	Master Playlist 的 OSS 位址。	oss://test-bucket/test-object/master.m3u8
VideoPlaylist	array<object>	影片 Media Playlist 檔案清單。
	object	影片 Media Playlist 檔案資訊。
Token	string	影片 Media Playlist 產生的 Token。可以使用該參數組裝成 ts 檔案產生的位址。說明根據返回的 Token 值，可以拼接出轉碼產生的 ts 位址。拼接格式為：oss://${Bucket}/${Object}-${Token}-${Index}.ts，其中 oss://${Bucket}/${Object} 為輸入參數的 Target URI 位址，${Token} 為返回的參數，${Index} 為 ts 的序號。	affe0c6042f09722fec95a21b8b******
URI	string	影片 Media Playlist 的 OSS 位址。	oss://test-bucket/test-object/output-video.m3u8
Resolution	string	影片解析度。	640x480
FrameRate	string	影片影格率。	25/1
AudioPlaylist	array<object>	音訊 Media Playlist 檔案清單。
	object	音訊 Media Playlist 檔案資訊。
Token	string	音訊 Media Playlist 產生的 Token。可以使用該參數組裝成 ts 檔案產生的位址。	affe0c6042f09722fec95a21b8b******
URI	string	音訊 Media Playlist 的 OSS 位址。	oss://test-bucket/test-object/output-audio.m3u8
Channels	integer	音訊聲道數量。	1
SubtitlePlaylist	array<object>	字幕 Media Playlist 檔案清單。
	object	字幕 Media Playlist 檔案資訊。
Token	string	字幕 Media Playlist 產生的 Token。可以使用該參數組裝成字幕檔案產生的位址。說明根據返回的 Token 值，可以拼接出轉碼產生的字幕檔案位址。拼接格式為：oss://${Bucket}/${Object}-${Token}_${Index}.ts，其中 oss://${Bucket}/${Object} 為輸入參數的 Subtitle URI 位址，${Token} 為返回的參數，${Index} 為字幕的序號。	affe0c6042f09722fec95a21b8b******
URI	string	字幕 Media Playlist 的 OSS 位址。	oss://test-bucket/test-object/output-subtitle.m3u8
Language	string	字幕串流的語言。說明語言來源於 SourceURI 來源影片的字幕串流資訊。如果來源影片不存在語言資訊，返回空值。	eng
Index	integer	字幕串流編號，從 0 開始。	1

樣本

正常返回樣本

JSON格式

{
  "RequestId": "CA995EFD-083D-4F40-BE8A-BDF75FFF*****",
  "Duration": 1082,
  "Token": "92376fbb-171f-4259-913f-705f7ee0****",
  "MasterURI": "oss://test-bucket/test-object/master.m3u8",
  "VideoPlaylist": [
    {
      "Token": "affe0c6042f09722fec95a21b8b******",
      "URI": "oss://test-bucket/test-object/output-video.m3u8",
      "Resolution": "640x480",
      "FrameRate": "25/1"
    }
  ],
  "AudioPlaylist": [
    {
      "Token": "affe0c6042f09722fec95a21b8b******",
      "URI": "oss://test-bucket/test-object/output-audio.m3u8",
      "Channels": 1
    }
  ],
  "SubtitlePlaylist": [
    {
      "Token": "affe0c6042f09722fec95a21b8b******",
      "URI": "oss://test-bucket/test-object/output-subtitle.m3u8",
      "Language": "eng",
      "Index": 1
    }
  ]
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。