联犀开发者文档

翻译与旁路处理器

约 2888 字大约 10 分钟

2026-10-16

本页包含扩展设计，不能作为当前整场景已实现的承诺。参见支持范围、场景索引和命令手册。图中S编号只用于本文定位，不放入实际JSON。

前置条件

面对面翻译建立独立 faceTranslation 会话；通话翻译使用已有 humanCall 会话。说话人来自人工选择或已验证的分离结果，不能按音量推断身份。

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

完整时序

报文索引

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

编号发送→接收Topic/接口方法及契约应答/等待状态或作用
S05-M01A→PAPP↑interaction.openHTTP受理；随后 interaction.result；10秒平台验证目标、策略和能力后邀请设备；接收 HTTP202 不是接通。
S05-M02P→AAPP↓interaction.result—；不等待经 WS interaction.event 发给原操作者，原 token；设备通知不能充当应用请求应答。
S05-M03P→DSIG↓sessionInvitesessionAccept 或 sessionReject；30秒/到期平台邀请；humanCall 固定 accept；direct 也必须设备确认资源和隐私状态，不能跳过 sessionAccept。
S05-M04D→PSIG↑sessionAcceptrequestAck；10秒沿用邀请 msgToken。邀请答复本身是需确认的请求，等待平台 ACK 后协商媒体。
S05-M05P→DSIG↓requestAck—；不等待原邀请 token；确认接听有效，不携带 SDP、不宣告已接通。
S05-M06D→PSIG↑mediaOffermediaAnswer；15秒设备为自身 Peer 的 offerer；初始与重协商同一方法，只允许一个在途 offer。
S05-M07P→DSIG↓mediaAnswer—；不等待完成 SDP 交换，仍需 ICE/DTLS 连通与 mediaState，不直接 established。
S05-M08D→PSIG↑mediaStaterequestAck；10秒报告设备实际传输状态。WebRTC 需 ICE/DTLS 成功；UDP 需有效会话媒体探测且平台也收到有效包。
S05-M09P→DSIG↓requestAck—；不等待仅确认状态上报；平台须独立验证自身连通状态。
S05-M10P→DSIG↓sessionEstablished—；不等待平台确认所需参与端媒体已连通后通知；不等于已收到首包或扬声器起播。
S05-M11P→AAPP↓interaction.state—；不等待原操作者/参与者会话事件；与 interaction.result 独立；有 eventSeq。
S05-M12P→DMSG↓translationResult—；不等待字幕和译音关联；旧配置结果不送新方向播报。
S05-M13A→PAPP↑interaction.configureHTTP受理；随后 interaction.result；10秒翻译语言方向变更；清旧方向缓存，结果带新 configRevision。
S05-M14P→AAPP↓interaction.result—；不等待经 WS interaction.event 发给原操作者，原 token；设备通知不能充当应用请求应答。
S05-M15P→DMSG↓translationResult—；不等待字幕和译音关联；旧配置结果不送新方向播报。
S05-M16D→PSIG↑sessionEndsessionEnded；10秒设备主动结束整个会话，立即本地停采集/播放；平台撤销轨、处理器、密钥/令牌及资源占用。
S05-M17P→DSIG↓sessionEnded—；不等待主动结束用原 token 和 code；其他结束用独立事件 token 与 eventSeq。ended 是唯一会话终态。
S05-M18A→PAPP↑interaction.processorControlHTTP受理；随后 interaction.result；10秒detach 先撤权再释放处理器；旁路失败只回本次操作错误，主通话继续。
S05-M19P→AAPP↓interaction.result—；不等待经 WS interaction.event 发给原操作者，原 token；设备通知不能充当应用请求应答。
S05-M20P→DSIG↓processorState—；不等待仅应用鉴权接口可附加；设备不能用事件授予自己或 AI 读流权限；旁路失败不挂主通话。
S05-M21A→PAPP↑interaction.processorControlHTTP受理；随后 interaction.result；10秒detach 先撤权再释放处理器；旁路失败只回本次操作错误，主通话继续。
S05-M22P→AAPP↓interaction.result—；不等待经 WS interaction.event 发给原操作者，原 token；设备通知不能充当应用请求应答。
S05-M23P→DSIG↓processorState—；不等待仅应用鉴权接口可附加；设备不能用事件授予自己或 AI 读流权限；旁路失败不挂主通话。
S05-M24P→AAPP↓interaction.result—；不等待经 WS interaction.event 发给原操作者，原 token；设备通知不能充当应用请求应答。

