视频直播提供直播推流状态、直播录制、按需录制、直播截图的事件回调,本文介绍这些回调的设置方式、回调参数和示例。

回调简介

当直播过程中某些事件被触发时,阿里云将主动发送请求到客户服务器,客户服务器负责应答请求,验证通过后,您可接收到事件回调信息的JSON数据包。

视频直播支持回调如下事件的信息:

回调方式

视频直播服务目前支持HTTP回调(兼容HTTPS)方式获取事件通知。您需要部署一个HTTP服务来接收回调消息,并在控制台或通过API配置回调地址。

  • 当推流或断流事件产生时,直播服务端会向该地址发起HTTP GET请求,具体内容将通过URL参数送达。
  • 当其他事件产生时,直播服务端会向该地址发起HTTP POST请求,具体内容将通过JSON Body送达。

注意事项

回调地址URL无需标识,只需可正常访问,URL的应答有如下要求:如果访问超时,会重试URL,目前超时时间是5秒,重试次数5次,重试间隔1秒。

直播推流状态回调

通知当前域名推流状态,包括推流成功、断流状态,支持通过控制台或API配置回调地址。

  • 直播推流状态回调设置方式
  • 直播推流状态回调

    推断流状态回调会将参数封装在MultiDict内。

    • 直播推流状态回调中开播(publish)状态回调逻辑
      1. RTMP推流在阿里云直播服务收到On Publish消息后2秒内,如果推流端不主动断开,阿里云直播服务就会发推流成功回调。如果您的业务需要阿里云直播收到On Publish建联并真正收到直播流数据后才发推流成功回调,请提交工单联系我们后台配置。
      2. 假设您有推流域名A和播流域名B,如果您的域名B使用拉流直播(固定拉流和触发回源拉流)需要回调,请在域名A配置推流回调。配置后域名B的拉流回调逻辑与上一条一致,建联后默认2秒无主动断开即认为拉流成功,需要真正收到数据才认为成功。请提交工单申请配置。
      说明 建议业务方不仅根据回调通知判断推流、拉流接入正常,同时配合在线流列表查询推流正常后,再下发直播流播放地址。
    • 直播推流状态回调参数
      参数 描述
      action 事件。
      • publish:推流。
      • publish_done:断流。
      ip 推流的客户端IP。
      id 推流流名称。
      app 推流域名。默认为自定义的推流域名,如果未绑定推流域名即为播流域名。
      appname 推流应用名称。
      time Unix时间戳。单位:秒。
      usrargs 用户推流的参数。
      node CDN接受流的节点或者机器名。
      height 分辨率的高。单位:像素。
      说明 分辨率信息(height和width)仅在首次回调时产生。
      width 分辨率的宽。单位:像素。
    • 推流状态回调参数示例
      http:// 1.1.1.1?action=publish&ip=192.168.XX.XX&id=world&app=test****.alivecdn.com&appname=hello&time=1609220385&usrargs={用户参数}&
      node=cdnvideocenter01020711****.cm3&height=720&width=1280
    • 断流流状态回调参数示例
      http:// 1.1.1.1?action=publish_done&ip=192.168.XX.XX&id=world&app=test****.alivecdn.com&appname=hello&time=1609220385&usrargs={用户参数}&
      node=cdnvideocenter01020711****.cm3&height=720&width=1280

直播录制回调

