How do I record live streams? - ApsaraVideo Live - Alibaba Cloud Documentation Center

ApsaraVideo Live provides the live stream recording feature that allows you to record live streams in real time and play historical streams. This topic describes the live stream recording feature in detail.

Overview

ApsaraVideo Live uses streaming URLs to play streams that are ingested by the stream ingest client in real time. If you want to play or modify the content of a live stream after the live stream ends, you can use the live stream recording feature.

The live stream recording feature is used to record the ingested streams that are received by a live center and store the recordings in a specific storage location. ApsaraVideo Live allows you to store the recordings of a live stream in ApsaraVideo VOD or Object Storage Service (OSS).

How live stream recording works

The live stream recording feature pulls the streams that you ingest, encapsulates the audio and video data into a number of separate media segments in the Transport Stream (TS) format, and then stores the TS segments. The live stream recording feature complies with the following principles:

The live stream recording feature only converts the container format of audio and video data from Real-Time Messaging Protocol (RTMP) or Flash Video (FLV) to TS. The feature does not modify the audio and video content at the coding layer. For example, if the live stream that you ingest is blurry, the recording is also blurry.
The live stream recording feature can write recordings to the storage location that you specify. However, the feature cannot modify or delete the task files from the storage location, including the stored recordings. You can manage the recordings in your storage location.

Storage method comparison

You can store the recordings of a live stream in ApsaraVideo VOD or OSS. The storage methods are used in different scenarios. You can select a storage method based on your business requirements.

Storage method	Associated service	Container format	Applicable scenario
ApsaraVideo VOD	ApsaraVideo VOD	TS/M3U8	You want to repurpose your recordings or focus on the post-production process of recordings, such as editing, playback, and video thumbnail creation.
OSS	OSS	TS/M3U8 MP4 FLV CMAF Note Regardless of the container format, the live stream recording feature first slices a live stream into a number of TS segments and then composes them to generate a recording in the specified container format.	You want to focus on the management and storage of recordings.

Note

You cannot store the recordings of a live stream in both ApsaraVideo VOD and OSS.

Limits

Audio and video encoding formats

ApsaraVideo Live needs to slice live streams into TS segments first. Therefore, the audio and video encoding formats of the live streams that you ingest must meet the requirements of the TS format. Based on the FLV and ISO/IEC 13818-1 standards, the live stream recording feature supports the following encoding formats:

Video: H.264, High Efficiency Video Coding (HEVC), and MPEG-4
Audio: Advanced Audio Coding (AAC) and MP3

Note

If the live streams contain audio and video data that is encoded in unsupported formats, unexpected exceptions, such as recording failures, black screen issues, and recordings without sound, may occur in the recording process.

Abnormal live streams

The live stream recording feature can generate recordings for normal live streams. Normal live streams refer to streams that are encoded in the supported formats and have stable frame rates and monotonically and linearly increasing timestamps. If the frame rate of a live stream is occasionally unstable or a few specific timestamps of the live stream jump, the feature can also generate recordings for the live stream due to its wide compatibility. However, if a serious exception is detected on an ingested live stream, the feature may fail to generate recordings for the ingested live stream. Serious exceptions include no video frame detected for a long period of time, irregularly increased timestamps, and missing audio and video headers.

Store recordings in ApsaraVideo VOD

Prerequisites

ApsaraVideo VOD is activated and a VOD bucket is enabled. For more information, see Activate ApsaraVideo VOD and Enable VOD buckets.

Important

If you store recordings in ApsaraVideo VOD, storage fees are generated. For more information, see Media storage.
When you enable the VOD bucket, make sure that the VOD bucket resides in the same region as the live center of the streaming domain.
You cannot configure the Live-to-VOD feature by using a Finance Cloud account.

Configure recording settings

After the prerequisites are met, you can configure the required settings to store recordings in ApsaraVideo VOD.

ApsaraVideo Live provides the following configuration methods to store recordings in ApsaraVideo VOD:

Use the ApsaraVideo Live console

Log on to the ApsaraVideo Live console.
In the left-side navigation pane, choose Feature Management > Recording. On the Recording page, click the VOD tab.
Select the streaming domain that you want to configure.
Click Add.

Configure the recording template.

The following table describes the parameters of a recording template.

