VAS_Real-time Screenshot

1. VAS intro

1.1 Brief introduction

With the flourishing of live streaming industry, broadcasting content through live streaming has been widely adopted and used, which is followed by increasing competitors and social issues. In response to these changes and demands, CDNetworks rolled out the feature of Real-Time Screenshot.

Basic Real-Time Screenshot
The governments have banned the porn, terrorism or other illegal content. In the interactive streaming business, live content is pushed by the anchor directly and it is hard for customer to control if the content is illegal in traditional manual identification method.

Under this situation, CDNetworks provides the service of basic real-time screenshot to help customers obtain live streaming content in the format of images, enabling video monitoring through images. When working in concert with some porn-identification APPs which identify porn by images, this feature can realize automatic identification, greatly lowering the labor cost and solving the issue of customer office network not being able to monitor hundreds of video streams simultaneously.

Meanwhile, live streaming methods are becoming increasingly diversified, and live streaming platforms need to make the live screenshot image as the cover of the streaming room or to introduce more service innovations. Basic real-time screenshot is also applicable for this type of demands.

CDNetworks supports storing real-time screenshot images in CDNetworks Cloud Storage (WCS as an abbreviation) for customers to access at any time.

Selective Real-Time Screenshot
CDNetworks screenshot function provides the feature of selective live screenshot, which enables customers to take screenshots of certain streams selected based on their business needs. The normal live streaming platforms can only take live screenshots of “key” anchors and use the them as room covers, instead of taking all anchors streaming on the platform during the platform operation.
The following is a comparison of the two features:

Features	Mode	Introduction	API
Basic Real-Time Screenshot	Mode 1	Customers call the API to take a single screenshot of an on-air live streaming.	Yes
	Mode 2	CDNetworks will negotiate the screenshot rules with customers and enable screenshot for the customers. Screenshots will be taken automatically for the screenshot enabled domains/application names/stream names.	No
Selective Real-Time Screenshot	Mode 1	Customers call the API to start or stop taking screenshots of an on-air live streaming.	Yes
	Mode 2	Customers call the API to enable or disable screenshot for a live streaming that has not started.	Yes

1.2 Applicable Product Line

Media Acceleration- Live Broadcast

1.3 Application scenarios

1. Use the screenshot to perform live streaming porn identification or other identification business.
2. Use the screenshot as the cover of a live streaming room.

2. Feature Detail

2.1 Basic Real-Time Screenshot

2.1.1 Feature Description

Currently, CDNetworks Basic Real-Time Screenshot supports two modes.

2.1.1.1 Mode 1

CDNetworks provides the real-time screenshot on demand feature. Once a customer initiates an image request, the request URL will trigger the screenshot, and CDNetworks will respond the customer with a screenshot image of live streaming. That is, CDNetworks will take one screenshot for each customer request, but will not store the screenshot image.
Customer request format: “http://www.test.com/live/livestream.jpg”
In the format example:
“www.test.com” is the domain of the new image;
“livestream.jpg” is the live streaming name.
Recommended request frequency: once per 30 seconds.

2.1.1.2 Mode 2

To reduce the labor cost and improve the efficiency of manual porn identification, and to better support the porn-identification APPs, CDNetworks provides the feature of timed screenshot for live streaming. After an anchor initiates live stream pushing, the CDNetworks WCS platform will take screenshots of the stream based on the frequency negotiated with the customer and store the screenshot images on the WCS platform. The customer API will be called to inform customers of the screenshot image.

Mode 2 is now commonly used by live streaming platforms.

Callback Descriptions of Mode 2
Callback
Proactive real-time screenshot supports to callback the customer API to inform customer of the screenshot image information. And multiple callback notifications can be merged together to avoid resource consumption caused by frequent notification.
Callback should not be too frequent, and the recommended callback frequency is once per 60S or once per 100 images.

Starting and stopping screenshot callback
Starting screenshot notification：
Example of notification address: http://abc.com?message_type=ws_record¬_start
Note: A 200 response from the notification address indicates a successful notification.

