AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 视频直播 功能特性 事件回调 回调管理

回调管理

更新时间：
产品详情
我的收藏

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

回调简介

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

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

回调方式

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

说明

目前有小部分SSL证书暂不能实现兼容，若回调失败可尝试使用HTTP回调。

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

  • 当其他事件产生时，直播服务端会向该地址发起HTTP POST请求，具体内容将通过JSON Body送达。

注意事项

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

直播推流回调

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

  • 直播推流回调设置方式

  • 推断流回调

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

    • 推断流回调中开播（publish）状态回调逻辑

      1. RTMP推流在阿里云直播服务收到On Publish消息后2秒内，如果推流端不主动断开，阿里云直播服务就会发推流成功回调。

      2. 假设您有推流域名A和播流域名B，如果您的域名B使用拉流直播（固定拉流和触发回源拉流）需要回调，请在域名A配置推流回调。配置后域名B的拉流回调逻辑与上一条一致，建联后默认2秒无主动断开即认为拉流成功。

      说明

      • 建议业务方不仅根据回调通知判断推流、拉流接入正常，同时配合查询域名在线流列表接口查询推流正常后，再下发直播流播放地址。

      • 当10秒内（包含十秒）没有流数据推送到直播中心时，直播服务就会自动断开推流。

    • 推断流回调参数

      参数

      描述

      action

      事件。

      • publish：推流。

      • publish_done：断流。

      ip

      推流的客户端IP。

      id

      推流流名称。

      app

      推流域名。默认为自定义的推流域名，如果未绑定推流域名即为播流域名。

      appname

      推流应用名称。

      time

      Unix时间戳。单位：秒。

      usrargs

      用户推流的参数。

      node

      CDN接受流的节点或者机器名。

      height

      分辨率的高。单位：像素。

      说明

      分辨率信息（height和width）仅在首次回调时产生。

      width

      分辨率的宽。单位：像素。

    • 推流状态回调参数示例：

      http://1.1.X.X?action=publish&ip=192.168.0.1&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={用户参数}&
node=cdnvideocenter01020711****.cm3&height=720&width=1280

    • 断流状态回调参数示例：

      http://1.1.X.X?action=publish_done&ip=192.168.0.0&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={用户参数}&
node=cdnvideocenter01020711****.cm3&height=720&width=1280

    • 推流异常事件回调

      • 推流异常事件回调参数

        参数

        描述

        action

        publish_exception_notify。

        domain

        推流域名。

        appname

        推流应用名称。

        stream

        直播流名称。

        ip

        推流的客户端IP。

        time

        回调时间。

        type

        异常事件类型。

        event_time

        异常事件发生时间。

      • 异常类型

        异常事件code

        事件类型

        1001

        URL存在非法字符。

        2001

        视频codec在黑名单中。

        2002

        视频codec不在白名单中。

        2003

        音频codec在黑名单中。

        2004

        音频codec不在白名单中。

        3001

        音频头解析失败。

        3002

        视频头解析失败。

        3003

        meta解析失败。

        4001

        视频宽高不一致。

        4002

        meta中不包含音频数据，但是发送数据时有音频数据。

        4003

        实际音视频数据和header不符。

        4004

        meta中不包含视频数据，但是发送数据时有视频数据。

        4005

        音频codec信息中途发送变化。

        4006

        视频频codec信息中途发送变化。

        4007

        在收到音频HDR前收到音频帧。

        4008

        在收到视频HDR前收到视频帧。

        5001

        CTS波动过大。

        5002

        DTS非递增。

        5003

        音视频时间戳差值过大。

        5004

        音频DTS增长过大。

        5005

        视频DTS增长过大。

        5006

        接收音频帧时间间隔过大。

        5007

        接收视频帧时间间隔过大。

      • 推流异常事件回调参数示例：

        {
"action": "publish_exception_notify",
"domain": "demo.aliyundoc.com",
"appname": "liveApp****",
"stream": "liveStream****",
"ip": "141.01.****"
"time": "1739760710"
"type": "5002"
"event_time": "1739760710"
}

    • 直播推流回调鉴权

      1. 推流回调鉴权功能默认关闭，用户可在配置推流回调地址时启用鉴权。启用功能后，鉴权逻辑如下：

        阿里云视频直播发起回调请求时在HTTP(S)请求头中带上ALI-LIVE-TIMESTAMP和 ALI-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字段值进行对比。如果不一致，则请求非法。

    • 直播推流状态回调鉴权

      推流回调鉴权功能默认关闭，用户可在配置推流回调地址时启用鉴权。启用功能后，鉴权逻辑如下：

      1. 阿里云视频直播发起回调请求时在HTTP(S)请求头中带上ALI-LIVE-TIMESTAMP和 ALI-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": "demo.aliyundoc.com",