Parameter	Description
AppName	The name of the application. The value of the AppName parameter must be the same as the application name specified in the ingest URL. Otherwise, the configuration does not take effect. If you want to record live streams in all applications under your domain name, enter an asterisk (*).
StreamName	You can store the recordings of a specific live stream in ApsaraVideo VOD by specifying the stream name. If you want to record all live streams in the application that is specified by the AppName parameter, enter an asterisk (). Note* The value of the AppName or StreamName parameter can be up to 255 characters in length and can contain letters, digits, hyphens (-), and underscores (_).
Storage Location	The storage location.
Recording Cycle	The recording cycle can range from 15 to 360 minutes. If the specified recording cycle is exceeded, the system generates a new recording based on the recording naming rule. By default, the length of a TS segment is 30 seconds. Note The recording cycle specifies the maximum length of a VOD file that is converted from the specified live stream.
Transcoding Settings	Select a storage transcoding rule from the drop-down list. You can transcode the recorded videos in ApsaraVideo VOD. The storage transcoding rule is used to convert the recorded videos to VOD files for transmission. You can transcode the recorded videos to videos of different resolutions or retain the original quality without transcoding. For more information about transcoding templates in ApsaraVideo VOD, see Transcoding templates. Note The region of the transcoding template that you use in ApsaraVideo VOD must be the same as the region of your domain name. For example, if your domain name resides in the China (Shanghai) region, the transcoding template that you use in ApsaraVideo VOD must also reside in the China (Shanghai) region.
Auto Merge	After you enable this feature, recordings of multiple recording cycles can be automatically merged into one recording and stored in ApsaraVideo VOD. Note After you enable auto merge of recordings of multiple cycles, the editing and production feature and the transcoding feature of ApsaraVideo VOD will be used. For more information about the billing of the features, see Billing of editing and production and Billing of media transcoding.
Transcoding Settings of Merged Video	Select a transcoding template from the drop-down list, which is obtained from ApsaraVideo VOD. The system performs transcoding on the merged video based on the settings of the transcoding template. For more information about a transcoding template for auto merge, see Transcoding templates. Note The region of the transcoding template that you use in ApsaraVideo VOD must be the same as the region of your domain name. For example, if your domain name resides in the China (Shanghai) region, the transcoding template that you use in ApsaraVideo VOD must also reside in the China (Shanghai) region.

Click OK.

Call an API operation

Java

// Replace the content in <> with actual values.
DefaultProfile profile = DefaultProfile.getProfile("<regionId>", "<ALIBABA_CLOUD_ACCESS_KEY_ID>", "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>");
IAcsClient client = new DefaultAcsClient(profile);   
AddLiveRecordVodConfigRequest addLiveRecordVodConfigRequest=new AddLiveRecordVodConfigRequest();
addLiveRecordVodConfigRequest.setDomainName("<DomainName>");
addLiveRecordVodConfigRequest.setAppName("<AppName>");
addLiveRecordVodConfigRequest.setStreamName("<StreamName>");
addLiveRecordVodConfigRequest.setVodTranscodeGroupId("VOD_NO_TRANSCODE");
// The address of the VOD bucket.
addLiveRecordVodConfigRequest.setStorageLocation("<StorageLocation>");
AddLiveRecordVodConfigResponse dddLiveRecordVodConfigResponse = null;
try {
    dddLiveRecordVodConfigResponse = client.getAcsResponse(addLiveRecordVodConfigRequest);
} catch (ClientException e) {
    e.printStackTrace();
}
 System.out.println(new Gson().toJson(dddLiveRecordVodConfigResponse));

Note

In the preceding sample code, a Live-to-VOD configuration is added for a domain name, which stores the recordings of a live stream in ApsaraVideo VOD. <DomainName> specifies the domain name, <AppName> specifies the application name, and <StreamName> specifies the stream name. VOD_NO_TRANSCODE specifies that recordings are not transcoded. <StorageLocation> specifies the address of the VOD bucket.
You can set the AppName or StreamName parameter to an asterisk (*) to match all applications or streams.
You can configure multiple rules. The rules take effect based on priorities:
- A rule in which the AppName and StreamName parameters are not set to asterisks (*) has the highest priority.
- A rule in which the AppName parameter is not set to an asterisk (*) but the StreamName parameter is set to an asterisk (*) has the second priority.
- A rule in which the AppName parameter is set to an asterisk (*) has the lowest priority. In this case, only the domain name must be specified.
For more information about the parameters, see AddLiveRecordVodConfig.

Important

For an ongoing live stream, the configured recording settings take effect only after you re-ingest the stream.
If a live stream is interrupted for 180 seconds, a recording is generated for the live stream.

Transcode recordings

Recordings that are stored in ApsaraVideo VOD are in the M3U8 format. If you want to store the recordings in another format, you can configure transcoding. The following sample code provides an example on how to configure transcoding:

Java

 addLiveRecordVodConfigRequest.setVodTranscodeGroupId("<TranscodeGroupId>");

Note

You must configure the transcoding template group in ApsaraVideo VOD. For more information, see Transcoding templates.
<TranscodeGroupId> specifies the ID of the transcoding template group in ApsaraVideo VOD.
After you configure transcoding, the recordings are transcoded and the corresponding transcoded stream URLs are generated. The original recordings are retained.

Merge recordings

Recordings can be merged in the following scenarios:

If a live stream is interrupted but is re-ingested within 180 seconds, the recordings that are generated before and after the interruption are automatically merged into one recording.
If the duration of a live stream exceeds the recording cycle, the recordings that are generated before and after the recording cycle can be merged. After the duration of a live stream exceeds the recording cycle, a new recording is generated. For example, if the recording cycle is 5 minutes and the stream ingest duration is 8 minutes, two recordings are generated for the live stream.
If you want to merge the recordings of different recording cycles, you can configure the merging settings.
Important
After you enable auto merge of recordings of multiple cycles, the editing and production feature and the transcoding feature of ApsaraVideo VOD will be used. For more information, see Billing of value-added services and Billing of basic services.
The following sample code provides an example on how to merge recordings:
Java
```
addLiveRecordVodConfigRequest.setAutoCompose("ON");
addLiveRecordVodConfigRequest.setComposeVodTranscodeGroupId("<TranscodeGroupId>");
```
Note
- Multiple recordings are merged into a new recording. The original recordings are retained.
- You must configure the transcoding template group in ApsaraVideo VOD. For more information, see Transcoding templates.
- <TranscodeGroupId> specifies the ID of the transcoding template group in ApsaraVideo VOD.
The following sample code provides an example on how to configure the recording cycle:
Java
```
// Valid values: 300 to 21600. Default value: 900. Unit: seconds.
addLiveRecordVodConfigRequest.setCycleDuration(<300>);
```

