联犀开发者文档

媒体与处理器命令

约 4929 字大约 16 分钟

2026-10-16

本页按 Topic、method 和方向定义完整契约。字段表与JSON中的可选扩展不等于当前全部启用，实际接入前请查支持范围；应用REST封装见应用接入。

mediaOffer · SIG↑

项目契约
Topic/接口$thing/up/signaling/{productID}/{deviceName}
发送→接收设备→平台
消息类型请求
对应应答mediaAnswer
触发与状态变化设备为自身 Peer 的 offerer；初始与重协商同一方法，只允许一个在途 offer。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试15秒；同token重试，不重复创建Peer
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S01、S05、S06、S07、S08、S09、S11

正文字段

字段类型必填条件枚举／默认及含义
mediaRevisionuint必填从1递增
webrtcWebRTC必填完整SDP offer

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

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

对应S01-M05；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

mediaAnswer · SIG↓

项目契约
Topic/接口$thing/down/signaling/{productID}/{deviceName}
发送→接收平台→设备
消息类型应答
对应应答—
触发与状态变化完成 SDP 交换，仍需 ICE/DTLS 连通与 mediaState，不直接 established。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试不等待ACK；重复按公共规则丢弃/重放
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S01、S05、S06、S07、S08、S09、S11

正文字段

字段类型必填条件枚举／默认及含义
mediaRevisionuint成功必填对应offer代次
webrtcWebRTC成功必填完整SDP answer

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

{
  "msgToken": "s01-2",
  "method": "mediaAnswer",
  "sessionId": "s01-session",
  "code": 200,
  "data": {
    "mediaRevision": 1,
    "webrtc": {
      "iceMode": "complete",
      "sdp": "<SDP answer>"
    }
  }
}

对应S01-M06；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

mediaState · SIG↑

人工候选voice子腿要求平台侧真实Peer也已连通，不能仅凭设备的connected自报设置就绪。未协商、平台Peer未连通或已Ready的新请求，须在SQL操作领取前拒绝；尚无外部副作用的前提失败不留下pending令牌阻断后续同token合法请求。已完成请求仍精确重放，已领取但结果未知的操作不重做；failed沿原授权下的安全清理路径处理，不要求失败资源曾经连通。此说明不改变原媒体代次、截止或最终双端/焦点屏障，实际验收见S13。

项目契约
Topic/接口$thing/up/signaling/{productID}/{deviceName}
发送→接收设备→平台
消息类型请求
对应应答requestAck
触发与状态变化报告设备实际传输状态。WebRTC 需 ICE/DTLS 成功；UDP 需有效会话媒体探测且平台也收到有效包。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试10秒；最多原token重试2次；事件形式不等待ACK
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S01、S02、S03、S05、S06、S07、S08、S09、S11

正文字段

字段类型必填条件枚举／默认及含义
mediaRevisionuint必填当前代次
statestring必填connected/failed
reasonstringfailed必填失败原因

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

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

对应S01-M07；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

trackControl · SIG↑

项目契约
Topic/接口$thing/up/signaling/{productID}/{deviceName}
发送→接收设备→平台
消息类型请求
对应应答反方向 trackState
触发与状态变化publish/stop 控制已协商源轨；publish不新增轨；subscribe/unsubscribe 仅本参与端订阅；pause/resume 只作用本端发布或订阅，不关闭其他观看者。请求不等于实际生效。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试10秒；最多原token重试2次；事件形式不等待ACK
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S06

正文字段

字段类型必填条件枚举／默认及含义
trackIdstring必填会话内轨ID
operationstring必填publish/subscribe/pause/resume/stop/unsubscribe
mediaRevisionuint必填当前代次
reasonstring可选停止原因

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

{
  "msgToken": "s06-84",
  "method": "trackControl",
  "sessionId": "s06-session",
  "params": {
    "trackId": "mic-1",
    "operation": "pause",
    "mediaRevision": 1
  }
}

对应S06-M16；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

trackState · SIG↑