"app": "liveApp****",
"stream": "liveStream****",
"event": "record_started"
}

  • 文件生成回调

    • 文件生成回调参数

      参数

      描述

      domain

      录制的播流域名。

      app

      应用名。

      stream

      流名。

      uri

      目标录制文件在用户录制OSS Bucket下的路径。

      record_id

      索引文件ID。

      file_url

      录制文件的URL地址。

      duration

      目标录制文件录制内容时长，单位：秒。

      start_time

      录制开始时间。Unix时间戳，单位：秒。

      stop_time

      录制结束时间。Unix时间戳，单位：秒。

      is_finished

      是否完成录制。

      file_url

      录制文件URL地址。

      oss_endpoint

      OSS 存储的 Endpoint 名称。

      oss_bucket

      OSS 存储的 Bucket 名称。

      push_args

      推流参数中以callback_为前缀的参数，如callback_arg1、callback_myid等。

      说明

      录制转码流不支持传递自定义参数。

      同一个参数名只能有一个参数值，如果传入多个值，回调仅包含第一个值。如推流参数包含callback_args1=value1&callback_args1=value2，回调中仍为"callback_args1": "value1"。

    • 文件生成回调参数示例

      推流URL为：

      rtmp://demo.aliyundoc.com/liveApp****/liveStream****?callback_args1=value1&callback_myid=1231389741

      则回调内容为：

      {
  "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",
  "file_url": "http://****.oss-****.aliyuncs.com/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"
  }
}
      说明

      以上回调示例，适用于所有没有定制回调模板的客户。

按需录制回调

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

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

  • 请求参数

    参数类型描述
    domainString主播流域名。
    appString播流所属应用名称。
    streamString播流名称。
    codecString编码方式。取值：
    • h264
    • h265
    vbitrateString视频码率。单位：kbps。

  • 返回参数

    参数类型是否必选描述
    ApiVersionString否

    API版本。默认为1.0版本。

    NeedRecordBool是是否需要录制。
    IntervalJSONObject否具体格式的录制周期变化。取值范围：5~21600。单位：秒。
    FormatJSONArray否录制格式。支持MP4、FLV、M3U8。

  • 请求示例

    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

  • 返回示例

    {
    "ApiVersion" : "1.0",
    "NeedRecord" : true,
    "Interval" : {
        "Mp4": 300,
        "Flv": 120,
        "M3U8": 180
    },
    "Format" : ["mp4","flv"]
}

  • 返回参数处理

    录制服务会对用户返回的参数配置和既有配置进行覆盖。例如，显示指定了Interval，那么录制服务会覆盖数据库中的录制配置里面的Interval，Format会和数据库中的配置取交集。如果用户指定的格式全不在既有配置之中，则不会录制这路直播流。

    说明

    • 所有非200 http status code，都会被认为是调用用户接口失败。

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

直播截图回调

视频直播支持直播截图结果回调，您可以在控制台或通过API配置回调地址。

  • 截图回调设置方式

    • 控制台

      进入视频直播控制台页面，选择左侧导航栏功能管理 > 事件回调进入事件回调页面，选择需要开启的域名，在回调设置页签下，开启截图回调开关，添加或修改推流回调地址。具体操作请参见截图回调。

    • API

      接口

      描述

      参考文档

      AddLiveSnapshotNotifyConfig

      添加截图回调配置。

      添加截图回调配置

      UpdateLiveSnapshotNotifyConfig

      修改截图回调配置。

      修改截图回调配置

      DescribeLiveSnapshotNotifyConfig

      获取截图回调配置。

      获取截图回调配置

      DeleteLiveSnapshotNotifyConfig

      删除截图回调配置。

      删除截图回调配置

    • 截图文件回调参数

      参数

      描述

      Event

      事件。

      DomainName

      截图的播流域名。

      AppName

      应用名。

      StreamName

      流名。

      OssBucket

      存储截图的Bucket名。

      OssEndpoint

      存储截图的OSS。

      OssObject

      截图的文件名。

      CreateTime

      截图时间。

      SnapshotUrl

      截图文件在用户录制OSS Bucket下的路径。

      Size

      图片大小。单位：byte。

      Width

      图片宽。单位：像素。

      Height

      图片高。单位：像素。

    • 截图文件回调参数示例

      {
    "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"
}

    • 直播截图支持截图回调鉴权配置。详细信息请参见设置截图回调鉴权配置、截图回调鉴权说明。