Manage recordings

You can view recordings that are stored in ApsaraVideo VOD in the ApsaraVideo Live console. To manage the recordings, use the ApsaraVideo VOD service. For more information, see Media asset management.

View the recordings in the ApsaraVideo Live console

Log on to the ApsaraVideo Live console.
In the left-side navigation pane, choose Feature Management > Recording. On the Recording page, click the Recordings tab.
Select the streaming domain.
On the VOD tab, view the recordings.

Store recordings in OSS

Prerequisites

OSS is activated and an OSS bucket is created. For more information, see Configure OSS.

Important

If you store recordings in OSS, storage fees are generated. For more information, see Storage fees.
The OSS bucket must reside in the same region as the live center of the streaming domain.

Configure recording settings

After the prerequisites are met, you can configure the required settings to store recordings in OSS.

ApsaraVideo Live provides the following configuration methods to store recordings in OSS:

Use the ApsaraVideo Live console

Log on to the ApsaraVideo Live console.
In the left-side navigation pane, choose Feature Management > Recording. On the Recording page, click the OSS tab.
Select the streaming domain that you want to configure.
Click Add.

Configure the recording template.

Table 1. Recording template parameters

Parameter	Description
AppName	The name of the application. The value of the AppName parameter must be the same as the application name specified in the ingest URL. Otherwise, the configuration does not take effect. If you want to record live streams in all applications under your domain name, enter an asterisk (*).
StreamName	You can store the recordings of a specific live stream in OSS by specifying the stream name. If you want to record all live streams in the application that is specified by the AppName parameter, enter an asterisk (). Note* The value of the AppName or StreamName parameter can be up to 255 characters in length and can contain letters, digits, hyphens (-), and underscores (_). Take note of the following points if you enter an asterisk () as the value of the AppName* or StreamName parameter: An asterisk () cannot match any strings, but can match only the names of existing applications or streams. An asterisk () cannot be used as a wildcard character.
Storage Location	The storage location. Note Buckets include standard buckets and media buckets. Standard buckets are OSS buckets that are used for storage. Media buckets are buckets that are customized for ApsaraVideo Media Processing. You can use ApsaraVideo Media Processing to transcode videos that are stored in media buckets. Standard buckets and media buckets are not distinguished in the bucket list. If you want to process input videos in ApsaraVideo Media Processing, you must remember the name of the media bucket that you use so that you can select the media bucket to store output videos.
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.
Storage Format	Valid values: flv, m3u8, mp4, and cmaf. Note Select at least one storage format. You cannot select the CMAF and M3U8 formats at the same time.
Naming Conventions	The naming conventions for the storage paths of recordings in different formats. Default values: M3U8: record/{AppName}/{StreamName}/{EscapedStartTime }_{EscapedEndTime } TS: record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence} FMP4: record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence} MP4: record/{AppName}/{StreamName}/{EscapedStartTime }_{EscapedEndTime } FLV: record/{AppName}/{StreamName}/{EscapedStartTime }_{EscapedEndTime } Example: If you set AppName to liveApp** and StreamName to liveStream, the storage path of recordings in the M3U8 format is record/liveApp/liveStream**/{EscapedStartTime}_{EscapedEndTime }.
TS File Duration	The duration of a TS segment. Default value: 30. Valid values: 5 to 30. Unit: seconds.
Recording Cycle	The recording cycle can range from 15 to 360 minutes. If the specified recording cycle is exceeded, the system generates a new recording based on the recording naming rule. Note The recording cycle specifies the maximum length of a VOD file that is converted from the specified live stream.

Table 2. Parameters for transcoded stream recording

Parameter	Description
Transcoded Stream Recording	Turn on Transcoded Stream Recording and configure the following parameters.
Storage Format	Valid values: flv, m3u8, mp4, and cmaf. Note Select at least one storage format. You cannot select the CMAF and M3U8 formats at the same time.
Naming Conventions	The naming conventions for the storage paths of recordings in different formats. Default values: M3U8: transcodeRecord/{AppName}/{StreamName}/{EscapedStartTime }_{EscapedEndTime } TS: transcodeRecord/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence} FMP4: transcodeRecord/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence} MP4: transcodeRecord/{AppName}/{StreamName}/{EscapedStartTime }_{EscapedEndTime } FLV: transcodeRecord/{AppName}/{StreamName}/{EscapedStartTime }_{EscapedEndTime } Example: If you set AppName to liveApp**, StreamName to liveStream, and Transcoding Template ID to lld, the storage path of transcoded stream recordings in the M3U8 format is transcodeRecord/liveApp/liveStream**_lld/{EscapedStartTime}_{EscapedEndTime }.
TS File Duration	The duration of a TS segment. Default value: 30. Valid values: 5 to 30. Unit: seconds.
Recording Cycle	The recording cycle can range from 15 to 360 minutes. If the specified recording cycle is exceeded, the system generates a new recording based on the recording naming rule. Note The recording cycle specifies the maximum length of a VOD file that is converted from the specified live stream.
Transcoding Template ID	You can select All Templates or up to 10 individual transcoding templates. Make sure that the application name in the transcoding template is the same as the application name in the recording template. If no transcoding template is available, add a transcoding template first. For more information, see Configure default transcoding.

