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

回调简介

当直播过程中某些事件被触发时,阿里云将主动发送请求到客户服务器,客户服务器负责应答请求,验证通过后,您可接收到事件回调信息的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
    • 直播推流状态回调鉴权
      推流回调鉴权功能默认关闭,用户可在配置推流回调地址时启用鉴权。启用功能后,鉴权逻辑如下:
      1. 阿里云视频直播发起回调请求时在HTTP(S)请求头中带上ALI-LIVE-TIMESTAMPALI-LIVE-SIGNATURE 字段,供回调消息接收服务端进行签名认证。其中,ALI-LIVE-SIGNATURE的值由如下计算而得:

        ALI-LIVE-SIGNATURE=MD5SUM(MD5CONTENT)

        MD5CONTENT=回调域名|ALI-LIVE-TIMESTAMP取值|鉴权KEY

        说明 回调域名指配置回调URL的推流域名。鉴权Key指用户为推流回调URL配置的鉴权Key。
      2. 回调消息接收服务端接收回调消息时,将回调域名、ALI-LIVE-TIMESTAMP取值、鉴权Key进行拼接后计算MD5值,得到加密字符串,再将计算出的加密字符串与视频直播发起的HTTP(S)请求头中的ALI-LIVE-SIGNATURE字段值进行对比。如果不一致,则请求非法。

直播录制回调

直播录制回调包括录制状态回调、文件生成回调,支持通过控制台和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"
    }

智能审核回调

