Record Live Streams to OSS with Multi-Format Output - ApsaraVideo Live - Alibaba Cloud - ApsaraVideo Live

Configures recording for an application and saves the output to Object Storage Service (OSS).

Operation description

Before you use this operation, make sure that you fully understand the billing methods and pricing of live stream recording. For billing details, see Live stream recording fees.
If you use the method of storing recordings in OSS to configure live stream recording, activate OSS and create a bucket. For more information, see Configure OSS.
Recordings stored in OSS incur storage fees. For billing details in OSS, see Storage fees.
The OSS bucket must be in the same region as the live center of the streaming domain. Cross-region recording is not supported.
The live stream recording feature records live content and saves it to a specified location for on-demand playback. Recordings stored in OSS support multiple container formats (TS, MP4, FLV, and CMAF) and custom recording policies (automatic recording, on-demand recording, and manual recording). Call this operation to configure recording templates. For more information about live stream recording, see Live stream recording.
The triplet (DomainName, AppName, StreamName) can correspond to only one configuration. If a configuration already exists for the triplet, calling this operation to add another configuration returns a configuration-already-exists error.
Configurations set through this operation take effect only after the live stream is re-ingested and remain effective permanently.

QPS limit

The single-user QPS limit for this operation is 30 calls per second. If this limit is exceeded, API calls are throttled, which may affect your business. Call this operation appropriately.

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 of the streamer.	example.com
AppName	string	Yes	The name of the application to which the stream belongs. The template takes effect only when the AppName value matches the AppName in the ingest URL. To match all application names, set this parameter to an asterisk (*).	liveApp****
OssEndpoint	string	Yes	The endpoint of the OSS bucket. To store live recordings in OSS, create an OSS bucket in advance. For more information, see Configure OSS.	oss-cn-beijing.aliyuncs.com
OssBucket	string	Yes	The name of the OSS bucket. To store live recordings in OSS, create an OSS bucket in advance. For more information, see Configure OSS.	liveBucket****
StreamName	string	No	The stream name. The template takes effect only when the StreamName value matches the StreamName in the ingest URL. To match all stream names under the specified AppName, set this parameter to an asterisk (*).	teststream
StartTime	string	No	The recording start time. Format: yyyy-MM-ddTHH:mm:ssZ (UTC). Note The specified time must be within 7 days of the actual stream ingest 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). Note The difference between EndTime and StartTime cannot exceed 7 days. If it exceeds 7 days, the value is calculated as 7 days. This parameter is valid only for stream-level recording (when StreamName is not empty).	2018-04-16T09:57:21Z
OnDemand	integer	No	The on-demand or manual recording mode. Valid values: 0 (default): disabled. Automatic recording is used. 1: on-demand recording through HTTP callback. You must first configure OnDemandUrl by calling the AddLiveRecordNotifyConfig operation. Otherwise, recording is not performed by default. 2: on-demand recording by parsing stream ingest parameters. 7: manual recording. Recording is not performed by default. You can call the RealTimeRecordCommand operation to manually start or stop recording.	1
DelayTime	integer	No	The stream discontinuity merging duration. If the live stream is disconnected for longer than the specified merging duration, a new file is generated. Valid values: 15 to 21600. Unit: seconds.	180
RecordFormat	array<object>	No	The recording details.
	object	No
