ApsaraVideo Live:Manage 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

• 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 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, click Domains. On the Domain Management page, find the ingest domain 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, turn on Stream Ingest Callbacks and specify 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. 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.

  • 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: 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 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, click Domains. On the Domain Management page, find the streaming domain 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, turn on Recording Callbacks and specify 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 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, click Domains. On the Domain Management page, find the streaming domain 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, turn on Snapshot Callbacks and specify 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 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: pixel.
    Height	The height of the snapshot. Unit: pixel.

  • 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 automated review

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, click Domains. On the Domain Management page, find the streaming domain 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, turn on Video Moderation Callbacks and specify a callback URL or modify the existing callback URL. For more information, see Configure callback settings.

    Note

    Only some live centers support the automated review 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, click Domains. On the Domain Management page, find the streaming domain 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, turn on Audio Moderation Callbacks and specify 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 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"
                    }
                ]
            }
        ]
    }