房间信令

Room 使用 TiRTC 命令通道 0x2200 承载 JSON-RPC 2.0 房间信令。信令用于同步房间状态，不承载音频数据。

消息格式

设备调用 TiRtcWhipConnect(peer_id, token) 完成连接后，应监听 Room 服务下发的房间信令。

Room 服务下发的房间事件使用 JSON-RPC Notification 消息，不包含 id，不需要设备端回复：

{
  "jsonrpc": "2.0",
  "method": "room_snapshot",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant_id": "device_device-001",
    "self": {
      "participant_id": "device_device-001",
      "device_id": "device-001"
    },
    "participants": [
      {
        "participant_id": "device_device-001",
        "device_id": "device-001",
        "state": "active",
        "mic_state": "on"
      }
    ]
  }
}

设备端可以通过 JSON-RPC Request 或 Notification 主动同步房间状态。Request 需要包含 id，Room 服务会返回同一个 id 的 Response；Notification 不包含 id，Room 服务不会返回响应。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_mic_state",
  "params": {
    "mic_state": "off"
  }
}

通用字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
method	string	Notification / Request 必填	信令方法名。
params	object	按方法定义	方法参数。没有参数的方法可省略该字段。
id	number	Request 必填，Notification 禁止	请求标识。Room 服务下发的事件不包含该字段。
result	object	Response 成功时按方法定义	请求成功结果。
error	object	Response 失败时必填	JSON-RPC 错误对象。

方法列表

方法	方向	类型	说明
join_room	设备端 → Room 服务	Request	校验身份和音频格式，成功后正式加入房间。
leave_room	设备端 → Room 服务	Notification	主动离开当前会话。
get_room_snapshot	设备端 → Room 服务	Request / Notification	主动拉取当前房间快照。
set_mic_state	设备端 → Room 服务	Request / Notification	上报本端麦克风状态。
room_snapshot	Room 服务 → 设备端	Notification	join_room 成功后下发当前房间快照。
participant_joined	Room 服务 → 设备端	Notification	新成员加入后，下发给其他在线设备。
participant_left	Room 服务 → 设备端	Notification	成员离开后，下发给其他在线设备。
participant_mic_state_changed	Room 服务 → 设备端	Notification	成员麦克风状态变化后，下发给其他在线设备。
room_closed	设备端 → Room 服务 / Room 服务 → 设备端	Notification	设备端请求关闭整个房间；房间关闭时，Room 服务向房间成员下发。

join_room

方向：设备端 → Room 服务。类型：Request。TiRTC 建连后必须在 10 秒内发送，且同一连接只能成功调用一次。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "join_room",
  "params": {
    "room_id": "room-001",
    "device_id": "device-001",
    "input_audio": {"codec": "pcm", "sample_rate": 16000, "channels": 1},
    "output_audio": {"codec": "g711a", "sample_rate": 16000, "channels": 1}
  }
}

room_id、device_id 必须与 WHIP Token 签名参数一致。input_audio 与 output_audio 可独立指定编码和采样率；上下行均支持 opus、pcm、g711a、amr，采样率支持 8000 和 16000，声道固定为 1。其中 amr/8000/1 对应 AMR-NB，amr/16000/1 对应 AMR-WB。成功响应包含 session_id、规范化后的 input_audio 和 output_audio，设备端必须以响应中的实际格式为准。

旧的 start_session 不再兼容。TiRTC 建连后，如果首个带 id 的业务请求不是 join_room，服务端会返回 method_not_found 并关闭连接；超过 10 秒未完成入房，服务端也会关闭连接。

leave_room

方向：设备端 → Room 服务。类型：Notification。设备端主动离房时，应在关闭媒体连接前发送。

{
  "jsonrpc": "2.0",
  "method": "leave_room"
}

leave_room 不需要参数，并且禁止携带 id。服务端收到后会立即移除当前参与者、关闭当前会话，并向其他在线设备下发 participant_left。如果携带 id，服务端会返回 invalid_request，且不会执行离房。

