Manage callbacks - ApsaraVideo Live - Alibaba Cloud Documentation Center

Overview

When an event is triggered during live streaming, Alibaba Cloud sends a request to your server and your server then responds to the request. After the verification is passed, a callback message that contains JSON-formatted data is returned to you.

ApsaraVideo Live supports callbacks for the following events:

Stream ingest status
Live stream recording
On-demand recording
Live stream snapshots
Automated review

Callback methods

ApsaraVideo Live supports event notifications by using HTTP and HTTPS callbacks. You must deploy an HTTP service to receive callback messages and specify a callback URL in the ApsaraVideo Live console or by calling an API operation.

When stream ingest is initiated or interrupted, ApsaraVideo Live sends an HTTP GET request to the specified callback URL. The specific event content is included in the URL parameters.
When other events are triggered, ApsaraVideo Live sends an HTTP POST request to the specified callback URL. The specific event content is included in the JSON-formatted request body.

Usage notes

A callback URL requires no identifier but must be accessible. If no response is returned from the URL within a specific timeout period, ApsaraVideo Live performs retries to access the URL. The current timeout period is 5 seconds. If no response is returned within 5 seconds, ApsaraVideo Live performs retries to access the URL for a maximum of five times at an interval of 1 second.

Callbacks for stream ingest status

You can configure callbacks to receive the notifications of stream ingest status under a domain name, such as successful or interrupted stream ingest. You can specify a callback URL in the ApsaraVideo Live console or by calling an API operation.

Configuration methods

Use the ApsaraVideo Live console
Log on to the ApsaraVideo Live console. In the left-side navigation bar, click Domains. On the Domains page, find the domain name that you want to configure and click Domain Settings in the Actions column. On the page that appears, choose Streaming Management > Callbacks. On the Callback Settings tab, enable Stream Ingest Callbacks. In the dialog box that appears, add a callback URL or modify the existing callback URL. For more information, see Configure callback settings.

Call an API operation


Operation	Description	References
SetLiveStreamsNotifyUrlConfig	Configures stream ingest callbacks under an ingest domain.	SetLiveStreamsNotifyUrlConfig
DescribeLiveStreamsNotifyUrlConfig	Queries the callback configuration for stream ingest under an ingest domain.	DescribeLiveStreamsNotifyUrlConfig
DeleteLiveStreamsNotifyUrlConfig	Deletes the callback configuration for stream ingest under an ingest domain.	DeleteLiveStreamsNotifyUrlConfig

Callbacks

The callback parameters are encapsulated in a MultiDict.

Callback logic
1. During stream ingest over Real-Time Messaging Protocol (RTMP), ApsaraVideo Live checks whether the stream ingest client closes the connection within 2 seconds after ApsaraVideo Live receives an OnPublish message.
2. For example, you have Ingest Domain A and Streaming Domain B. You can configure regular stream pulling and triggered stream pulling for Streaming Domain B. If you want to receive callback notifications about the stream pulling status, configure stream ingest callbacks for Ingest Domain A. After the configuration is complete, the preceding callback logic is used for Streaming Domain B. By default, stream pulling is considered successful if the connection is established for 2 seconds.
Note We recommend that you release the streaming URL after you confirm that the stream ingest or pulling is successful based on callback notifications and the results of the DescribeLiveStreamsOnlineList operation.

Callback parameters


Parameter	Description
action	The name of the event. Valid values: publish: stream ingest publish_done: stream interruption
ip	The IP address of the stream ingest client.
id	The name of the ingested stream.
app	The ingest domain. The default value is a custom ingest domain. If no ingest domain is bound, a streaming domain is used.
appname	The name of the application that ingests the stream.
time	UNIX timestamp. Unit: seconds.
usrargs	The custom parameters that are used to ingest the stream.
node	The name of the Alibaba Cloud CDN node or the host that receives the stream.
height	The height of the resolution. Unit: pixel. Note The height and width of the resolution are returned only when the callback is invoked for the first time.
width	The width of the resolution. Unit: pixel.

Sample callback for successful stream ingest:

http://1.1.1.1?action=publish&ip=192.168.0.1&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={Custom parameters}&
node=cdnvideocenter01020711****.cm3&height=720&width=1280

Sample callback for interrupted stream ingest:

http://1.1.1.1?action=publish_done&ip=192.168.0.0&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={Custom parameters}&
node=cdnvideocenter01020711****.cm3&height=720&width=1280

