Adds a recording configuration for an application or a live stream.
Usage notes
The recording feature supports automatic recording, on-demand recording, and manual recording. You must call this operation to configure a recording template regardless of the recording mode used. You can specify the format and duration of a recording in a recording template. The format of a recording can be TS, MP4, or FLV. You can specify multiple recording modes at the same time. For example, you can specify automatic recording for an application and manual recording for a specific live stream. A live stream can be recorded in only one mode. If you specify a recording mode for an application and another recording mode for a live stream under the application, the live stream is recorded in the mode specified for the live stream. If you specify automatic recording for an application and manual recording for specific live streams under the application, the specific live streams are manually recorded. If you configure only a recording template but do not call the operations related to manual recording for the live streams, the live streams are not recorded.
If the permissions to write live stream recordings to a specified bucket are deleted, use the following methods to reconfigure the permissions:
Configure the permissions in the ApsaraVideo Live console. For more information, see Configure OSS.
Authorize a RAM user to access ApsaraVideo Live. For more information, see Permission management overview.
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 limit on an API operation in ApsaraVideo Live.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
Action | String | Yes | AddLiveAppRecordConfig | The operation that you want to perform. Set the value to AddLiveAppRecordConfig. |
DomainName | String | Yes | example.com | The main streaming domain. |
AppName | String | Yes | liveApp**** | The name of the application to which the live stream belongs. |
OssEndpoint | String | Yes | learn.developer.aliyundoc.com | The endpoint of the Object Storage Service (OSS) bucket. To store live stream recordings in OSS, you need to create an OSS bucket in advance. For more information, see Configure OSS. |
OssBucket | String | Yes | liveBucket**** | The name 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. |
StreamName | String | No | teststream | The name of the live stream. |
StartTime | String | No | 2018-04-10T09:57:21Z | The recording start time. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC. Note The start time must be within seven days after the stream ingest starts. This parameter takes effect only for the live stream specified by the StreamName parameter. If the StreamName parameter is not specified, this parameter does not take effect. |
EndTime | String | No | 2018-04-16T09:57:21Z | The recording end time. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC. Note The time range that is specified by the EndTime and StartTime parameters must be less than or equal to seven days. If the value exceeds seven days, ApsaraVideo Live considers seven days as the time range. This parameter takes effect only for the live stream specified by the StreamName parameter. If the StreamName parameter is not specified, this parameter does not take effect. |
OnDemand | Integer | No | 1 | Configures on-demand recording. Valid values:
Note If you set the OnDemand parameter to 1, you must call the AddLiveRecordNotifyConfig operation to configure the OnDemandUrl parameter. Otherwise, ApsaraVideo Live does not perform on-demand recording. |
DelayTime | Integer | No | 180 | The interruption duration for merge. If the stream interruption duration exceeds the specified duration, a new recording is generated. The value of this parameter ranges from 15 to 21600. |
RecordFormat.N.SliceDuration | Integer | No | 30 | The duration of a single TS segment. Unit: seconds. Important This parameter takes effect only if you set the RecordFormat.N.Format parameter to m3u8. If you do not specify this parameter, the default value 30 seconds is used. Valid values: 5 to 30. |
RecordFormat.N.SliceOssObjectPrefix | String | No | record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence} | The name of the TS segment. Important This parameter is required only if you set the RecordFormat.N.Format parameter to m3u8.
|
RecordFormat.N.CycleDuration | Integer | No | 1 | The recording period. Unit: seconds. If you do not specify this parameter, the default value 6 hours is used. Note
|
RecordFormat.N.OssObjectPrefix | String | No | record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime} | The name of the recording that is stored in OSS.
|
RecordFormat.N.Format | String | No | m3u8 | The recording format. Supported formats include M3U8, FLV, and MP4. Valid values: Important You need to specify at lease one of the RecordFormat and TranscodeRecordFormat parameters.
|
TranscodeRecordFormat.N.SliceDuration | Integer | No | 30 | The duration of a single TS segment in the transcoded stream recording. Unit: seconds. Important This parameter takes effect only if you set the TranscodeRecordFormat.N.Format parameter to m3u8. If you do not specify this parameter, the default value 30 seconds is used. Valid values: 5 to 30. |
TranscodeRecordFormat.N.SliceOssObjectPrefix | String | No | record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence} | The name of the TS segment in the transcoded stream recording. Important This parameter is required only if you set the TranscodeRecordFormat.N.Format parameter to m3u8.
|
TranscodeRecordFormat.N.CycleDuration | Integer | No | 21600 | The transcoded stream recording period. Unit: seconds. If you do not specify this parameter, the default value 6 hours is used. |
TranscodeRecordFormat.N.OssObjectPrefix | String | No | record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime} | The name of the transcoded stream recording that is stored in OSS.
|
TranscodeRecordFormat.N.Format | String | No | m3u8 | The format of the transcoded stream recording. Supported formats include M3U8, FLV, and MP4. Valid values:
|
TranscodeTemplates.N | String | No | sd |
|
Response parameters
Parameter | Type | Example | Description |
RequestId | String | 16A96B9A-F203-4EC5-8E43-CB92E68F4CD8 | The request ID. |
Examples
Sample requests
http(s)://live.aliyuncs.com/?Action=AddLiveAppRecordConfig
&AppName=liveApp****
&DomainName=example.com
&OssBucket=liveBucket****
&OssEndpoint=learn.developer.aliyundoc.com
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<?xml version="1.0" encoding="UTF-8" ?>
<AddLiveAppRecordConfigResponse>
<RequestId>16A96B9A-F203-4EC5-8E43-CB92E68F4CD8</RequestId>
</AddLiveAppRecordConfigResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"AddLiveAppRecordConfigResponse" : {
"RequestId" : "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}
}
Error codes
HttpCode | Error code | Error message | Description |
400 | InvalidOssBucket.Malformed | Specified parameter OssBucket is not valid. | The error message returned because the OSS bucket is not found. Check whether the value of the OssBucket parameter is valid. |
400 | InvalidOssBucket.NotFound | The parameter OssBucket does not exist. | The error message returned because the OSS bucket is not found. Check whether the value of the OssBucket parameter is valid. |
400 | InvalidFormat.Malformed | Specified parameter Format is not valid. | The error message returned because the format specified for the recording is invalid. Check whether the value of the RecordFormat.N.Format parameter is valid. |
400 | InvalidCycleDuration.Malformed | Specified CycleDuration Format is not valid. | The error message returned because the format of the recording period is invalid. Check whether the value of the RecordFormat.N.CycleDuration parameter is valid. |
400 | MissingOssObjectPrefix | OssObjectPrefix is mandatory for this action. | The error message returned because the name of the recording is not specified. Check whether the value of the RecordFormat.N.OssObjectPrefix parameter is valid. |
400 | InvalidOssObjectPrefix.Malformed | Specified parameter OssObjectPrefix is not valid. | The error message returned because the name of the recording is invalid. Check whether the value of the RecordFormat.N.OssObjectPrefix parameter is valid. |
400 | InvalidSliceOssObjectPrefix.Malformed | Specified parameter SliceOssObjectPrefix is not valid. | The error message returned because the name of the TS segment is invalid. Check whether the value of the RecordFormat.N.SliceOssObjectPrefix parameter is valid. |
400 | ConfigAlreadyExists | Config has already exist. | The error message returned because an existing recording configuration is found. |
400 | InvalidStartTime.Malformed | Specified StartTime is malformed. | The error message returned because the value specified for StartTime is invalid. Check whether the value of the StartTime parameter is valid. |
400 | InvalidEndTime.Malformed | Specified EndTime is malformed. | The error message returned because the value specified for EndTime is invalid. Check whether the value of the EndTime parameter is valid. |
For a list of error codes, see Service error codes.
Precautions
ApsaraVideo Live supports triggered stream pulling. If the streaming URL of the corresponding domain name is used for streaming, ApsaraVideo Live is automatically triggered to pull the live stream. If no one is watching the live stream, ApsaraVideo Live does not pull the live stream from the origin. In this case, automatic recording, on-demand recording, and manual recording are also disabled.