Live Recording

Last updated: 2021-08-13 11:22:28
    • Live recording stores the files generated by muxing original streams (without modifying information such as audio and video data and corresponding timestamps) on the VOD platform.

      Notes

      • You can use either of the following methods to record: create a recording task or create a recording template. If you create both a recording template and a recording task for the same live stream, it will be recorded repeatedly.
      • As there is a short delay in starting a recording task after a stream is pushed, a very short push cannot generate recording files. It is recommended that the duration of each push for recording be longer than 10s.

      Recording Storage

      As the recording files are stored on the VOD platform, you need to activate the VOD service first.

      Note:

      For the naming rules of generated recording files, see VodFileName.

      Recording Format

      Supported recording file formats include .aac (for audio recording), .flv, .hls, and .mp4.

      Recording Use Cases

      Use Case Description
      Multi-level recording by push domain name and stream name You can configure whether to record a stream at the push domain name and stream name level.
      Recording within a specified time period You can call APIs to set the start time and end time to record a stream within the specified time period.
      Real-time recording You can call APIs to record any frame of a stream in real time.
      Pure audio recording You can use .aac format to record pure audio streams.

      Enabling Recording for All Live Streams under a Specified Push Domain Name

      Recording parameters are managed by templates. You can create recording templates for different scenarios and flexibly manage the recording configurations by binding the templates with different push domain names and stream names.
      After activating VOD, you can record live streams under a specified push domain name in two ways:

      CSS console

      1. Select Feature Configuration > Live Recording to create a recording template.
      2. Select Domain Management to add a domain name, and click Manage to bind it with the recording template. For more information, see Recording Configuration.

      APIs

      1. Call the CreateLiveRecordTemplate API to set at least one recording format, such as FlvParam.
      2. Call the CreateLiveRecordRule API to set the DomainName (push domain name) and TemplateId (returned in step 1) parameters. You can enter an empty string in AppName and StreamName as a wildcard to indicate all streams under the domain name.

      You can also bind the template with names of specific live streams to record them.
      As one template can be bound with different push domain names and stream names, one stream may be matched with multiple templates. In this case, the template with the highest priority will be used. The rules of template matching by priority are shown below (for complex use cases only and can be ignored by most users).

      DomainName StreamName Priority
      0
      Empty string 1
      Empty string 2
      Empty string Empty string 3

      Here, Empty string is a wildcard, indicates exact match, and 0 represents the highest priority. Once a template with the highest priority is matched, the matching will stop and this template will be returned.

    Disabling Recording for Specific Streams Under a Push Domain Name

    When you have already configured recording for a push domain name but do not need to record some streams under it:

    1. Call the CreateLiveRecordTemplate API without specifying any recording format.

        https://live.tencentcloudapi.com/?Action=CreateLiveRecordTemplate
      &TemplateName=norecord
      &description=test
      &<Common request parameters>
      
    2. Go to the CSS console or use the CreateLiveRecordRule API to bind the above recording template with specific DomainName and StreamName.

      Note:

      This method is applicable to scenarios where only a few streams do not need to be recorded. If there are too many streams, you’re advised to use another push domain name to manage them, because:

      • The allowed maximum number of recording templates or recording rules is 50.
      • Management by push domain name is more flexible as recording templates and recording rules won't be affected even when your business changes.

      Recording Within a Specified Time Period

      You can use APIs to specify the start time, end time and other parameters of recording for some streams. That is different from using a preset recording template with specified parameters. Usually, APIs are used when no recording template is created.

      APIs

      Call the CreateRecordTask API.

    Recording sample

    • In simple scenarios, you need to specify only StreamName, DomainName, AppName, and EndTime.
      The following sample code creates a video recording task in .flv format for 8 AM to 10 AM, August 10, 2020, with 30-minute segments, and the recording files will be retained permanently.
    • Sample input code:*
      https://live.tencentcloudapi.com/?Action=CreateRecordTask
      &AppName=live
      &DomainName=mytest.live.push.com
      &StreamName=livetest
      &StartTime=1597017600
      &EndTime=1597024800
      &TemplateId=0
      &<Common request parameters>
      
    • You can also specify the recording format, recording type, and storage parameters.
      The following sample code creates a recording task in .mp4 format for 8 AM to 10 AM, August 10, 2020, with 1-hour segments, and the recording files will be retained permanently.
      1. Call the CreateLiveRecordTemplate API to create a recording template.
    • Sample input code:*
      https://live.tencentcloudapi.com/?Action=CreateLiveRecordTemplate
      &TemplateName=templat
      &description=test
      &Mp4Param.Enable=1
      &Mp4Param.RecordInterval=3600
      &Mp4Param.StorageTime=0
      &<Common request parameters>
      
    • Sample output code:*
      {
      "Response": {
      "RequestId": "839d12da-95a9-43b2-a9a0-03366d01b532",
      "TemplateId": 17016
      }
      }
      
      1. Call the CreateRecordTask API to create a recording task.
    • Sample input code:*
      https://live.tencentcloudapi.com/?Action=CreateRecordTask
      &StreamName=livetest
      &AppName=live
      &DomainName=mytest.live.push.com
      &StartTime=1597017600
      &EndTime=1597024800
      &TemplateId=17016
      &<Common request parameters>
      
    Note:

    • For the same live stream, there is no conflict between scheduled tasks or between a scheduled task and a recording task of another type. In other words, the time periods of multiple scheduled tasks can overlap, and you can call APIs to create a recording task in addition to enabling a recording configuration.
    • You’re advised to create recording tasks in advance (e.g., one hour in advance or in the early morning), and to set the task start time a bit earlier than the event start time.

    Real-Time Recording

    If you want to record any frames immediately in the process of live streaming to generate highlight clips, you can call APIs to enable real-time recording.

    https://live.tencentcloudapi.com/?Action=CreateRecordTask
    &StreamName=test
    &AppName=live
    &DomainName=mytest.live.push.com
    &EndTime=1597024800
    &<Common request parameters>
    

    Notes on real-time recording:

    • Make sure that the push is ongoing when you create a recording task.

    • You can call the StopRecordTask API to stop a task in advance.

    • This is also supported for streams outside the Chinese mainland.

      Mixed Stream Recording

      First, please familiarize yourself with Live Stream Mixing.

      There are two types of stream mixing indicated by the OutputStreamType parameter:

    • If OutputStreamType is set to 0, the output stream is in the input stream list, meaning that no new stream will be generated.

    • If OutputStreamType is set to 1, the output stream is not in the input stream list, meaning that a new stream will be generated.

      Assume the pushed streams are A and B, and the mixed stream is the output stream C:

    • Suppose OutputStreamType is set to 0 and the name of stream A is used as the name of the output stream C. After the recording is started, recording files of stream A (mixed stream) and stream B will be generated. As the name of stream A is reused, the original stream A will not generate a recording file.

    • If OutputStreamType is set to 1, recording files of stream A, stream B, and stream C (mixed stream) will be generated after the recording is started.

      If you only want to record the mixed stream, you can call the CreateRecordTask API. Please note that if OutputStreamType is set to 1, the StreamType parameter should be set to 1 when this API is called.

      Note:

      Mixed stream recording does not support mixing streams in and outside Chinese mainland, as recording file errors will occur and affect normal playback.

    Auto-Spliced Recording (Multi-Push Recording)

    If several recording files are generated when a push is interrupted multiple times due to network jitters, it will affect the continuous playback of the live stream. To solve this problem, live recording can auto-splice multiple recording files between short stream interruptions into one file.

    This feature segments audio and video data by #EXT-X-DISCONTINUITY tags in HLS recording. Due to stream interruptions, timestamps of audio and video data, video codec, audio codec and sample rates before and after tagging may be different. The player needs to refresh the decoder to achieve seamless playback. To use this feature, the player should support the #EXT-X-DISCONTINUITY tag. Currently, the tag is supported on native player and Safari on iOS, ExoPlayer on Android, and HLS.js player on web, but not supported on VLC player.

    After this feature is enabled, you need to set the auto-splicing timeout period. This period is up to 30 minutes, meaning that recording files between interruptions of up to 30 minutes can be spliced into one HLS file after the last push ends.

    Currently, auto-spliced recording is supported only for HLS format. You can set the auto-splicing timeout period in Live Recording.

    Note:

    • This feature does not support live streams with no audio data.
    • You need to call the ComposeMedia API of VOD to compose video files.
    • After HLS recording resumption is enabled, no callback will be returned for push interruptions, and only callbacks for the final generated file will be returned.

    Obtaining Recording Files

    The generated recording files are automatically stored in the VOD system and can be obtained in the following ways:

    VOD console

    Log in to the VOD console and select Media Assets > Video Management on the non-admin page to browse all the generated recording files.

    Recording event notification

    The recording callback address can be set in the console or through API calls. A notification will be sent to the callback address after the recording files are generated. After that, you can refer to the recording callback event message notification to take your next step.

    As the event notification callbacks are efficient, reliable, and in real time, you’re recommended to use them to get recording file information.

    Query by VOD API

    • You can call the SearchMedia API of VOD to filter and query recording files.
      Note:

      When you call the CreateRecordTask API, stream_param parameters carried in the push URL will not be returned in the recording callback. Yet if you use other recording methods, such parameters will be returned in the recording callback.

    Notes on Modifying Configuration

    You are advised to restart the push and verify the recording configuration if you modified the configuration. The configuration takes effect by the following rules:

    • By default, the configuration takes effect in 10 minutes.
    • The configuration is effective upon the start of the live push and will not be updated in the process of recording.
    • In scenarios where the push lasts for a long time (surveillance recording for example), you need to interrupt and restart the push for the configuration to take effect.