视频直播支持视频审核和语音审核的结果回调,您可以在控制台或通过API配置回调地址。

  • 视频审核回调设置方式
    • 控制台

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

      说明 中国内地的直播中心中,青岛直播中心的域名暂不支持智能审核;海外的直播中心中,只有新加坡支持智能审核。
    • API
      接口 描述 参考文档
      AddLiveDetectNotifyConfig 添加直播视频审核回调配置。 添加直播审核回调配置
      DescribeLiveAudioAuditNotifyConfig 查询直播视频审核回调配置。 查询直播审核回调配置
      UpdateLiveDetectNotifyConfig 更新直播视频审核回调配置。 更新直播审核回调配置
      DeleteLiveDetectNotifyConfig 删除直播视频审核回调配置。 删除直播审核回调配置
  • 视频审核回调

    只会对于有问题的视频内容进行回调通知,通知内容包含问题视频截图的审核信息和存储信息。

    • 视频审核回调参数
      参数 类型 描述
      DomainName String 播流域名。
      AppName String 应用名称。
      StreamName String 流名称。
      OssEndpoint String 存储对象Endpoint。
      OssBucket String 存储对象的Bucket。
      OssObject String 存储对象的文件名。
      Result JSONArray 检测结果。请参见表 1
      表 1. Result
      参数 类型 描述
      BizType String 业务类型。可用于选择模型,默认值为域名。
      Scene String 检测场景
      • porn:鉴黄。
      • terrorism:暴恐涉政。
      • ad:图文违规。
      • live:不良场景。
      • logo:图片logo。
      Label String 检测结果的分类。不同检测场景的结果分类不同,具体如下:
      • 图片智能鉴黄(porn)结果分类:
        • normal:正常。
        • sexy:性感。
        • porn:色情。
      • 图片暴恐涉政(terrorism)结果分类:
        • normal:正常。
        • bloody:血腥。
        • explosion:爆炸烟光。
        • outfit:特殊装束。
        • logo:特殊标识。
        • weapon:武器。
        • politics:涉政。
        • violence :打斗。
        • crowd:聚众。
        • parade:游行。
        • carcrash:车祸现场。
        • flag:旗帜。
        • location:地标。
        • others:其他。
      • 图文违规(ad)结果分类:
        • normal:正常。
        • ad:其他广告。
        • npx:牛皮癣广告。
        • qrcode:含二维码。
        • programCode:含小程序码。
      • 不良场景(live)结果分类:
        • normal:正常。
        • meaningless:图片中无内容(例如,黑屏、白屏)。
        • PIP:画中画。
        • smoking:吸烟。
        • drivelive:车内直播。
      • 图片logo(logo)结果分类:
        • normal:正常。
        • TV:含受管控的logo。
        • trademark:含商标。
      Rate Float 置信度分数。取值范围:0(表示置信度最低)~100(表示置信度最高)。
      说明 该值仅作为参考,强烈建议您不要在业务中使用。建议您参考Label结果用于内容违规判定。
      Extent String 预留字段。
      说明 默认新用户将使用此版本,老用户维持不变,如需使用此版本,请您提交工单
    • 视频审核回调参数示例
      {
       "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": {}}
               ]
           }
       ]
      }
                          
  • 语音审核回调设置方式

    目前不支持控制台方式设置语音审核,您可以通过API设置。

    接口 描述 参考文档
    AddLiveAudioAuditNotifyConfig 添加直播语音审核回调配置。用户可以根据自己需求自定义回调JSON格式。 添加直播语音审核回调配置
    DeleteLiveAudioAuditNotifyConfig 删除直播语音审核回调配置。 删除直播语音审核回调配置
    UpdateLiveAudioAuditNotifyConfig 更新直播语音审核回调配置。 更新直播语音审核回调配置
    DescribeLiveAudioAuditNotifyConfig 查询直播语音审核回调配置。 查询直播语音审核回调配置
  • 语音审核回调

    只会对于有问题的音频内容进行回调通知,通知内容包含问题语音的文本信息以及最近一分钟内的上下文信息。

    • 语音审核回调参数
      参数 类型 描述
      domain String 播流域名。
      app String 应用名称。
      stream String 流名称。
      timestamp Int 回调时间戳。单位:秒。
      result JSONArray 检测结果。请参见表 2
      表 2. Result
      参数 类型 描述
      scene String 检测场景。
      label String 检测结果的分类。取值:
      • normal:正常文本
      • spam:含垃圾信息
      • ad:广告
      • politics:涉政
      • terrorism:暴恐
      • abuse:辱骂
      • porn:色情
      • flood:灌水
      • contraband:违禁
      • meaningless:无意义
      • customized:自定义(例如命中自定义关键词)
      suggestion String 处理建议。取值:
      • pass:结果正常,无需进行其余操作。
      • review:结果不确定,需要进行人工审核。
      • block:结果违规,建议直接删除或者限制公开。
      rate Float 置信度分数。取值范围:0(表示置信度最低)~100(表示置信度最高)。
      说明 该值仅作为参考,强烈建议您不要在业务中使用。建议您参考Label结果用于内容违规判定。
      details JSONArray 语音对应的文本详情,每一句文本对应一个元素,可以包含一个或者多个元素。关于每个元素的结构描述,请参见表 3
      表 3. Detail
      参数 类型 描述
      startTime Int 句子开始的时间戳,单位:秒。
      endTime Int 句子结束的时间戳,单位:秒。
      text String 问题语音转换成文本的结果。
      label String 检测结果的分类。取值:
      • normal:正常文本
      • spam:含垃圾信息
      • ad:广告
      • politics:涉政
      • terrorism:暴恐
      • abuse:辱骂
      • porn:色情
      • flood:灌水
      • contraband:违禁
      • meaningless:无意义
      • customized:自定义(例如命中自定义关键词)
    • 语音审核回调参数示例
      {
          "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": "丽江陇川等酒店免费居住权120天居住权可与亲友共享来云栖社国际烧酒店接待中心地址芒市团结大街96号邓朝ktv旁咨询热线2285699",
                          "label": "ad"
                      },
                      {
                          "startTime": 1572248040,
                          "endTime": 1572248070,
                          "text": "典藏经典别墅尊享隆多温泉、梁河金塔、温泉旅游小镇二期滨江苑地区11月2号盛大开盘天然龙窝、温泉水入户户型多样,设计经典价位超值,值得您拥有开盘当天还有超值优惠,欢迎您前来品鉴,凭借地址,然和县遮岛镇先锋路229号分享热线069269557776955777",
                          "label": "normal"
                      },
                      {
                          "startTime": 1572248072,
                          "endTime": 1572248077,
                          "text": "快乐的时光,有你相伴惬意的日子,格外轻松。",
                          "label": "normal"
                      },
                      {
                          "startTime": 1572248078,
                          "endTime": 1572248086,
                          "text": "fme043忙里偷闲音乐时光有歌曲温暖,有你想念影院。",
                          "label": "normal"
                      }
                  ]
              }
          ]
      }