设备断开连接或调用 DELETE session 时，服务端也会兜底清理会话；正常离房应优先发送 leave_room。

get_room_snapshot

方向：设备端 → Room 服务。

类型：Request 或 Notification。

触发时机：设备端需要主动刷新本地成员列表时发送。常见场景是命令通道刚打开、设备端错过初始快照，或本地成员列表需要重新对齐。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_room_snapshot",
  "params": {}
}

字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
id	number	Request 必填；Notification 禁止	请求标识。使用 Notification 发送时省略。
method	string	是	固定为 get_room_snapshot。
params	object	否	当前无参数，可省略或传空对象。

Room 服务处理成功后，会向当前设备下发一条 room_snapshot Notification；如果使用带 id 的 Request，Room 服务还会按 JSON-RPC 返回成功或失败 Response。

set_mic_state

方向：设备端 → Room 服务。

类型：Request 或 Notification。

触发时机：本端麦克风开关或讲话状态变化时发送。该信令只同步状态，不直接控制音频混流；设备端仍需要自行控制是否采集和上行音频。

{
  "jsonrpc": "2.0",
  "method": "set_mic_state",
  "params": {
    "mic_state": "speaking"
  }
}

字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
id	number	Request 必填；Notification 禁止	请求标识。使用 Notification 发送时省略。
method	string	是	固定为 set_mic_state。
params	object	是	麦克风状态参数。
params.mic_state	string	是	on 表示开，speaking 表示开且正在说话，off 表示关。

Room 服务记录状态后，会向其他在线设备下发 participant_mic_state_changed。如果发送的是带 id 的 Request，成功响应如下：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "ok": true
  }
}

room_snapshot

方向：Room 服务 → 设备端。

类型：Notification。

触发时机：设备连接完成并加入房间后，Room 服务向该设备下发当前房间快照。

{
  "jsonrpc": "2.0",
  "method": "room_snapshot",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant_id": "device_device-001",
    "self": {
      "participant_id": "device_device-001",
      "device_id": "device-001"
    },
    "participants": [
      {
        "participant_id": "device_device-002",
        "device_id": "device-002",
        "state": "active",
        "mic_state": "on"
      }
    ]
  }
}

字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
method	string	是	固定为 room_snapshot。
params	object	是	当前房间快照参数。
id	number	否	Notification 不包含 id。
params.room_id	string	是	房间 ID。
params.participant_id	string	是	当前接收该快照的参与者 ID。
params.self	object	是	当前设备自身信息。
params.self.participant_id	string	是	当前设备对应的参与者 ID。
params.self.device_id	string	是	当前设备 ID。
params.participants	array	是	当前房间内的参与者列表。
params.participants[].participant_id	string	是	参与者 ID。
params.participants[].device_id	string	是	参与者对应的设备 ID。
params.participants[].state	string	是	参与者状态。当前在线成员为 active。
params.participants[].mic_state	string	是	参与者麦克风状态：on 表示开，speaking 表示开且正在说话，off 表示关。

participant_joined

方向：Room 服务 → 设备端。

类型：Notification。

触发时机：有新成员连接完成并加入房间后，Room 服务向其他在线设备下发该通知。

{
  "jsonrpc": "2.0",
  "method": "participant_joined",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant": {
      "participant_id": "device_device-002",
      "device_id": "device-002",
      "state": "active",
      "mic_state": "on"
    }
  }
}

字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
method	string	是	固定为 participant_joined。
params	object	是	新成员加入参数。
id	number	否	Notification 不包含 id。
params.room_id	string	是	房间 ID。
params.participant	object	是	新加入的参与者信息。
params.participant.participant_id	string	是	新加入成员的参与者 ID。
params.participant.device_id	string	是	新加入成员对应的设备 ID。
params.participant.state	string	是	新加入成员状态。当前在线成员为 active。
params.participant.mic_state	string	是	新加入成员的麦克风状态：on、speaking 或 off。

participant_left

方向：Room 服务 → 设备端。

类型：Notification。

触发时机：成员断开连接或退出房间后，Room 服务向其他在线设备下发该通知。