Callback authentication
The callback authentication is disabled by default. You can enable it while configuring the callback URL. The authentication logic is as follows:
1. ApsaraVideo Live includes the ALI-LIVE-TIMESTAMP and ALI-LIVE-SIGNATURE fields in the HTTP(S) request header when sending callback information to the callback URL. The value of ALI-LIVE-SIGNATURE is calculated using the following formula:
  ALI-LIVE-SIGNATURE=MD5SUM (MD5CONTENT)
  
  MD5CONTENT=Stream pushing domain name|Value of ALI-LIVE-TIMESTAMP|Cryptographic key
  
  Note The Stream pushing domain name refers to the domain to which the callback URL is configured. The Cryptographic key refers to the authentication key for the callback URL.
2. The server that hosts the callback URL generates an MD5 hash from a concatenated string of the stream pushing domain name, the value of ALI-LIVE-TIMESTAMP, and the cryptographic key. It then compares the MD5 hash with the value of ALI-LIVE-SIGNATURE in the HTTP(S) request header. If the MD5 hash is not consistent with the value of ALI-LIVE-SIGNATURE, the request is considered invalid.

Callbacks for live stream recording

Callbacks for live stream recording include recording status callbacks and file generation callbacks. You can configure these callbacks in the ApsaraVideo Live console or by calling an API operation.

Recording status callbacks: invoked when recording starts or ends. The callback message notifies you that recording starts or ends.
File generation callbacks: invoked when recordings are generated. The callback message contains the name, start time, end time, and duration of a recording.

Configuration methods

Use the ApsaraVideo Live console
Log on to the ApsaraVideo Live console. In the left-side navigation bar, click Domains. On the Domains page, find the domain name that you want to configure and click Domain Settings in the Actions column. On the page that appears, choose Streaming Management > Callbacks. On the Callback Settings tab, enable Recording Callbacks. In the dialog box that appears, add a callback URL or modify the existing callback URL. For more information, see Configure callback settings.

Call an API operation


Operation	Description	References
AddLiveRecordNotifyConfig	Configures callbacks for live stream recording under a domain name. To enable recording status callbacks, set the NeedStatusNotify parameter to true.	AddLiveRecordNotifyConfig
DescribeLiveRecordNotifyConfig	Queries the configuration of callbacks for live stream recording under a domain name.	DescribeLiveRecordNotifyConfig
DeleteLiveRecordNotifyConfig	Deletes the configuration of callbacks for live stream recording under a domain name.	DeleteLiveRecordNotifyConfig

Recording status callbacks

Callback parameters


Parameter	Description
domain	The streaming domain.
app	The name of the application.
stream	The name of the stream.
event	The name of the event. record_started: Recording is started. record_paused: Recording is paused. record_resumed: Recording is resumed.

Sample callback

{
"domain": "demo.aliyundoc.com",
"app": "liveApp****",
"stream": "liveStream****",
"event": "record_started"
}

File generation callbacks

Callback parameters


Parameter	Description
domain	The streaming domain.
app	The name of the application.
stream	The name of the stream.
uri	The storage path of the recordings in the specified Object Storage Service (OSS) bucket.
duration	The duration of the recording content. Unit: seconds.
start_time	The recording start time. The time is a UNIX timestamp. Unit: seconds.
stop_time	The recording end time. The time is a UNIX timestamp. Unit: seconds.
push_args	The stream ingest parameters that are prefixed with callback_, such as callback_arg1 and callback_myid. Note Each parameter supports only one value. If you pass multiple values to a parameter, the callback returns only the first value that is passed to the parameter. For example, if you pass value1 and then value2 to the `callback_args1` parameter, the callback returns only `"callback_args1": "value1"`.

Sample callback

Example stream ingest URL:

rtmp://demo.aliyundoc.com/liveApp****/liveStream****?callback_args1=value1&callback_myid=1231389741

Example callback content:

{
  "domain": "demo.aliyundoc.com",
  "app": "liveApp****",
  "stream": "liveStream****",
  "uri": "liveApp****/liveStream****/0_2017-03-08-23:09:46_2017-03-08-23:10:40.flv",
  "duration": 69.403,
  "start_time": 1488985786,
  "stop_time": 1488985840,
  "push_args": {
    "callback_args1": "value1",
    "callback_myid": "1231389741"
  }
}

Note The preceding sample callback notification is applicable if you have no custom callback templates.

Callbacks for on-demand recording

Before on-demand recording starts, a callback for on-demand recording is invoked to pass the parameters of a live stream to you. Then, you can determine whether recording is required.