逐条JSON

S05-M01 · interaction.open

{
  "msgToken": "s05-62",
  "method": "interaction.open",
  "params": {
    "purpose": "faceTranslation",
    "sourceLanguage": "zh-CN",
    "targetLanguage": "en-US"
  },
  "target": {
    "productID": "p-demo",
    "deviceName": "device-demo"
  }
}

S05-M02 · interaction.result

{
  "msgToken": "s05-62",
  "method": "interaction.result",
  "sessionId": "s05-session",
  "code": 200,
  "data": {
    "operation": "interaction.open",
    "state": "invited",
    "sessionId": "s05-session"
  }
}

S05-M03 · sessionInvite

{
  "msgToken": "s05-63",
  "method": "sessionInvite",
  "sessionId": "s05-session",
  "eventSeq": 1,
  "params": {
    "purpose": "faceTranslation",
    "admission": "accept",
    "transport": "webrtc",
    "tracks": [
      {
        "trackId": "mic-1",
        "kind": "audio",
        "sourceId": "mic",
        "direction": "sendonly",
        "codec": "opus",
        "state": "requested"
      },
      {
        "trackId": "speaker-1",
        "kind": "audio",
        "sourceId": "speaker",
        "direction": "recvonly",
        "codec": "opus",
        "state": "requested"
      }
    ],
    "expiresAt": 1900000000000,
    "sourceLanguage": "zh-CN",
    "targetLanguage": "en-US"
  }
}

S05-M04 · sessionAccept

{
  "msgToken": "s05-63",
  "method": "sessionAccept",
  "sessionId": "s05-session",
  "params": {
    "acceptedTracks": [
      "mic-1",
      "speaker-1"
    ]
  }
}

S05-M05 · requestAck

{
  "msgToken": "s05-63",
  "method": "requestAck",
  "sessionId": "s05-session",
  "code": 200,
  "data": {
    "requestMethod": "sessionAccept",
    "result": {
      "state": "negotiating"
    }
  }
}

S05-M06 · mediaOffer

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

S05-M07 · mediaAnswer

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

S05-M08 · mediaState

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

S05-M09 · requestAck

{
  "msgToken": "s05-65",
  "method": "requestAck",
  "sessionId": "s05-session",
  "code": 200,
  "data": {
    "requestMethod": "mediaState",
    "result": {
      "mediaRevision": 1,
      "state": "connected"
    }
  }
}

S05-M10 · sessionEstablished

{
  "msgToken": "s05-66",
  "method": "sessionEstablished",
  "sessionId": "s05-session",
  "eventSeq": 2,
  "data": {
    "state": "established",
    "mediaRevision": 1
  }
}

S05-M11 · interaction.state

{
  "msgToken": "s05-67",
  "method": "interaction.state",
  "sessionId": "s05-session",
  "eventSeq": 3,
  "data": {
    "state": "established"
  }
}

S05-M12 · translationResult

{
  "msgToken": "s05-68",
  "method": "translationResult",
  "sessionId": "s05-session",
  "messageSeq": 1,
  "data": {
    "resultSeq": 1,
    "speakerId": "person-a",
    "sourceLanguage": "zh-CN",
    "targetLanguage": "en-US",
    "sourceText": "你好",
    "translatedText": "Hello",
    "outputTrackId": "speaker-1",
    "configRevision": 1
  }
}

S05-M13 · interaction.configure

{
  "msgToken": "s05-69",
  "method": "interaction.configure",
  "sessionId": "s05-session",
  "params": {
    "sourceLanguage": "en-US",
    "targetLanguage": "zh-CN",
    "speakerId": "person-b",
    "configRevision": 2
  }
}

S05-M14 · interaction.result

