1. VAS intro

1.1 Brief introduction

The development of live streaming industry ushers in a popular content proliferation method of live streaming in the Internet, followed by the influx of more and more competitors and social problems. To cope with these changes and demands, CDNetworks rolls out the live recording feature.

Basic Live Recording
The VoD review of live streaming has become a necessary feature for live streaming platforms. In addition, many countries have issued regulatory rules to supervise the platform in response to the rapid development of live streaming industry across the world, the local storage of live streaming content is required in many countries for future inspection.
Compared with live recording by self-built origin, CDN live recording has overwhelming advantages in terms of cost. CDNetworks live recording product is a combination of CDNetworks live streaming and CDNetworks Cloud Storage (WCS as an abbreviation), working as a one-stop solution for recording plus storage.

Selective Live Recording
In addition to the basic live recording feature, which is pre-configured in live domains with the cooperation of CDN, CDNetworks develops the “selective live recording” feature, with which customers can selectively record part of their streams based on their business need.

The feature is mainly applied in aspects below:

• It offers services for the already-hot live content. To maintain the heat of classic content, live streaming platforms need to replay it or offer video-on-demand service after live streaming ends.
• If the content for replay and VoD is not required by the whole platform. As the basic live recording is not capable of precisely selecting specific live content, start time or end time, the selective live recording feature is a good pick for customers who need to selectively record live content.

1.2 Applicable Product Line

• Media Acceleration- Live Broadcast.

1.3 Applicable Scenarios

1. Record content played on the live stream platform for future inspection in accordance with the requirement of Provisions on the Administration of Internet Live-Streaming Services
2. Reserve the fascinating content of anchors for second wave publicity and for enriching VoD programs of platforms.
3. Retain the heat by replaying key sport events and popular live streaming.

2. Feature Detail

2.1 Basic Live Recording

2.1.1 Feature Description

After a live recording file is generated, the live streaming file will be uploaded to WCS, and the one-stop service of recording+storage+transcoding can be implemented. The time-effectiveness of converting live streaming to VoD can be controlled at the granularity of second.
The recording scheme is elaborated as below.

1. Recording format: support flv, mp4 and ts.
2. File naming format: stream name+timestamp
3. Support chunk recording by time length, such as one recording every 5 minutes.
4. Support audio/video processing such as transcoding, transmuxing and watermarking.
5. Support configurable recording callback of customer interface.
6. Support retry when callback notification failed.

2.1.2 Callback Description

Starting and stopping recording callback
CDNetworks notifies customer through customer interface callback when recording starts and ends. The callback is timely and high-efficient, with the granularity at second level. And the notification can be merged according to the frequency and number to avoid resource waste caused by frequent notification.
Starting recording notification:
Notification address example: http://abc.com?messagetype=wsrecord¬_start
Note: notification is successful when the address responds 200.

Notification content:
The notification address will receive Json information encoded by URL security Base64, and customers will resolve it to get the content. The content format after resolution is as follows:

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

Stop recording notification:
Notification address example: http://abc.com?message_type=wsrecordfinish
Notes: notification is successful when the address responds 200.
The notification address will receive Json information encoded by URL security Base64, and customers need to resolve it to get the content. The content format after resolution 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>"
}

2.1.3 Instructions

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.

2.2 Selective Live Recording

2.2.1 Feature Description

CDNetworks selective live recording is implemented via API calling, and it can be divided into two modes:
Mode 1: call API to record live streaming when one or more streams start. Recording starts when API is called, and ends when calling is finished. The configuration takes effect only on this live streaming.
Mode 2: support calling at the granularity of domain name, application name and stream. Call API to enable default recording when the live streaming has not started yet. With this feature, recording will start when live streaming begins, and ends when it finishes. Every live streaming will be recorded when the default configuration is enabled.

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 Interface Description

2.2.2.1 Interface of Mode 1

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: POST method
URL: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

Return value of the starting task
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
POST method:
URL: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&_method=DELETE

DELETE method:
URL: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

Return value of the stopping task
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.2.2 Interface of Mode 2

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.

Start default recording
POST method：
URL: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

Return value of starting recording
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

Stop recording
POST method：
URL: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&_method=DELETE
DELETE method：
URL: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 stopping recording
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": []
}

Recording query task
GET method：
URL: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 Mode 1, the recording can be stopped in two methods: 1. API calling; 2. anchor ends live streaming;
• For Mode 2, 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