CSS Recording

Last updated: 2021-03-12 11:23:59

    CSS recording is a service that stores the files generated by muxing original streams (without modifying such information as audio and video data and corresponding timestamps) on the VOD platform.


    • You can use either of the following methods to record: create a recording task or create a recording template. If you create both recording template and 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. For a better quality of recording files, the duration of each recorded push should be longer than 10s.

    Recording Storage

    As CSS recording files are stored on the VOD platform, you need to apply for activation of the VOD service first.


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

    Recording Format

    Supported recording 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 set the start time and end time through APIs to record a stream within the specified time period.
    Real-time recording You can record any frame of a stream in real time through APIs.
    Audio recording You can configure audio recording in .aac format if the push is pure audio.

    Enabling Recording for All Live Streams Under Specified Push Domain Name

    Recording parameters are managed in the form of templates. You can create recording configuration templates for different scenarios and flexibly manage the recording configuration by binding the templates to 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 Template > Recording Configuration to create a recording template.
    2. Select Domain Management to add a push domain name, and click Manage to bind it to the recording template. For more information, please see Recording Configuration.


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

    Likewise, you can bind the template to different stream names to record particular live streams.
    In addition, as one recording template can be bound to 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 prevail. The priority rule of template matching is as shown below (which is for complex cases only and can be ignored by most users).

    DomainName StreamName Priority
    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 be stopped and the corresponding template will be returned.

    Disabling Recording for Certain Streams Under Specified Push Domain Name

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

    1. Call CreateLiveRecordTemplate without specifying any recording format.
      &<Common request parameters>
    2. Set the DomainName and StreamName parameters in the console or through the CreateLiveRecordRule API and bind the above-mentioned recording template to the specified push domain name and stream name.


    This scheme is applicable to scenarios where only a few streams do not need to be recorded. If there are too many of them, we recommend you 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 in this mode even your business changes.

    Recording Within Specified Time Period

    For some streams, you can start and end recording at the specified points in time through APIs. Unlike configuring a recording template, the recording parameters need to be specified through APIs. This approach is generally adopted if no recording method has been set.


    For more information on how to create a recording task through the API, please see CreateRecordTask.

    Recording sample

    • In the simple case, you just need to specify parameters: 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 that will be retained permanently.

    Sample input:

    &<Common request parameters>
    • The recording format, recording type, and storage parameters can also be specified.
      The following sample code creates a recording task in .mp4 format for 8 AM to 10 AM, August 10, 2020 with 1-hour segments that will be retained permanently.
      1. Call CreateLiveRecordTemplate to create a recording template.
        Sample input:
        &<Common request parameters>
        Sample output:
        "Response": {
        "RequestId": "839d12da-95a9-43b2-a9a0-03366d01b532",
        "TemplateId": 17016
      2. Call CreateRecordTask to create a recording task.

    Sample input:

    &<Common request parameters>


    • 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 the API can be called to create a recording task in addition to enabling a recording configuration.
    • We recommend you create recording tasks in advance (e.g., one hour in advance or in the early morning for recording later on), and the task start time should be set to be a little 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 for future use, you can call the API to enable real-time recording.

    &<Common request parameters>

    The following notes on real-time recording require your attention:

    • Make sure that the push is ongoing when you create a recording task.
    • This is suitable for recording short clips of up to 30 minutes.
    • You can call the StopRecordTask API to stop a task prematurely.
    • This is also supported for streams outside Chinese mainland.

    Stream Mix-based Recording

    First, please familiarize yourself with the stream mixing service in On-cloud Stream Mix.

    For CSS scenarios where the on-cloud recording service is used, stream mixing is divided into two types by the OutputStreamType parameter on the recording side:

    • If OutputStreamType = 0, the output stream is in the input stream list, meaning that no new stream has been generated.
    • If OutputStreamType = 1, the output stream is not in the input stream list, meaning that a new stream has been generated.

    Suppose streams A and B are output as stream C after stream mix:

    • If OutputStreamType = 0 and stream C has the same name as stream A with mixed video, after the recording is started, a recording file mixing stream A (mixed video) and stream B will be generated by default. Note that as the same stream ID is reused, the original stream A will not generate a recording file.
    • If OutputStreamType = 1, after the recording is started, a recording file mixing stream A, stream B, and stream C (mixed video) will be generated by default.

    To record a mixed stream only, you can call the CreateRecordTask API. It should be noted that if OutputStreamType =1, the StreamType parameter should be set to 1 when the API above is called.


    Stream mix-based 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-Stream Recording)

    If a push is interrupted multiple times because of network jitters, multiple recording files will be generated, causing inconvenience to continuous playback of the live stream. To solve this problem, CSS recording can auto-splice multiple recording files during the same push into one single file.

    This feature works by segmenting audio and video data by HLS' #EXT-X-DISCONTINUITY tag in HLS recording. This tag marks that the information such as timestamps of audio and video data, video codecs, audio codecs, and sample rates before and after it may be different. As a result, the player needs to refresh the decoder for continuous playback. Therefore, to use this feature, the player must support the #EXT-X-DISCONTINUITY tag. Currently, the native player and Safari on iOS, ExoPlayer on Android, and hls.js player on the web support this tag, but VLC player does not.

    After this feature is enabled, you need to set the auto-splicing interval (up to 30 minutes, meaning that recording files in intervals of up to 30 minutes can be spliced into one file). After the last push ends, the recording files before and after the interruptions will be automatically spliced to generate an HLS recording file.

    Currently, auto-spliced recording is available only to the HLS format. You can set the auto-splicing timeout value in Recording Configuration.


    • This mode does not support live streams with no audio data.
    • The ComposeMedia API of VOD can be used to compose video files. For more information, please see ComposeMedia.

    Getting Recording File

    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 URL 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 Callback Event Message Notification for recording to take your next step.

    The event notification is an efficient, reliable, and real-time mechanism, so we recommend you use the callback method to get recording files.

    VOD API query

    For more information on how to query and filter recording files, please see SearchMedia.

    Precautions for Configuration Update

    After the recording configuration is updated, we recommend you restart the push and verify the configuration. The validity rules for the configuration are as follows:

    • It takes 10 minutes for the configuration to take effect by default.
    • The configuration takes effect upon the start of the CSS push and will not be updated in the process of recording.
    • In scenarios where the push lasts for a long time such as surveillance recording, the push needs to be stopped and then restarted to make the configuration take effect.