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:
- For mandatory resource types, indicate with a prefix of * .
- 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 array of live transcoding playlists. The maximum length of the array is 6. Each element corresponds to at most one video media playlist and one or more subtitle media playlists. Note
If the array contains more than one element, the MasterURI parameter cannot be left empty.
| |
| object | Yes | The live transcoding information. | ||
| 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 that does not contain the file name extension.
Note
If the MasterURI parameter is not left empty, the path 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 element 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 element 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.
| |
| Subtitle | TargetSubtitle | No | The subtitle processing configuration. Note
The Subtitle and Video or Audio parameters in the same element 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 reduces the time required to start the first playback, which enhances the viewing experience. If you want to use live transcoding in traditional video-on-demand scenarios, you can pre-transcode entire videos.
| 30.0 |
| InitialSegments | array | No | The array of the durations of the pre-transcoded TS files. The maximum length of the array is 6. 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, the value of the Tags parameter in the current level is used.
| |
| string | No | The value of the tag. | {\"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 have no 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. 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 |