Using the Voice Interface

Preview
7 分で読めます

以下の呼び出しでは、実装に使用できる Voice RTC API を使用しています。Voice Web API については、「Web API の概要」および「Voice Web API」のドキュメントを参照してください。

Voice インターフェースを使用するには、以下の手順に従う必要があります。

  1. ゲームで使用する 統合方法 をレビューして決定する
  2. Voice のサンプル (C および C# を調べて、製品での Voice インターフェースの使用方法を習得する
  3. Voice インターフェースをアプリケーションに組み込む
    1. クライアント ポリシー を設定する
    2. 選択した統合方法に基づいて Voice インターフェイスを統合します。
  4. Voice インターフェースの ベスト プラクティス、Voice のメトリック、および 使用上の制限事項 をレビューする

Voice を Lobby で使用する 場合、Lobbies インターフェイスによって以下が自動的に行われます。

  • ルーム トークンの再リクエストとリフレッシュ
  • ユーザーのロビーへ入室 / 退出時にあわせたボイス ルームへの参加 / 退出

信頼済みサーバーで Voice を使用する場合、以下を行う必要があります。

  • ユーザーの代わりにトークンをリクエストする
  • ゲーム クライアントにトークンを更新するための呼び出しを行わせる
  • ゲーム クライアントにボイス ルームの入室 / 退出のための呼び出しを行わせる

ルームに参加するためのトークンをリクエストする (信頼済みサーバーによる手法)

Lobby インターフェースはメンバーに対して自動的にルーム トークンを返します。

信頼済みサーバーのカスタム実装を使用する場合は、ルーム アクセスを管理し、プレイヤーがメディア サーバー上のそのルームに参加できるようにするためのトークンをリクエストする必要があります。EOS_RTCAdmin_QueryJoinRoomToken を使って行うことができます。Developer Portal で 'Voice:createRoomToken' ポリシー アクション を有効にする必要があります。

EOS_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 は変更なし、1-- は 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 ビットのインターリーブ サンプルが入っており、チャンネル数、サンプリング レート、および含まれているサンプル数が定義されています。このバッファを音声転写サービスに送信し、対応するテキスト表現を受信して表示することができます。