Click OK.

Call an API operation

Java

        // Replace the content in <> with actual values.
        DefaultProfile profile = DefaultProfile.getProfile("<regionId>", "<ALIBABA_CLOUD_ACCESS_KEY_ID>", "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>");
        IAcsClient client = new DefaultAcsClient(profile);   
        AddLiveAppRecordConfigRequest addLiveAppRecordConfigRequest=new AddLiveAppRecordConfigRequest();
        addLiveAppRecordConfigRequest.setAppName("<AppName>");
        addLiveAppRecordConfigRequest.setStreamName("<StreamName>");
        addLiveAppRecordConfigRequest.setDomainName("<DomainName>");
        addLiveAppRecordConfigRequest.setOssEndpoint("<OssEndpoint>");
        addLiveAppRecordConfigRequest.setOssBucket("<OssBucket>");
        List<AddLiveAppRecordConfigRequest.RecordFormat> formatList=new ArrayList<AddLiveAppRecordConfigRequest.RecordFormat>();
        AddLiveAppRecordConfigRequest.RecordFormat m3u8Format=new AddLiveAppRecordConfigRequest.RecordFormat();
        m3u8Format.setFormat("m3u8");
        // The naming format of a recording to store in OSS.
        m3u8Format.setOssObjectPrefix("<record/{AppName}/{StreamName}/{EscapedStartTime}_{EscapedEndTime}>");
        // The naming format of a segment.
        m3u8Format.setSliceOssObjectPrefix("<record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}>");
        formatList.add(m3u8Format);
        addLiveAppRecordConfigRequest.setRecordFormats(formatList);
        AddLiveAppRecordConfigResponse addLiveAppRecordConfigResponse = null;
        try {
            addLiveAppRecordConfigResponse = client.getAcsResponse(addLiveAppRecordConfigRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        System.out.println(new Gson().toJson(addLiveAppRecordConfigResponse));

Note

In the preceding sample code, a recording configuration is added for a domain name, which stores the recordings of a live stream in an OSS bucket. <DomainName> specifies the domain name, <AppName> specifies the application name, <StreamName> specifies the stream name, and <OssBucket> specifies the name of the OSS bucket. The recordings are in the M3U8 format.
The value of the OssObjectPrefix or SliceOssObjectPrefix parameter cannot exceed 255 characters in length after the variables are matched. For more information, see AddLiveAppRecordConfig.
You can obtain the value of the <OssEndpoint> parameter based on the region of the OSS bucket that is specified by the <OssBucket> parameter. For more information, see Regions, endpoints and open ports.
You can set the AppName or StreamName parameter to an asterisk (*) to match all applications or streams.
You can configure multiple rules. The rules take effect based on priorities:
- A rule in which the AppName and StreamName parameters are not set to asterisks (*) has the highest priority.
- A rule in which the AppName parameter is not set to an asterisk (*) but the StreamName parameter is set to an asterisk (*) has the second priority.
- A rule in which the AppName parameter is set to an asterisk (*) has the lowest priority. In this case, only the domain name must be specified.

Important

For an ongoing live stream, the configured recording settings take effect only after you re-ingest the stream.
After a live stream is interrupted for 180 seconds, a recording is generated for the live stream. You can specify the interruption duration threshold. For more information, see the description about the Interruption Duration Threshold parameter.

Record transcoded streams

By recording transcoded streams, you can adjust the video bitrate, increase the video compression rate, and reduce the size of recordings, without affecting the video quality. OSS allows you to store the original and transcoded streams. You can also store only the original or transcoded streams.

Important

When you use the live stream transcoding feature, you are charged based on the transcoding standard, resolution, and total length of transcoded streams. For more information, see Billing of live stream transcoding.

Sample code for recording transcoded streams

Java

        // Replace the content in <> with actual values.        
        List<AddLiveAppRecordConfigRequest.TranscodeRecordFormat> transcodeFormatList=new ArrayList<AddLiveAppRecordConfigRequest.TranscodeRecordFormat>();
        AddLiveAppRecordConfigRequest.TranscodeRecordFormat m3u8TranscodeFormat=new AddLiveAppRecordConfigRequest.TranscodeRecordFormat();
        m3u8TranscodeFormat.setFormat("m3u8");
        // The naming format of a transcoded stream recording to store in OSS.
        m3u8TranscodeFormat.setOssObjectPrefix("<transcodeRecord/{AppName}/{StreamName}/{EscapedStartTime}_{EscapedEndTime}>");
        // The naming format of a segment in a transcoded stream recording.
        m3u8TranscodeFormat.setSliceOssObjectPrefix("<transcodeRecord/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}>");
        transcodeFormatList.add(m3u8TranscodeFormat);
        addLiveAppRecordConfigRequest.setTranscodeRecordFormats(transcodeFormatList);
        List<String> transcodeTemplateList=new ArrayList<String>();
        // The ID of the transcoding template.
        transcodeTemplateList.add("<lld>");
        addLiveAppRecordConfigRequest.setTranscodeTemplatess(transcodeTemplateList);

Note

If you want to record only transcoded streams, you do not need to configure setRecordFormats, which is used to configure settings for original streams.
If you configure setTranscodecordFormats, you must also configure setTranscodeTemplatess to specify the ID of a configured transcoding template. For more information, see Live stream transcoding.
In the configured transcoding template, transcoding must be set to be triggered by stream ingest.
In the name of a transcoded stream recording, the StreamName field is changed to StreamName_Transcoding template ID.

Configure the interruption duration threshold

If a live stream is interrupted but is re-ingested within the interruption duration threshold, the recordings that are generated before and after the interruption are automatically merged into one recording. By default, the interruption duration threshold is 180 seconds.

Note

A new recording is generated only after the interruption duration threshold elapses.

You can configure the interruption duration threshold based on your business requirements. Sample code:

Java

// Valid values: 15 to 21600. Unit: seconds.
addLiveAppRecordConfigRequest.setDelayTime(<180>);

We recommend that you not specify a time that is excessively short or long. If the time is excessively short, a large number of recordings may be generated when a live stream is frequently disconnected and reconnected due to reasons such as network fluctuations. If the time is excessively long, recordings may require a long period of time to be generated after a live stream ends.

In specific business scenarios, you may not want to wait for the generation of a recording until the interruption duration threshold elapses. In this case, you can configure the system to generate a recording immediately after a live stream ends. To do so, configure stream ingest callbacks to receive notifications that indicate the ending of stream ingest. When you receive such a notification, call the RealTimeRecordCommand operation to cancel the threshold mechanism and immediately generate a recording. For information about how to configure stream ingest callbacks, see Callbacks for stream ingest status.

Sample code for canceling the threshold mechanism

Java

        // Replace the content in <> with actual values.
        RealTimeRecordCommandRequest realTimeRecordCommandRequest=new RealTimeRecordCommandRequest();
        realTimeRecordCommandRequest.setCommand("cancel_delay");
        realTimeRecordCommandRequest.setAppName("<AppName>");
        realTimeRecordCommandRequest.setStreamName("<StreamName>");
        realTimeRecordCommandRequest.setDomainName("<DomainName>");
        RealTimeRecordCommandResponse realTimeRecordCommandResponse = null;
        try {
            realTimeRecordCommandResponse = client.getAcsResponse(realTimeRecordCommandRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        System.out.println(new Gson().toJson(realTimeRecordCommandResponse));

Note

If you record a transcoded stream, change StreamName to StreamName_Transcoding template ID.
setCommand("cancel_delay"): resets the interruption duration, completely stops recording, and immediately generates a recording.

Configure custom recording rules

In the Configure recording settings section, the live stream recording feature is configured. When a live stream is ingested, the recording process starts. This is called automatic recording.

In some cases, you may want to determine whether to record a live stream based on your business requirements. You can use one of the following methods to record a live stream as required:

1. ApsaraVideo Live sends a request to ask whether to record a live stream. After ApsaraVideo Live receives a response to record the live stream, the recording process starts. This is called on-demand recording.

2. Your business system sends a notification to ApsaraVideo Live to record a live stream. This is called manual recording.

On-demand recording

To implement on-demand recording, your business system must provide a callback URL for ApsaraVideo Live. For more information, see Callbacks for on-demand recording.

The following sample code provides an example on how to configure on-demand recording:

Java

        // Set the OnDemand parameter to 1, which enables on-demand recording by using the HTTP callback method. 
        addLiveAppRecordConfigRequest.setOnDemand(1);

You can also call the AddLiveRecordNotifyConfig operation to configure recording callbacks for a domain name.

Sample code for configuring recording callbacks

Java

        // Replace the content in <> with actual values.
        AddLiveRecordNotifyConfigRequest addLiveRecordNotifyConfigRequest=new AddLiveRecordNotifyConfigRequest();
        // Specify a callback URL for on-demand recording.
        addLiveRecordNotifyConfigRequest.setOnDemandUrl("<OnDemandUrl>");
        addLiveRecordNotifyConfigRequest.setNotifyUrl("<NotifyUrl>");
        addLiveRecordNotifyConfigRequest.setDomainName("<DomainName>");
        AddLiveRecordNotifyConfigResponse addLiveRecordNotifyConfigResponse = null;
        try {
            addLiveRecordNotifyConfigResponse = client.getAcsResponse(addLiveRecordNotifyConfigRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        System.out.println(new Gson().toJson(addLiveRecordNotifyConfigResponse));

Important

<OnDemandUrl> specifies the callback URL for on-demand recording. <NotifyUrl> specifies the callback URL that is used to receive notifications about recording events and status.
The <NotifyUrl> parameter is required. If you want to receive only on-demand recording requests but do not want to call back recording events and status, you can set the <NotifyUrl> parameter to a URL that does not support the requested method.

Manual recording

To enable manual recording, you must disable automatic recording. Sample code:

        // Set the OnDemand parameter to 7, which disables automatic recording. 
        addLiveAppRecordConfigRequest.setOnDemand(7);

During live streaming, you can call the RealTimeRecordCommand operation to start recording based on your business requirements.

Sample code for starting recording

Java

        // Replace the content in <> with actual values. 
        RealTimeRecordCommandRequest realTimeRecordCommandRequest=new RealTimeRecordCommandRequest();
        realTimeRecordCommandRequest.setCommand("start");
        realTimeRecordCommandRequest.setAppName("<AppName>");
        realTimeRecordCommandRequest.setStreamName("<StreamName>");
        realTimeRecordCommandRequest.setDomainName("<DomainName>");
        RealTimeRecordCommandResponse realTimeRecordCommandResponse = null;
        try {
            realTimeRecordCommandResponse = client.getAcsResponse(realTimeRecordCommandRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        System.out.println(new Gson().toJson(realTimeRecordCommandResponse));

Note

If you record a transcoded stream, change StreamName to StreamName_Transcoding template ID.
setCommand("start"): starts recording.

Stop recording

You can call the RealTimeRecordCommand operation to manually stop recording, no matter you are using automatic recording, on-demand recording, or manual recording.

Sample code for stopping recording

Java

        // Replace the content in <> with actual values. 
        RealTimeRecordCommandRequest realTimeRecordCommandRequest=new RealTimeRecordCommandRequest();
        realTimeRecordCommandRequest.setCommand("stop");
        realTimeRecordCommandRequest.setAppName("<AppName>");
        realTimeRecordCommandRequest.setStreamName("<StreamName>");
        realTimeRecordCommandRequest.setDomainName("<DomainName>");
        RealTimeRecordCommandResponse realTimeRecordCommandResponse = null;
        try {
            realTimeRecordCommandResponse = client.getAcsResponse(realTimeRecordCommandRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        System.out.println(new Gson().toJson(realTimeRecordCommandResponse));

Note

setCommand("stop"): stops recording.
If you manually stop recording, a recording is generated after the interruption duration threshold elapses.
If you record a transcoded stream, change StreamName to StreamName_Transcoding template ID.

Related API operations

Configure the recording cycle

After the duration of a live stream exceeds the recording cycle that you specify, a new recording is generated. For example, if the live stream lasts for 20 minutes and the recording cycle is set to 15 minutes, two recordings are generated. You can set the recording cycle to a value that ranges from 15 to 360 minutes.

Sample code for configuring the recording cycle

Java

        List<AddLiveAppRecordConfigRequest.RecordFormat> formatList=new ArrayList<AddLiveAppRecordConfigRequest.RecordFormat>();
        AddLiveAppRecordConfigRequest.RecordFormat m3u8Format=new AddLiveAppRecordConfigRequest.RecordFormat();
        m3u8Format.setFormat("m3u8");
        m3u8Format.setOssObjectPrefix("<record/{AppName}/{StreamName}/{EscapedStartTime}_{EscapedEndTime}>");
        m3u8Format.setSliceOssObjectPrefix("<record/{AppName}/{StreamName}/{UnixTimestamp}_{Sequence}>");
       // Configure the recording cycle. Unit: seconds.
        m3u8Format.setCycleDuration(<900>);
        AddLiveAppRecordConfigRequest.RecordFormat mp4Format=new AddLiveAppRecordConfigRequest.RecordFormat();
        mp4Format.setFormat("mp4");
        mp4Format.setOssObjectPrefix("<record/{AppName}/{StreamName}/{EscapedStartTime}_{EscapedEndTime}>");
        // Configure the recording cycle. Unit: seconds.
        mp4Format.setCycleDuration(<1500>);
        formatList.add(mp4Format);
        formatList.add(m3u8Format);
        addLiveAppRecordConfigRequest.setRecordFormats(formatList);

Note

In the preceding sample code, two storage formats are configured for recordings, each with a specific recording cycle. If a stream is ingested for 20 minutes, three recordings are generated. One recording is in the MP4 format, and two recordings are in the M3U8 format.

If the duration of a live stream does not exceed the recording cycle, a recording is generated after the live stream ends. If you want to view the recording content before the live stream ends, you can call the RealTimeRecordCommand operation to forcibly restart recording. If you restart recording when the live stream is being recorded, a recording is immediately generated.

Sample code for restarting recording

Java

        // Replace the content in <> with actual values. 
        RealTimeRecordCommandRequest realTimeRecordCommandRequest=new RealTimeRecordCommandRequest();
        realTimeRecordCommandRequest.setCommand("restart");
        realTimeRecordCommandRequest.setAppName("<AppName>");
        realTimeRecordCommandRequest.setStreamName("<StreamName>");
        realTimeRecordCommandRequest.setDomainName("<DomainName>");
        RealTimeRecordCommandResponse realTimeRecordCommandResponse = null;
        try {
            realTimeRecordCommandResponse = client.getAcsResponse(realTimeRecordCommandRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        System.out.println(new Gson().toJson(realTimeRecordCommandResponse));

Note

setCommand("restart"): restarts recording.
If you record a transcoded stream, change StreamName to StreamName_Transcoding template ID.
If you configure multiple storage formats for recordings of the live stream, recordings that are generated after the restart are stored in the configured formats.

Merge and extract recordings

ApsaraVideo Live allows you to create index files for recordings and extract the recording content by time range. You can also merge multiple recordings that are generated within a time range into one recording.

Note

Regardless of the storage format of recordings, ApsaraVideo Live first slices the live stream into a number of TS segments and then composes them to generate recordings in the specified container format. You can create an M3U8 index file that references TS segments. This way, you can merge and extract the recording content based on the index file.
Only recordings that are stored in the M3U8 format can be merged or extracted.

To create an index file, call the CreateLiveStreamRecordIndexFiles operation.

Sample code for creating an index file

Java

        CreateLiveStreamRecordIndexFilesRequest createLiveStreamRecordIndexFilesRequest=new CreateLiveStreamRecordIndexFilesRequest();
        createLiveStreamRecordIndexFilesRequest.setAppName("<AppName>");
        createLiveStreamRecordIndexFilesRequest.setStreamName("<StreamName>");
        createLiveStreamRecordIndexFilesRequest.setDomainName("<DomainName>");
        createLiveStreamRecordIndexFilesRequest.setOssEndpoint("<OssEndpoint>");
        createLiveStreamRecordIndexFilesRequest.setOssBucket("<OssBucket>");
        createLiveStreamRecordIndexFilesRequest.setStartTime("<StartTime>");
        createLiveStreamRecordIndexFilesRequest.setEndTime("<EndTime>");
        createLiveStreamRecordIndexFilesRequest.setOssObject("<IndexFiles/OssObject.m3u8>");
        CreateLiveStreamRecordIndexFilesResponse createLiveStreamRecordIndexFilesResponse = null;
        try {
            createLiveStreamRecordIndexFilesResponse = client.getAcsResponse(createLiveStreamRecordIndexFilesRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        System.out.println(new Gson().toJson(createLiveStreamRecordIndexFilesResponse));

Note

In the preceding sample code, an index file is created for the recording content of a live stream within a specific time range. <AppName> specifies the application name. <StreamName> specifies the stream name. <StartTime> specifies the beginning of the time range. <EndTime> specifies the end of the time range. The index file is stored in an OSS bucket. <OssEndpoint> specifies the OSS endpoint. <OssBucket> specifies the name of the OSS bucket. <IndexFiles/OssObject.m3u8> specifies the name of the index file.
The values of <StartTime> and <EndTime> are in the yyyy-MM-ddTHH:mm:ssZ format, displayed in UTC.

Important

You can create an index file only after a live stream is ingested. If no live stream is available within the specified time range or the name of the specified live stream is invalid, the index file fails to be created.
The recording content contains files and information about the files, such as application names, stream names, and OSS storage paths. The information about TS segments and M3U8 index files is stored in ApsaraVideo Live. The files, including TS segments and M3U8 index files, are stored in OSS.
The retention period of the files that are stored in OSS is determined by the configuration of the OSS bucket.
ApsaraVideo Live stores information about TS segments only for three months. You can create M3U8 index files only for the recordings of the last three months.
ApsaraVideo Live stores information about M3U8 index files only for six months. You can query only the information about the M3U8 index files that are created in the last six months.
If you want to merge or extract transcoded streams, you must change StreamName to StreamName_Transcoding template ID.
The OSS bucket that is specified by the <OssBucket> parameter must reside in the same region as the live center of the domain name. Otherwise, you cannot use the domain name to query information about the M3U8 index files.

Related API operations

Manage recordings

View recordings

You can use the following three methods to view recordings that are stored in OSS:

Use the ApsaraVideo Live console

Log on to the ApsaraVideo Live console.
In the left-side navigation pane, choose Feature Management > Recording. On the Recording page, click the Recordings tab.
Select the streaming domain.
Click the OSS tab, and view the recordings.

Call an API operation

Java

        // Replace the content in <> with actual values. 
        DefaultProfile profile = DefaultProfile.getProfile("<regionId>", "<ALIBABA_CLOUD_ACCESS_KEY_ID>", "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>");
        IAcsClient client = new DefaultAcsClient(profile);
        DescribeLiveStreamRecordIndexFilesRequest describeLiveStreamRecordIndexFilesRequest=new DescribeLiveStreamRecordIndexFilesRequest();
        describeLiveStreamRecordIndexFilesRequest.setAppName("<AppName>");
        describeLiveStreamRecordIndexFilesRequest.setStreamName("<StreamName>");
        describeLiveStreamRecordIndexFilesRequest.setDomainName("<DomainName>");
        describeLiveStreamRecordIndexFilesRequest.setStartTime("<StartTime>");
        describeLiveStreamRecordIndexFilesRequest.setEndTime("<EndTime>");
        DescribeLiveStreamRecordIndexFilesResponse describeLiveStreamRecordIndexFilesResponse = null;
        try {
            describeLiveStreamRecordIndexFilesResponse = client.getAcsResponse(describeLiveStreamRecordIndexFilesRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }

        for(int i=0;i<describeLiveStreamRecordIndexFilesResponse.getRecordIndexInfoList().size();i++){
            System.out.println(new Gson().toJson(describeLiveStreamRecordIndexFilesResponse.getRecordIndexInfoList().get(i)));

        }

Important

You can query only the data in the last six months.
The values of EndTime and StartTime are in the yyyy-MM-ddTHH:mm:ssZ format, displayed in UTC. The time range cannot exceed four days.
For more information about the API operation, see DescribeLiveStreamRecordIndexFiles.

Use the OSS service

When you configure the live stream recording feature, you need to specify the storage location of recordings in OSS. For information about how to use OSS to view recordings, see List objects.

Delete recordings

ApsaraVideo Live stores recording information, such as the application names, stream names, and OSS storage paths, while OSS stores the actual files. If you want to delete relevant files that are stored in OSS when you delete recordings in ApsaraVideo Live, you must create the AliyunMTSVideoLifecycleRole role and attach the system policy AliyunMTSVideoLifecycleRolePolicy to the role.

Authorization procedure

Before you delete recordings in the ApsaraVideo Live console, perform the following operations to create a Resource Access Management (RAM) role and grant permissions to the RAM role.

Log on to the RAM console with your Alibaba Cloud account.
In the left-side navigation pane, choose Identities > Roles.
On the Roles page, click Create Role.
In the Select Role Type step, select Alibaba Cloud Service in the Select Trusted Entity section and click Next.
In the Configure Role step, configure the following parameters:
- Set Role Type to Normal Service Role.
- Enter AliyunMTSVideoLifecycleRole in the RAM Role Name field.
- (Optional) Enter content in the Note field based on your needs.
- Select Media Transcoding Service from the Select Trusted Service drop-down list.
Click OK.
In the Finish step, a message indicating that the role is created appears. On the role details page, click Precise Permission.
In the Precise Permission panel, configure the following parameters:
- Set Type to System Policy.
- Enter AliyunMTSVideoLifecycleRolePolicy in the Policy Name field.
Click OK.

You can use the following three methods to delete recordings that are stored in OSS:

Use the ApsaraVideo Live console

Log on to the ApsaraVideo Live console.
In the left-side navigation pane, choose Feature Management > Recording. On the Recording page, click the Recordings tab.
Select the domain name for which you want to delete a recording.
Click the OSS tab, find the recording that you want to delete, and click Delete in the Actions column.
Click OK.
By default, the "Also delete the recording file stored in OSS" option is not selected. If you select this option, the recording file stored in OSS is also deleted when you delete the recording in the ApsaraVideo Live console.

Call an API operation

Java

        DeleteLiveStreamRecordIndexFilesRequest deleteLiveStreamRecordIndexFilesRequest=new DeleteLiveStreamRecordIndexFilesRequest();
        deleteLiveStreamRecordIndexFilesRequest.setAppName("<AppName>");
        deleteLiveStreamRecordIndexFilesRequest.setStreamName("<StreamName>");
        deleteLiveStreamRecordIndexFilesRequest.setDomainName("<DomainName>");

        List<String> recordList=new ArrayList<>();
        // Specify the ID of the index file.
        recordList.add("<recordId>");
        deleteLiveStreamRecordIndexFilesRequest.setRecordIds(recordList);
        deleteLiveStreamRecordIndexFilesRequest.setRemoveFile("<true>");
        DeleteLiveStreamRecordIndexFilesResponse deleteLiveStreamRecordIndexFilesResponse = null;
        try {
            deleteLiveStreamRecordIndexFilesResponse = client.getAcsResponse(deleteLiveStreamRecordIndexFilesRequest);
        } catch (ClientException e) {
            e.printStackTrace();
        }

        System.out.println(new Gson().toJson(deleteLiveStreamRecordIndexFilesResponse));

Important

<recordId> specifies the ID of the index file. For information about how to obtain the ID, see the View recordings section.
For more information about the API operation, see DeleteLiveStreamRecordIndexFiles.

Use the OSS service

In most cases, we do not recommend that you directly delete recording files stored in OSS. If you want to delete a recording file stored in OSS, you can select the "Also delete the recording file stored in OSS" option when you delete the recording in the ApsaraVideo Live console. For information about how to directly delete recording files stored in OSS, see Delete objects.

Other information

You can query recording data in the last six months. If you want to delete files that were generated more than six months ago, you can use OSS. For more information, see Delete objects.

If you want to automatically delete expired recording files in an OSS bucket, you must authorize ApsaraVideo Live to access OSS resources. To do so, go to the Cloud Resource Access Authorization page and click Agree to Authorization. Then, submit a ticket. The after-sales team configures a validity period based on your requirements. For more information about how to submit a ticket, see Contact us. After the validity period is configured, ApsaraVideo Live can automatically delete expired recording files that are stored in OSS.

Note

By performing the preceding operations, you are assigned the role that grants ApsaraVideo Live the permissions to access resources of other Alibaba Cloud services. If you accidentally delete the role, you can perform the authorization again.

References

For information about how to use the server SDK for Java, see Use the server SDK for Java.

For more information about recording callbacks, see Callbacks for live stream recording and Callbacks for on-demand recording.