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

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

介面說明

請確保在使用該介面前，已充分瞭解Intelligent Media Management產品的收費方式和價格。
調用該介面前，請確保當前 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
Video	TargetVideo	否	視頻處理參數配置，空值（預設）表示禁用視頻處理，輸出 ts 檔案中將不包含視頻流。說明同一 Target 內的 Video 和 Subtitle 欄位互斥。如果設定了 Video 欄位會忽略 Subtile 欄位。
Audio	TargetAudio	否	音頻處理參數配置，空值（預設）表示禁用音頻處理，輸出 ts 檔案中將不包含音頻流。說明同一 Target 內的 Audio 和 Subtitle 欄位互斥。如果設定了 Audio 欄位會忽略 Subtile 欄位。Audio 和 Video 可以同時設定，Audio 表示輸出視頻中的音頻資訊。也可以只設定 Audio，只產生音頻資訊。
Subtitle	TargetSubtitle	否	字幕處理參數配置。說明同一 Target 內的 Subtile 和 Video 或 Audio 欄位互斥，只有單獨設定 Subtile 才能產生字幕。
TranscodeAhead	integer	否	觸發邊轉邊播時向前轉碼的 ts 檔案數量。預設向前轉碼 2 分鐘時間長度的視頻。樣本：Duraiton 為 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, 2, 4, 4, 8, 8]
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
    }
  ]
}

錯誤碼

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

變更歷史

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