ApsaraVideo Live supports callbacks for live stream pushing status, live stream recording, on-demand recording, live streaming snapshots, and automated review. This topic describes the configuration methods, parameters, and examples of such 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 verification is passed, a callback message that contains JSON-formatted data is returned to you.

ApsaraVideo Live supports callbacks for the following events:

Callback methods

ApsaraVideo Live supports event notifications by using HTTP and HTTPS callbacks.

You must deploy an HTTP service to receive callback messages and set a callback URL in the ApsaraVideo Live console or by calling API operations. When an event is generated, ApsaraVideo Live sends an HTTP GET request to the specified callback URL. The specific event content is sent in the HTTP request body.

Usage notes

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

Callbacks for live stream pushing status

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

  • How to configure callbacks for live stream pushing status
    • Use the ApsaraVideo Live console

      Log on to the ApsaraVideo Live console and go to the Domains page. Find the stream pushing domain that you want to configure and click Domain Settings. Choose Stream Management > Basic Settings. Click the Stream Ingest Information tab. On the Stream Ingest Information tab, set or modify the callback URL for stream pushing.

    • Call API operations
      Operation Description Reference
      SetLiveStreamsNotifyUrlConfig Configures stream pushing callbacks for a stream pushing domain. SetLiveStreamsNotifyUrlConfig
      DescribeLiveStreamsNotifyUrlConfig Queries the callback configuration for stream pushing under a stream pushing domain. DescribeLiveStreamsNotifyUrlConfig
      DeleteLiveStreamsNotifyUrlConfig Deletes the callback configuration for stream pushing under a stream pushing domain. DeleteLiveStreamsNotifyUrlConfig
  • Callbacks for live stream pushing status

    The callback parameters are stored in a MultiDict.

    • Callback logic for live stream pushing status
      1. During stream pushing over Real-Time Messaging Protocol (RTMP), ApsaraVideo Live checks whether the stream pushing client closes the connection within 2 seconds after ApsaraVideo Live receives an OnPublish message. If the stream pushing client does not close the connection, ApsaraVideo Live sends a callback notification about successful stream pushing. You may require ApsaraVideo Live to send this callback notification only when ApsaraVideo Live receives live streaming data after the connection is established. In this case, submit a ticket.
      2. Assume that you have stream pushing domain A and streaming domain B, and you use the stream pulling feature for live streaming under streaming domain B. You can configure ApsaraVideo Live to pull a stream at the specified time, or enable ApsaraVideo Live to automatically pull a stream when the origin server starts live streaming. If you want to receive a callback notification about the stream pulling status, configure stream pushing callbacks for stream pushing domain A. After the configuration, ApsaraVideo Live uses the same callback logic as that for live stream pushing status to send callback notifications about the stream pulling status under streaming domain B. By default, ApsaraVideo Live sends a callback notification about successful stream pulling if the stream pulling client does not close the connection within 2 seconds after the connection is established. If you require ApsaraVideo Live to send this callback notification only when live streaming data is received, submit a ticket.
      Note We recommend that you deliver the streaming URL only after you determine that stream pushing or pulling is successful based on callback notifications and the list of online streams.
    • The following table describes the parameters that are used to configure callbacks for live stream pushing status.
      Parameter Description
      action The name of the event. Valid values:
      • publish: stream pushing
      • publish_done: stream interruption
      ip The IP address of the client that pushes the stream.
      id The name of the pushed stream.
      app The stream pushing domain. The default value is a custom stream pushing domain. If no stream pushing domain is bound, a streaming domain is used.
      appname The name of the application that pushes the stream.
      time The UNIX timestamp. Unit: seconds.
      usrargs The custom parameters used to push the stream.
      node The name of the Alibaba Cloud CDN node or the host that receives the stream.
    • Sample callback when stream pushing is complete
      {
        "action": "publish",
        "ip": "192.168.XX.XX",
        "id": "world",
        "app": "test****.alivecdn.com",
        "appname":"hello",
        "time": "1609220385",
        "usrargs": {Custom parameters},
        "node": "cdnvideocenter01020711****.cm3"
      }
    • Sample callback when stream pushing is interrupted
      {
        "action": "publish_done",
        "ip": "192.168.XX.XX",
        "id": "world",
        "app": "test****.alivecdn.com",
        "appname":"hello",
        "time": "1609220385",
        "usrargs": {Custom parameters},
        "node": "cdnvideocenter01020711****.cm3"
      }

Callbacks for live stream recording

