Call GenerateVideoPlaylist to create a video playlist for live transcoding - Intelligent Media Management - Alibaba Cloud - Intelligent Media Management

Creates a just-in-time transcoding playlist that generates an M3U8 file from a video file. The playlist can be played immediately after generation, and transcoding is performed on demand based on playback progress. Compared with offline transcoding, this significantly reduces transcoding wait time and substantially lowers transcoding and storage costs.

Operation description

Before you use this operation, make sure that you understand the billing of Intelligent Media Management (IMM) and its pricing.
Before you invoke this operation, make sure that an active project exists in the current region. For more information, see Project management.
By default, this operation processes only one video, audio, or subtitle stream. You can configure the number of video, audio, and subtitle streams to process.
Important The Video, Audio, and Subtitle parameters under Targets cannot all be empty. An empty value indicates that the corresponding processing is disabled. For example, if Video is empty, video processing is disabled and the output TS files do not contain video streams.
The minimum duration of the source video is approximately 0.x seconds, which varies depending on the output frame rate.
This operation supports generating both Media Playlists and Master Playlists. Pay attention to the metric descriptions in this document.
This is a synchronous operation. Synchronous or asynchronous transcoding is triggered only during playback or pre-transcoding. You can set the Notification parameter to receive transcoding task results through message notifications.
For more information about this feature, see Just-in-time transcoding.
OSS data processing also provides a playlist generation feature, but it only supports generating Media Playlists with simplified parameters. For details, see Generate a playlist in OSS data processing.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

imm:GenerateVideoPlaylist

none

*Project

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

None

Request parameters

Parameter	Type	Required	Description	Example
ProjectName	string	Yes	The project name. For information about how to obtain the project name, see Create a project.	immtest
UserData	string	No	The custom information, which is returned in asynchronous message notifications. This helps you associate message notifications within your system. Maximum length: 2,048 bytes.	{"ID": "user1","Name": "test-user1","Avatar": "http://example.com?id=user1"}
SourceURI	string	Yes	The OSS URI of the video. The OSS URI follows the format oss://${Bucket}/${Object}, where ${Bucket} is the name of the OSS bucket in the same region as the current project, and ${Object} is the full path of the file including the file name extension. Note Only OSS buckets with Standard storage are supported. Buckets with hotlink protection whitelists configured are not supported.	oss://test-bucket/test-source-object/video.mp4
SourceStartTime	number	No	The start time for generating the playlist. Unit: seconds. Valid values: 0 (default) or empty: starts from the beginning of the source video. A value greater than 0: starts from the specified time point in the source video. Note You can set this parameter together with SourceDuration to generate a playlist for a specific portion of the source video.	0
SourceDuration	number	No	The duration for generating the playlist. Unit: seconds. Valid values: 0 (default) or empty: continues until the end of the source video. A value greater than 0: continues for the specified duration from the start time of the playlist. Note If the time point corresponding to the specified parameter exceeds the end of the source video, the default value is used.	0
SourceSubtitles	array<object>	No	The list of subtitles to add. Default value: empty. A maximum of two subtitles are supported.
	object	No	The subtitle information.
URI	string	Yes	The OSS URI of the subtitle to embed. The OSS URI follows the format oss://${Bucket}/${Object}, where ${Bucket} is the name of the OSS bucket in the same region as the current project, and ${Object} is the full path of the file. Note The MasterURI parameter must not be empty, and the OSS URI `oss://${Bucket}/${Object}` of the subtitle must be in the same directory as or a subdirectory of the MasterURI parameter.	oss://test-bucket/test-object/subtitle/eng.vtt
Language	string	No	The subtitle language. The value follows the ISO 639-2 standard. Default value: empty.	eng
MasterURI	string	No	The OSS URI of the Master Playlist. The OSS URI follows the format oss://${Bucket}/${Object}, where ${Bucket} is the name of the OSS bucket in the same region as the current project, and ${Object} is the full path of the file with the ".m3u8" extension. Note If the playlist has subtitle input or multiple Target outputs, MasterURI is required. The subtitle URI or Target URI must be in the same directory as or a subdirectory of MasterURI.	oss://test-bucket/test-object/master.m3u8
Targets	array<object>	Yes	The array of just-in-time transcoding playlists. The maximum array length is 6. Each Target corresponds to at most one video Media Playlist and one or more subtitle Media Playlists. Note If more than one Target is configured, the MasterURI parameter must not be empty.
	array<object>	No	The details of the just-in-time transcoding task.
