AddLiveAppRecordConfig - ApsaraVideo Live - Alibaba Cloud Documentation Center

Configures application recording to save output content to OSS.

Operation description

Before using this operation, ensure that you understand the billing methods and pricing of live recording. For billing details, see Live recording fees.
If you configure live recording to store recordings in OSS, you need to activate OSS and create a bucket. For more information, see Configure OSS.
Recording files stored in OSS incur storage fees. For OSS billing details, see Storage fees.
The live recording feature lets you record live content and save it to a specified location for later playback. Recordings stored in OSS support multiple formats (TS, MP4, FLV, CMAF) and custom recording policies (automatic recording, on-demand recording, manual recording). You can call this operation to configure recording templates. For more information about live recording, see the Live recording documentation.
A (DomainName, AppName, StreamName) trituple can only correspond to one configuration. If a configuration already exists for the trituple, calling this operation to add another configuration will return an error indicating that the configuration already exists.
The configurations set through this operation take effect only after the live stream is restarted and remain effective for a long time.

QPS limits

The QPS limit for this operation is 30 queries per second per user. If the limit is exceeded, API calls will be throttled, which may affect your business. Please call the operation properly.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that support authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

live:AddLiveAppRecordConfig

create

*Domain

acs:cdn:*:{#accountId}:domain/{#DomainName}

None

Request parameters

Parameter	Type	Required	Description	Example
DomainName	string	Yes	The streaming domain.	example.com
AppName	string	Yes	The name of the application to which the stream belongs. The template takes effect only when the AppName matches the AppName in the ingest URL. If you do not want to limit the AppName, you can enter *, which matches all AppNames.	liveApp****
OssEndpoint	string	Yes	The OSS storage endpoint name. To store live recording files in OSS, you must create an OSS bucket in advance. For information about how to create a bucket, see Configure OSS.	learn.developer.aliyundoc.com
OssBucket	string	Yes	The OSS storage bucket name. To store live recording files in OSS, you must create an OSS bucket in advance. For information about how to create a bucket, see Configure OSS.	liveBucket****
StreamName	string	No	The stream name. The template takes effect only when the StreamName matches the StreamName in the ingest URL. If you do not want to limit the StreamName, you can enter *, which matches all StreamNames under the AppName.	teststream
StartTime	string	No	The recording start time. Format: yyyy-MM-ddTHH:mm:ssZ (UTC time). Note The specified time must be within 7 days from the actual stream start time. This parameter is valid only for stream-level recording (when StreamName is not empty).	2018-04-10T09:57:21Z
EndTime	string	No	The 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 exceeds 7 days, the system will calculate based on 7 days. This parameter is valid only for stream-level recording (when StreamName is not empty).	2018-04-16T09:57:21Z
OnDemand	integer	No	On-demand/manual recording. Valid values: 0 (default): Disabled, which means automatic recording. 1: On-demand recording via HTTP callback. You need to configure OnDemandUrl through the AddLiveRecordNotifyConfig operation first, otherwise recording is disabled by default. 2: On-demand recording by parsing stream parameters. 7: Manual recording, disabled by default. You can manually control recording start or stop through the RealTimeRecordCommand operation.	1
DelayTime	integer	No	The stream interruption concatenation duration. When a live stream is interrupted for longer than the specified concatenation duration, a new file will be generated. The stream interruption concatenation duration supports 15 to 21600 seconds.	180
RecordFormat	array	No	The recording details.
	object	No
SliceDuration	integer	No	The duration of a single segment. Unit: seconds. Important This parameter takes effect only when RecordFormat.N.Format is set to m3u8 or cmaf. If not specified, the default value is 30 seconds. Valid values: 5s to 30s.	30
SliceOssObjectPrefix	string	No	The segment name. Important This parameter needs to be configured only when RecordFormat.N.Format is set to m3u8 or cmaf. By default, each segment is 30 seconds long and less than 256 bytes. The parameter supports variable matching, including {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence}. The parameter value must include the {UnixTimestamp} and {Sequence} variables.	record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}
CycleDuration	integer	No	The cycle recording duration. Unit: seconds. Note If not specified, the default value is used. Different recording formats have different default values: m3u8 and cmaf formats default to 6 hours, while flv and mp4 formats default to 1 hour. If a live stream is interrupted during a recording cycle but resumes normal streaming within the stream interruption concatenation duration, recording will continue in the same recording file. A recording file is generated only when a live stream is interrupted for longer than the stream interruption concatenation duration.	1
OssObjectPrefix	string	No	The name of the recording file stored in OSS. The file name must be less than 256 bytes and supports variable matching, including {AppName}, {StreamName}, {Sequence}, {StartTime}, {EndTime}, {EscapedStartTime}, and {EscapedEndTime}. The parameter value must include {StartTime} or {EscapedStartTime} and {EndTime} or {EscapedEndTime}.	record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime}
Format	string	No	The format. Currently, M3U8, FLV, MP4, and CMAF are supported. Valid values: Important At least one of RecordFormat and TranscodeRecordFormat must be set. If you select the m3u8 or cmaf format, you must also set the RecordFormat.N.SliceOssObjectPrefix and RecordFormat.N.SliceDuration request parameters. m3u8. flv. mp4. cmaf.	m3u8
TranscodeRecordFormat	array	No	The transcoding recording details.
	object	No
