Live stream recording

• HLS recording

• MP4 recording

• FLV recording

• Video callback

Prerequisites

To use live stream recording, you must contact Kingsoft Cloud sales team to activate Kingsoft Cloud Live Service (KLS), Content Delivery Network (CDN), and VoD Transcoding.

Concepts

• Live stream recording is a service that converts the container format of the audio and video data of original live streams to obtain recording files without modifying information such as the encoding mode, audio and video data, and corresponding timestamps. The recording files are stored in Kingsoft Cloud Standard Storage Service (KS3).
• Slicing: You can specify a length for slicing. When the length of the recording file reaches the length for slicing, stream data is written to a new recording file that is generated based on the naming rule. Assume that stream pushing lasts for 6 hours and that the length for slicing is set to 2 hours, that is, a new file is generated every 2 hours. Then, a total of 3 files with different names are generated.
• Recording period: You can specify a recording period. When the length of a recording file reaches the length of the recording period, data continues to be written to the same file as long as stream pushing continues. However, when stream pushing resumes after interruption, if the length of the recording file is already longer than the recording period, stream data is written to a new recording file that is generated based on the naming rule. Assume that stream pushing lasts for 11 hours and that the recording period is set to 10 hours. When the length of the recording file reaches 10 hours, data continues to be written to the same recording file, and a 11-hour-long recording file is generated. However, because the length of this generated recording file is already longer than the recording period, at the next stream pushing, a new recording file is generated based on the naming rule.
• The priority of slicing is higher than that of the recording period.
• Interrupted stream splicing: You can specify a duration within which interrupted streams are spliced. If the length of a recording file has not reached the length for slicing or the recording period when the stream pushing is interrupted, the data is appended to the original recording file after the stream pushing resumes within this specified duration. Otherwise, stream data is written to a new recording file that is generated based on the naming rule. Assume that the interrupted stream splicing duration is set to 3 minutes. If stream pushing resumes within 3 minutes after interruption, stream data is appended to the original recording file. However, if stream pushing resumes over 3 minutes later after interruption, stream data is written to a new recording file that is generated based on the naming rule.

Service activation

• To use live stream recording, you must first activate KS3 and create storage buckets and a callback URL in the KLS console. Please contact Kingsoft Cloud sales team to activate KS3.

Note

• Live stream recording is only available in Beijing.
• Live stream recording only changes the container format of audio and video data without modifying the encoding parameters. If slices of an MP4 or FLV recording file have inconsistent encoding parameters, the file may be corrupted. When the encoding parameters of push streams with the same name are inconsistent, we recommend that you turn off stream splicing. Instead, you can call the CreateTask API operation to splice the recording files.
• To use MP4 or FLV recording, you must enable HLS recording first.
• You can modify in the KS3 console the time at which files are saved.
• Example of a push stream URL with a vdoid parameter

    rtmp://uniquename.uplive.ks-cdn.com/live/stream?vdoid=1477402932

HLS Recording

Recording generation rules: Recording files of push streams with the same name are spliced if stream pushing resumes within 3 minutes (which can be configured) after interruption. A recording file is sliced after it reaches 6 hours (which can be configured) in length.

Path: /record/{App}/{StreamName}/hls/

Naming rule: [stream name]-[file start time]-[file end time].m3u8

Format: {StreamName}-{StartTime}-{EndTime}.m3u8

Example:

mystream-1585829187-1585829324.m3u8

Path description

Directory	Description
record	The root directory for ease of management.
App	The app name that comes with the push stream. Default value: live.
StreamName	The name of the push stream.
hls	The directory where .m3u8 files are stored.
Vdoid	The unique identifier. This field will be deprecated soon.

MP4 Recording

Note: If a push stream does not carry the vdoid parameter and its path is empty, the MP4 file cannot be generated.

Recording generation rules: Recording files of push streams with the same name are spliced if stream pushing resumes within 3 minutes (which can be configured) after interruption. A recording file is sliced after it reaches 6 hours (which can be configured) in length.

Path: /record/{App}/{StreamName}/mp4/

Naming rule: [stream name]-[file start time]-[file end time].mp4

Format: {StreamName}-{StartTime}-{EndTime}.mp4

Example:

mystream-1585829187-1585829324.mp4

FLV recording

Recording generation rules: Recording files of push streams with the same name are spliced if stream pushing resumes within 3 minutes (which can be configured) after interruption. A recording file is sliced after it reaches 6 hours (which can be configured) in length.

Path:/record/{App}/{StreamName}/flv/

Naming rule: [stream name]-[file start time]-[file end time].flv

Format: {StreamName}-{StartTime}-{EndTime}.flv

