VAS_Live Recording

更新时间:2023-06-25 17:32:47

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

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

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.

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

  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
  1. 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
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
本篇文档内容对您是否有帮助?
有帮助
我要反馈
提交成功!非常感谢您的反馈,我们会继续努力做到更好!