智能审核回调

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

  • 视频审核回调设置方式

  • 视频审核回调

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

    • 视频审核回调参数

      参数

      类型

      描述

      DomainName

      String

      播流域名。

      AppName

      String

      应用名称。

      StreamName

      String

      流名称。

      OssEndpoint

      String

      存储对象Endpoint。

      OssBucket

      String

      存储对象的Bucket。

      OssObject

      String

      存储对象的文件名。

      Result

      JSONArray

      检测结果。请参见Result。

      表 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": "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": {}}
         ]
     }
 ]
}

  • 语音审核回调设置方式

  • 语音审核回调

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

    • 语音审核回调参数

      参数

      类型

      描述

      domain

      String

      播流域名。

      app

      String

      应用名称。

      stream

      String

      流名称。

      timestamp

      Int

      回调时间戳。单位：秒。

      result

      JSONArray

      检测结果。请参见Result。

      表 2. Result

      参数

      类型

      描述

      scene

      String

      检测场景。

      label

      String

      检测结果的分类。取值：

      • normal：正常文本

      • spam：含垃圾信息

      • ad：广告

      • politics：涉政

      • terrorism：暴恐

      • abuse：辱骂

      • porn：色情

      • flood：灌水

      • contraband：违禁

      • meaningless：无意义

      suggestion

      String

      处理建议。取值：

      • pass：结果正常，无需进行其余操作。

      • review：结果不确定，需要进行人工审核。

      • block：结果违规，建议直接删除或者限制公开。

      rate

      Float

      置信度分数。取值范围：0（表示置信度最低）~100（表示置信度最高）。

      说明

      该值仅作为参考，强烈建议您不要在业务中使用。建议您参考Label结果用于内容违规判定。

      details

      JSONArray

      语音对应的文本详情，每一句文本对应一个元素，可以包含一个或者多个元素。关于每个元素的结构描述，请参见Detail。

      表 3. Detail

      参数

      类型

      描述

      startTime

      Int

      句子开始的时间戳，单位：秒。

      endTime

      Int

      句子结束的时间戳，单位：秒。

      text

      String

      问题语音转换成文本的结果。

      label

      String

      检测结果的分类。取值：

      • normal：正常文本

      • spam：含垃圾信息

      • ad：广告

      • politics：涉政

      • terrorism：暴恐

      • abuse：辱骂

      • porn：色情

      • flood：灌水

      • contraband：违禁

      • meaningless：无意义

    • 语音审核回调参数示例

      {
    "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": "丽江陇川等酒店免费居住权120天居住权可与亲友共享来云栖社国际烧酒店接待中心地址芒市团结大街96号邓朝ktv旁咨询热线2285699",
                    "label": "ad"
                },
                {
                    "startTime": 1572248040,
                    "endTime": 1572248070,
                    "text": "典藏经典别墅尊享隆多温泉、梁河金塔、温泉旅游小镇二期滨江苑地区11月2号盛大开盘天然龙窝、温泉水入户户型多样，设计经典价位超值，值得您拥有开盘当天还有超值优惠，欢迎您前来品鉴，凭借地址，然和县遮岛镇先锋路229号分享热线0692695577769***
",
                    "label": "normal"
                },
                {
                    "startTime": 1572248072,
                    "endTime": 1572248077,
                    "text": "快乐的时光，有你相伴惬意的日子，格外轻松。",
                    "label": "normal"
                },
                {
                    "startTime": 1572248078,
                    "endTime": 1572248086,
                    "text": "fme043忙里偷闲音乐时光有歌曲温暖，有你想念影院。",
                    "label": "normal"
                }
            ]
        }
    ]
}

双流灾备回调

接收双流灾备切流结果的通知。

  • 回调设置方式：

  • 切流回调：

    参数

    描述

    action

    事件类型：multistream_set_master_result，表示切流结果。

    domain

    推流域名。

    appname

    应用名称。

    streamname

    流名称。

    upstreamsequence

    切流后主流的流标识。

    upstreamip

    切流后主流推流客户端的IP地址。

    upstreamtime

    切流后主流推流开始时间，Unix时间戳，单位：秒。

    changereason

    触发切流的原因。

    changetime

    执行切流操作的时间，Unix时间戳，单位：秒。

    time

    回调通知的生成时间，Unix时间戳，单位：秒。

  • 回调示例：

    {
  "action": "multistream_set_master_result",
  "domain": "demo.aliyundoc.com",
  "appname": "liveApp****",
  "streamname": "liveStream****",
  "upstreamsequence": "main",
  "upstreamip": "203.**.***.10",
  "upstreamtime": 17*****710,
  "changereason": "merge_cut_manually",
  "changetime": 17*****705,
  "time": 17*****706
}

上一篇：事件回调下一篇：回调设置