Manage live streaming callbacks - ApsaraVideo Live - Alibaba Cloud Documentation Center

ApsaraVideo Live supports callbacks for stream ingest status, live stream recording, on-demand recording, live stream snapshot, and content moderation. This topic describes the configuration methods, parameters, and examples of these callbacks.

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 request passes verification, 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 snapshot
Content moderation

Callback methods

ApsaraVideo Live supports event notifications by using HTTP and HTTPS callbacks. You must deploy an HTTP service to receive callback messages and configure a callback URL by using the ApsaraVideo Live console or 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 configure a callback URL by using the ApsaraVideo Live console or calling an API operation.

Configuration methods

Use the ApsaraVideo Live console
Log on to the ApsaraVideo Live console. In the left-side navigation pane, choose Feature Management > Callbacks. On the Callbacks page, select the domain name that you want to configure. On the Callback Settings tab, turn on Stream Ingest Callbacks and specify a callback URL or modify the existing callback URL. For more information, see Stream ingest callbacks.

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. If the stream ingest client does not close the connection, ApsaraVideo Live sends a callback notification about the successful stream ingest.
2. Assume that you have Ingest Domain A and Streaming Domain B that are associated with each other, and you 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, the same callback logic as the preceding applies to stream pulling under Streaming Domain B. By default, stream pulling is considered successful if the client does not close the connection within 2 seconds.
Note
- We recommend that you issue the streaming URL after you confirm that the stream ingest or pulling is successful based on callback notifications and the response to your call of the DescribeLiveStreamsOnlineList operation.
- ApsaraVideo Live automatically terminates stream ingest when no streaming data is pushed to the live center for 10 seconds.

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 available, a streaming domain is used.
appname	The name of the application that ingests the stream.
time	The UNIX timestamp. Unit: seconds.
usrargs	The custom parameters that are used to ingest the stream.
node	The name of the point of presence (POP) or the host that receives the stream.
height	The height of the resolution. Unit: pixels. 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: pixels.

Sample callback for successful stream ingest:

http://1.1.X.X?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.X.X?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
By default, authentication for stream ingest callbacks is disabled. You can enable the feature when you specify the stream ingest callback URL. After you enable the feature, the following authentication logic applies:
1. When ApsaraVideo Live initiates a callback request, it includes the ALI-LIVE-TIMESTAMP and ALI-LIVE-SIGNATURE headers in the HTTP or HTTPS request so that the callback message receiving server can authenticate the signature. The value of ALI-LIVE-SIGNATURE is calculated based on the following formula:
  ALI-LIVE-SIGNATURE = MD5SUM (MD5CONTENT)
  MD5CONTENT = Domain name|ALI-LIVE-TIMESTAMP value|Cryptographic key
  Note
  Domain name is the ingest domain for which you configure the callback URL. Cryptographic key is the cryptographic key that you specify for the callback URL.
2. After receiving a callback message, the callback message receiving server concatenates the domain name of the callback, value of the ALI-LIVE-TIMESTAMP header, and cryptographic key in the preceding format. The server calculates the MD5 value of the string to obtain an encrypted string. Then, the server compares the encrypted string with the value of the ALI-LIVE-SIGNATURE header in the HTTP or HTTPS request initiated by ApsaraVideo Live. If the two values are different, the request is invalid.

Callbacks for live stream recording

Callbacks for live stream recording include recording status callbacks and file generation callbacks. You can configure these callbacks by using the ApsaraVideo Live console or 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 pane, choose Feature Management > Callbacks. On the Callbacks page, select the domain name that you want to configure. On the Callback Settings tab, turn on Recording Callbacks and specify a callback URL or modify the existing callback URL. For more information, see Recording callbacks.

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 recording 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, as in `callback_args1=value1&callback_args1=value2`, 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 snapshot

ApsaraVideo Live supports callbacks for live stream snapshot. You can configure a callback URL by using the ApsaraVideo Live console or calling an API operation.

Configure callbacks for live stream snapshot

Use the ApsaraVideo Live console
Log on to the ApsaraVideo Live console. In the left-side navigation pane, choose Feature Management > Callbacks. On the Callbacks page, select the domain name that you want to configure. On the Callback Settings tab, turn on Snapshot Callbacks and specify a callback URL or modify the existing callback URL. For more information, see Snapshot callbacks.

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 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 snapshot. For more information, see SetSnapshotCallbackAuth and Usage notes for callback authentication.

Callbacks for content moderation

ApsaraVideo Live supports callbacks for video moderation and audio moderation results. You can configure a callback URL by using the ApsaraVideo Live console or 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, choose Feature Management > Callbacks. On the Callbacks page, select the domain name that you want to configure. On the Callback Settings tab, turn on Video Moderation Callbacks and specify a callback URL or modify the existing callback URL. For more information, see Video moderation callbacks.
Note
Only some live centers support the content moderation feature. 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 name of the OSS bucket.
OssObject	String	The name of the OSS object.
Result	JSONArray	The video moderation results. For more information, see Attributes of the Result parameter.

Table 1. Attributes of the Result parameter

Attribute	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: terrorism 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 ad npx: illegal ad qrcode: QR code programCode: mini program code If Scene is set to live, the valid values are: normal meaningless: no content in the image, such as black or white screen PIP: picture-in-picture smoking drivelive: live streaming in a running vehicle If Scene is set to logo, the valid values are: normal TV: controlled logo 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. If you are an existing user and want to use this version, submit a ticket. For more information, see Contact us.

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, choose Feature Management > Callbacks. On the Callbacks page, select the domain name that you want to configure. On the Callback Settings tab, turn on Audio Moderation Callbacks and specify a callback URL or modify the existing callback URL. For more information, see Audio moderation callbacks.

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 Attributes of the result parameter.

Table 2. Attributes of the result parameter

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
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 Fields of the details attribute.

Table 3. Fields of the details attribute

Field	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

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