To configure callbacks for on-demand recording, you must specify a callback URL, a domain name, and an application or a live stream. When ApsaraVideo Live receives a recording request that matches the specified domain name, application, or live stream, ApsaraVideo Live sends a request to the specified callback URL so that you can determine whether the live stream needs to be recorded. The request contains five parameters.

Request parameters


Parameter	Type	Description
domain	String	The main streaming domain.
app	String	The name of the application to which the live stream belongs.
stream	String	The name of the live stream.
codec	String	The encoding format. Valid values: h264 h265
vbitrate	String	The bitrate of the video. Unit: Kbit/s.

Response parameters


Parameter	Type	Required	Description
ApiVersion	String	No	The version of the API. The default version is 1.0.
NeedRecord	Bool	Yes	Indicates whether recording is required.
Interval	JSONObject	No	The duration of the recording in each format in each cycle. Valid values: 5 to 21600. Unit: seconds.
Format	JSONArray	No	The format of the recording. The recording can be in the MP4, FLV, or M3U8 format.

Sample request

GET /?app=seq_all&domain=demo.aliyundoc.com&stream=ondemand8&vbitrate=2000&codec=h264 HTTP/1.1
Host: pull.aliyundoc.com
User-Agent: Go-http-client/1.1
Accept-Encoding: gzip

Sample response

{
    "ApiVersion" : "1.0",
    "NeedRecord" : true,
    "Interval" : {
        "Mp4": 300,
        "Flv": 120,
        "M3U8": 180
    },
    "Format" : ["mp4","flv"]
}

Processing of response parameters
ApsaraVideo Live uses the returned parameter settings to overwrite or modify the existing recording configuration. For example, if the Interval parameter is returned, ApsaraVideo Live uses the return value to overwrite the value of the Interval parameter in the existing recording configuration. If the Format parameter is returned, ApsaraVideo Live uses the intersection of the formats specified by the returned Format parameter and the formats specified in the existing recording configuration. If none of the formats specified by the returned Format parameter are in the existing recording configuration, the live stream is not recorded.
Note
- If a non-200 HTTP status code is returned, an error occurred.
- The request body cannot exceed 2,048 characters in length. Otherwise, the body is truncated to prevent malicious attacks.

Callbacks for live stream snapshots

ApsaraVideo Live supports callbacks for video moderation and audio moderation results. You can set a callback URL by using the ApsaraVideo Live console or API.

Configure callbacks for live stream snapshots

Use the ApsaraVideo Live console
Log on to the ApsaraVideo Live console. In the left-side navigation bar, click Domains. On the Domains page, find the domain name that you want to configure and click Domain Settings in the Actions column. On the page that appears, choose Streaming Management > Callbacks. On the Callback Settings tab, enable Snapshot Callbacks. In the dialog box that appears, add a callback URL or modify the existing callback URL. For more information, see Configure callback settings.

Call an API operation


Operation	Description	References
AddLiveSnapshotNotifyConfig	Configures snapshot callbacks.	AddLiveSnapshotNotifyConfig
UpdateLiveSnapshotNotifyConfig	Modifies the configuration of snapshot callbacks.	UpdateLiveSnapshotNotifyConfig
DescribeLiveSnapshotNotifyConfig	Queries the configuration of snapshot callbacks.	DescribeLiveSnapshotNotifyConfig
DeleteLiveSnapshotNotifyConfig	Deletes the configuration of snapshot callbacks.	DeleteLiveSnapshotNotifyConfig

Callback parameters


Parameter	Description
Event	The name of the event.
DomainName	The streaming domain.
AppName	The name of the application.
StreamName	The name of the stream.
OssBucket	The name of the Object Storage Service (OSS) bucket in which the snapshot is stored.
OssEndpoint	The endpoint of the OSS bucket in which the snapshot is stored.
OssObject	The name of the snapshot.
CreateTime	The point in time at which the snapshot is captured.
SnapshotUrl	The storage path of the snapshot in the specified OSS bucket.
Size	The size of the snapshot.
Width	The width of the snapshot. Unit: pixels.
Height	The height of the snapshot. Unit: pixels.

Sample callback

{
    "Event":"Snapshot",
    "DomainName":"demo.aliyundoc.com",
    "AppName":"liveApp****",
    "StreamName":"liveStream****",
    "OssBucket":"liveBucket****",
    "OssEndpoint":"oss-cn-shan****.aliyuncs.com",
    "OssObject":"1****.jpg",
    "CreateTime":"2015-12-01T17:36:00Z",
    "SnapshotUrl":"http://liveBucket****.oss-cn-shan****.aliyuncs.com/1****.jpg",
    "Size":"36291",
    "Width":"1280",
    "Height":"720"
}