URI	string	No	The OSS URI prefix for the just-in-time transcoding output files, including M3U8 files and TS files. The OSS URI follows the format oss://${Bucket}/${Object}, where ${Bucket} is the name of the OSS bucket in the same region as the current project, and ${Object} is the full path prefix of the file without the file name extension. Example: If URI is oss://test-bucket/test-object/output-video, an oss://test-bucket/test-object/output-video.m3u8 file and multiple oss://test-bucket/test-object/output-video-${token}-${index}.ts files are generated. ${token} is a unique string generated based on the transcoding parameters and is included in the API response. ${index} is the sequence number of the TS file starting from 0. Note If the MasterURI parameter is not empty, the URI must be in the same directory as or a subdirectory of the MasterURI parameter.	oss://test-bucket/test-object/output-video
Video	TargetVideo	No	The video processing parameter settings. An empty value (default) indicates that video processing is disabled and the output TS files do not contain video streams. Note The Video and Subtitle fields within the same Target are mutually exclusive. If the Video field is set, the Subtitle field is ignored.
Audio	TargetAudio	No	The audio processing parameter settings. An empty value (default) indicates that audio processing is disabled and the output TS files do not contain audio streams. Note The Audio and Subtitle fields within the same Target are mutually exclusive. If the Audio field is set, the Subtitle field is ignored. Audio and Video can be set at the same time. Audio specifies the audio information in the output video. You can also set only Audio to generate audio-only output.
Subtitle	TargetSubtitle	No	The subtitle processing parameter settings. Note The Subtitle field is mutually exclusive with the Video and Audio fields within the same Target. Subtitles are generated only when Subtitle is set independently.
TranscodeAhead	integer	No	The number of TS files to transcode ahead when just-in-time transcoding is triggered. By default, 2 minutes of video is transcoded ahead. Example: If Duration is 10, the default value of TranscodeAhead is 12. You can specify this parameter to control the number of asynchronous ahead-of-time transcoding files. Valid values: [10, 30].	12
Duration	number	No	The playback duration of a single TS file. Unit: seconds. Default value: 10. Valid values: [5, 15].	10
InitialTranscode	number	No	The initial transcoding duration. Unit: seconds. Default value: 30. If the value is set to 0, no pre-transcoding is performed. If the value is less than 0 or exceeds the source video length, the entire video is initially transcoded. If the specified duration falls in the middle of a TS file, transcoding continues until the end of that TS file. Note This parameter is mainly used to reduce the wait time for the first playback and improve the playback experience. If you want to replace a traditional VOD scenario, try initially transcoding the entire video.	30
InitialSegments	array	No	The array of initial transcoding TS file durations. The maximum array length is 6. Default value: empty. This parameter is independent of the Duration parameter.
	number	No	The duration of an initial transcoding TS file. Valid values: [1, Duration]. Example: If the initial transcoding TS duration array is `[2, 2, 4, 4, 8, 8]`, the TS file at index 0 has a duration of 2, the TS file at index 1 has a duration of 2, the TS file at index 2 has a duration of 4, the TS file at index 3 has a duration of 4, the TS file at index 4 has a duration of 8, and the TS file at index 5 has a duration of 8. Note Customizing smaller initial transcoding TS file durations makes video loading smoother.	2
Tags	object	No	The OSS object tags to add to the generated TS files. You can use OSS tags to control the lifecycle of OSS files. Note The tag values at this level are merged with the Tags defined at the parent level to form the tag values for the current Target. If a tag with the same name exists, the value at this level takes precedence.
	string	No	The tag value.	{\"key1\":\"value1\"}
Tags	object	No	The OSS object tags to add to the generated TS files. You can use tags to control the lifecycle of OSS files.	{"key1": "value1", "key2": "value2"}
	string	No	The tag value.	{"key1": "value1", "key2": "value2"}
CredentialConfig	CredentialConfig	No	Leave this parameter empty unless you have special requirements. The China authorization configuration. This parameter is optional. For more information, see Use chained authorization to access resources of other entities.
Notification	Notification	No	The message notification configuration. Click Notification for details. For the format of asynchronous notification messages, see Asynchronous notification message format.
OverwritePolicy	string	No	The overwrite policy when a Media Playlist already exists. Valid values: overwrite (default): overwrites the existing Media Playlist. skip-existing: skips generation and retains the existing Media Playlist.	overwrite

Response elements

Element	Type	Description	Example
	object	Schema of Response
RequestId	string	The request ID.	CA995EFD-083D-4F40-BE8A-BDF75FFF*****
Duration	number	The total duration of the output video.	1082
Token	string	The token of the Master Playlist.	92376fbb-171f-4259-913f-705f7ee0****
MasterURI	string	The OSS URI of the Master Playlist.	oss://test-bucket/test-object/master.m3u8
VideoPlaylist	array<object>	The list of video Media Playlist files.
	object	The video Media Playlist file information.
Token	string	The token generated for the video Media Playlist. You can use this parameter to construct the addresses of the generated TS files. Note Based on the returned Token value, you can construct the addresses of the transcoded TS files. The format is: oss://${Bucket}/${Object}-${Token}-${Index}.ts, where oss://${Bucket}/${Object} is the Target URI specified in the input parameters, ${Token} is the returned parameter, and ${Index} is the sequence number of the TS file.	affe0c6042f09722fec95a21b8b******
URI	string	The OSS URI of the video Media Playlist.	oss://test-bucket/test-object/output-video.m3u8
Resolution	string	The video resolution.	640x480
FrameRate	string	The video frame rate.	25/1
AudioPlaylist	array<object>	The list of audio Media Playlist files.
	object	The audio Media Playlist file information.
Token	string	The token generated for the audio Media Playlist. You can use this parameter to construct the addresses of the generated TS files.	affe0c6042f09722fec95a21b8b******
URI	string	The OSS URI of the audio Media Playlist.	oss://test-bucket/test-object/output-audio.m3u8
Channels	integer	The number of audio channels.	1
SubtitlePlaylist	array<object>	The list of subtitle Media Playlist files.
	object	The subtitle Media Playlist file information.
Token	string	The token generated for the subtitle Media Playlist. You can use this parameter to construct the addresses of the generated subtitle files. Note Based on the returned Token value, you can construct the addresses of the transcoded subtitle files. The format is: oss://${Bucket}/${Object}-${Token}_${Index}.ts, where oss://${Bucket}/${Object} is the Subtitle URI specified in the input parameters, ${Token} is the returned parameter, and ${Index} is the sequence number of the subtitle file.	affe0c6042f09722fec95a21b8b******
URI	string	The OSS URI of the subtitle Media Playlist.	oss://test-bucket/test-object/output-subtitle.m3u8
Language	string	The language of the subtitle stream. Note The language is obtained from the subtitle stream information of the source video specified by SourceURI. If the source video does not contain language information, an empty value is returned.	eng
Index	integer	The sequence number of the subtitle stream, starting from 0.	1

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.