VAS_Live Recording_Product Features_Media Acceleration Live Broadcast-文档中心

1. Brief intro

CDNetworks offers the capability to record your live streams for timeshifting or later playback. This guide will walk you through the process of setting up live stream recording.

Basic Live Recording
Basic Live Recording is a pre-configured feature that automatically records all of your streamed content into storage for future use.

Selective Live Recording
Selective Recording helps you record parts of streams based on your specific business requirements. It can be achieved through API interface calls and consists of two modes:

Real-time recording: This mode enables you to call the API interface for recording while one or more streams are active. The recording will start from the API interface call and end when the call is completed. This mode is only valid for the current live streaming session.
Preset recording: This mode enables you to trigger the API interface to apply recording configurations for specific domains, application names or stream names. The recording will automatically begin based on the preset configuration before the live stream starts and stop when the live stream ends. The preset configuration will apply to every live stream as long as it remains active.

Features	Mode	Introduction	API
Basic Live Recording		After confirming recording rules with the customer, we will set up the corresponding configurations on our backen system. These configurations will enable automatic recording for specific domains, application names, or stream names.	No
Selective Live Recording	Real-time recording	Call API to initiate or terminate the recording of on-air live streaming.	Yes
Selective Live Recording	Preset recording	Use API call to enable or disable the live recording configuration for live streaming that has not yet started.	Yes

2. Feature Details

2.1 Basic Live Recording

2.1.1 Feature Description

After the recording completes, the recorded files will be automatically stored in your Object Storage. The details of the recording scheme are as follows

Recording formats supported are flv, mp4 and ts.
File naming format is stream name plus the timestamp.
Chunk recording is supported, wherein one recording is done for every specified duration such as five minutes.
Audio and video processing is supported via functionalities such as transcoding, transmuxing, and watermarking.
Configurable recording callback interface is available for customers.
Support for retrying when callback notification failed is available."

2.1.2 Callback

We can call your interface to notify the customer when the recording starts or ends. And it is possible to merge notifications based on frequency or number to avoid excessive resource consumption due to frequent notifications.

Start recording notification:
Example of callback url: http://abc.com?messagetype=wsrecord_start

You will receive JSON information encoded by Base64 with URL-safe characters, and you will need to decode it to access the content. The format of the content after decoding is as follows:

{
	"persistentId": "<persistentId>",
	"streamname": "<streamname>",
	"ops": "<Record ops>",
	"bucket": "<bucket>",
	"batch_notify_id": "<batch_notify_id>"
}

Field name	Required field	Description
persistentId	Yes	Unique identifier of recording task
streamname	Yes	Live stream name, format is "application name"-"stream name".
ops	Yes	Recording parameter, including information such as output format and bit-rate.
bucket	Yes	Space name for recording storage
batch_notify_id	No	Associated ID for notification merging. If the result notification merging for multiple recording tasks is configured, the field is null.

Note: It is required to respond with a 200 status code to confirm that you have successfully received the notification.

Stop recording notification:
Example of callback url: http://abc.com?message_type=ws_record_finish
You will receive JSON information encoded by Base64 with URL-safe characters, and you will need to decode it to access the content. The format of the content after decoding is as follows:

{
    "items": [
        {
            "persistentId": "< persistentId >",
            "streamname": "<streamname>",
            "ops": "<ops>",
            "bucket": "<bucket>",
            "code": "<code>",
            "desc": "<desc>",
            "error": "<error>",
            "keys": [
                "key1",
                "key2",
                "key3"
            ],
            "urls": [
                "url1",
                "url2"
            ]
            "detail": [
        	   {
                     "key": "<key string>",
                     "url": "<url string>",
                     "duration": "<duration double>",
                     "hash": "<hash string>",
                     "fsize": "<fsize int>",
                     "startTime": "<startTime string>",
                     "endTime": "<endTime string>",
                     "bit_rate": "<bit_rate string>",
                     "resolution": "<resolution string>"
              }
      	]

        },
        {
            "persistentId": "<persistentId >",
            "streamname": "<streamname>",
            "ops": "<ops>",
            "bucket": "<bucket>",
            "code": "<code>",
            "desc": "<desc>",
            "error": "<error>",
            "keys": [
                "key1",
                "key2",
                "key3"
            ],
            "urls": [
                "url1",
                "url2"
            ]
            "detail": [
        	   {
                     "key": "<key string>",
                     "url": "<url string>",
                     "duration": "<duration double>",
                     "hash": "<hash string>",
                     "fsize": "<fsize int>",
                     "startTime": "<startTime string>",
                     "endTime": "<endTime string>",
                     "bit_rate": "<bit_rate string>",
                     "resolution": "<resolution string>"
              }
      	]

        }
    ],
    "batch_notify_id": "<batchnotifyid>"
}

