联犀开发者文档

共通失败与恢复

约 1857 字大约 6 分钟

2026-10-16

本页包含已接线核心流程及可选扩展；具体子能力必须按设备、平台与用户授权求交集。参见支持范围、场景索引和命令手册。图中S编号只用于本文定位，不放入实际JSON。

前置条件

S01–S10 的通用异常子流程；除异步投递外均按本会话 sessionId 处理。下列互斥分支展示具体失败报文，不是在一次会话连续发生。

IPC 名册同步的可恢复错误与权威撤权必须分开：未协商 participantRosterSync、旁路成员读取未知、请求代次冲突、原快照过期或水位落后时，不安装部分名册、不把未知转成 participants=[]，保留原主媒体与已消费展示。只有原Owner的权威授权确实失效，才按原终止链路释放媒体。原token重放不重新生成快照、推进事件水位或延长会话/媒体许可；关联报文和失败样例见 sessionSnapshot。当前同连接同步实施不能替代下图15秒断网恢复及旧连接围栏验收。

图中P代表经鉴权的平台业务控制器和媒体节点，不要求同一进程；A是用户应用，D是设备。控制图描述一种合法顺序，跨通道不承诺严格同序。

完整时序

报文索引

编号按图阅读；编号保留历史引用，不要求数值连续。字段定义以命令链接为准。

编号发送→接收Topic/接口方法及契约应答/等待状态或作用
S11-M01D→PSIG↑sessionCreatesessionCreated；10秒设备发起会话；平台验证设备能力、业务配置、资源与授权交集，不指定供应商。
S11-M02P→DSIG↓sessionCreated—；不等待仅代表创建并分配媒体资源成功，不代表媒体连通；成功必须带顶层 sessionId。
S11-M03D→PSIG↑mediaOffermediaAnswer；15秒设备为自身 Peer 的 offerer；初始与重协商同一方法，只允许一个在途 offer。
S11-M04P→DSIG↓mediaAnswer—；不等待完成 SDP 交换，仍需 ICE/DTLS 连通与 mediaState，不直接 established。
S11-M05P→DSIG↓sessionError—；不等待带 code 的异步错误；不可恢复时随后 sessionEnded，可恢复错误不自动结束主会话。
S11-M06P→DSIG↓sessionEnded—；不等待独立终态事件，关闭Peer和订阅。
S11-M07P→DSIG↓sessionEnded—；不等待主动结束用原 token 和 code；其他结束用独立事件 token 与 eventSeq。ended 是唯一会话终态。
S11-M08D→PSIG↑audioStartrequestAck；10秒串联每轮新 inputId；实时一次启动持续多轮。恢复暂停用新 inputId，不新建会话。
S11-M09P→DSIG↓requestAck—；不等待首次请求启动输入。
S11-M10D→PSIG↑audioStartrequestAck；10秒串联每轮新 inputId；实时一次启动持续多轮。恢复暂停用新 inputId，不新建会话。
S11-M11P→DSIG↓requestAck—；不等待重放缓存应答，不重新启动采集任务。
S11-M12D→PSIG↑mediaStaterequestAck；10秒报告设备实际传输状态。WebRTC 需 ICE/DTLS 成功；UDP 需有效会话媒体探测且平台也收到有效包。
S11-M13P→DSIG↓requestAck—；不等待仅确认状态上报；平台须独立验证自身连通状态。

逐条JSON

S11-M01 · sessionCreate

{
  "msgToken": "forbidden",
  "method": "sessionCreate",
  "params": {
    "purpose": "ipcLiveView",
    "transport": "webrtc",
    "tracks": [
      {
        "trackId": "v",
        "kind": "video",
        "sourceId": "front",
        "direction": "sendonly",
        "codec": "H264",
        "state": "requested"
      }
    ],
    "cameraId": "front"
  }
}

S11-M02 · sessionCreated

{
  "msgToken": "forbidden",
  "method": "sessionCreated",
  "code": 403,
  "data": {
    "reason": "permissionDenied"
  }
}