新增IPC质量计划事实形态：设备收到 mediaUpdated(pending) 后实际调整驱动，再以独立 msgToken、无 code/eventSeq/messageSeq 的 trackState.data 上报；必须包含 trackId/state/mediaRevision/requestToken/revision，其中后两者关联原 mediaUpdate 计划。成功state为active/paused/stopped；失败为failed并带reason=qualityFailed/qualityUnsupported/qualityTimeout。应答为原上报token的 requestAck(data.requestMethod="trackState")，按原字节在10/20秒重试，30秒未确认记结果未知，不重新执行驱动。原计划或代次不匹配的迟到事实拒绝；通用成员轨事件仍不因此启用。

项目契约
Topic/接口$thing/up/signaling/{productID}/{deviceName}
发送→接收设备→平台
消息类型应答或事件
对应应答—
触发与状态变化双向实际状态；应答同 token 和 code，主动报告独立 token。设备失联只能标 unknown，不能假报 stopped。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试原控制回执不等待ACK；质量计划主动事实在10/20秒同token重试，30秒记未知
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S07、S09

正文字段

字段类型必填条件枚举／默认及含义
trackIdstring必填会话轨
statestring必填active/paused/stopped；质量失败为failed；unknown为其他设计场景，不能作质量成功
mediaRevisionuint必填当前代次
reasonstring失败或异步停轨必填原因
participantIdstring成员轨可选发布者
requestTokenstring质量计划事实必填原mediaUpdate token，不是此次上报的msgToken
revisionuint质量计划事实必填原pending确认的计划修订；与mediaRevision分开

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

{
  "msgToken": "s07-105",
  "method": "trackState",
  "sessionId": "s07-session",
  "code": 200,
  "data": {
    "trackId": "video-1",
    "state": "active",
    "mediaRevision": 1
  }
}

对应S07-M16；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

trackControl · SIG↓

对讲接收轨设备契约示例（speaker-1必须来自本会话原邀请，内部RPC用途字段不进入设备JSON）：

{
  "msgToken": "ipc-speaker-pause",
  "method": "trackControl",
  "sessionId": "ipc-talk-leg",
  "eventSeq": 3,
  "params": {
    "trackId": "speaker-1",
    "operation": "pause",
    "mediaRevision": 1
  }
}

设备驱动实际暂停后发送SIG↑回执，不附加新的eventSeq：

{
  "msgToken": "ipc-speaker-pause",
  "method": "trackState",
  "sessionId": "ipc-talk-leg",
  "code": 200,
  "data": {
    "trackId": "speaker-1",
    "state": "paused",
    "mediaRevision": 1
  }
}

恢复使用新token和递增eventSeq，operation=resume；实际成功回state=active。主动重复建立事件不能覆盖设备已确认的paused。失败按data.reason返回，不夹带成功state；会议挂断仍走sessionEnd，不用speaker stop替代。

项目契约
Topic/接口$thing/down/signaling/{productID}/{deviceName}
发送→接收平台→设备
消息类型请求
对应应答反方向 trackState
触发与状态变化publish/stop 控制已协商源轨；publish不新增轨；subscribe/unsubscribe 仅本参与端订阅；pause/resume 只作用本端发布或订阅，不关闭其他观看者。请求不等于实际生效。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试10秒；最多原token重试2次；事件形式不等待ACK
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S07、S09

正文字段

字段类型必填条件枚举／默认及含义
trackIdstring必填会话内轨ID
operationstring必填publish/subscribe/pause/resume/stop/unsubscribe
mediaRevisionuint必填当前代次
reasonstring可选停止原因

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

{
  "msgToken": "s07-105",
  "method": "trackControl",
  "sessionId": "s07-session",
  "eventSeq": 3,
  "params": {
    "trackId": "video-1",
    "operation": "publish",
    "mediaRevision": 1
  }
}

对应S07-M15；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

trackState · SIG↓

项目契约
Topic/接口$thing/down/signaling/{productID}/{deviceName}
发送→接收平台→设备
消息类型应答或事件
对应应答—
触发与状态变化双向实际状态；应答同 token 和 code，主动报告独立 token。设备失联只能标 unknown，不能假报 stopped。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试10秒；最多原token重试2次；事件形式不等待ACK
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S06

正文字段

字段类型必填条件枚举／默认及含义
trackIdstring必填会话轨
statestring必填active/paused/stopped/unknown
mediaRevisionuint必填当前代次
reasonstring失败或异步停轨必填原因
participantIdstring成员轨可选发布者

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

