音声通話

ゲーム向け（声で話すアプリにも使えます）。音声通話はリアルタイムの部屋の中で使います。voiceを付けて部屋を作ると、その部屋のプレイヤー同士で声をやり取りできます。パーティー、チーム、対戦、大人数の集まりなどに使えます。1回の通話は100人までです。8人まではプレイヤー同士をつなぎ（P2P）、9人以上はKUMODeckの中継サーバー（SFU）を通します。どちらになるかは部屋の人数で自動で決まり、使い方は同じです。ONにするまではOFFで、リアルタイムの部屋もONにする必要があります。

kumodeck features on realtimeChannels voice
kumodeck config push --env development

KUMODeckは通話を録音しません。 声は聴く人へ届けるだけで、つなぐための合図のメッセージも中継したら捨てます。KUMODeckが持つのは、今だれが通話にいるかと、入った時刻だけです。

通話を始める#

const party = await kumo.realtime.create({ voice: true, maxMembers: 4, join: 'invited' });
await party.invite(playerId);                 // 入れる人（party.name をその人に渡す）

// join() はボタンから呼ぶ: ブラウザがマイクの許可を聞き、音はタップやクリックの後でないと鳴らせないため
await party.voice.join();                    // { mic: false } = 聴くだけ
party.voice.mute();                          // 自分のマイク
party.voice.unmute();
party.voice.on('speaking', ({ playerId, speaking }) => { … });   // 話している人を光らせる
await party.voice.leave();                   // 通話から出る（部屋には残る）

大人数の通話も同じ書き方です。

const hall = await kumo.realtime.create({ voice: true, maxMembers: 60 });   // 9人以上 = 中継サーバー
hall.voice.mode;                             // 'sfu'

通話があるのはvoiceを付けて作った部屋だけです。ほかの部屋ではch.voiceはnullです。ほかのプレイヤーはいつもどおり部屋に入り（kumo.realtime.join(party.name)）、そのあとch.voice.join()を呼びます。接続が切れたときは、SDKが部屋と通話に自動で入り直します。

人数と方式#

方式は部屋を作るときに決まり、通話の途中では変わりません。

中継サーバー（'sfu'）の部屋の決まり

• 聴こえるのは、自分以外で最近話した上位8人です。 大勢が同時に話しても聞き取れるのは数人までなので、聴く量（料金）が人数の2乗で増えないようにしています。ch.voice.peersは今聴いている人（8人まで）で、speakingもその人たちについて届きます。通話にいる全員はch.voice.membersで分かります。
• ミュートはサーバーが強制します。 持ち主や自分のサーバーがミュートした人、話せる人の名簿に無い人の声は、中継サーバーが誰にも配りません。改造したクライアントでも聴けません。
• 相手のIPアドレスは見えません（声は中継サーバーから届きます）。

状態・イベント・エラー#

自分のサーバーから（秘密鍵）#

自分のサーバーからも通話のある部屋を用意できます。PUT /v1/realtime/channels/@nameに{ "voice": true }を送ります（いつものjoin、send、maxMembers、allow、speakersも一緒に使えます）。人数による方式の決まりは上と同じで、{ "voice": { "mode": "sfu" } }で少人数でも中継サーバーにできます。{ "voice": { "mode": "p2p" } }は8人までの部屋にだけ使えます（9人以上はvoice_too_large）。すでにあるP2Pの部屋を9人以上に広げるときは、maxMembersと一緒に{ "voice": { "mode": "sfu" } }を送ってください（maxMembersだけでは方式は変わらず、voice_too_largeになります）。GETでvoice（modeを含む）と通話にいる人が分かります。通話に人がいる間は、音声の設定を変えられません（409 voice_in_use）。

P2Pの部屋では、既定で声はすべて中継を通るので、プレイヤーに相手のIPアドレスは見えません。これを外せるのは自分のサーバーだけで、部屋ごとに{ "voice": { "relayOnly": false } }とします（直接つながった組は中継の費用がかかりません）。13歳未満のプレイヤーは常に中継を通ります。中継サーバーの部屋ではこの設定は効きません。

ミュート・キック・BAN#

部屋の決まりがそのまま通話に効きます。持ち主（または自分のサーバー）のmute、send: 'invited'の部屋の話せる人の名簿、kick、banです。

• キックとBANは通信そのものを止めます。 そのプレイヤーは部屋と通話から外れ、中継を使う資格もすぐに取り消されます。ゲームからBANしたプレイヤーは、どの部屋にも入れません。キックした人は、部屋が入れる相手ならまた入れます。入らせたくないときはBANしてください。
• ミュートの効き方は方式で違います。 中継サーバー（'sfu'）では、サーバーがその人の声を配るのをやめます。P2P（'p2p'）では、KUMODeckが全員に「この人は話せない」と伝え、聴く人それぞれのSDKがその声の再生を止めます。声そのものはほかの人に届いているので、改造したクライアントなら再生できてしまいます。確実にミュートしたい部屋（知らない人どうしの通話など）はvoice: { mode: 'sfu' }で作るか、キックしてください。
• 表示名は誰かの証明になりません。 誰でもほかの人と同じ名前や「運営」のような名前を付けられます。持ち主や運営の印は、表示名ではなくプレイヤーID（ownerId）で出してください。
• 発言の中身の見張りは、クリエイターの責任です。 誰が話せるかを決め、困ったときにすぐ動けるようにしておいてください（ミュート・キック・BAN）。悪用があったときは、KUMODeckの運営が部屋やゲームの音声通話だけを止めることもあります（suspended）。

上限#

前払いの残高がなくなると、ほかのプレイヤー向けの機能と同じく、新しい通話は始められず、通話中の人も通話から外れます（closedのunavailable）。

料金#

KUMODeckの利用料（原価どおり）として、前払いの残高から差し引きます。費用がかかるのは、聴く人それぞれへ届けた声の量です。黙っている人はほとんど送りません（無音の間はSDKが送らない）。P2Pで直接つながった組は費用がかかりません。

P2P（8人まで）:

中継サーバー（9人以上）。1人が聴くのは8人までなので、費用は人数にほぼ比例します: