141 lines
No EOL
11 KiB
Markdown
141 lines
No EOL
11 KiB
Markdown
### 语音通信（VoIP）
|
||
|
||
本模块描述了房间内两位用户如何建立语音通信（VoIP）通话。语音和视频通话均基于 WebRTC 1.0 标准构建。通话信令通过向房间发送[消息事件](#events)来实现。在本规范版本中，仅支持双方通信（如两点对两点，或点对多点会议设备）。虽然通话可在包含多位成员的房间中发起，但同一时间仅允许两台设备参与通话。
|
||
|
||
所有 VoIP 事件均包含一个 `version` 字段。该字段用于判断设备是否支持此新版本的协议。例如，客户端可利用该字段判断是否应期待来自对方的 `m.call.select_answer` 事件。如果客户端接收到的事件 `version` 字段不是 `0` 或 `"1"`（包括如数值型 `1`），则应视同其 `version` == `"1"` 处理。
|
||
|
||
需注意，这意味着未来任何版本的 VoIP 事件均应保持向后兼容性。如有必要引入非兼容性新规范，则将采用一套独立的事件类型。
|
||
|
||
#### 通话方标识符
|
||
每当客户端首次参与新通话时，应为自身生成一个 `party_id`，在通话期间一直使用。此标识符应足够长，确保即使多设备同时生成应答，其间发生冲突的概率极低：建议使用 8 个大小写字母+数字字符。通话方通过 `(user_id, party_id)` 元组进行识别。
|
||
|
||
客户端将包含该 `party_id` 字段，并放置于所有 VoIP 事件内容的顶层，包括 `m.call.invite`。客户端用此字段识别自身事件的远端回显：由于用户可能与自己通话，无法简单地忽略来自自身用户的事件。此外，该字段还能区分不同客户端对同一邀请发出的不同应答，并将 `m.call.candidates` 事件与相应的应答/邀请进行匹配。
|
||
|
||
客户端实现可选择使用端到端加密中使用的设备 ID，用作此目的；或者可为每次通话生成不同 ID，以避免在未加密房间中泄露使用设备信息，或隐藏单一设备（即 Access Token）被用于多个通话方信令发送等信息。
|
||
|
||
`party_id` 的语法定义见[下文](#grammar-for-voip-ids)。
|
||
|
||
#### 礼让规则
|
||
根据 [WebRTC 完美协商示例](https://w3c.github.io/webrtc-pc/#perfect-negotiation-example)，在重新协商过程中存在礼让（politeness）规则。被叫方始终为礼让方。在碰撞（glare）情况下，通话方的礼让状态由是采纳呼入通话还是主动呼叫决定：如果客户端舍弃本地呼出而采用呼入通话，则其为礼让方。
|
||
|
||
#### 通话事件存活性
|
||
`m.call.invite` 中包含 `lifetime` 字段，指示邀约有效的时长。收到邀请后，客户端应结合事件同步响应中的 `age` 字段与自接收到该事件以来的时间，判断邀约是否依然有效。使用 `age` 字段可确保客户端设备错误时钟不会导致通话异常。
|
||
|
||
若邀约有效*且在用户可接受通话期间保持有效*，应提示有来电。用户可接受通话的时长可由不同客户端自行决定，例如在锁定的移动设备上，可以比在解锁的桌面设备上更长。
|
||
|
||
在处理完整个同步响应（sync response）并（对于加密房间）尝试解密该房间全部加密事件后，客户端才应提示来电。这样可以避免同步响应中含有随后指示通话已挂断、被拒绝或已被他处接听的事件时，重复提示来电。
|
||
|
||
若客户端启动后，在处理本地已存储事件后，发现仍有有效的邀约，应在与 homeserver 完成一次同步后再予以提示。
|
||
|
||
建议的最小有效时长为 90 秒——这样可确保用户有充足时间接听来电。
|
||
|
||
#### ICE 候选（Candidate）批量发送
|
||
客户端应设法只发送少量候选事件，具体指引如下：
|
||
* 在邀请/应答事件本身中，应立即或几乎立即发现的 ICE 候选（例如 host 类型 candidate）。如能在短时间内收集到服务器反射或中继 candidate，应一并发送。建议初始延迟约 200ms。
|
||
* 之后，客户端应等待一段时间以收集更多候选，实现批量发送，而非每获一个立刻发送。建议在发送邀请后等待 2 秒，或发送应答后等待 500ms（因发送邀请后，客户端本就等待用户接听，可利用此延迟）。
|
||
|
||
#### 结束候选通知（End-of-candidates）
|
||
值为空字符串的 ICE 候选表示不会再发送新的 ICE 候选。客户端必须在 `m.call.candidates` 消息中发送此类候选。虽然 WebRTC 规范要求浏览器生成此候选，但截止目前，并非所有浏览器都实现（Chrome 不生成，但会产生 `icegatheringstatechange` 事件）。候选生成结束时，客户端应立即发送全部候选，而不应再等待上文时间间隔。这可方便桥接到不支持逐步 ICE（trickle ICE）协议时对候选的批量处理。
|
||
|
||
#### DTMF
|
||
Matrix 客户端可按 WebRTC 规范发送 DTMF。截至 2020 年 8 月，WebRTC 标准尚不支持接收 DTMF，但 Matrix 客户端可接收并解析 RTP 负载中的 DTMF 信号。
|
||
|
||
#### VoIP 标识符的语法
|
||
|
||
`call_id` 和 `party_id` 必须遵循[不透明标识符语法](/appendices#opaque-identifiers)。
|
||
|
||
#### 离开房间时的行为
|
||
若客户端检测到正在通话的用户离开房间，应将其视作所有正在进行中的通话的挂断事件。对于发送邀约而被邀请方离开房间的情形，规范未做硬性规定，但若房间内已无可接听用户，客户端可选择将其视作被拒绝（如仅剩发送方本人，或邀约的 `invitee` 字段被设置后未被接听）。
|
||
|
||
历史通话回溯时亦应如此处理。
|
||
|
||
#### 支持的编解码器
|
||
Matrix 规范未强制指定特定音视频编解码器，完全遵循 WebRTC 规范。兼容的 Matrix VoIP 客户端将像被支持的“浏览器”一样，根据所支持的编解码器及其变体运作。需遵循最新的 WebRTC 规范版本，因此客户端应及时跟进 WebRTC 规范的新版本，无论 Matrix 规范是否变更。
|
||
|
||
#### 事件
|
||
|
||
##### 通用字段
|
||
|
||
{{% event-fields event_type="call_event" %}}
|
||
|
||
##### 事件
|
||
|
||
{{% event-group group_name="m.call" %}}
|
||
|
||
#### 客户端行为
|
||
|
||
通话建立流程如下，双方通过消息事件进行通信：
|
||
|
||
```
|
||
呼叫方 被叫方
|
||
[发起呼叫]
|
||
m.call.invite ----------->
|
||
m.call.candidate -------->
|
||
[..candidates..] -------->
|
||
[接听来电]
|
||
<--------------- m.call.answer
|
||
m.call.select_answer ----------->
|
||
[通话正在进行中]
|
||
<--------------- m.call.hangup
|
||
```
|
||
|
||
或通话被拒绝时：
|
||
|
||
```
|
||
呼叫方 被叫方
|
||
m.call.invite ------------>
|
||
m.call.candidate --------->
|
||
[..candidates..] --------->
|
||
[拒绝通话]
|
||
<-------------- m.call.hangup
|
||
```
|
||
|
||
通话协商遵循 WebRTC 规范进行。
|
||
|
||
面对来电，客户端可采取多种操作：
|
||
* 发送 `m.call.answer`，尝试接听通话。
|
||
* 主动在所有设备上拒绝通话：如上图，发送 `m.call.reject`，则所有用户设备均停止响铃，并通知呼叫方其来电被拒。
|
||
* 忽略通话：不发送任何事件，仅本地停止通话提示。用户的其他设备仍会继续响铃，呼叫方设备继续显示响铃，若无设备响应，通话将自动超时。
|
||
|
||
##### 多流（Streams）
|
||
|
||
客户端可在一次 VoIP 通话中发送多路流。应通过在 [`m.call.invite`](/client-server-api/#mcallinvite)、[`m.call.answer`](/client-server-api/#mcallanswer) 以及 [`m.call.negotiate`](/client-server-api/#mcallnegotiate) 事件中加入 `sdp_stream_metadata` 属性来区分流。当元数据发生变更但无需重新协商时，可发送 [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed) 事件。
|
||
|
||
推荐客户端对于带 `audio_muted` 字段且值设为 true 的来流，不要本地关闭 WebRTC 音轨。这是因为当对方取消静音后，客户端发送音频与 [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed) 事件到达之间可能略有延迟，这段音频会被错过。对方静音后将停止发送音频，无需担心无意识的音频发送。
|
||
|
||
对于 `video_muted`，建议仍应本地关闭视频流，避免接收端看到黑屏。
|
||
|
||
如 `sdp_stream_metadata` 存在，但来流未被列在其中，应直接忽略。若某流用途未知（`purpose` 类型未知）也应忽略。
|
||
|
||
为保证兼容性，若对方首次发来的 [`m.call.invite`](/client-server-api/#mcallinvite) 或 [`m.call.answer`](/client-server-api/#mcallanswer) 缺少 `sdp_stream_metadata` 属性，客户端应假定对方不支持此属性，即无法区分多流，客户端仅应使用第一条来流，并勿发送多于一条。
|
||
|
||
实现本规范的客户端应忽略无流的轨道（streamless tracks）。
|
||
|
||
##### 被邀请方
|
||
|
||
若通话仅面向特定用户，`invitee` 字段应被加入，并设置为该用户的 Matrix ID。不含 `invitee` 字段的邀请，默认为面向房间内除发送者以外任何成员。
|
||
|
||
客户端在接收到未过期的邀请，`invitee` 字段缺失或等于本用户 Matrix ID 时，应视为有效来电，但是否响铃需根据与呼叫方关系和来电地点判定。建议客户端默认忽略来自公共房间的呼叫邀请。强烈建议即便未为来电响铃，客户端也应在房间中展示来电并标记其被忽略。
|
||
|
||
##### 通话碰撞（Glare）
|
||
|
||
“通话碰撞”指两位用户几乎在同一时间互相呼叫对方，导致已有呼入/呼出通话而无法建立。可使用碰撞解决算法决定应挂断哪个通话，应接听哪个通话。如双方客户端实用相同算法，将会选择同一个通话，通话得以正常建立。
|
||
|
||
因通话目标为房间而非具体用户，以下碰撞解决算法仅适用于同一房间的通话：
|
||
|
||
- 若客户端在准备发送 `m.call.invite` 至某房间时，收到了同一房间的 `m.call.invite`：
|
||
- 客户端应取消本地外呼，转而自动为用户接听来电。
|
||
- 若客户端已向某房间发送 `m.call.invite` 并在等待响应时收到同房间的 `m.call.invite`：
|
||
- 客户端应对两个通话的 call_id 按字典序比较，保留较小者，挂断较大者；如来电为较小者，客户端应代表用户接听之。
|
||
|
||
对用户而言，通话建立过程应如同直接接通，无需察觉背后切换。任何初始化媒体流应当平滑迁移至被采纳的通话。
|
||
|
||
#### 服务器行为
|
||
|
||
Homeserver 可以（可选）向客户端提供 TURN 服务器信息，便于客户端通过 TURN 实现点对点通信。客户端可通过下述 HTTP API 获取 TURN 服务器信息。
|
||
|
||
{{% http-api spec="client-server" api="voip" %}}
|
||
|
||
#### 安全性考量
|
||
|
||
通话仅应在仅有两位用户的房间发起。若在多人聊天室发起，其他用户可能会拦截并接听该通话。 |