{
  "msgToken": "s05-69",
  "method": "interaction.result",
  "sessionId": "s05-session",
  "code": 200,
  "data": {
    "operation": "interaction.configure",
    "state": "applied"
  }
}

S05-M15 · translationResult

{
  "msgToken": "s05-70",
  "method": "translationResult",
  "sessionId": "s05-session",
  "messageSeq": 2,
  "data": {
    "resultSeq": 2,
    "speakerId": "person-b",
    "sourceLanguage": "en-US",
    "targetLanguage": "zh-CN",
    "sourceText": "Thank you",
    "translatedText": "谢谢",
    "outputTrackId": "speaker-1",
    "configRevision": 2
  }
}

S05-M16 · sessionEnd

{
  "msgToken": "s05-71",
  "method": "sessionEnd",
  "sessionId": "s05-session",
  "params": {
    "reason": "userHangup"
  }
}

S05-M17 · sessionEnded

{
  "msgToken": "s05-71",
  "method": "sessionEnded",
  "sessionId": "s05-session",
  "code": 200,
  "data": {
    "state": "ended",
    "reason": "userHangup"
  }
}

S05-M18 · interaction.processorControl

{
  "msgToken": "s05-72",
  "method": "interaction.processorControl",
  "sessionId": "s-call",
  "params": {
    "processorId": "translation-1",
    "processor": "translation",
    "operation": "attach",
    "sourceTrackIds": [
      "call-mic",
      "call-peer"
    ],
    "consentIds": [
      "consent-a",
      "consent-b"
    ],
    "targetLanguage": "zh-CN"
  }
}

S05-M19 · interaction.result

{
  "msgToken": "s05-72",
  "method": "interaction.result",
  "sessionId": "s-call",
  "code": 200,
  "data": {
    "operation": "interaction.processorControl",
    "state": "active",
    "processorId": "translation-1"
  }
}

S05-M20 · processorState

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

S05-M21 · interaction.processorControl

{
  "msgToken": "s05-74",
  "method": "interaction.processorControl",
  "sessionId": "s-call",
  "params": {
    "processorId": "translation-1",
    "processor": "translation",
    "operation": "detach",
    "sourceTrackIds": [
      "call-mic",
      "call-peer"
    ]
  }
}

S05-M22 · interaction.result

{
  "msgToken": "s05-74",
  "method": "interaction.result",
  "sessionId": "s-call",
  "code": 200,
  "data": {
    "operation": "interaction.processorControl",
    "state": "detached",
    "processorId": "translation-1"
  }
}

S05-M23 · processorState

{
  "msgToken": "s05-75",
  "method": "processorState",
  "sessionId": "s-call",
  "eventSeq": 2,
  "data": {
    "processorId": "translation-1",
    "processor": "translation",
    "state": "detached",
    "sourceTrackIds": [
      "call-mic",
      "call-peer"
    ],
    "reason": "consentRevoked"
  }
}

S05-M24 · interaction.result

{
  "msgToken": "s05-72",
  "method": "interaction.result",
  "sessionId": "s-call",
  "code": 403,
  "data": {
    "operation": "interaction.processorControl",
    "state": "failed",
    "reason": "participantConsentMissing",
    "processorId": "translation-1"
  }
}

媒体与本地动作

编号路径格式与约束
S05-R01D→PWebRTC ICE + DTLS 握手；完整 SDP 不代表握手成功；只有网络连通后才报告 connected。
S05-R02D→PWebRTC DTLS-SRTP Opus 原声；双方知情同意；原声和译音不能形成回灌。
S05-R03P→DWebRTC 独立译音轨 speaker-1；字幕和译音可以不同时间到达。

异常、状态与资源释放

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

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

运行中处理器故障上报 processorState(failed)，主通话保持 established。撤权先断旁路输入再清上下文，不继续发送字幕或译音；恢复需要重新授权。

能力不支持、无权限、设备拒绝、协商失败、断网、重复请求、过期会话及迟到媒体按S11共通失败流程和公共错误表处理。业务专属分支以本页为准，不因错误静默打开额外能力。

验证入口

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

更新日志

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