Example:

mystream-1585829187-1585829324.flv

Recording callback

HLS recording callback

Callback URL configuration

You can configure a callback URL for recording files in the KLS console. When a recording file is generated, you are informed through a callback in the form of HTTP POST.

Sample callback

The default callback information is as follows:

{
    "status":3,
    "taskid":"xxxxx",
    "itmes":[
        {
            "cmd":"",
            "desc":"success",
            "keys":[
                "record/live/NEWLIVE4q665314vdoid6683676M2W3/hls/filename.m3u8"
            ],
            "vdoid":"",
            "code":3
        }
    ],
    "mediaSize":0
}

If you want to add a start time and end time in the callback information, please contact technical support to enable it.

Parameter description

Parameter	Example	Description
status	3	The task execution status. Valid values: 3: succeeded; 4: failed.
taskid	00PNwad2wdoO	The unique task ID of the current live recording operation.
desc	success	The task execution result.
keys	/streamname/11111.m3u8	The name of the .m3u8 VoD file generated.
code	3	The code returned after the task execution is completed.

MP4 or FLV video callback

Callback URL configuration

You can configure a callback URL for recording files in the KLS console. When a recording file is generated, you are informed through a callback in the form of HTTP POST.

Sample callback

{
    "taskid":"xxxxx",
    "status":3,
    "type":"avtrans",
    "details":{
        "errnum":0,
        "bucket":"xxxx",
        "starttime":"1456800010",
        "endtime":"1456800020",
        "stream":"xxxx",
        "throughParams":"xxxx",
        "items":[
            {
                "dstpath":"xxxxx.mp4",
                "ETag":"cb1b99f6657c91dac6c1913cd99131a1",
                "outMediainfo":"{\"metadata\":{},\"format\":{\"format_name\":\"mp4\",\"size\":1027254935,\"duration\":\"5241\",\"bit_rate\":1568024},\"streams\":[{\"codec_name\":\"h264\",\"codec_type\":\"video\",\"width\":1280,\"height\":720,\"r_frame_rate\":\"25/1\"},{\"index\":1,\"codec_name\":\"aac\",\"codec_type\":\"audio\",\"channels\":2,\"sample_rate\":32000}]}"
            }
        ]
    },
 // Historical fields, which can be ignored
    "itmes":[
        {
            "cmd":"tag=avtranstag=saveas&bucket=media-kslive&object=YTMwNGQzNzQzZTdhNGRmNmE1NzAwZjkxNDJhY2RjZTlfdmRvaWQyMDE3MDkwNC5tcDQ=",
            "desc":"success",
            "keys":[
                "xxxxx.mp4"
            ],
            "code":3
        }
    ]
}

Parameter description

Field name	Type	Required	Description
taskid	String	Yes	The task ID.
status	Int	Yes	The status of the task. Valid values: 3: succeeded; 4: failed.
type	String	Yes	The type of the task, same as the type of the template used at task creation.
details	JSON object	Yes	More detailed information.

• Description of the details field

Field name	Type	Required	Description
errnum	Int	Yes	The video information.
errmsg	String	Yes	The video metadata.
bucket	String	Yes	The video stream information list.
stream	String	No	The stream name.
starttime	String	No	The start time of the stream.
endtime	String	No	The end time of the stream.
throughParams	String	No	The pass-through parameters.
items	JSON array	Yes	The custom callback information, such as output file information.

• Description of the items field

Field name	Type	Required	Description
dstpath	Int	Yes	The relative path of the output file in KS3.
ETag	String	Yes	The MD5 value of the video content.
outMediainfo	String	Yes	The callback field for avtrans tasks that store information about the output video. The value is a string in JSON format.

• Description of the outMediainfo field

Field name	Type	Required	Description
metadata	JSON object	Yes	The video metadata.
streams	JSON array	Yes	The video stream information list.
format	JSON object	Yes	The video file information.

Description of the metadata field

Field name	Type	Required	Description
rotate	String	No	The rotation information.

Description of the streams field

Field name	Type	Required	Description
index	Int	Yes	The index number.
codec_type	String	Yes	The stream type.
codec_name	String	Yes	The encoding format.
bit_rate	Int	Yes	The bitrate, in bps.
width	Int	No	The width.
height	Int	No	The height.
r_frame_rate	String	No	The frame rate.
channels	Int	No	The number of audio channels.
sample_rate	Int	No	The audio sampling rate.

Description of the format field

Field name	Type	Required	Description
duration	String	Yes	The file length, in seconds.
format_name	String	Yes	The container format of the file.
size	Int	Yes	The file size, in bytes.