S11-M03 · mediaOffer

{
  "msgToken": "bad-offer",
  "method": "mediaOffer",
  "sessionId": "s11-session",
  "params": {
    "mediaRevision": 2,
    "webrtc": {
      "iceMode": "complete",
      "sdp": "<invalid SDP>"
    }
  }
}

S11-M04 · mediaAnswer

{
  "msgToken": "bad-offer",
  "method": "mediaAnswer",
  "sessionId": "s11-session",
  "code": 502,
  "data": {
    "reason": "mediaNegotiationFailed"
  }
}

S11-M05 · sessionError

{
  "msgToken": "failure-1",
  "method": "sessionError",
  "sessionId": "s11-session",
  "code": 502,
  "eventSeq": 1,
  "data": {
    "reason": "mediaNegotiationFailed",
    "retryable": false,
    "mediaRevision": 2
  }
}

S11-M06 · sessionEnded

{
  "msgToken": "failure-3",
  "method": "sessionEnded",
  "sessionId": "s11-session",
  "data": {
    "state": "ended",
    "reason": "mediaFailed"
  },
  "eventSeq": 2
}

S11-M07 · sessionEnded

{
  "msgToken": "failure-5",
  "method": "sessionEnded",
  "sessionId": "s11-session",
  "data": {
    "state": "ended",
    "reason": "networkTimeout"
  },
  "eventSeq": 3
}

S11-M08 · audioStart

{
  "msgToken": "same-start",
  "method": "audioStart",
  "sessionId": "s11-session",
  "params": {
    "inputId": "same-input",
    "firstPacketSeq": 256
  }
}

S11-M09 · requestAck

{
  "msgToken": "same-start",
  "method": "requestAck",
  "sessionId": "s11-session",
  "code": 200,
  "data": {
    "requestMethod": "audioStart",
    "result": {
      "inputId": "same-input"
    }
  }
}

S11-M10 · audioStart

{
  "msgToken": "same-start",
  "method": "audioStart",
  "sessionId": "s11-session",
  "params": {
    "inputId": "same-input",
    "firstPacketSeq": 384
  }
}

S11-M11 · requestAck

{
  "msgToken": "same-start",
  "method": "requestAck",
  "sessionId": "s11-session",
  "code": 200,
  "data": {
    "requestMethod": "audioStart",
    "result": {
      "inputId": "same-input"
    }
  }
}

S11-M12 · mediaState

{
  "msgToken": "late",
  "method": "mediaState",
  "sessionId": "s11-session",
  "params": {
    "mediaRevision": 1,
    "state": "connected"
  }
}

S11-M13 · requestAck

{
  "msgToken": "late",
  "method": "requestAck",
  "sessionId": "s11-session",
  "code": 409,
  "data": {
    "requestMethod": "mediaState",
    "reason": "sessionExpired"
  }
}

媒体与本地动作

编号路径格式与约束
S11-R01D→P旧会话UDP包或旧Peer SRTP；平台丢弃，不解码给新会话、不转交模型；设备也丢弃失效通道媒体。

异常、状态与资源释放

以下JSON仅为报文正文；编号、方向、说明不发送。loop下一轮需分配新token/inputId；同一次请求重试必须沿用原token。字段以命令手册为准。

路由缩写均展开于公共约定。ACT/PROP超时以产品配置为准；内部工具以工具超时为准，不套用10秒设备统一信令超时。

所有错误响应保留原请求 token；异步 sessionError 用独立 token。超时重试窗口与幂等规则见命令公共约定。已经 ended 的会话不能通过 ICE restart 复活；重新建会话必须使用新 sessionId、新密钥/Peer。

验证入口

检查本场景对应的支持范围，以及公共流程。示例可解析不等于网络、权限或硬件运行已验证。

更新日志

2026/10/16 16:04
查看所有更新日志
  • fe3a7-docs(AI与音视频): 按场景整理完整接入流程与命令契约于