Configure APP recording, with output saved to OSS.
Operation description
The live stream recording feature allows you to record a live stream and stores the recordings in a specified location. You can view the recordings whenever you want to. Recordings that are stored in OSS support multiple formats, such as Transport Stream (TS), MP4, Flash Video (FLV), and Common Media Application Format (CMAF). You can use different recording policies, including automatic recording, on-demand recording, and manual recording. By calling this operation, you can configure the recording template. For more information about live stream recording, see Live stream recording.
QPS limit
You can call this operation up to 30 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limits.
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 Resources
is 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 |
---|---|---|---|---|
live:AddLiveAppRecordConfig | create | *Domain acs:cdn:*:{#accountId}:domain/{#DomainName} |
| none |
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
DomainName | string | Yes | The main streaming domain. | example.com |
AppName | string | Yes | The name of the application to which the live stream belongs. | liveApp**** |
OssEndpoint | string | Yes | The endpoint of the OSS bucket. To store live stream recordings in OSS, you need to create an OSS bucket in advance. For more information, see Configure OSS. | learn.developer.aliyundoc.com |
OssBucket | string | Yes | The name of the OSS bucket where live streaming recording files are stored. To store recorded files in OSS, you need to create an OSS bucket in advance. For creation method, please refer to Configure OSS. | liveBucket**** |
StreamName | string | No | Stream broadcast name. | teststream |
StartTime | string | No | Start time of the recording. Format: yyyy-MM-ddTHH:mm:ssZ (UTC time). Note
The set time must be within 7 days of the actual streaming start time, and is only valid for stream-level recording (when StreamName is not empty).
| 2018-04-10T09:57:21Z |
EndTime | string | No | Recording end time. Format: yyyy-MM-ddTHH:mm:ssZ (UTC time). Note
The difference between EndTime and StartTime should not exceed 7 days; if it does, it will be calculated as 7 days. This is only valid for stream-level recording (when StreamName is not empty).
| 2018-04-16T09:57:21Z |
OnDemand | integer | No | On-demand recording. Valid values:
Note
When OnDemand is set to 1, you need to first configure the OnDemandUrl via the AddLiveRecordNotifyConfig interface; otherwise, recording is disabled by default.
| 1 |
DelayTime | integer | No | Duration for stream concatenation. If the live streaming interruption exceeds the set concatenation duration, a new file will be generated. The concatenation duration can be set between 15 to 21600 seconds. | 180 |
RecordFormat | array<object> | No | The recording details. | |
object | No | |||
SliceDuration | integer | No | The duration of a single segment. Unit: seconds. Note
This parameter takes effect only if you set the RecordFormat.N.Format parameter to m3u8 or cmaf.
If you do not specify this parameter, the default value 30 seconds is used. Valid values: 5 to 30. | 30 |
SliceOssObjectPrefix | string | No | The naming format of a segment. Note
This parameter is required only if you set the RecordFormat.N.Format parameter to m3u8 or cmaf.
| record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence} |
CycleDuration | integer | No | The recording cycle. Unit: seconds. If you do not specify this parameter, the default value 6 hours is used. Note
| 1 |
OssObjectPrefix | string | No | The name of the recording that is stored in OSS.
| record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime} |
Format | string | No | The recording format. Supported formats include M3U8, FLV, and MP4. Valid values: Note
You need to specify at lease one of the RecordFormat and TranscodeRecordFormat parameters. If you set this parameter to m3u8 or cmaf, you must also specify the RecordFormat.N.SliceOssObjectPrefix and RecordFormat.N.SliceDuration parameters.
| m3u8 |
TranscodeRecordFormat | array<object> | No | The transcoded stream recording details. | |
object | No | |||
SliceDuration | integer | No | The duration of a single segment in the transcoded stream recording. Unit: seconds. Note
This parameter takes effect only if you set the TranscodeRecordFormat.N.Format parameter to m3u8 or cmaf.
If you do not specify this parameter, the default value 30 seconds is used. Valid values: 5 to 30. | 30 |
SliceOssObjectPrefix | string | No | The naming format of a segment in the transcoded stream recording. Note
This parameter is required only if you set the TranscodeRecordFormat.N.Format parameter to m3u8 or cmaf.
| record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence} |
CycleDuration | integer | No | The transcoded stream recording cycle. Unit: seconds. If you do not specify this parameter, the default value 6 hours is used. | 21600 |
OssObjectPrefix | string | No | The name of the transcoded stream recording that is stored in OSS.
| record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime} |
Format | string | No | The format of the transcoded stream recording. Supported formats include M3U8, FLV, and MP4. Valid values: Note
If you set this parameter to m3u8 or cmaf, you must also specify the TranscodeRecordFormat.N.SliceOssObjectPrefix and TranscodeRecordFormat.N.SliceDuration parameters.
| m3u8 |
TranscodeTemplates | array | No | Transcoding stream recording template group. | |
string | No |
Note
TranscodeTemplates does not allow inputting raw , which is a reserved identifier.RepeatList signifies the N in TranscodeTemplates.N, interpretable as incrementally setting multiple configurations, e.g., TranscodeTemplates.1=sd, TranscodeTemplates.2=hd. | sd |
Response parameters
Examples
Sample success responses
JSON
format
{
"RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F****"
}
Error codes
HTTP status code | Error code | Error message | Description |
---|---|---|---|
400 | InvalidOssEndpoint.Malformed | %s | - |
400 | InvalidOssBucket.Malformed | Specified parameter OssBucket is not valid. | - |
400 | InvalidOssBucket.NotFound | The parameter OssBucket does not exist. | - |
400 | InvalidFormat.Malformed | Specified parameter Format is not valid. | Invalid value of Format. Check whether the Format parameter that you specified is correct. |
400 | InvalidCycleDuration.Malformed | Specified CycleDuration Format is not valid. | Invalid format of CycleDuration. Check whether the format of the CycleDuration parameter is correct. |
400 | InvalidSliceDuration.Malformed | Specified SliceDuration Format is not valid. | - |
400 | InvalidTemplateLength.Malformed | Specified record template length is not valid. | - |
400 | InvalidTemplate.ForbidRaw | Template named raw is Forbidden. | - |
400 | MissingTemplate | Template is mandatory for this action. | - |
400 | MissingOssObjectPrefix | OssObjectPrefix is mandatory for this action. | - |
400 | MissingSliceOssObjectPrefix | SliceOssObjectPrefix is mandatory for this action. | - |
400 | InvalidOssObjectPrefix.Malformed | Specified parameter OssObjectPrefix is not valid. | - |
400 | InvalidSliceOssObjectPrefix.Malformed | Specified parameter SliceOssObjectPrefix is not valid. | - |
400 | ConfigAlreadyExists | Config has already exist. | - |
400 | InvalidFormat.IllegalOperation | Specified parameter Format can not be multiple. | - |
400 | InvalidDelayTime | Specified Delaytime is invalid. | - |
400 | Live2Vod.ConfigAlreadyExists | Had live2vod record config already. | - |
400 | InvalidStartTime.Malformed | Specified StartTime is malformed. | - |
400 | InvalidEndTime.Malformed | Specified EndTime is malformed. | - |
400 | InvalidEndTime.Mismatch | Specified EndTime does not math the specified StartTime or current time. | - |
400 | InvalidStartTime.Mismatch | Specified StartTime does not math the current time. | - |
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation |
---|
Considerations:
- ApsaraVideo Live supports triggered stream pulling. If the streaming URL for a domain name is used for playback, ApsaraVideo Live is automatically triggered to pull live streams. If no live streams are played, ApsaraVideo Live does not pull live streams from the origin. In this case, automatic recording, on-demand recording, and manual recording are also disabled.