Field name	Required	Description
persistentId	Yes	Unique identifier of recording task
streamname	Yes	Live stream name, format is “application name”-“stream name”.
ops	Yes	Recording parameter, including information such as output format and bit-rate.
bucket	Yes	Space name of recording storage
code	Yes	Status code of recording task. Value 1, 2 and 3 means in process, process failed and process succeeded respectively
desc	Yes	Description of task status code. Value is fileOperateActive, fileOperateFail and fileOperateSucceed, which represents in process, process failed, and process succeeded respectively.
error	No	Error description
keys	No	Output file name list. When the recording is not successful, this field is null.
urls	No	Access address list of the output file. When the recording is not successful, this field is null.
details	No	Detailed information of the output file. When the recording is not successful, this field is null.
key	No	Output file name. When the recording is not successful, this field is null.
url	No	Access address of the output file. When the recording is not successful, this field is null.
duration	No	Duration of the output video file. When the recording is not successful, this field is null.
hash	No	Hash value of the output video file. When the recording is not successful, this field is null.
fsize	No	Size of the output video file, unit is B (byte). When the recording is not successful, this field is null.
startTime	No	Start time of recording
endTime	No	End time of recording
bit_rate	No	Video bit-rate of the output file
resolution	No	Video resolution of the output file
batch_notify_id	No	Associated ID for notification merging. If result notification merging for multiple recording tasks is configured, this filed is null.

Note: It is required to respond with a 200 status code to confirm that you have successfully received the notification.

2.1.3 How to use

If customers want to enable basic live recording, they should provide the following information to CDNetworks:

Time length of recording chunk;
Naming rule of recording file;
Recording file format
Detail information of audio/video bit-rate when trans-coding is needed. Bit-rate information of each stream should be provided for multiple-bit-rate video conversion.
Their callback addresses. CDNetworks will negotiate with customer on the callback content format and the processing mechanism of callback failure.

To enable basic live recording, you’ll need to provide CDNetworks with the following information:

The desired time length for each recording chunk.
The naming rule for recordings.
The required file format for recording.
Detailed information on the required audio/video bitrate if transcoding is needed. For multi-bit-rate video conversion, bit-rate information of each stream should be provided.
Callback addresses for notification of recording status.
CDNetworks and the customer will negotiate on the callback content format and the mechanism for handling callback failures.

2.2 Selective Live Recording

2.2.1 API Description

API has access permission control, and it will only be correctly called when the account has enabled CDNetworks service and inputs parameter with certain rules. Access control policy is determined by three parameters of n, r, k, whose detailed descriptions are as follows:

n: set to Portal platform account name by default;
r: a unique random character string; 10 characters at most; recommend using timestamp
k: md5 verification value.
MD5 calculation method is: k = md5(r+key), which means that a new string, equals to r plus key, will be hashed by MD5 and converted into a new value k.
Note: you can get key from our customer service staff.
For example:
1.Apply and get the key=012f37a3f2952
2.A random character string r=1409284800 is generated
3.Merge and generate a new character string=1409284800012f37a3f2952

Calculate the new string with MD5 to get the k value: b9fed80be752551834eec3e52fa94115

2.2.2 Real-time Recording

API address:
http://livect.ossin.cdnetworks.com/v2/api/stream_listen_call.action (Used for Asia area)
http:// livect.osame.cdnetworks.com/v2/api/stream_listen_call.action (Used for Europe and America area)
We’ll use http://livect.ossin.cdnetworks.com/v2/api/stream_listen_call.action as example in below.

Start real-time recording
Method: POST

http://livect.ossin.cdnetworks.com/v2/api/stream_listen_call.action?type=record&domain=ws.test.cn&appname=test&streamnames=pushtest1, pushtest2&n=xxx&r=xxx&k=xxx

Parameter specification

Field name	Field type	Field meaning	Required field	Default value	Example
type	character string	Control type	Yes	record	record= record
domain	character string	Domain name	Yes		ws.test.com
appname	character string	Application name	Yes		test
stream names	character string	stream name	Yes		Support multiple streams, and the stream names are separated by “,”, for example: push_test1,push_test2
n	character string	User	Yes
r	character string	Random number	Yes	Current timestamp
k	character string	Verification value	Yes	Md5(r+token)