SliceDuration	integer	No	The segment length of a single segment. Unit: seconds. Important This parameter takes effect only when RecordFormat.N.Format is set to m3u8 or cmaf. If this parameter is not specified, the default value is 30 seconds. Valid values: 5 to 30.	30
SliceOssObjectPrefix	string	No	The segment name. Important This parameter is required only when RecordFormat.N.Format is set to m3u8 or cmaf. The default segment length is 30 seconds. The value must be less than 256 bytes and supports variable matching, including {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence}. The value must contain the {UnixTimestamp} and {Sequence} variables.	record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}
CycleDuration	integer	No	The recording length per epoch. Unit: seconds. Note If this parameter is not specified, the default value varies by recording format: 6 hours for m3u8 and cmaf formats, and 1 hour for flv and mp4 formats. If a live stream is disconnected within a recording epoch but resumes stream ingest within the stream discontinuity merging duration, recording continues in the same file. This is Normal behavior. A recording file is generated only after the live stream is disconnected for longer than the stream discontinuity merging 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 value must contain {StartTime} or {EscapedStartTime} and {EndTime} or {EscapedEndTime}.	record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime}
Format	string	No	The format. M3U8, FLV, MP4, and CMAF are supported. Valid values: Important At least one of RecordFormat and TranscodeRecordFormat must be set. If you select m3u8 or cmaf, you must also set the request parameters RecordFormat.N.SliceOssObjectPrefix and RecordFormat.N.SliceDuration. m3u8. flv. mp4. cmaf. Note Settings for RecordFormat and TranscodeRecordFormat: at least one must be specified.	m3u8
TranscodeRecordFormat	array<object>	No	The transcoded stream recording details.
	object	No
SliceDuration	integer	No	The segment length of a single segment for transcoding stream recording. Unit: seconds. Important This parameter takes effect only when TranscodeRecordFormat.N.Format (transcoding stream recording format) is set to m3u8 or cmaf. If this parameter is not specified, the default value is 30 seconds. Valid values: 5 to 30.	30
SliceOssObjectPrefix	string	No	The segment name for transcoded stream recording. Important This parameter is required only when TranscodeRecordFormat.N.Format is set to m3u8 or cmaf. The default segment length is 30 seconds. The value must be less than 256 bytes and supports variable matching, including {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence}. The value must contain the {UnixTimestamp} and {Sequence} variables.	record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}
CycleDuration	integer	No	The recording length per epoch for transcoding stream recording. Unit: seconds. Note If this parameter is not specified, the default value varies by recording format: 6 hours for m3u8 and cmaf formats, and 1 hour for flv and mp4 formats.	21600
OssObjectPrefix	string	No	The name of the transcoded stream 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 value must contain {StartTime} or {EscapedStartTime} and {EndTime} or {EscapedEndTime}.	record/{AppName}/{StreamName}/{Sequence}_{EscapedStartTime}_{EscapedEndTime}
Format	string	No	The transcoding stream recording format. M3U8, FLV, MP4, and CMAF are supported. Valid values: Important If you select m3u8 or cmaf, you must also set the request parameters TranscodeRecordFormat.N.SliceOssObjectPrefix and TranscodeRecordFormat.N.SliceDuration. m3u8. flv. mp4. cmaf. Note Settings: if you select m3u8 or cmaf format, the corresponding slice parameters must also be configured.	m3u8
TranscodeTemplates	array	No	The transcoding template group for transcoded stream recording.	sd
	string	No	The transcoding templates for transcoded stream recording. You can specify up to 10 templates. When TranscodeRecordFormat.N.xxx is configured, at least one TranscodeTemplates value must be specified. To record multiple or all transcoded streams, set TranscodeTemplates.1 to ***. Note** TranscodeTemplates does not allow the value `raw`, which is a reserved identifier. RepeatList is represented by N in TranscodeTemplates.N, which can be understood as incremental settings for multiple values, such as TranscodeTemplates.1=sd and TranscodeTemplates.2=hd.	sd

Response elements

Element	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 codes

HTTP status code	Error code	Error message	Description
400	InvalidOssEndpoint.Malformed	%s
400	InvalidOssBucket.Malformed	Specified parameter OssBucket is not valid.	The OSSBucket parameter is invalid. Verify that the OSS BUCKET parameter is correct.
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.	Missing transcoding template parameter configuration.
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.	The SliceOssObjectPrefix parameter is invalid. Verify that the SliceOssObjectPrefix parameter is correct.
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.