All Products
Search

This Product

    ApsaraVideo Live:AddLiveAppRecordConfig

    Document Center

    ApsaraVideo Live:AddLiveAppRecordConfig

    Last Updated:Sep 20, 2024

    Adds a recording configuration for an application. The recordings are stored in Object Storage Service (OSS).

    Usage notes

    The live stream recording feature allows you to record a live stream and stores the recordings in a specified location. You can view the recordings whenever you want to. Recordings that are stored in OSS support multiple formats, such as Transport Stream (TS), MP4, Flash Video (FLV), and Common Media Application Format (CMAF). You can use different recording policies, including automatic recording, on-demand recording, and manual recording. By calling this operation, you can configure the recording template. For more information about live stream recording, see Live stream recording.

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

    Debugging

    OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically 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 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

    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 need to 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 threshold.

    If the stream interruption duration exceeds the threshold, a new recording is generated. The value of this parameter ranges from 15 to 21600 seconds.

    RecordFormat.N.SliceDuration Integer No 30

    The duration of a single segment. Unit: seconds.

    Important This parameter takes effect only if you set the RecordFormat.N.Format parameter to m3u8 or cmaf.

    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 naming format of a segment.

    Important This parameter is required only if you set the RecordFormat.N.Format parameter to m3u8 or cmaf.
    • By default, the duration of a segment is 30 seconds. The segment name must be less than 256 bytes in length and can contain the {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence} variables.
    • The segment name must contain the {UnixTimestamp} and {Sequence} variables.
    RecordFormat.N.CycleDuration Integer No 1

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

    Note
    • If a live stream is interrupted during a recording cycle 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, 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 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. If you set this parameter to m3u8 or cmaf, you must also specify the RecordFormat.N.SliceOssObjectPrefix and RecordFormat.N.SliceDuration parameters.
    • m3u8
    • flv
    • mp4
    • cmaf
    TranscodeRecordFormat.N.SliceDuration Integer No 30

    The duration of a single segment in the transcoded stream recording. Unit: seconds.

    Important This parameter takes effect only if you set the TranscodeRecordFormat.N.Format parameter to m3u8 or cmaf.

    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 naming format of a segment in the transcoded stream recording.

    Important This parameter is required only if you set the TranscodeRecordFormat.N.Format parameter to m3u8 or cmaf.
    • By default, the duration of a segment is 30 seconds. The segment name must be less than 256 bytes in length and can contain the {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence} variables.
    • The segment name must contain the {UnixTimestamp} and {Sequence} variables.
    TranscodeRecordFormat.N.CycleDuration Integer No 21600

    The transcoded stream recording cycle. 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.

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

    Important If you set this parameter to m3u8 or cmaf, you must also specify the TranscodeRecordFormat.N.SliceOssObjectPrefix and TranscodeRecordFormat.N.SliceDuration parameters.
    • m3u8
    • flv
    • mp4
    • cmaf
    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 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

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidOssBucket.Malformed Specified parameter OssBucket is not valid. The OSS bucket is malformed. Check whether the value of the OssBucket parameter is valid.
    400 InvalidOssBucket.NotFound The parameter OssBucket does not exist. 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 recording format is invalid. Check whether the value of the Format parameter is valid.
    400 InvalidCycleDuration.Malformed Specified CycleDuration Format is not valid. The format of the recording cycle is invalid. Check whether the value of the CycleDuration parameter is valid.
    400 MissingOssObjectPrefix OssObjectPrefix is mandatory for this action. The name of the recording is not specified. Check whether the value of the OssObjectPrefix parameter is valid.
    400 InvalidOssObjectPrefix.Malformed Specified parameter OssObjectPrefix is not valid. The name of the recording is invalid. Check whether the value of the OssObjectPrefix parameter is valid.
    400 InvalidSliceOssObjectPrefix.Malformed Specified parameter SliceOssObjectPrefix is not valid. The segment name is invalid. Check whether the value of the SliceOssObjectPrefix parameter is valid.
    400 ConfigAlreadyExists Config has already exist. The configuration already exists.
    400 InvalidStartTime.Malformed Specified StartTime is malformed. 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 format of the end time is invalid. Check whether the value of the EndTime parameter is valid.

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

    Considerations

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