You can configure authentication for callbacks for live stream snapshots. For more information, see SetSnapshotCallbackAuth and Usage notes for callback authentication.

Callbacks for automated review

ApsaraVideo Live supports callbacks for video moderation and audio moderation results. You can specify a callback URL in the ApsaraVideo Live console or by calling an API operation.

Configure callbacks for video moderation results

Use the ApsaraVideo Live console
Log on to the ApsaraVideo Live console. In the left-side navigation pane, click Domains. On the Domains page, find the domain name that you want to configure and click Domain Settings in the Actions column. On the page that appears, choose Streaming Management > Callbacks. On the Callback Settings tab, enable Video Moderation Callbacks. In the dialog box that appears, add a callback URL or modify the existing callback URL. For more information, see Configure callback settings.

Note Only specific live centers support content moderation. For more information, see Supported regions.

Call an API operation


Operation	Description	References
AddLiveDetectNotifyConfig	Configures callbacks for video moderation results.	AddLiveDetectNotifyConfig
DescribeLiveAudioAuditNotifyConfig	Queries the configuration of callbacks for video moderation results.	DescribeLiveDetectNotifyConfig
UpdateLiveDetectNotifyConfig	Modifies the configuration of callbacks for video moderation results.	UpdateLiveDetectNotifyConfig
DeleteLiveDetectNotifyConfig	Deletes the configuration of callbacks for video moderation results.	DeleteLiveDetectNotifyConfig

Callbacks for video moderation results

ApsaraVideo Live sends a callback message only when illegal video content is detected. The callback message contains the review information and storage information of the illegal video content.

Callback parameters


Parameter	Type	Description
DomainName	String	The streaming domain.
AppName	String	The name of the application.
StreamName	String	The name of the stream.
OssEndpoint	String	The endpoint of the OSS bucket.
OssBucket	String	The bucket where the OSS object is stored.
OssObject	String	The name of the OSS object.
Result	JSONArray	The video moderation results. For more information, see Result.

Table 1. Result
Parameter	Type	Description
BizType	String	The business type. You can specify a model. The default value is the domain name.
Scene	String	The moderation scenario. Valid values: porn: pornographic content terrorism: terrorist or politically sensitive content ad: ad violation live: undesirable scene logo: logo image
Label	String	The category of the moderation results. Valid values vary based on the specified moderation scenario. If Scene is set to porn, the valid values are: normal sexy porn If Scene is set to terrorism, the valid values are: normal bloody explosion outfit logo weapon politics violence crowd parade carcrash flag location others If Scene is set to ad, the valid values are: normal: normal content ad: ad violation npx: illegal ad qrcode: QR code programCode: mini program code If Scene is set to live, the valid values are: normal: normal content meaningless: no content in the image, such as black or white screen PIP: picture-in-picture smoking: smoking drivelive: live streaming in a running vehicle If Scene is set to logo, the valid values are: normal: normal content TV: controlled logo trademark: trademark
Rate	Float	The score of the confidence level. Valid values: 0 to 100. A greater value indicates a higher confidence level. Note This score is only for reference. We strongly recommend that you not use this score in your business. We recommend that you determine whether there is illegal content based on the value of the Label attribute.
Extent	String	The reserved attribute.

Note By default, this version is used for new users. Existing users can submit a ticket. For more information, see Contact us. to apply for use of this version.

Sample callback

{
 "DomainName": "demo.aliyundoc.com",
 "AppName": "liveApp****",
 "StreamName": "liveStream****",
 "OssEndpoint": "oss-cn-hang****.aliyuncs.com",
 "OssBucket": "liveBucket****",
 "OssObject": "example.jpg",
 "Result": [
     {
         "BizType": "demo.aliyundoc.com",
         "Result": [
             {"Label": "Porn", "Rate":11, "Suggestion": "review", "Scene":"porn", "Extent": {}},
             {"Label": "Ad", "Rate":11, "Suggestion": "review", "Scene":"ad", "Extent": {}}
         ]
     }
 ]
}

Configure callbacks for audio moderation results

