以下の呼び出しでは、実装に使用できる Voice RTC API を使用しています。Voice Web API については、「Web API の概要」および「Voice Web API」のドキュメントを参照してください。
Voice インターフェースを使用するには、以下の手順に従う必要があります。
ゲームで使用する 統合方法 をレビューして決定する
Voice インターフェースをアプリケーションに組み込む
クライアント ポリシー を設定する
選択した統合方法に基づいて Voice インターフェイスを統合します。
Voice インターフェースの ベスト プラクティス、Voice のメトリック、および 使用上の制限事項 をレビューする
Voice を Lobby で使用する 場合、Lobbies インターフェイスによって以下が自動的に行われます。
ルーム トークンの再リクエストとリフレッシュ
ユーザーのロビーへ入室 / 退出時にあわせたボイス ルームへの参加 / 退出
信頼済みサーバーで Voice を使用する場合、以下を行う必要があります。
ユーザーの代わりにトークンをリクエストする
ゲーム クライアントにトークンを更新するための呼び出しを行わせる
ゲーム クライアントにボイス ルームの入室 / 退出のための呼び出しを行わせる
ルームに参加するためのトークンをリクエストする (信頼済みサーバーによる手法)
Lobby インターフェースはメンバーに対して自動的にルーム トークンを返します。
信頼済みサーバーのカスタム実装を使用する場合は、ルーム アクセスを管理し、プレイヤーがメディア サーバー上のそのルームに参加できるようにするためのトークンをリクエストする必要があります。EOS_RTCAdmin_QueryJoinRoomToken を使って行うことができます。Developer Portal で 'Voice:createRoomToken' ポリシー アクション を有効にする必要があります。
EOS_RTCAdminQueryJoinRoomTokenEOS_RTCAdminQueryJoinRoomToken は非同期の操作であり、完了時に (EOS_RTCAdmin_QueryJoinRoomTokenCompleteCallbackInfo を参照) メディア サーバーの URL およびトークンを取得する QueryId が提供されます。
QueryId QueryId はそのコールバックの存続中のみ有効であるため、そのコールバック内でトークンを取得する必要があります。
そのコールバック内で、EOS_RTCAdmin_CopyUserTokenByIndex および EOS_RTCAdmin_CopyUserTokenByUserId を使用してトークンを取得できます。
EOS_RTCAdmin_UserToken が不要になったら、EOS_RTCAdmin_UserToken_Release を使用してそのリソースを解放できます。
EOS_RTCAdmin_QueryJoinRoomToken を使用すると、1 回の呼び出しで複数のユーザー用のトークンをリクエストできます (EOS_RTCAdmin_QueryJoinRoomTokenOptions を参照)。
トークンの有効期限 (信頼済みサーバーによる手法)
ロビーの統合により、トークンが自動的に更新されます。
トークンの有効期限が切れるため、クライアントは新しいトークンをリクエストする必要があります。
トークンの有効期限を検出し、別のトークンを要求するには、EOS_RTC_AddNotifyDisconnected を使用する必要があります。切断時に提供されるエラー通知は EOS_EResult :: InvalidAuth です。
ルームへの参加と退出 (信頼済みサーバーによる手法)
ルームに参加するためのトークンとメディア サーバーの URL を取得したクライアントで、ルームに参加するには EOS_RTC_JoinRoom を呼び出し、ルームを退出するには EOS_RTC_LeaveRoom を呼び出します。
明示的に デバイスを指定 しない場合、SDK はデフォルトの出力および入力オーディオデバイスを想定します。
テスト時には、EOS_RTC_JoinRoomOptions.Flags フィールドに EOS_RTC_JOINROOMFLAGS_ENABLE_ECHO を追加することで、エコーを有効にすることができます。そうすると、メディア サーバーがユーザーの音声を送り返すようになります。
デフォルトでは、ルームへの参加時に音声は有効になっています。EOS_RTCAudio_UpdateSending を使用して、ミュートされた部屋に入ることができます。これにより、実際に部屋に参加する前の状態が設定されます。ただし、最初にルームに対する通知を登録する必要があります。
以下に例を示します。
EOS_RTCAudio_AddNotifyParticipantStatusChangedを呼び出して、SDK の内部処理で必要とされる状態にします。EOS_RTCAudio_UpdateSendingを呼び出し、AudioStatus`フィールドをEOS_RTCAS_Disabled`に設定して、入力時にミュートします。EOS_RTC_JoinRoomを呼び出して、そのルームに参加します。
参加者が部屋に出入りするタイミングを検出する
プレイヤーが部屋に参加または退室するタイミングを検出するには、それぞ EOS_RTC_AddNotifyParticipantStatusChanged または EOS_RTC_RemoveNotifyParticipantStatusChanged を使用します。
プレイヤーが部屋に参加する前にこの通知を設定すると、部屋のすべてのメンバーに通知が表示されます。これにより、プレイヤーは、後で参加した場合でも、誰がすでに部屋にいるのかを知ることができます。
、プレイヤーは、部屋に入るときにも通知を受け取りますが、部屋を出るときは通知を受け取りません。EOS_RTC_AddNotifyDisconnected および EOS_RTC_RemoveNotifyDisconnected を使用して、プレーヤーが部屋を離れる / 切断するとき (たとえば、キックされた場合) にプレーヤーに通知します。
EOS_RTC_AddNotifyDisconnected は、token expiration の検出にも使用され、必須です。
オーディオ デバイスの選択
明示的に変更していない場合、SDK は OS のデフォルトの入力と出力のオーディオ デバイスを使用します。ただし、SDK を使用して、使用可能な入力デバイス (マイクロフォン) および出力デバイス (スピーカー) のリストの取得をリクエストすることができます。
入力デバイスについては、EOS_RTCAudio_GetAudioInputDevicesCount を呼び出して、使用可能なデバイスの数を取得し、その後に EOS_RTCAudio_GetAudioInputDeviceByIndex を繰り返し呼び出してデバイスのリストを取得します。応答として、EOS_RTCAudio_AudioInputDeviceInfo はデバイスを一意に識別する DeviceId を提供します。次に、この DeviceId を EOS_RTCAudio_SetAudioInputSettings に渡して、使用するデバイスを選択できます。
同様に、出力デバイスの場合、EOS_RTCAudio_GetAudioOutputDevicesCount を使用して、使用可能な出力デバイスの数を確認し、EOS_RTC_GetAudioOutputDeviceByIndex を呼び出してリストを反復処理します。応答として、EOS_RTCAudio_AudioOutputDeviceInfo はデバイスを一意に識別する DeviceId を提供します。次に、この DeviceId を EOS_RTCAudio_SetAudioOutputSettings に渡して、使用するデバイスを選択できます。
使用可能な入力および出力オーディオ デバイスは、セッション中に変更される場合があります。たとえば、製品の実行中にユーザーが新しいヘッドセットを接続または削除する場合があります。EOS_RTCAudio_AddNotifyAudioDevicesChanged を使用して、使用可能なデバイスが変更されたときに通知することができます。
この通知では入力デバイスと出力デバイスは区別されないため、入力デバイス リストと出力デバイス リストを再度繰り返し、それに応じて製品の状態を更新する必要があります。
オーディオ デバイスの変化の通知が不要になった場合は、EOS_RTCAudio_RemoveNotifyAudioDevicesChanged を呼び出します。
ボリュームを変更する
オーディオ デバイスの選択 で使用するのと同じ機能を使用して、EOS_RTCAudio_SetAudioOutputSettingsOptions と EOS_RTCAudio_SetAudioInputSettingsOptions の入力ボリュームと出力ボリュームを変更できます。
このボリューム フィールドは、 0`から 100`の範囲内で設定できます。
出力ボリュームの場合、「0」は無音を意味し、「50」は変更されていないことを意味し、「100」は 2 倍のゲインを意味します。
入力ボリュームでは、効果をもたらす値は「0」 (無音) のみです。「0」以外の値ではボリュームは一切変化しません。
ミュート
自分に対して誰かをミュートにすることができ、自分をミュートにすることもできます。
ソース コードのヘッダーでは「ローカル ミュート」と記載されていることもあります。
自分をミュートするには、EOS_RTCAudio_UpdateSending を使用します。
他の参加者をミュートにするには、EOS_RTCAudio_UpdateReceiving を使用します。1 人の参加者をミュートにするには ParticipantId フィールドでその ID を指定し、ParticipantId フィールドを空にするとルーム全体がミュートになります。
このようなミュートは自分のセッションのみに影響を及ぼします。例えば、EOS_RTCAudio_UpdateReceiving を使用して他の誰かをミュートにする場合、そのプレイヤーからの音声の受信を停止しますが、そのルームの他のプレイヤーのためにそのプレイヤーをミュートしているわけではありません。
ルームで別の 1 人の参加者との通信を完全に遮断する (送信も受信もしない) には、EOS_RTC_BlockParticipant を使用します。これは EOS_RTCAudio_UpdateSending とは異なります。前者は双方向 (誰かを完全に無視/遮断するために使用する) をブロックしますが、後者はルームで自分をミュートにします。
EOS_RTCAudio_UpdateSending と EOS_RTCAudio_UpdateReceiving のどちらを使用する場合も、事前にそのルームに対して通知を登録しておく必要があります。
そのプレイヤーを全員に対してミュートにするには リモート ミュート を使用します。
リモート ミュート (信頼済みサーバーによる手法)
Lobby インターフェース統合は現在リモート ミュート (ハード ミュート) をサポートしていません。
信頼済みサーバー統合を使用する場合、Voice:mute policy action を有効にして、RoomId、ProductUserId、mute ステータスで EOS_RTCAdmin_SetParticipantHardMute を呼び出すことができます。
これにより、ローカルのミュート ステータスに関係なく、ルーム内のプレイヤーの可聴性がすべての人に対して切り替わります。
参加者を追い出す
信頼済みサーバー統合を使用する場合、Voice:kick policy action を有効にして、 EOS_RTCAdmin_Kick を使って個々のプレイヤーを削除することができます。これにより、ユーザーが以前に発行したルーム トークンも無効になり、同じトークンでユーザーがルームに再参加することはできなくなります。
Lobby インターフェース統合を使用する場合、ロビーの所有者は EOS_Lobby_KickMember を呼び出してロビーとボイス ルームからメンバーを追い出すことができます。
発言ステータスの変更
個々のプレイヤーが現在話しているかどうかを視覚的に示すには、
EOS_RTCAudio_AddNotifyParticipantUpdated とEOS_RTCAudio_RemoveNotifyParticipantUpdated を使用できます。
この通知のコールバックでは、通知がどの参加者を指しているか、その参加者の音声ストリームの状態 (unsupported、enabled、disabled など)、およびその参加者が現在発言しているかどうかが伝えられます。
独自のオーディオを挿入する
オーディオを勝手にキャプチャしないように SDK に指示することで、独自のオーディオ ソースを指定できるようになります。
この機能を有効にするには、まず EOS_RTC_JoinRoom を呼び出すときに bManualAudioInputEnabled フィールドを true に設定する必要があります。
その後に、EOS_RTCAudio_SendAudio を使用して独自のオーディオを挿入できます。そうするには、送信するオーディオ データを EOS_RTCAudio_AudioBuffer 構造体にセットアップする必要があり、そのデータの持続時間は「10 ミリ秒」である必要があります。
SDK はバッファをコピーします。
オーディオを変更する
送信と受信の両方のオーディオをインターセプトすることによって、ボイス エフェクトを実装することができます。
送信オーディオをインターセプトするには EOS_RTCAudio_AddNotifyAudioBeforeSend を使用します。
受信オーディオをインターセプトするには EOS_RTCAudio_AddNotifyAudioBeforeRender を使用します。ルーム内のすべての参加者を完全にミックスするか、または空間オーディオなどの用途のために参加者ごとに個別のストリームを取得することができます。EOS_RTCAudio_AddNotifyAudioBeforeRenderOptions 構造体の bUnmixedAudio フィールドを設定することで、どちらにするかを選択できます。
変更できるのは実際のオーディオ フレーム (Frames フィールドが指しているデータ) のみです。EOS_RTCAudio_AudioBuffer の他のフィールドを変更してはいけません。
音声転写
EOS Voice サービス自体では音声転写は現時点では提供されていませんが、オーディオ バッファを取得し、それを任意の音声転写サービスに送信することができます。
EOS_RTCAudio_AddNotifyAudioBeforeRender を使用すると、オーディオ バッファがオーディオ デバイスでレンダリングされる前に、オーディオ バッファを受信するように登録できます。次に、EOS_RTCAudio_AddNotifyAudioBeforeRenderOptions の bUnmixedAudio フラグを使用して、すべてのスピーカーの混合オーディオ チャネルを変換するか、個々のスピーカーの混合オーディオ チャネルを変換するかを選択できます。
EOS_RTCAudio_AudioBeforeRenderCallbackInfo には、RoomId、ProductUserId、各スピーカーの EOS_RTCAudio_AudioBuffer が入っています。
オーディオ バッファ自体では、16 ビットのインターリーブ サンプルが入っており、チャンネル数、サンプリング レート、および含まれているサンプル数が定義されています。このバッファを音声転写サービスに送信し、対応するテキスト表現を受信して表示することができます。