Example Response
Correct ：HTTP-CODE 200

{
    "msg": "success", // prompt
    "http_code": 200, // business status
    "trace_id": "0e06b1cb-5bfc-47e4-872f-6dac38dd0f54", // transaction record
    "call_time": "2017-08-02 11:43:34", // request time
    "list": [  // task details
        {
            "task": "flv", // file format
            "id": "test", // stream name
            "http_code": 200, // process succeed
            "msg": null,  // prompt
            "persistentId": "21_111222233344567885555544" // file identifier
        }]
}

Authentication parameter missing: HTTP-CODE 403

{
"msg": "apiName, n, r, k not exist or empty",
"http_code": 1002,
"trace_id": "74abec25-5662-4d6c-88a7-db15f7fd7e70",
"call_time": "2017-08-02 11:43:34"
}

No permission：HTTP-CODE 403
Partial failure：HTTP-CODE 200，HTTP_BODY is as follows：

{
    "msg": "stream record part of failure",
    "http_code": 1011,
    "trace_id": "cee8e3f7-e1ab-4d9c-ad98-2259045a6bac",
    "call_time": "2017-08-02 11:43:34",
    "list": [
        {
            "task": "flv",
            "id": "id",
            "http_code": 200,
            "msg": null,
            "persistentId": "21_111222233344567885555544"
        },
        {
            "task": "jpg",
            "id": "id",
            "http_code": 1007, // prompt for non-success
            "msg": "call wcs failure",  // prompt for failure
            "persistentId": null
        }]
}

Stop recording
Method: DELETE

http://livect.ossin.cdnetworks.com/v2/api/stream_listen_call.action?type=record&domain=ws.test.com&appname=test&streamnames=pushtest1,pushtest2&n=xxx&r=xxx&k=xxx

Example Response
Correct: HTTP-CODE 200，HTTP-BODY is as follows：

{
    "msg": "success",
    "http_code": 200,
    "trace_id": "8fe8e186-8435-4f6b-b38e-d30854dfe467",
    "call_time": "2017-08-02 11:43:34",
    "list": [
        {
            "task": "jpg",
            "http_code": 200,
            "msg": "success",
            "persistentId": "21_111222233344567885555544"
        }]
}

Request parameter error：HTTP-CODE 400
No permission：HTTP-CODE 403
Control task does not exist：HTTP-CODE 200，HTTP-BODY is as follows：

{
    "msg": "id:stop record param not exists;id2:stop record param not exists;",
    "http_code": 1007,
    "trace_id": "3caed803-63d4-4e2a-8a8e-abc9160e2977",
    "call_time": "2017-08-02 11:43:34",
    "list": []
}

2.2.3 Pre-set Recording

API address

http://livect.ossin.cdnetworks.com/v2/api/stream_listen_setting.action(Used for Asia area);
http://livect.osame.cdnetworks.com /v2/api/stream_listen_setting.action(Used for Europe and America area);

We’ll use http://livect.ossin.cdnetworks.com/v2/api/ stream_listen_setting.action as example in below.

Enable pre-set recording
Method: POST

http://livect.ossin.cdnetworks.com/v2/api/stream_listen_setting.action?type=record&domain=ws.test.com&appname=test&streamnames=pushtest1,pushtest2&n=xx&r=xx&k=xxx

Parameter specification

Field name	Field type	Field meaning	Required field	Default value	Example
type	character string	Control type	Yes	record	Type=record, indicates recording
domain	character string	Domain name	Yes		ws.test.com
appname	character string	Application name	No		test
stream names	character string	stream name	No		Support multiple streams, and the stream names are separated by “,”, for example: push_test1,push_test2
n	character string	User	Yes
r	character string	Random number	Yes	Current timestamp
k	character string	Verification value	Yes	Md5(r+token)

Example Response
Correct：HTTP-CODE 200，HTTP-BODY is as below：

{
    "msg": "success",
    "http_code": 200,
    "trace_id": "d891992f-ce3a-41d3-ac6e-37695e797aac",
    "call_time": "2017-08-02 11:43:34"
}

Authentication parameter is missing：HTTP-CODE 403

{
"msg": "apiName, n, r, k not exist or empty",
"http_code": 1002,
"trace_id": "74abec25-5662-4d6c-88a7-db15f7fd7e70",
"call_time": "2017-08-02 11:43:34"
}

