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:

1. 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.
2. 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.

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.

1. 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>"
}

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

2. 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>"
}

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:

1. Time length of recording chunk;
2. Naming rule of recording file;
3. Recording file format
4. 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.
5. 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:

1. n: set to Portal platform account name by default;
2. r: a unique random character string; 10 characters at most; recommend using timestamp
3. 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

4. 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

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

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