多人语音房间

# 多人语音房间

三到四个人可以在同一个语音房间里通话，每个人使用自己的浏览器。一个房间最多容纳四个人。音频由LiveKit传输，谁可以加入、说话和收听则由OneSay决定：无论客户端发送什么，服务端都会检查每一步。[控制台](../developer/CONSOLE.md)提供了现成的多人语音房间面板，会带你完成这些步骤。本页讲解这些步骤，方便你在自己的应用中实现同样的流程。

这是成员固定的预览版。邀请其他人之前，请先阅读本页末尾的当前限制。

## 准备工作

- Staging上的一个项目环境，以及其中的一个应用。
- 每个人都需要：通过你的应用用自己的OneSay账号登录，得到一个短期有效的人类用户Token（不要把API密钥放进浏览器）；还需要一个麦克风音频源。
- 每个人在该项目环境中都需要以下授权：`room.read`、`participant.read`、`room.join`、`source.use`、`signal.audio.publish`、`rtc.subscription.configure`、`signal.audio.subscribe`、`signal.audio.end`、`app.session.create`和`app.session.close`。创建房间的人还需要`room.create`和`room.close`。

## 步骤

每个人按顺序完成以下步骤。请依次加入：等前一个人出现在参与者列表（`listRoomParticipants`；在控制台中为“房间里有谁”）中后再加入；同时加入或同时开始收听的人可能连接失败，或者其他人一直听不到他们。

1. **创建或加入房间。**由一个人用`POST /rooms`（`createRoom`）创建房间，把`max_participants`设为小组人数（3或4），并分享以`room_`开头的房间ID。其他人用`GET /rooms/{room_id}`（`getRoom`）读取房间，确认它仍然开放并且还没有开始。
2. **启动应用会话：**为你的应用调用`POST /app-sessions`（`createAppSession`）。
3. **连接：**使用SDK的`client.rtc.connect`（`createRTCConnection`）。此时还没有人能听到你。
4. **发布麦克风：**用你的麦克风音频源调用`session.audio.publishMicrophone`（`createRTCPublication`）。
5. **让下一个人加入。**等你出现在参与者列表中（第6步）后，下一个人再开始第3步。
6. **查看成员列表。**`GET /rooms/{room_id}/participants`（`listRoomParticipants`）列出房间里的人，`GET /rooms/{room_id}/signals`（`listRoomSignals`）列出他们的音频。如果某人有一个信号的预设是`audio.rtc.v1`、状态是`active`，这个人就在说话。只选`active`的信号：`pending`表示还没有发布。
7. **开始收听，只做一次。**所有人都在说话后，每个人用`session.audio.setSubscriptions`（`updateRTCSubscriptions`）设置一次订阅：列出以`pub_`开头的ID，取自其他人信号的`publication_id`字段（只取`active`的信号），排好序，并把`expected_policy_version`设为0。请每个人间隔几秒依次开始收听，之后不要再更改订阅的音轨。
8. **打开声音：**由本人点击来调用`session.audio.enablePlayback`，这是浏览器的要求。
9. **离开。**先结束麦克风音轨（`endRTCPublication`），再关闭会话，这会撤销连接（`revokeRTCConnection`），然后关闭应用会话（`closeAppSession`）。房间创建者还可以关闭房间（`closeRoom`）。

## JavaScript

下面的示例只使用公开的JavaScript SDK。`humanToken`、各个ID和幂等键都来自你的应用。请保存每个键，这样重试同一步骤时会发送同一个键。

```js
import { OneSayClient } from "@onesay/sdk";

// A short-lived Human token from your own sign-in; never an API key.
const client = new OneSayClient({ environment: "staging", tokenProvider: async () => humanToken });

// Step 3: connect with your app session.
const session = await client.rtc.connect({ roomId, appSessionId, idempotencyKey: connectKey });

// Step 4: publish your microphone Source.
const microphone = await session.audio.publishMicrophone({ sourceId, idempotencyKey: publishKey });

// Step 7: when everyone speaks, listen once to the others' active publications.
await session.audio.setSubscriptions({ publicationIds: otherPublicationIds, expectedPolicyVersion: 0, idempotencyKey: listenKey });

// Step 8: sound starts from the person's own click.
soundButton.onclick = () => session.audio.enablePlayback();

// Step 9: leave.
await microphone.end({ idempotencyKey: endKey });
await session.close({ idempotencyKey: closeKey });
```

房间和应用会话通过Control API创建（`createRoom`、`createAppSession`），见第1步和第2步。

## 用户同意

在Staging上，凡是创建、修改或结束资源的步骤，都会先请本人确认：创建房间、启动应用会话、连接、发布、收听，以及离开时的每一步。你的应用先针对这一步的确切输入向OneSay发起确认请求（`createConsentRequest`），展示给本人，记录本人自己选择的允许或拒绝（`decideConsentRequest`），然后用同样的输入执行这一步。默认不会允许任何操作；查看成员列表这类读取操作不需要确认。控制台的多人语音房间面板演示了这种做法。

## 当前限制（预览版）

- **成员固定。**创建者选定三到四个人。所有人都先加入并开始说话，然后才开始收听，每个人只设置一次订阅。
- **有人离开不再会结束其他人的连接，但成员无法变更。**本预览版中无法添加或移除任何人：有人离开后请不要更改订阅的音轨。要换一组人继续通话，请离开并新建一个房间。
- **依次加入。**一次只加入一个人。请依次加入：等前一个人出现在参与者列表（`listRoomParticipants`；在控制台中为“房间里有谁”）中后再加入；同时加入或同时开始收听的人可能连接失败，或者其他人一直听不到他们。如果某一步因服务繁忙而失败，请用同一个键重试。如果仍听不到某个人，请离开并新建一个房间。
- **一个房间最多四个人。**
- **仅支持语音。**本预览版不包含视频、屏幕共享、录制、主持管理、访客链接和电话拨入。