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 Resource Access Management (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

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer automatically generates the sample code of the operation for different SDKs.

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 must 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 must 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 7 days after the stream ingest starts. This parameter takes effect only on 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 difference between EndTime and StartTime must be within 7 days. If the difference exceeds 7 days, ApsaraVideo Live considers 7 days as the difference. This parameter takes effect only on 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

Specifies whether to enable on-demand recording. Valid values:

  • 0: disables on-demand recording.
  • 1: enables on-demand recording by using the HTTP callback method.
  • 2: enables on-demand recording by parsing the stream ingest parameters.
  • 7: By default, ApsaraVideo Live does not automatically record live streams. You can call the RealTimeRecordCommand operation to manually start or stop recording.
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.
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 is 30 seconds. 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.
  • By default, the duration of a TS segment is 30 seconds. The name must be less than 256 bytes in length and can contain the {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence} variables.
  • The name must contain the {UnixTimestamp} and {Sequence} variables.
RecordFormat.N.CycleDuration Integer No 1

The duration of the recording period. Unit: seconds. If you do not specify this parameter, the default value is 6 hours.

Note
  • If a live stream is interrupted during a recording period but is resumed within 3 minutes, the stream is recorded in the same recording before and after the interruption.
  • If a live stream is interrupted for more than 3 minutes, a new recording is generated. To change the default stream interruption time, submit a ticket. For more information about how to submit a ticket, see Contact us.
RecordFormat.N.OssObjectPrefix String No record/{AppName}/{StreamName}/{Sequence}{EscapedStartTime}{EscapedEndTime}

The name of the recording that is stored in OSS.

  • The name must be less than 256 bytes in length and can contain the {AppName}, {StreamName}, {Sequence}, {StartTime}, {EndTime}, {EscapedStartTime}, and {EscapedEndTime} variables.
  • The name must contain the {StartTime} and {EndTime} variables or the {EscapedStartTime} and {EscapedEndTime} variables.
RecordFormat.N.Format String No m3u8

The format of the recording. Supported formats include M3U8, FLV, and MP4. Valid values:

Important You must specify the RecordFormat parameter or/and TranscodeRecordFormat parameter.
  • m3u8. If you set this parameter to m3u8, you must also specify the RecordFormat.N.SliceOssObjectPrefix and RecordFormat.N.SliceDuration parameters.
  • flv
  • mp4
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 is 30 seconds. 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.
  • By default, the duration of a TS segment is 30 seconds. The name must be less than 256 bytes in length and can contain the {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence} variables.
  • The name must contain the {UnixTimestamp} and {Sequence} variables.
TranscodeRecordFormat.N.CycleDuration Integer No 1

The duration of the transcoded stream recording period. Unit: seconds. If you do not specify this parameter, the default value is 6 hours.

TranscodeRecordFormat.N.OssObjectPrefix String No record/{AppName}/{StreamName}/{Sequence}{EscapedStartTime}{EscapedEndTime}

The name of the transcoded stream recording that is stored in OSS.

  • The name must be less than 256 bytes in length and can contain the {AppName}, {StreamName}, {Sequence}, {StartTime}, {EndTime}, {EscapedStartTime}, and {EscapedEndTime} variables.
  • The name must contain the {StartTime} and {EndTime} variables or the {EscapedStartTime} and {EscapedEndTime} variables.
TranscodeRecordFormat.N.Format String No m3u8

The format of the transcoded stream recording. Supported formats include M3U8, FLV, and MP4. Valid values:

  • m3u8. If you set this parameter to m3u8, you must also specify the RTranscodeRecordFormat.N.SliceOssObjectPrefix and TranscodeRecordFormat.N.SliceDuration parameters.
  • flv
  • mp4
TranscodeTemplates.N String No sd
  • The transcoding template of the transcoded stream. You can configure up to 10 transcoding templates at a time.
  • If you specify the TranscodeRecordFormat.N.xxx parameters, configure at least one transcoding template.
  • If you want to record multiple or all transcoded streams, set TranscodeTemplates.1 to *.
    Note

    You cannot set the TranscodeTemplates parameter to raw, which is a reserved identifier.

    RepeatList is expressed as N in TranscodeTemplates.N, which means multiple templates are configured. Examples: TranscodeTemplates.1=sd and TranscodeTemplates.2=hd.

Response parameters

Parameter Type Example Description
RequestId String 16A96B9A-F203-4EC5-8E43-CB92E68F4CD8

The ID of the request.

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

HTTP status code Error code Error message Description
400 InvalidOssBucket.Malformed Specified parameter OssBucket is not valid. The error message returned because the OSS bucket is invalid. 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 format of the start time 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 format of the end time is invalid. Check whether the value of the EndTime parameter is valid.
400 MissingTemplate You must specify Template. The error message returned because the recording template is not specified. Make sure that the recording template is specified correctly.
400 InvalidSliceDuration.Malformed The specified format of SliceDuration is invalid. The error message returned because the specified segment duration is invalid. Check whether the value of the RecordFormat.N.SliceDuration parameter is valid.
400 InvalidTemplate.ForbidRaw Template named raw is forbidden. The error message returned because the name of the recording template is invalid. You are not allowed to configure a template named raw.
400 InvalidTemplateLength.Malformed The specified number of record template is invalid. The error message returned because the number of specified recording templates is invalid. Check whether the number of specified recording templates is correct.

For a list of error codes, see Service error codes.

Precautions

  • 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.