AddLiveAppRecordConfig - ApsaraVideo Live - Alibaba Cloud Documentation Center

Configures live recording settings and saves the output to Object Storage Service (OSS).

Operation description

Before using this API, ensure that you understand the billing methods and pricing of live recording. For details, see Billing of live recording.
To save recordings to OSS, you must first activate the OSS service and create a bucket. For instructions, see Record and store in OSS.
Storing recorded files in OSS incurs storage fees, which are billed separately. For details, see Storage fees.
The live recording feature allows you to record live streams and save them to a specified location for later playback. When saving to OSS, multiple formats (TS, MP4, FLV, CMAF) and recording strategies (automatic, on-demand, manual) are supported. Use this API to configure a recording template. For more information, see Live recording.
A unique recording configuration is identified by the triplet (DomainName, AppName, StreamName). Calling this API for a triplet that already has a configuration will result in an error indicating that the configuration already exists.
Configurations set using this API take effect only after the stream is reingested. Once active, the configuration remains effective indefinitely.

QPS limits

You can call this operation up to 30 times per second per account. Requests that exceed this limit are dropped and you may experience service interruptions.

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 supports 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 AppName of the live stream. The template only applies if this name matches the `AppName` in the ingest URL. Use an asterisk (`*`) to match all AppNames.	liveApp****
OssEndpoint	string	Yes	The endpoint for OSS storage. You must create an OSS bucket before using this feature. See Configure OSS.	learn.developer.aliyundoc.com
OssBucket	string	Yes	The name of the OSS bucket for storage.	liveBucket****
StreamName	string	No	The stream name. The template only applies if this name matches the StreamName in the ingest URL. Use an asterisk (`*`) to match all streams under the AppName.	teststream
StartTime	string	No	The recording start time. Format: yyyy-MM-ddTHH:mm:ssZ (UTC time). Note This parameter is only effective for stream-level recordings (i.e., when `StreamName` is specified). The time must be within 7 days of the actual stream start time.	2018-04-10T09:57:21Z
EndTime	string	No	The recording end time. Format: yyyy-MM-ddTHH:mm:ssZ (UTC time). Note This parameter is only effective for stream-level recordings. The interval between EndTime and StartTime cannot exceed 7 days.	2018-04-16T09:57:21Z
OnDemand	integer	No	Specifies the recording mode. Valid values: 0 (default): 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 parameters in the ingest URL. 7: Manual recording, disabled by default. You can manually start o. stop recording through the RealTimeRecordCommand API.	1
DelayTime	integer	No	The window in seconds for merging fragmented recording after an interruption. If a stream disconnects and reconnects within this window, the recording will continue in the same file. Valid values: 15 to 21600.	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 naming pattern for segments. Important This parameter takes effect only when RecordFormat.N.Format is set to m3u8 or cmaf. By default, each segment is 30 seconds long and less than 256 bytes. Supports variables: {AppName}, {StreamName}, {UnixTimestamp}, {Sequence}. The value must include the {UnixTimestamp} and {Sequence} variables.	record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}
CycleDuration	integer	No	The duration of a single recording cycle in 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 merge window, recording will continue in the same file. A recording file is generated only when a live stream is interrupted for longer than the merge window.	1
OssObjectPrefix	string	No	The naming pattern for the recording file stored in OSS. The file name must be less than 256 bytes. Supports variables: {AppName}, {StreamName}, {Sequence}, {StartTime}, {EndTime}, {EscapedStartTime}, {EscapedEndTime}. The value must include either {StartTime} or {EscapedStartTime} and either {EndTime} or {EscapedEndTime}.	record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime}
Format	string	No	The recording format. Valid values: Important If you choose m3u8 or cmaf, you must also set SliceOssObjectPrefix and SliceDuration. 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 naming pattern for segments of the transcoded stream. Important This parameter is required only when TranscodeRecordFormat.N.Format is set to m3u8 or cmaf. By default, each segment is 30 seconds long. The file name must be less than 256 bytes. Supports variables: {AppName}, {StreamName}, {UnixTimestamp}, {Sequence}. The value must include the {UnixTimestamp} and {Sequence} variables.	record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}
CycleDuration	integer	No	The duration of a single recording cycle in 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 maning pattern of the recording file stored in OSS for transcoded stream. The file name must be less than 256 bytes. Supports variables: {AppName}, {StreamName}, {Sequence}, {StartTime}, {EndTime}, {EscapedStartTime}, {EscapedEndTime}. The value must include either {StartTime} or {EscapedStartTime} and either {EndTime} or {EscapedEndTime}.	record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime}
Format	string	No	The format for transcoded stream recording. 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.	sd
	string	No	The transcoding template. 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. The .N in TranscodeTemplates.N represents an incremental index for specifying multiple templates. For example: TranscodeTemplates.1=sd, TranscodeTemplates.2=hd.	sd

Response elements

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.