VAS_Live Recording

Last update:2022-04-14 16:08:53

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.
Features Mode Introduction API
Basic Live Recording After CDNetworks negotiates with customers on the recording rules, CDNetworks will set the configuration for customers. And recording will be performed automatically for the configured domain/application name/stream name. No
Selective Live Recording Mode 1 Customer calls API to start or stop recording on-air live streaming Yes
Mode 2 Customer calls API to enable or disable the live recording configuration for live streaming which has not started. Yes

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

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.

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

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.

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

Field name Field type Field meaning Required field Default value Example
_method character string Operation type No No default value Please refer to calling example, request method 1: POST
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)

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

Field name Field type Field meaning Required field Default value Example
_method character string Operation type No No default value Please refer to the example of call stopping, request method 1: POST
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)

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

Code Prompt Description
1001 Request parameter is incomplete Parameter is missing
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
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
persistentId is null or empty
1007 WCS interface calling failure, and the error information is provided by WCS
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
Is the content of this document helpful to you?
Yes
No
Submitted successfully! Thank you very much for your feedback, we will continue to strive to do better!