{
  "jsonrpc": "2.0",
  "method": "participant_left",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant_id": "device_device-002"
  }
}

字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
method	string	是	固定为 participant_left。
params	object	是	成员离开参数。
id	number	否	Notification 不包含 id。
params.room_id	string	是	房间 ID。
params.participant_id	string	是	已离开成员的参与者 ID。

participant_mic_state_changed

方向：Room 服务 → 设备端。

类型：Notification。

触发时机：某个成员通过 set_mic_state 上报麦克风状态变化后，Room 服务向其他在线设备下发该通知。

{
  "jsonrpc": "2.0",
  "method": "participant_mic_state_changed",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant_id": "device_device-002",
    "mic_state": "off"
  }
}

字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
method	string	是	固定为 participant_mic_state_changed。
params	object	是	成员麦克风状态变化参数。
id	number	否	Notification 不包含 id。
params.room_id	string	是	房间 ID。
params.participant_id	string	是	状态变化成员的参与者 ID。
params.mic_state	string	是	on 表示开，speaking 表示开且正在说话，off 表示关。

room_closed

方向：设备端 → Room 服务；Room 服务 → 设备端。

类型：Notification。

触发时机：业务允许设备关闭房间时，设备端可以发送该通知请求关闭整个房间；Room 服务关闭房间时向房间成员下发该通知。

{
  "jsonrpc": "2.0",
  "method": "room_closed",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "reason": "closed_by_service"
  }
}

字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
method	string	是	固定为 room_closed。
params	object	是	房间关闭参数。
id	number	否	Notification 不包含 id。
params.room_id	string	是	房间 ID。
params.reason	string	否	关闭原因。未提供时设备端仅按房间已关闭处理。

Request 与 Response

设备端必须把 join_room 作为 Request 发送，也可以把 get_room_snapshot 和 set_mic_state 作为 Request 发送。带 id 的 Request 会收到成功或失败 Response；leave_room 必须作为不带 id 的 Notification 发送，不会收到响应。

Request 示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_mic_state",
  "params": {
    "mic_state": "off"
  }
}

Request 字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
id	number	是	请求标识，Room 服务会在响应中原样返回。
method	string	是	请求方法名。当前公开 join_room、get_room_snapshot 和 set_mic_state。
params	object	否	请求参数。没有参数时可省略或传空对象。

错误 Response 示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not found"
  }
}

错误 Response 字段说明：

字段	类型	是否必填	含义
jsonrpc	string	是	固定为 2.0。
id	number	是	对应 Request 的 id。
error	object	是	错误对象。
error.code	number	是	错误码。
error.message	string	是	错误描述。
result	object	否	成功响应结果。错误响应不包含该字段。

错误码

Room 服务遵循 JSON-RPC 2.0 错误格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not found"
  }
}

Room 服务定义了以下标准错误码：

错误码	名称	说明
-32700	parse_error	JSON 解析失败。
-32600	invalid_request	请求格式非法。
-32601	method_not_found	方法不存在或当前未开放。
-32602	invalid_params	参数非法。
-32603	internal_error	内部错误。

Room 服务还定义了以下业务错误码：

错误码	名称	说明
-32001	room_not_ready	房间会话尚未就绪。
-32002	participant_mismatch	信令中的参与者与 token 不一致。
-32003	room_full	房间人数已满。
-32004	permission_denied	没有执行该操作的权限。

处理建议

• TiRTC TiRtcWhipConnect 返回连接完成后，设备端应先发送 join_room；成功后监听 room_snapshot 初始化本地成员列表，如需主动对齐状态可发送 get_room_snapshot。
• 收到 participant_joined、participant_left 或 participant_mic_state_changed 后，应更新本地成员状态。
• 本端麦克风开关或讲话状态变化时，可发送 set_mic_state 同步状态；该方法不代替本地采集和上行控制。
• 主动离房时，应先发送 leave_room Notification，再进入资源释放流程。
• 收到 room_closed 后，应立即停止播放并释放本地媒体资源。