{
  "msgToken": "s06-84",
  "method": "trackState",
  "sessionId": "s06-session",
  "code": 200,
  "data": {
    "trackId": "mic-1",
    "state": "paused",
    "mediaRevision": 1
  }
}

对应S06-M17；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

participantChanged · SIG↓

此事件的 sessionId 必须是接收设备当前的独立会话腿，不是 IM 会议／通话组 ID。平台只向已在本次连接显式声明 features:[...,"participantRoster"] 的设备发送；能力缺省为不支持，不因已声明 humanCall、视频或多观看者而自动开启。成员关系和话权由原 IM 权威状态决定，设备名册投影及 tracks 描述不授予采集、媒体订阅或发言许可。共享 eventSeq 沿当前会话已消费水位判断重复／迟到，不要求相邻名册事件序号连续；其他信令也会消耗该水位。

当前会议音频已实现平台成员名册生成／持久投递、C++ 有界消费及完整名册查询；本生产子集的 tracks 必须为显式空数组，非空描述严格拒绝。加入复用原 IM group_invite/group_join 与 interaction.open，interaction.leave 已接入本人自退／主持移出，见 当前会议音频流程。interaction.join、成员独立轨关联／订阅及 trackState(reason=participantLeft) 仍待实现；下面完整轨字段与示例保留为完整设计，不能把当前名册或四端混音通过称为多轨会议完成。

项目契约
Topic/接口$thing/down/signaling/{productID}/{deviceName}
发送→接收平台→设备
消息类型事件
对应应答—
触发与状态变化成员变化独立于 sessionEstablished；离开撤销该成员源轨和订阅，不结束其他成员会话。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试不等待ACK；重复按公共规则丢弃/重放
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S06

正文字段

字段类型必填条件枚举／默认及含义
participantIdstring必填平台成员ID
changestring必填joined/left；joined为该成员当前完整条目快照，同成员的新事件替换原展示条目；left移除该成员条目，不操作真实媒体
tracksTrack[]必填joined携带该成员当前完整轨描述，可为空数组表示仅成员信息；不是轨增量。left携带离开的轨描述，但撤除整条成员展示记录，不据此授权或停止其他成员实际媒体

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

{
  "msgToken": "s06-93",
  "method": "participantChanged",
  "sessionId": "s-group-device-leg",
  "eventSeq": 1,
  "data": {
    "participantId": "user-b",
    "change": "joined",
    "tracks": [
      {
        "trackId": "user-b-audio",
        "kind": "audio",
        "sourceId": "user-b",
        "direction": "recvonly",
        "codec": "opus",
        "state": "requested"
      }
    ]
  }
}

对应S06-M39；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

processorState · SIG↓

项目契约
Topic/接口$thing/down/signaling/{productID}/{deviceName}
发送→接收平台→设备
消息类型事件
对应应答—
触发与状态变化仅应用鉴权接口可附加；设备不能用事件授予自己或 AI 读流权限；旁路失败不挂主通话。
前置条件会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试不等待ACK；重复按公共规则丢弃/重放
幂等与迟到遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景S05、S09

正文字段

字段类型必填条件枚举／默认及含义
processorIdstring必填处理器实例
processorstring必填translation/aiAssist
statestring必填attaching/active/detaching/detached/failed
sourceTrackIdsstring[]必填授权输入轨
reasonstring失败或撤销必填原因

所有成功字段表以外的共通错误负载为 data.reason:string；条件不满足时不要求成功字段。未声明可选字段缺省为“未提供”，无隐式开启能力。

报文实例

{
  "msgToken": "s05-73",
  "method": "processorState",
  "sessionId": "s-call",
  "eventSeq": 1,
  "data": {
    "processorId": "translation-1",
    "processor": "translation",
    "state": "active",
    "sourceTrackIds": [
      "call-mic",
      "call-peer"
    ]
  }
}

对应S05-M20；完整应答和异常在该场景或S11。设备Topic中的productID/deviceName来自认证，不从正文取身份。

新增/替换轨或修改协商参数走mediaUpdate，既有轨启停走trackControl；冲突与实际执行复用见公共流程。

更新日志

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