ApsaraVideo Live:Live stream recording

How live stream recording works

The live stream recording feature is used to generate recordings from live streams. When you use the feature, ApsaraVideo Live pulls the streams that you ingest and encapsulates the audio and video data into a number of separate media segments in the TS format. The TS segments are then stored in the OSS bucket that you specify or stored in ApsaraVideo VOD. ApsaraVideo Live complies with the following principles in the recording process:

• ApsaraVideo Live only converts the container format of audio and video data from Real-Time Messaging Protocol (RTMP) or FLV to TS. However, ApsaraVideo Live never modifies the audio and video content, that is, the content of the coding layer. For example, if the live stream that you ingest is blurry, the recording is also blurry.

• ApsaraVideo Live has the permissions to write recordings to your bucket. However, it has no permissions to modify or delete the task files in your bucket, including the stored recordings. You have the sole privilege to manage the recordings in your bucket.

Storage of recordings

ApsaraVideo Live provides the following storage methods for recordings. You can use one of the methods based on your business requirements.

• Store recordings in OSS: The OSS bucket that is used to store recordings must reside in the same region as the live center of your streaming domain. Cross-region recording is not supported.

• Store recordings in ApsaraVideo VOD: Live streams are recorded and stored in ApsaraVideo VOD. The recordings are generated based on the VOD recording settings. You can use the online editing feature of ApsaraVideo VOD to edit and process the video content of live streams to produce short videos.

Container formats of recordings

The recording feature allows you to record live streams to files in the TS, M3U8, MP4, and FLV formats. Regardless of the container format, ApsaraVideo Live first slices the live streams into a number of separate TS segments and then composes them to generate recordings in the specified container format.

For the M3U8 format, ApsaraVideo Live stores both TS segments and M3U8 playlists in your bucket. This is because M3U8 playlists are only used as index files of the HTTP Live Streaming (HLS) protocol and audio and video data is separately stored in TS segments. For the MP4 and FLV formats, only the composed MP4 and FLV segments are stored in your bucket.

Limits

• Store recordings in OSS

  You can store recordings in OSS only if you create an OSS bucket that resides in the same region as the live center of your streaming domain. Cross-region recording is not supported. For more information, see Create an OSS bucket.

  When you activate ApsaraVideo Live, the system considers that you authorize ApsaraVideo Live to write data to your OSS buckets by default. Therefore, ApsaraVideo Live has the permissions to store recordings in the bucket that you specify. If the permissions are accidentally deleted, you can reconfigure it by using the following methods:

  • Configure the permissions in the console. You must authorize ApsaraVideo Live to write video data to OSS before the video data can be stored in the bucket that you specify. For more information, see Grant the write permissions on OSS to ApsaraVideo Live.

  • Use Resource Access Management (RAM) to configure the permissions. For more information, see Create and grant permissions to a RAM user.

• Store recordings in ApsaraVideo VOD

  You must activate ApsaraVideo VOD before you can store recordings in ApsaraVideo VOD. The region where you activate ApsaraVideo VOD must be the same as the region in which the live center of your streaming domain resides. For more information, see Activate ApsaraVideo VOD.

• 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. According to the FLV standard and ISO/IEC 13818-1 standard, the recording feature only supports the following encoding formats:

  • Video: H.264, HEVC, and MPEG-4

  • Audio: AAC and MP3

  Note

  If the live streams contain audio and video data that is encoded in none of the preceding formats, the following unexpected exceptions may occur in the recording process: recording failures, black screen issues, and recordings with no sound.

• Abnormal live streams

  ApsaraVideo Live can generate recordings from normal live streams that meet the following requirements: The live streams are encoded in one of the supported formats and have stable frame rates and monotonically and linearly increasing timestamps. For live streams with occasional frame rate instability or timestamp jumps, ApsaraVideo Live can also generate recordings thanks to its wide compatibility.

  However, ApsaraVideo Live may fail to generate recordings if an ingested live stream encounters the following serious exceptions: No video frame is detected for a long time, the timestamps do not increase in a monotonic and linear way, or the audio and video headers are missing.

Different recording methods and scenarios

ApsaraVideo Live provides the following recording methods. You can select a recording method based on your scenario.

Recording at the domain name, application, or stream level

ApsaraVideo Live allows you to record live streams at the domain name, application, or stream level. You can specify a domain name or application name to record all live streams under the domain name or for the application. You can also specify a stream name to record the live stream.

A check mark (✓) indicates that the parameter has a value other than an asterisk (*) in the recording template that you configure in the console or in the recording rule that you configure by calling an API operation.

You cannot store the recordings of a live stream in both OSS and ApsaraVideo VOD. The following section describes how to store recordings in OSS or ApsaraVideo VOD.

Store recordings in OSS

• ApsaraVideo Live console:

  For information about how to use the ApsaraVideo Live console to store recordings in OSS, see Store recordings in OSS.

• API calling:

  1. Call the AddLiveAppRecordConfig operation to configure recording rules. For more information, see AddLiveAppRecordConfig.

  2. Perform stream ingest. For more information, see Stream ingest, stream pulling, and streaming.

  The following table describes other related API operations.

  API operation	Description
  DeleteLiveAppRecordConfig	Deletes a rule that specifies the recording configuration of an application if the rule is no longer needed.
  DescribeLiveRecordConfig	Queries all configured rules.

Store recordings in ApsaraVideo VOD