No permission：HTTP-CODE 403

Disable pre-set recording
Method: DELETE

http://livect.ossin.cdnetworks.com/v2/api/stream_listen_setting.action?type=record&domain=ws.test.com&appname=test&streamnames=pushtest1,pushtest2&n=xx&r=xx&k=xxx

Example Response
When it is correct：HTTP-CODE 200，HTTP-BODY is as below：

{
    "msg": "success",
    "http_code": 200,
    "trace_id": "8fe8e186-8435-4f6b-b38e-d30854dfe467",
    "call_time": "2017-08-02 11:43:34",
    "list": [
        {
            "task": "jpg",
            "http_code": 200,
            "msg": "success",
            "persistentId": "21_111222233344567885555544"
        }]
}

Request parameter error：HTTP-CODE 400
No permission：HTTP-CODE 403 
Control task does not exist：HTTP-CODE 200，HTTP-BODY is as below：

{
    "msg": "id:stop record param not exists;id2:stop record param not exists;",
    "http_code": 1007,
    "trace_id": "3caed803-63d4-4e2a-8a8e-abc9160e2977",
    "call_time": "2017-08-02 11:43:34",
    "list": []
}

Query recording tasks
Method: GET

http://livect.ossin.cdnetworks.com/v2/api/stream_listen_setting.action?type=record&domain=ws.test.com&appname=test&streamnames=pushtest1,pushtest2&n=xx&r=xx&k=xxx

Return value of the recording query task
Correct：HTTP-CODE 200，HTTP-BODY is as below：

{
    "msg": "success",
    "http_code": 200,
    "trace_id": "bed5431b-2569-488e-a71c-75ab76431a04",
    "call_time": "2017-08-02 11:43:34",
    "list": [
        {
            "function": "record",
            "domain": "push.cloud-director.8686c.com",
            "appName": "live",
            "streamName": "1",
            "isDeleted": 1,
            "createTime": 1501582307
        },
        {
            "function": "record",
            "domain": "push.cloud-director.8686c.com",
            "appName": "live",
            "streamName": "2",
            "isDeleted": 1,
            "createTime": 1501582307
        }    ]
}

Authentication parameter is missing：HTTP-CODE 403

{
"msg": "apiName, n, r, k not exist or empty",
"http_code": 1002,
"trace_id": "74abec25-5662-4d6c-88a7-db15f7fd7e70",
"call_time": "2017-08-02 11:43:34"
}

No permission：HTTP-CODE 403

2.2.3 Notices

CDNetworks “Selective Live Recording” is an extension of “CDNetworks Basic Live Recording” as it is evolved from the latter, and its file storage and callback interface formats should be consistent with CDNetworks “Basic Live Recording”;
For Real-time recording, the recording can be stopped in two methods: 1. API calling; 2. anchor ends live streaming;
For Pre-set recording, domain, app name and stream names cannot be empty when default recording is configured at the granularity of stream name. For example, if the stream name is not empty (meaning default recording will be configured at the granularity of stream name), the parameter appname is also required.

2.2.4 Appendix of return code specification

Code	Prompt	Description
1001	Request parameter is incomplete	Parameter is missing
1001	Request parameter channel is error	Domain name error
1002	authentication is failure	Authentication failed
	sign is not right	Signature error
	apiName, n, r, k not exist or empty	Parameter cannot be emptyr
	random is repeat	Random number repeats
	random.lengthgt 25 or key.length ne 32	Random number length error
	Md5 is error	MD5 verification error
	you do not have right to access this api	Token value is not found, and report no permission to access the interface
	frequency is great than limitCount	Interface calling frequency is greater than limited times
	user and host not relation	Use name is not bound with this domain
1003	get liveChannelStatus from redisrealTime table error
1003	update PersistentId failure
1004	live_channel_status is not exist the record	Streams to be recorded does not exist in the real-time streams
1005	record_parameter_confis not exist the record	Recording parameter configuration does not exist
1006	record_single_stream_startwcs'sb result persistentId is empty	Recording parameter configuration is not complete
1006	persistentId is null or empty
1007		WCS interface calling failure, and the error information is provided by WCS
1007	call wsc failure	WCS calling error. For example: cannot connect to WCS, connection timeout, configured WCS address error
1008	add stream record failure	Stream recording configuration error

Media Delivery

Cloud Security

Web Performance

Enterprise Application

Storage

Edge Computing

Console Guide

API Docs

VAS_Live Recording