Generates a live transcoding playlist and converts video files into M3U8 files. After a playlist is generated, the videos in the playlist are immediately played and the video files are transcoded based on the playback progress. Compared with offline transcoding, online transcoding significantly reduces the time spent in waiting for the videos to be transcoded and reduces transcoding and storage costs.
Operation description
- Before you call this operation, make sure that you are familiar with the billing of Intelligent Media Management (IMM).
- Make sure that the project that you want to use is available in the current region. For more information, see Project Management.
- By default, you can call this operation to process only one video, audio, or subtitle track. You can specify the number of the video, audio, or subtitle tracks that you want to process.
- You can call this operation to generate a media playlist and a master playlist. For more information, see the parameter description.
- This operation is a synchronous operation. Synchronous or asynchronous transcoding is triggered only during playback or pre-transcoding. You can configure the Notification parameter to obtain the transcoding task result.
- For information about the feature description of this operation, see Live transcoding.
- The data processing capability of Object Storage Service (OSS) also provides the playlist generation feature. However, this feature can generate only a media playlist, and related parameters are simplified.
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resourcesis used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| imm:GenerateVideoPlaylist | none | *Project acs:imm:{#regionId}:{#accountId}:project/{#ProjectName} |
| none |
Request parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| ProjectName | string | Yes | immtest | |
| UserData | string | No | The custom user information, which is returned in asynchronous notifications to help you handle the notifications in the system. The maximum length of a notification is 2048 bytes. | {"ID": "user1","Name": "test-user1","Avatar": "http://example.com?id=user1"} |
| SourceURI | string | Yes | The OSS path of the video file. The OSS path must be in the oss://${Bucket}/${Object} format. ${Bucket} specifies the name of the OSS bucket that is in the same region as the current project. ${Object} specifies the full path of the file that contains the file name extension. Note
Only OSS buckets of the Standard storage class are supported. OSS buckets for which hotlink protection whitelists are configured are not supported.
| oss://imm-test/testcases/video.mp4 |
| SourceStartTime | float | No | The time when the playlist starts to generate. Unit: seconds.
Note
If you use this parameter together with the SourceDuration parameter, a playlist can be generated based on the partial content of a source video.
| 0 |
| SourceDuration | float | No | The period of time during which the playlist is generated. Unit: seconds.
Note
If you set this parameter to a value that exceeds the end time of a source video, use the default value.
| 0 |
| SourceSubtitles | array<object> | No | The subtitle files. By default, this parameter is left empty. Up to two subtitle files are supported. | |
| object | No | The subtitle file. | ||
| URI | string | Yes | The OSS path of the subtitle file. The OSS path must be in the oss://${Bucket}/${Object} format. ${Bucket} specifies the name of the OSS bucket that is in the same region as the current project. ${Object} specifies the full path of the file. Note
The MasterURI parameter cannot be left empty, and the OSS path oss://${Bucket}/${Object} of a subtitle file must be in the directory specified by the MasterURI parameter or its subdirectory.
| oss://test-bucket/test-object/subtitle/eng.vtt |
| Language | string | No | The subtitle language. If you configure this parameter, the value must comply with the ISO 639-2 standard. By default, this parameter is left empty. | eng |
| MasterURI | string | No | The OSS path of the master playlist. The OSS path must be in the oss://${Bucket}/${Object} format. ${Bucket} specifies the name of the OSS bucket that is in the same region as the current project. ${Object} specifies the full path of the file that is suffixed with .m3u8. Note
If a playlist contains subtitles or multiple outputs, the MasterURI parameter is required and the URI of subtitle files or outputs must be in the directory specified by the MasterURI parameter or its subdirectory.
| oss://bucket/object/master.m3u8 |
| Targets | array<object> | Yes | The live transcoding playlists. Up to 6 playlists are supported. Each output corresponds to at most one video media playlist and one or more subtitle media playlists. Note
If more than one output is configured, the MasterURI parameter is required.
| |
| object | Yes | The live transcoding playlist. | ||
| URI | string | No | The prefix of the OSS path that is used to store the live transcoding files. The live transcoding files include a M3U8 file and multiple TS files. The OSS path must be in the oss://${Bucket}/${Object} format. ${Bucket} specifies the name of the OSS bucket that is in the same region as the current project. ${Object} specifies the prefix of the full path of the file that does not contain the file name extension.
Note
If the MasterURI parameter is not left empty, the URI specified by this parameter must be in the directory specified by the MasterURI parameter or its subdirectory.
| oss://imm-test/testcases/video |
| Video | TargetVideo | No | The video processing configuration. If you set this parameter to null (default), video processing is disabled. The generated TS files do not contain video streams. Note
The Video and Subtitle parameters in the same output are mutually exclusive. If the Video parameter is configured, the Subtitle parameter is ignored.
| |
| Audio | TargetAudio | No | The audio processing configuration. If you set this parameter to null (default), audio processing is disabled. The generated TS files do not contain audio streams. Note
The Audio and Subtitle parameters in the same output are mutually exclusive. If the Audio parameter is configured, the Subtitle parameter is ignored. The Audio and Video parameters can be configured at the same time. You can also configure only the Audio parameter to generate only audio information.
| |
| Subtitle | TargetSubtitle | No | The subtitle processing configuration. Note
The Subtitle and Video or Audio parameters in the same output are mutually exclusive. You must configure the Subtitle parameter independently to generate subtitles.
| |
| TranscodeAhead | integer | No | The number of TS files that are pre-transcoded when the live transcoding is triggered. By default, a 2-minute video is pre-transcoded.
| 3 |
| Duration | float | No | The playback duration of a single TS file. Unit: seconds. Default value: 10. Valid values: 5 to 15. | 5 |
| InitialTranscode | float | No | The pre-transcoding duration. Unit: seconds. Default value: 30.
Note
This parameter is used to reduce the time spent in waiting for the initial playback of a video and improve the playback experience. If you want to replace the traditional video on demand (VOD) business scenario, you can try to pre-transcode the entire video.
| 30.0 |
| InitialSegments | array | No | The array of the durations of the pre-transcoded TS files. The array can contain the durations of up to six pre-transcoded TS files. By default, this parameter is left empty. This parameter is independent of the Duration parameter. | |
| float | No | The duration of the pre-transcoded TS file. Valid values: [1,Duration].
Note
If you set the duration of a pre-transcoded TS file to a small value, video loading can be smooth.
| 2.0 | |
| Tags | object | No | The tags that you want to add to a TS file in OSS. You can use tags to manage the lifecycles of TS files in OSS. Note
The combination of the value of the Tags parameter and the value of the Tags parameter in the upper level is used as the tag value of the current output. If the value of the Tags parameter in the current level is the same as the value of the Tags parameter in the upper level, use the value of the Tags parameter in the current level.
| |
| string | No | The tag value. | {\"key1\":\"value1\"} | |
| Tags | object | No | The tags that you want to add to a TS file in OSS. You can use tags to manage the lifecycles of TS files in OSS. | |
| string | No | The tag value. | {"key1": "value1", "key2": "value2"} | |
| CredentialConfig | CredentialConfig | No | If you do not have special requirements, leave this parameter empty. The authorization chain settings. For more information, see Use authorization chains to access resources of other entities. | |
| Notification | Notification | No | The notification settings. To view details, click Notification. For information about the asynchronous notification format, see Asynchronous message examples. | |
| OverwritePolicy | string | No | The overwrite policy when the media playlist exists. Valid values:
| overwrite |
Response parameters
Examples
Sample success responses
JSONformat
{
"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://imm-test/testcases/video.m3u8",
"Resolution": "640x480",
"FrameRate": "25/1"
}
],
"AudioPlaylist": [
{
"Token": "affe0c6042f09722fec95a21b8b******\n",
"URI": "oss://imm-test/testcases/video.m3u8\n",
"Channels": 1
}
],
"SubtitlePlaylist": [
{
"Token": "affe0c6042f09722fec95a21b8b******\n",
"URI": "oss://imm-test/testcases/vide_0.m3u8",
"Language": "en",
"Index": 1
}
]
}Error codes
For a list of error codes, visit the Service error codes.
Change history
| Change time | Summary of changes | Operation |
|---|---|---|
| 2024-03-26 | The response structure of the API has changed | View Change Details |
| 2023-04-04 | The internal configuration of the API is changed, but the call is not affected | View Change Details |