Use the ApsaraVideo Live console
Log on to the ApsaraVideo Live console. In the left-side navigation pane, click Domains. On the Domains page, find the domain name that you want to configure and click Domain Settings in the Actions column. On the page that appears, choose Streaming Management > Callbacks. On the Callback Settings tab, enable Audio Moderation Callbacks. In the dialog box that appears, add a callback URL or modify the existing callback URL. For more information, see Configure callback settings.

Call an API operation


Operation	Description	References
AddLiveAudioAuditNotifyConfig	Configures callbacks for audio moderation results. Important Callbacks for audio moderation results are returned in the form of a JSON string.	AddLiveAudioAuditNotifyConfig
DeleteLiveAudioAuditNotifyConfig	Deletes the configuration of callbacks for audio moderation results.	DeleteLiveAudioAuditNotifyConfig
UpdateLiveAudioAuditNotifyConfig	Modifies the configuration of callbacks for audio moderation results.	UpdateLiveAudioAuditNotifyConfig
DescribeLiveAudioAuditNotifyConfig	Queries the configuration of callbacks for audio moderation results.	DescribeLiveAudioAuditNotifyConfig

Callbacks for audio moderation results

ApsaraVideo Live sends a callback message only when illegal audio content is detected. The callback message contains the detected text of the illegal audio content and the context in the last minute.

Callback parameters


Parameter	Type	Description
domain	String	The streaming domain.
app	String	The name of the application.
stream	String	The name of the stream.
timestamp	Int	The timestamp of the callback. Unit: seconds.
result	JSONArray	The audio moderation results. For more information, see Result.

Table 2. Result
Attribute	Type	Description
scene	String	The moderation scenario.
label	String	The category of the moderation results. Valid values: normal spam ad politics terrorism abuse porn flood: excessive junk content contraband: prohibited content meaningless customized: custom content, such as a custom term
suggestion	String	The recommended subsequent operation for you to perform. Valid values: pass: The moderated audio does not require further actions. review: The moderated audio contains suspected violations and requires human review. block: The moderated audio contains violations. We recommend that you delete or block the audio.
rate	Float	The score of the confidence level. Valid values: 0 to 100. A greater value indicates a higher confidence level. Note This score is only for reference. We strongly recommend that you not use this score in your business. We recommend that you determine whether there is illegal content based on the value of the label attribute.
details	JSONArray	The details about the text in the moderated audio. The value is a JSON array that contains one or more elements. Each element corresponds to a text entry. For more information about the structure of each element, see Attributes of the details parameter.

Table 3. Attributes of the details parameter
Attribute	Type	Description
startTime	Int	The start time of the text entry. Unit: seconds.
endTime	Int	The end time of the text entry. Unit: seconds.
text	String	The content of the text entry that is converted from the audio.
label	String	The category of the moderation results. Valid values: normal spam ad politics terrorism abuse porn flood: excessive junk content contraband: prohibited content meaningless customized: custom content, such as a custom term

Sample callback

{
    "domain": "example.aliyundoc.com",
    "app": "liveApp****",
    "stream": "5d9747eba39b44769852d276f9ff****",
    "timestamp": 1572248095,
    "result": [
        {
            "scene": "antispam",
            "label": "ad",
            "suggestion": "block",
            "rate": 99.91,
            "details": [
                {
                    "startTime": 1572248023,
                    "endTime": 1572248040,
                    "text": "You can share the privilege of 120-day free stay in hotels in Lijiang and Longchuan with your friends and relatives. Welcome to Yunqi International Hotel. The hotel is located next to Dengchao KTV, No. 96, Tuanjie Street, Mang City. The hotel phone number is 2285699.",
                    "label": "ad"
                },
                {
                    "startTime": 1572248040,
                    "endTime": 1572248070,
                    "text": "Classic villas near warm springs such as Longduo Spring, Lianghe Jinta Spring, and Spring Tourist Town in Binjiangyuan are available for sale on November 2. We offer various layouts, classic designs, and attractive prices. Buy a villa and then you can enjoy spring at home. Welcome to visit the villas. The address is No. 229, Xianfeng Road, Zhedao Town, Ranhe County. Call our hotline at 0692695577769***.
",
                    "label": "normal"
                },
                {
                    "startTime": 1572248072,
                    "endTime": 1572248077,
                    "text": "Happy time with you is great.",
                    "label": "normal"
                },
                {
                    "startTime": 1572248078,
                    "endTime": 1572248086,
                    "text": "fme043 Snatch a little leisure from a busy life. With songs, I feel relaxed. With films, I miss you.",
                    "label": "normal"
                }
            ]
        }
    ]
}