Back
Media Acceleration Live Broadcast
CDNetworks Documentation Media Acceleration Live Broadcast VAS_Real-time Screenshot

VAS_Real-time Screenshot

Last update：2022-04-14 16:08:55

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
Is the content of this document helpful to you?
Yes
I have suggestion
Submitted successfully! Thank you very much for your feedback, we will continue to strive to do better!

CDNetworks Inc., © 2024. 1840 Enterprise Way, Monrovia, CA 91016 – All rights reserved.