直播录制回调包括录制状态回调、文件生成回调,支持通过控制台和API进行配置。

  • 录制状态回调:在文件开始录制与结束录制时发出,主要表示文件已经开始和结束录制。
  • 文件生成回调:在文件生成时发出,主要包括文件名称,开始结束时间与时长信息。
  • 直播录制回调设置方式
    • 控制台

      视频直播控制台域名管理页面,选择需要配置的播流域名,单击域名配置,进入模版配置 > 录制配置页面,添加或修改回调地址。

    • API
      接口 描述 参考文档
      AddLiveRecordNotifyConfig 添加域名级别录制回调配置。

      若需要开启录制任务状态回调,请将NeedStatusNotify参数值设置为true。

      添加直播录制回调配置
      DescribeLiveRecordNotifyConfig 查询域名级别录制回调配置。 查询直播录制回调配置
      DeleteLiveRecordNotifyConfig 删除域名级别录制回调配置。 删除直播录制回调配置
  • 录制状态回调
    • 录制状态回调参数
      参数 描述
      domain 录制的播流域名。
      app 应用名。
      stream 流名。
      event 事件名。
      • record_started:录制已经成功开始。
      • record_paused:录制已经成功暂停。
      • record_resumed:录制已经成功恢复继续录制。
    • 录制状态回调参数示例
      {
      "domain": "test****.alivecdn.com",
      "app": "gs****_app",
      "stream": "gs****_stream",
      "event": "record_started"
      }
  • 文件生成回调
    • 文件生成回调参数
      参数 描述
      domain 录制的播流域名。
      app 应用名。
      stream 流名。
      uri 目标录制文件在用户录制OSS Bucket下的路径。
      duration 目标录制文件录制内容时长,单位:秒。
      start_time 录制开始时间。Unix时间戳,单位:秒。
      stop_time 录制结束时间。Unix时间戳,单位:秒。
      push_args 推流参数中以callback_为前缀的参数,如callback_arg1、callback_myid等。
      说明 同一个参数名只能有一个参数值,如果传入多个值,回调仅包含第一个值。如推流参数包含callback_args1=value1&callback_args1=value2,回调中仍为"callback_args1": "value1"
    • 文件生成回调参数示例
      推流URL为:
      rtmp://qt01****.alivecdn.com/mp4flvtest****_flv/callback****_test?callback_args1=value1&callback_myid=1231389741
      则回调内容为:
      {
        "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"
        }
      }
      说明 以上回调示例,适用于所有没有定制回调模版的客户。

按需录制回调

按需录制回调是录制之前通过回调的方式,传递直播流的相关参数给用户,由用户判断是否需要录制的功能。

用户指定一个回调地址,并设置一个domain、app或stream级别的录制为按需录制。当录制服务收到匹配domain、app或stream名称的流时,向用户的回调地址发送请求(请求包含5个参数),来询问用户是否需要录制这路流。

  • 请求参数
    参数 类型 描述
    domain String 播流域名。
    app String 播流所属应用名称。
    stream String 播流名称。
    codec String 编码方式。取值:
    • h264
    • h265
    vbitrate String 视频码率。单位:Kbps。
  • 返回参数
    参数 类型 是否必选 描述
    ApiVersion String

    API版本。默认为1.0版本。

    NeedRecord Bool 是否需要录制。
    Interval Json Object 具体格式的录制周期变化。取值范围:5~21600。单位:秒。
    Format Array 录制格式。支持MP4、FLV、M3U8。
  • 请求示例
    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
  • 返回示例
    {
        "ApiVersion" : "1.0",
        "NeedRecord" : true,
        "Interval" : {
            "Mp4": 300,
            "Flv": 120,
            "M3U8": 180
        },
        "Format" : ["mp4","flv"]
    }
  • 返回参数处理
    录制服务会对用户返回的参数配置和既有配置进行覆盖。例如,显示指定了Interval,那么录制服务会覆盖数据库中的录制配里面的Interval,Format会和数据库中的配置取交集。如果用户指定的格式全不在既有配置之中,则不会录制这路直播流。
    说明
    • 所有非200 http status code,都会被认为是调用用户接口失败。

    • 对于范围body长度有限制,超过2048会被截断,以防恶意攻击。

直播截图回调

直播提供截图文件回调,您可以通过调用UpdateLiveAppSnapshotConfig接口,配置Callback参数开启。更多信息,请参见更新直播截图配置

  • 截图文件回调参数
    参数 描述
    Event 事件。
    DomainName 截图的播流域名。
    AppName 应用名。
    StreamName 流名。
    OssBucket 存储截图的Bucket名。
    OssEndpoint 存储截图的OSS。
    OssObject 截图的文件名。
    CreateTime 截图时间。
    SnapshotUrl 截图文件在用户录制OSS Bucket下的路径。
    Size 图片大小。
    Width 图片宽。单位:像素。
    Height 图片高。单位:像素。
  • 截图文件回调参数示例
    {
        "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"
    }