複数人の音声ルーム

# 複数人の音声ルーム

3〜4人が、それぞれ自分のブラウザーから1つの音声ルームで話せます。1つのルームには最大4人まで参加できます。音声はLiveKitが伝送し、誰が参加し、話し、聞けるかはOneSayが決めます。クライアントが何を送っても、サーバーがすべてのステップを確認します。[コンソール](../developer/CONSOLE.md)には、これらのステップを案内する音声ルームパネルが用意されています。このページでは各ステップを説明するので、同じ流れを自分のアプリケーションで構築できます。

これはメンバーが固定のプレビューです。ほかの人を招待する前に、このページの最後にある現在の制限をお読みください。

## 必要なもの

- Staging上のプロジェクト環境と、その中のアプリケーション。
- 参加者ごとに、アプリケーションを通じた本人のOneSayサインイン（これで人間のユーザーの短期トークンを得ます。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. **ルームを作成または参加する。**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 });
```

ルームとアプリセッションは、ステップ1と2のとおりControl APIで作成します（`createRoom`、`createAppSession`）。

## 同意

Stagingでは、何かを作成、変更、終了するステップは、必ず先に本人に確認を求めます。ルームの作成、アプリセッションの開始、接続、公開、受信、退出の各ステップです。アプリケーションは、そのステップそのものの確認をOneSayに依頼し（`createConsentRequest`）、それを表示し、本人が選んだ許可または拒否を記録してから（`decideConsentRequest`）、同じ入力でステップを実行します。既定で許可されるものはなく、参加者一覧のような読み取りには確認は不要です。コンソールの音声ルームパネルがこの流れを示しています。

## 現在の制限（プレビュー）

- **メンバーは固定。**作成者が3〜4人を決めます。全員が参加して話し始めてから受信を始め、各自のサブスクリプションは一度だけ設定します。
- **誰かが退出しても、ほかの人の接続は終了しなくなりましたが、メンバーは変更できません。**このプレビューでは、メンバーの追加も削除もできません。誰かが退出した後は、サブスクリプションの対象を変えないでください。別のメンバーで話すには、退出して新しいルームを始めてください。
- **一人ずつ。**一人ずつ参加してください。前の人が参加者一覧（`listRoomParticipants`。コンソールでは「参加者」）に表示されるまで待ってから参加します。同時に参加したり同時に受信を開始したりすると、接続に失敗したり、声が届かないままになったりすることがあります。サービスが混み合っていてステップが失敗した場合は、同じキーで再試行してください。それでも誰かの声が聞こえない場合は、退出して新しいルームを始めてください。
- **1つのルームは最大4人。**
- **音声のみ。**ビデオ、画面共有、録音、モデレーション、ゲストリンク、ダイヤルインはこのプレビューに含まれません。