Notification content
The notification address will receive URL-safe Base64-encoded Json information, and customers need to resolve the content after receiving it. The resolved content will be in the following format:

{
    "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 screenshot task.
streamname	Yes	Live stream name, format is "application name"-"stream name".
ops	Yes	The screenshot parameter which includes the output format, frequency, etc.
bucket	Yes	Name of the WCS space in which the image is stored.
batch_notify_id	No	Associated ID for notification merging. If the result notifications of multiple screenshot tasks are merged, this field is null.

Notification of screenshot stop：
Example of notification address: http://abc.com?message_type=ws_record_finish
Note: A 200 response from the notification address indicates a successful notification.
Notification content:
The notification address will receive URL-safe Base64-encoded Json information, and the customer needs to resolve the content after receiving it. The resolved content will be in the following format:

{
    "items": [
        {
            "persistentId": "< persistentId >",
            "streamname": "<streamname>",
            "ops": "<ops>",
            "bucket": "<bucket>",
            "code": "<code>",
            "desc": "<desc>",
            "error": "<error>",
            "keys": [
                "key1",
                "key2",
                "key3"
            ],
            "urls": [
                "url1",
                "url2"
            ]
        },
        {
            "persistentId": "< persistentId >",
            "streamname": "<streamname>",
            "ops": "<ops>",
            "bucket": "<bucket>",
            "code": "<code>",
            "desc": "<desc>",
            "error": "<error>",
            "keys": [
                "key1",
                "key2",
                "key3"
            ],
            "urls": [
                "url1",
                "url2"
            ]
        }
    ],
    "batch_notify_id": "<batchnotifyid>"
}

Field name	Required	Description
persistentId	Yes	Unique identifier of screenshot task.
streamname	Yes	Live stream name, format is “application name”-“stream name”.
ops	Yes	The screenshot parameter which includes the output format, frequency, etc.
bucket	Yes	Name of the WCS space in which the image is stored.
code	Yes	Status code of the screenshot task. The values 1, 2 and 3 represent the statuses of processing, processing failed and processing succeeded respectively.
desc	Yes	Description of the task status code. Its value can be fileOperateActive, fileOperateFail and fileOperateSucceed.
error	No	Description of the error.
keys	No	Name list of the output files. If the screenshot fails, this field is empty.
urls	No	Access address list of output files. If the screenshot fails, this field is empty.
batch_notify_id	No	Correlation ID for notification merging. If the result notifications of multiple screenshot tasks are merged, this field is null.

Mode 2 supported configurations:

1. Output image format, e.g. jpg, png, etc.
2. Image height and width in pixel (px).
3. Image rotation (no rotation by default); can be configured with a rotation of 90, 180 or 270 degrees.
4. Screenshot frequency can also be configured, and the recommended frequency is once per 30S.

2.1.2 Instructions

Mode 1
To use the feature, customers need to provide the following information:

1. New domain for screenshot.
2. New domain for screenshot image accessing.
3. Screenshot frequency negotiated with CDNetworks

Mode 2
To use this feature, customers need to provide the following information:

1. The format of screenshot images; jpg and png formats are supported.
2. Callback address of the screenshot, and the callback frequency of merged notification (CDNetworks make sure the callback frequency does not affect normal services.)
3. Enable the WCS storage service of CDNetworks, and provide the live streaming platform with the store space name.
4. Real-time screenshot frequency negotiated with CDNetworks.

2.2 Selective Real-Time Screenshot

2.2.1 Feature Description

The selective Real-Time Screenshot feature of CDNetworks is realized by calling the API interface, and it has two modes:

Mode 1: Call the API interface to take screenshots of a live stream when one or multiple live streams are on-air. Screenshot taking will start when API calling starts and end when the calling is finished. It is only valid for this live streaming.

Mode 2: It supports calling at the granularity of domain, application name and stream. Before the live streaming starts, call the API interface to enable default screenshot which will initiate screenshot taking when the live streaming starts and stop it when the live streaming finishes. As long as the default screenshot is valid, screenshots will be taken for each live steaming.

API has access control permission control, which can only be called correctly when the account has enabled CDNetworks service and inputs parameter with certain rules. The access control is determined by parameters n, r and k. Following is the specification of these three parameters:

1. n: by default, it is the Portal account name;
2. r: it is a unique random character string with a maximum length of 10 characters, and timestamp is recommended.
3. k: it is the md5 authentication value.
   MD5 calculation method:
   k = md5(r+key), which means that a new string, equal to r plus key, will be hashed by MD5 and converted into a new value k. Note: “key” can be obtained from the corresponding customer service engineer.

For example:

1. Apply to get key=012f37a3f2952
2. Generate a random character string r=1409284800
3. Combine to generate the character string new=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 screenshot
POST method:
URL:http://livect.ossin.cdnetworks.com/v2/api/stream_listen_call.actiontype=frame&domain=ws.test.com&appname=test&streamnames=push_test1,push_test2&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 the call stopping example, and its request method is POST.
type	character string	Control type	Yes		type=frame, which means screenshot.
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 the start task
Correct：HTTP-CODE 200

{
    "msg": "success", // Prompt
    "http_code": 200, // Operation status
    "trace_id": "0e06b1cb-5bfc-47e4-872f-6dac38dd0f54", //Transaction record
    "call_time": "2017-08-02 11:43:34", // Request time
    "list": [  // Task details
        {
            "task": "jpg", // File format
            "id": "test", // Stream name
            "http_code": 200, // Processing succeeded
            "msg": null,  // Prompt
            "persistentId": "21_111222233344567885555544" // File ID
        }]
}

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
Partly failed：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": "jpg",
            "id": "id",
            "http_code": 200,
            "msg": null,
            "persistentId": "21_111222233344567885555544"
        },
        {
            "task": "jpg",
            "id": "id",
            "http_code": 1007, // Prompt of unsuccessful operation
            "msg": "call wcs failure",  // Prompt of operation failure 
            "persistentId": null
        }]
}