Callbacks for live stream recording include callbacks for recording status and callbacks for recorded files. You can configure such callbacks in the ApsaraVideo Live console or by calling API operations.

  • Callbacks for recording status: fired when recording starts and ends. The callback message notifies you that recording starts or ends.
  • Callbacks for recorded files: fired when recorded files are generated. The callback message contains the name of a recorded file, the start time and end time of the recording, and the recording duration.
  • How to configure callbacks for live stream recording
    • Use the ApsaraVideo Live console

      Log on to the ApsaraVideo Live console and go to the Domains page. Find the streaming domain that you want to configure and click Domain Settings. Choose Templates > Recording Settings. On the tab that appears, set or modify the callback URL.

    • Call API operations
      Operation Description Reference
      AddLiveRecordNotifyConfig Configures callbacks for live stream recording for a domain name.

      To enable callbacks for recording status, set the NeedStatusNotify parameter to true.

      AddLiveRecordNotifyConfig
      DescribeLiveRecordNotifyConfig Queries the configuration of callbacks for live stream recording for a domain name. DescribeLiveRecordNotifyConfig
      DeleteLiveRecordNotifyConfig Deletes the configuration of callbacks for live stream recording for a domain name. DeleteLiveRecordNotifyConfig
  • Callbacks for recording status
    • The following table describes the parameters that are used to configure callbacks for recording status.
      Parameter Description
      domain The streaming domain.
      app The name of the application.
      stream The name of the live stream.
      event The name of the event. Valid values:
      • record_started: Recording is started.
      • record_paused: Recording is paused.
      • record_resumed: Recording is resumed.
    • Sample callback when recording is started
      {
      "domain": "test****.alivecdn.com",
      "app": "gs****_app",
      "stream": "gs****_stream",
      "event": "record_started"
      }
  • Callbacks for recorded files
    • The following table describes the parameters that are used to configure callbacks for recorded files.
      Parameter Description
      domain The streaming domain.
      app The name of the application.
      stream The name of the live stream.
      uri The storage path of the recorded file in the specified Object Storage Service (OSS) bucket.
      duration The duration of the recording content.
      start_time The start time of the recording. The time is a UNIX timestamp. Unit: seconds.
      stop_time The end time of the recording. The time is a UNIX timestamp. Unit: seconds.
    • Sample callback when a file is recorded
      {
        "domain": "qt01****.alivecdn.com",
        "app": "mp4flvtest****_flv",
        "stream": "callback****_test",
        "uri": "mp4flvtest****_flv/callback****_test/0_2017-03-08-23:09:46_2017-03-08-23:10:40.flv",
        "duration": 69.403,
        "start_time": 1488985786,
        "stop_time": 1488985840
      }

Callbacks for on-demand recording

Before on-demand recording starts, a callback for on-demand recording is fired to pass the parameters of a live stream to you. Then, you can determine whether the 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 stream, it sends a request to the specified callback URL to check whether the stream needs to be recorded. The request contains five parameters.

  • Request parameters
    Parameter Type Description
    domain String The 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 Json Object No The duration of the recording in each format in each cycle. Valid values: 5 to 21600. Unit: seconds.
    Format Array No The format of the recording. The recording can be in the MP4, FLV, or M3U8 format.
  • Sample request
    GET /?app=seq_all&domain=qt01.alivecdn.com&stream=ondemand8&vbitrate=2000&codec=h264 HTTP/1.1
    Host: live.abc.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 the formats specified by the returned Format parameter are not in the existing recording configuration, the live stream is not recorded.
    Note
    • If a non-200 HTTP status code is returned, an error has occurred.

    • The request body cannot exceed 2,048 characters in length. Otherwise, the body is truncated to prevent malicious attacks.

Callbacks for snapshots

ApsaraVideo Live supports callbacks for snapshots. To enable such callbacks, submit a ticket.

  • The following table describes the parameters that are used to configure callbacks for snapshots.
    Parameter Description
    Event The name of the event.
    DomainName The streaming domain.
    AppName The name of the application.
    StreamName The name of the live stream.
    OssBucket The name of the OSS bucket where the snapshot is stored.
    OssEndpoint The URL of the OSS bucket where the snapshot is stored.
    OssObject The name of the snapshot.
    CreateTime The 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 when a snapshot is captured
    {
        "Event":"Snapshot",
        "DomainName":"test****.alivecdn.com",
        "AppName":"app****_name",
        "StreamName":"stream****_name",
        "OssBucket":"bucket",
        "OssEndpoint":"oss-cn-shan****.aliyuncs.com",
        "OssObject":"1****.jpg",
        "CreateTime":"2015-12-01T17:36:00Z",
        "SnapshotUrl":"http://bucket.oss-cn-shan****.aliyuncs.com/1****.jpg",
        "Size":"36291",
        "Width":"1280",
        "Height":"720"
    }

Callbacks for automated review

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

  • How to configure callbacks for video moderation results
    • Use the ApsaraVideo Live console

      Log on to the ApsaraVideo Live console and go to the Domains page. Find the streaming domain that you want to configure and click Domain Settings. Choose Templates > Content Moderation Settings. On the page that appears, set or modify the callback URL.

      Note Among the live centers in mainland China, the automated review feature is not supported for domains whose live center resides in the China (Qingdao) region. Among the live centers in all regions outside mainland China, the automated review feature is supported only in the Singapore region.
  • 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.

    • The following table describes the parameters that are used to configure callbacks for video moderation results.
      Parameter Type Description
      DomainName String The streaming domain.
      AppName String The name of the application.
      StreamName String The name of the live stream.
      OssEndpoint String The URL of the OSS object.
      OssBucket String The bucket where the OSS object is stored.
      OssObject String The name of the OSS object.
      Result JSONArray The moderation results. For more information, see Result.
      Table 1. Result
      Parameter Type Description
      BizType String The type of business. You can specify a model. The default value is the domain name.
      Scene String The moderation scenario. Valid values:
      • porn: pornography detection
      • terrorism: terrorist content detection
      • ad: ad violation detection
      • live: undesirable scene detection
      • logo: logo detection
      Label String The category of the moderation result. Valid values vary based on the specified moderation scenario.
      • Valid values if the Scene parameter is set to porn:
        • normal: normal content
        • sexy: sexy content
        • porn: pornographic content
      • Valid values if the Scene parameter is set to terrorism:
        • normal: normal content
        • bloody: bloody content
        • explosion: explosion and smoke
        • outfit: special costume
        • logo: logo
        • weapon: weapon
        • politics: political content
        • violence: violence
        • crowd: crowd
        • parade: parade
        • carcrash: car accident
        • flag: flag
        • location: landmark
        • others: other specified content
      • Valid values if the Scene parameter is set to ad:
        • normal: normal content
        • ad: other ads
        • npx: illegal ad
        • qrcode: QR code
        • programCode: mini program code
      • Valid values if the Scene parameter is set to live:
        • normal: normal content
        • meaningless: no content in the image, such as black or white screen
        • PIP: picture-in-picture
        • smoking: smoking
        • drivelive: live broadcasting in a running vehicle
      • Valid values if the Scene parameter is set to logo:
        • 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 do not use this score in your business system. We recommend that you determine whether the moderation object contains illegal content based on the value of the Label parameter.
      Extent String The reserved parameter.
      Note By default, this version is used for new users. Existing users can submit a ticket to apply for using this version.
    • Sample callback when the video moderation is complete
      {
       "DomainName": "test****.alive.com",
       "AppName": "app****_name",
       "StreamName": "stream****_name",
       "OssEndpoint": "oss-cn-hang****.aliyuncs.com",
       "OssBucket": "xbucket",
       "OssObject": "abc.jpg",
       "Result": [
           {
               "BizType": "test****.alive.com",
               "Result": [
                   {"Label": "Porn", "Rate":11, "Suggestion": "review", "Scene":"porn", "Extent": {}},
                   {"Label": "Ad", "Rate":11, "Suggestion": "review", "Scene":"ad", "Extent": {}}
               ]
           }
       ]
      }
                          
  • How to configure callbacks for audio moderation results

    You can configure callbacks for audio moderation results only by calling API operations.

  • 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.

    • The following table describes the parameters that are used to configure callbacks for audio moderation results.
      Parameter Type Description
      domain String The streaming domain.
      app String The name of the application.
      stream String The name of the live stream.
      timestamp Int The timestamp of the callback. Unit: seconds.
      result JSONArray The moderation results. For more information, see Result.
      Table 2. Result
      Parameter Type Description
      scene String The moderation scenario.
      label String The category of the moderation result. Valid values:
      • normal: normal content
      • spam: junk content
      • ad: ad
      • politics: political content
      • terrorism: terrorist content
      • abuse: abuse
      • porn: pornographic content
      • flood: excessive junk content
      • contraband: prohibited content
      • meaningless: meaningless content
      • customized: custom content, such as a custom keyword
      suggestion String The recommended subsequent operation for you to perform. Valid values:
      • pass: The moderation object does not require further actions.
      • review: The moderation object contains suspected violations and requires manual review.
      • block: The moderation object contains violations. We recommend that you delete or block the object.
      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 do not use this score in your business system. We recommend that you determine whether the moderation object contains illegal content based on the value of the Label parameter.
      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 Detail.
      Table 3. Detail
      Parameter 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 result. Valid values:
      • normal: normal content
      • spam: junk content
      • ad: ad
      • politics: political content
      • terrorism: terrorist content
      • abuse: abuse
      • porn: pornographic content
      • flood: excessive junk content
      • contraband: prohibited content
      • meaningless: meaningless content
      • customized: custom content, such as a custom keyword
    • Sample callback when the audio moderation is complete
      {
          "domain": "live.abc.com",
          "app": "live",
          "stream": "5d9747eba39b44769852d276f9ff690c",
          "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 that 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 069269557776955777.",
                          "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"
                      }
                  ]
              }
          ]
      }