SliceDuration	integer	No	The duration of a single segment for transcoded stream recording. Unit: seconds. Important This parameter takes effect only when TranscodeRecordFormat.N.Format is set to m3u8 or cmaf. If not specified, the default value is 30 seconds. Valid values: 5s to 30s.	30
SliceOssObjectPrefix	string	No	The segment name for transcoded stream recording. Important This parameter needs to be configured only when TranscodeRecordFormat.N.Format is set to m3u8 or cmaf. By default, each segment is 30 seconds long and less than 256 bytes. The parameter supports variable matching, including {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence}. The parameter value must include the {UnixTimestamp} and {Sequence} variables.	record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}
CycleDuration	integer	No	The cycle recording duration for transcoded stream recording. Unit: seconds. Note If not specified, the default value is used. Different recording formats have different default values: m3u8 and cmaf formats default to 6 hours, while flv and mp4 formats default to 1 hour.	21600
OssObjectPrefix	string	No	The name of the recording file stored in OSS for transcoded stream recording. The file name must be less than 256 bytes and supports variable matching, including {AppName}, {StreamName}, {Sequence}, {StartTime}, {EndTime}, {EscapedStartTime}, and {EscapedEndTime}. The parameter value must include {StartTime} or {EscapedStartTime} and {EndTime} or {EscapedEndTime}.	record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime}
Format	string	No	The format for transcoded stream recording. Currently, M3U8, FLV, MP4, and CMAF are supported. Valid values: Important If you select the m3u8 or cmaf format, you must also set the TranscodeRecordFormat.N.SliceOssObjectPrefix and TranscodeRecordFormat.N.SliceDuration request parameters. m3u8. flv. mp4. cmaf.	m3u8
TranscodeTemplates	array	No	The transcoding template group for transcoded stream recording.	sd
	string	No	The transcoding template for transcoded stream recording. You can configure multiple templates, up to 10. When setting TranscodeRecordFormat.N.xxx configurations, you need to set at least one TranscodeTemplates. To record multiple or all transcoded streams, you can set TranscodeTemplates.1 to *** (five asterisks). Note** TranscodeTemplates is not allowed to pass in `raw`, which is a reserved identifier. RepeatList refers to N in TranscodeTemplates.N, which can be understood as incrementing for multiple settings, such as: TranscodeTemplates.1=sd, TranscodeTemplates.2=hd.	sd

Response parameters

Parameter	Type	Description	Example
	object
RequestId	string	The request ID.	16A96B9A-F203-4EC5-8E43-CB92E68F****

Examples

Success response

JSON format

{
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F****"
}

Error response

JSON format

{
    "Code":"InternalError",
    "HostId":"live.aliyuncs.com",
    "Message":"The request processing has failed due to some unknown error.",
    "RequestId":"6EBD1AC4-C34D-4AE1-963E-B688A228BE31"
}

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.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.