Stop screenshot

POST method：
URL:http://livect.ossin.cdnetworks.com/v2/api/stream_listen_call.action?type=frame&domain=ws.test.com&appname=test&streamnames=push_test1,push_test2&n=xxx&r=xxx&k=xxx&_method=DELETE

DELETE method：
URL:http://livect.ossin.cdnetworks.com/v2/api/stream_listen_call.action?type=frame&domain=ws.test.com&appname=test&streamnames=push_test1,push_test2&n=xxx&r=xxx&k=xxx

Return value of the stop 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 screenshot
POST method:
URL:http://livect.ossin.cdnetworks.com/v2/api/stream_listen_setting.action?type=frame&domain=ws.test.com&appname=test&streamnames=push_test1,push_test2&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 call stopping example, and its request method is POST.
type	character string	Control type	Yes		type=frame, which means screenshot.
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 screenshot
Correct：HTTP-CODE 200，HTTP-BODY is as follows：

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

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

Stop screenshot

POST method:
URL:http://livect.ossin.cdnetworks.com/v2/api/stream_listen_setting.action?type=frame&domain=ws.test.com&appname=test&streamnames=push_test1,push_test2&n=xx&r=xx&k=xxx&_method=DELETE

DELETE method:
URL:http://livect.ossin.cdnetworks.com/v2/api/stream_listen_setting.action?type=frame&domain=ws.test.com&appname=test&streamnames=push_test1,push_test2&n=xx&r=xx&k=xxx

Return value of stopping screenshot
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": []
}

screenshot query task
GET method:
URL:http://livect.ossin.cdnetworks.com/v2/api/stream_listen_setting.action?type=frame&domain=ws.test.com&appname=test&streamnames=push_test1,push_test2&n=xx&r=xx&k=xxx

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

{
    "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 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 Real-Time Screenshot” is an extension of “CDNetworks Basic Real-Time Screenshot” as it is evolved from the latter. Its file storage and callback interface formats should comply with that of the “CDNetworks Basic Real-Time Screenshot”;
• For Mode 1, The screenshot 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 description

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