ApsaraVideo Live supports callbacks for stream ingest status, live stream recording, on-demand recording, and live stream snapshots.This topic describes the configuration methods and parameters of these callbacks and provides 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 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 specify a callback URL in the ApsaraVideo Live console or by calling API operations.

  • 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 retries to access the URL. The current timeout period is 5 seconds. If no response is returned within 5 seconds, ApsaraVideo Live retries to access the URL for a maximum of five times at intervals 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 API operations.

  • Configure callbacks for stream ingest status
    • Use the ApsaraVideo Live console

      Log on to the ApsaraVideo Live console and go to the Domains page. Find the ingest 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 ingest.

    • Use API operations
      Operation Description Documentation
      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 for stream ingest status

    The callback parameters are stored in a MultiDict.

    • Callback logic for live stream ingest status
      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. 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. For example, you have Ingest 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 point in 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 ingest callbacks for Ingest Domain A. After the configuration, ApsaraVideo Live uses the same callback logic as that for stream ingest 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 the stream ingest 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 stream ingest status.
      Parameter Description
      action The name of the event. Valid values:
      • publish: stream ingest
      • publish_done: stream interruption
      ip The IP address of the client that ingests the stream.
      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 The 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 when stream ingest is complete
      http:// 1.1.1.1?action=publish&ip=192.168.XX.XX&id=world&app=test****.alivecdn.com&appname=hello&time=1609220385&usrargs={Custom parameters}&
      node=cdnvideocenter01020711****.cm3&height=720&width=1280
    • Sample callback when stream ingest is interrupted
      http:// 1.1.1.1?action=publish_done&ip=192.168.XX.XX&id=world&app=test****.alivecdn.com&appname=hello&time=1609220385&usrargs={Custom parameters}&
      node=cdnvideocenter01020711****.cm3&height=720&width=1280
    • Callback authentication logic
      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 callbacks for recording status and callbacks for recordings. You can configure these callbacks in the ApsaraVideo Live console or by calling API operations.

  • Callbacks for recording status: invoked when recording starts and ends. The callback message notifies you that recording starts or ends.
  • Callbacks for recordings: invoked when recordings are generated. The callback message contains the name of a recording, the start time and end time of the recording, and the recording duration.
  • 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 VOD tab, specify or modify the callback URL.

    • Use API operations
      Operation Description Documentation
      AddLiveRecordNotifyConfig Configures callbacks for live stream recording under 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 under a domain name. DescribeLiveRecordNotifyConfig
      DeleteLiveRecordNotifyConfig Deletes the configuration of callbacks for live stream recording under 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 recordings
    • The following table describes the parameters that are used to configure callbacks for recordings.
      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 recording in the specified Object Storage Service (OSS) bucket.
      duration The duration of the recording content. Unit: seconds.
      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.
      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 when a recording is generated
      The following code provides an example of the stream ingest URL:
      rtmp://qt01****.alivecdn.com/mp4flvtest****_flv/callback****_test?callback_args1=value1&callback_myid=1231389741
      The following code provides an example of the callback notification:
      {
        "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,
        "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 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 live stream, ApsaraVideo Live sends a request to the specified callback URL to check 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 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 live stream snapshots

ApsaraVideo Live supports callbacks for live stream snapshots. To enable these callbacks, you can set the Callback parameter in the UpdateLiveAppSnapshotConfig operation. For more information, see UpdateLiveAppSnapshotConfig.

  • The following table describes the parameters that are used to configure callbacks for live stream 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 snapshots are 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 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"
    }