• ApsaraVideo Live console:

  For information about how to use the ApsaraVideo Live console to store recordings in ApsaraVideo VOD, see Store recordings in ApsaraVideo VOD.

• API calling:

  1. Call the AddLiveRecordVodConfig operation to configure recording rules. For more information, see AddLiveRecordVodConfig.

  2. Perform stream ingest. For more information, see Stream ingest, stream pulling, and streaming.

  The following table describes other related API operations.

  API operation	Description
  DeleteLiveRecordVodConfig	Deletes the live-to-VOD configuration if the configuration is no longer needed.
  DescribeLiveRecordVodConfigs	Queries the live-to-VOD configuration.

Automatic recording based on scheduled tasks

If you want to record a live stream within a specified time period, you can call an API operation to automatically record the live stream as scheduled.

Example

On-demand recording

The principle of on-demand recording is that when a live stream is ingested, ApsaraVideo Live sends an HTTP callback to the preset AppServer. You can determine whether to record the live stream based on the content of the callback and dynamically change the recording format and recording cycle.

You need to develop the AppServer shown in the following figure to receive HTTP callbacks and determine whether to start recording based on your business logic.

API calling:

1. Call the AddLiveAppRecordConfig operation to configure recording rules. Set the OnDemand parameter to 1 to allow ApsaraVideo Live to send an HTTP callback asking whether to record a live stream.

2. Call the AddLiveRecordNotifyConfig operation to set the OnDemandUrl parameter.

3. Perform stream ingest.

4. The AppServer receives a callback of on-demand recording, determines whether to record the live stream based on your business logic, and then sends a response.

5. ApsaraVideo Live determines whether to start recording based on the response from the AppServer.

The following table lists the API operations used for on-demand recording.

Example

1. Call the AddLiveAppRecordConfig operation to configure ApsaraVideo Live to automatically record all live streams under the domain name example.com for the application whose name is liveBucket****.

   /?AppName=liveApp****
   &DomainName=example.com
   &OssBucket=liveBucket****
   &OssEndpoint=oss-cn-shanghai.aliyuncs.com
   &RecordFormat.1.Format=m3u8
   &<Common request parameters>

2. Call the AddLiveRecordNotifyConfig operation to set the OnDemandUrl parameter to http://example.aliyundoc.com.

   /?DomainName=example.com
   &OnDemandUrl=http://example.aliyundoc.com
   &<Common request parameters>

3. Perform stream ingest.

4. Check the on-demand recording callback that is received by the AppServer. For more information, see Callbacks of on-demand recording.

   GET /?app=liveApp****&domain=example.com&stream=liveStream****&vbitrate=2000&codec=h264 HTTP/1.1
   Host: demo.aliyundoc.com
   User-Agent: Go-http-client/1.1

5. Determine whether to start recording based on the response in the callback. For more information, see Callbacks of on-demand recording.

   • Start recording if the following response is received:

     {
         "ApiVersion" : "1.0",
         "NeedRecord" : true
     }

   • Do not start recording if the following response is received:

     {
         "ApiVersion" : "1.0",
         "NeedRecord" : false
     }

Manual recording

ApsaraVideo Live allows you to manually record a live stream. If a live stream is being recorded, you can also manually stop the recording of the live stream.

API calling:

1. Call the AddLiveAppRecordConfig operation to configure the recording rules. Set the OnDemand parameter to 7, which specifies that ApsaraVideo Live does not automatically record an ingested live stream.

2. Perform stream ingest.

3. Call the RealTimeRecordCommand operation to start recording.

4. (Optional) Call the RealTimeRecordCommand operation to stop recording.

Example

• Manually start recording

  If the live stream example.com/liveApp****/liveStream**** is being ingested, call the RealTimeRecordCommand operation to start recording.

  /?AppName=liveApp****
  &DomainName=example.com
  &StreamName=liveStream****
  &Command=start
  &<Common request parameters>

• Manually stop recording

  If the live stream example.com/liveApp****/liveStream**** is being recorded, call the RealTimeRecordCommand operation to stop recording.

  /?AppName=liveApp****
  &DomainName=example.com
  &StreamName=liveStream****
  &Command=stop
  &<Common request parameters>

Obtain recordings

Usage notes

• If you want to know whether automatic recording at the domain name, application, or stream level or automatic recording based on scheduled tasks takes effect, or if you want to process each recording in real time, you can configure recording callbacks. For more information, see Retrieval and management of recordings.

• A recording cycle is the maximum length of a recording. If the duration of a live stream exceeds the recording cycle, multiple recordings are generated. You can set the recording cycle to a value from 15 to 360 minutes. You can configure the recording cycle when you configure a recording template in the ApsaraVideo Live console. You can also call the AddLiveRecordVodConfig operation to configure the recording cycle for live streams that are recorded to VOD or call the AddLiveAppRecordConfig operation to configure the recording cycle for live streams that are recorded to OSS.

• 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. A new recording is generated for a live stream only if the live stream is interrupted for more than 3 minutes.

• ApsaraVideo Live supports triggered stream pulling. If the streaming URL of the corresponding domain name is used for streaming, ApsaraVideo Live is automatically triggered to pull the live stream. If no one is watching the live stream, ApsaraVideo Live does not pull the live stream from the origin. In this case, automatic recording, on-demand recording, and manual recording are also disabled.

FAQ

FAQ about live stream recording