Using the Voice Interface

Preview
阅读时间7分钟

以下调用使用的Voice RTC API可用于你的实现。如需了解语音Web API，请查阅我们的Web API概览和语音Web API文档。

如需使用语音接口，你应当：

  1. 回顾和决定你想在游戏中使用的集成方法。
  2. 研究语音示例(C和C#)，了解在产品中使用Voice接口的方法。
  3. 将语音接口集成到应用程序中：
    1. 配置客户端政策
    2. 根据所选集成方法集成Voice接口。
  4. 回顾针对语音接口的最佳实践、语音指标和使用限制。

使用有大厅的语音时，大厅界面将自动执行：

  • 请求和刷新房间令牌
  • 在用户进入或离开大厅时加入和离开语音房间

使用 有可信服务器的语音时，你需要：

  • 代表用户在其服务器上请求令牌
  • 让游戏客户端执行调用以刷新令牌
  • 让游戏客户端执行调用，以加入或离开语音房间

请求令牌以加入房间（可信服务器方法）

大厅界面会自动为其成员返回房间令牌。

针对可信服务器使用自定义实现方法时，你需要负责管理房间访问权限，为玩家请求令牌，以便让他们加入媒体服务器上的房间。你可以使用EOS_RTCAdmin_QueryJoinRoomToken完成此操作，但需要在 开发人员门户 中启动Voice:createRoomToken policy action。

EOS_RTCAdminQueryJoinRoomToken是一项异步操作，完成后（参阅EOS_RTCAdmin_QueryJoinRoomTokenCompleteCallbackInfo）可为你提供媒体服务器URL和QueryId，以便检索令牌。

给定的 QueryId 仅在回调期间有效，因此你需要从回调内部检索令牌。

你可以从回调内部使用EOS_RTCAdmin_CopyUserTokenByIndex和EOS_RTCAdmin_CopyUserTokenByUserId，以检索令牌。

一旦不再需要EOS_RTCAdmin_UserToken，你可以使用EOS_RTCAdmin_UserToken_Release来释放其资源。

EOS_RTCAdmin_QueryJoinRoomToken允许你使用一次调用为多名用户请求令牌（参阅EOS_RTCAdmin_QueryJoinRoomTokenOptions）

令牌有效期（可信服务器方法）

大厅集成将为你自动刷新令牌。

令牌过期，因此客户端需要请求一个新令牌。

你必须使用EOS_RTC_AddNotifyDisconnected检测令牌有效期，并请求另一个令牌。断开连接时提供的错误通知为 EOS_EResult::InvalidAuth。

加入和离开房间（可信服务器方法）

一旦客户端具备加入房间的令牌和媒体服务器URL，你可以调用EOS_RTC_JoinRoom以加入房间，以及调用 EOS_RTC_LeaveRoom以离开房间。

如果未明确要使用的指定设备，SDK会假定默认的输出和输入音频设备。

出于测试目的，你可以通过将 EOS_RTC_JOINROOMFLAGS_ENABLE_ECHO 标记添加到 EOS_RTC_JoinRoomOptions.Flags 字段来启动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会使用操作系统的默认输入和输出音频设备。但是，你可以请求使用有效输入设备（麦克风）和输出设备（扬声器）列表来选择替代设备。

于输入设备而言，你可以使用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 中的 Volume 字段，使用与“音频设备选择”相同的功能，从而调节输入和输出音量。

该音量字段字段的取值范围是 0 到 100：

  • 对于输出音量来说，0 表示静音，50 表示未修改，100 表示2倍增益。
  • 对于输入音量来说，可产生效果的唯一数值是 0（静音）。除 0 以外的任何数值均不会使音量发生任何变化。

禁言

你可以将任何与你相关的人禁言，甚至让你自己禁言。

在源代码头文件中，你可能还会看到这被称为“本地禁言”。

如需将你自己禁言，使用EOS_RTCAudio_UpdateSending。

如需将其他人禁言，你可以使用EOS_RTCAudio_UpdateReceiving。你可以填写 ParticipantId 字段，将单个参与者禁言，也可以将其留空，将整个房间禁言。

此禁言操作仅会影响你自己的会话。当你使用EOS_RTCAudio_UpdateReceiving将某人禁言时，你不会再收到该玩家的音频，但你不能为房间内的其他玩家屏蔽该玩家的发言。

如需完全屏蔽与房间内另一名参与者的通信（不收发消息），你可以使用EOS_RTC_BlockParticipant。该操作与EOS_RTCAudio_UpdateSending不同。前者将屏蔽双方通信（完全忽略/屏蔽某人），而后者是将你在房间里禁言。

EOS_RTCAudio_UpdateSending和EOS_RTCAudio_UpdateReceiving两种情况情况均需要你先进行登记以便收到此房间的通知。

使用远程禁言为所有人禁言该玩家（目前仅支持可信服务器集成）。

远程禁言（可信服务器方法）

大厅接口集成目前不支持远程禁言（硬禁言）。

使用可信服务器集成（trusted server integration）时，你可以使用Voice:mute policy action，然后使用 RoomId、ProductUserId 和 mute 状态来调用EOS_RTCAdmin_SetParticipantHardMute。 该操作会为所有人切换房间内某个玩家的音频接收状态，无论他们是否处于本地禁言状态与否。

踢出参与者

使用可信服务器集成时，你可以启用Voice:kick policy action，并使用 EOS_RTCAdmin_Kick 从房间移除个体玩家。该操作会使用户先前签发的房间令牌失效，以防被踢出的玩家使用相同令牌重新加入房间。

使用大厅接口集成时，厅主可以调用EOS_Lobby_KickMember，将成员从大厅和语音房间踢出。

发言状态变更

为了直观地显示个体玩家当前是否在发言，你可以使用 EOS_RTCAudio_AddNotifyParticipantUpdated和EOS_RTCAudio_RemoveNotifyParticipantUpdated。 此通知的回调包含参与者、该参与者音频流送状态（不支持、已启用、已禁用等），以及参与者当前的发言状态。

注入你自己的音频

你可以通过命令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_RTCAudio_AddNotifyAudioBeforeRender接收音频缓冲。然后，你可以使用 EOS_RTCAudio_AddNotifyAudioBeforeRenderOptions 中的 bUnmixedAudio 标记，选择转换成所有发言人或个体发言人的混合音频信道。

EOS_RTCAudio_AudioBeforeRenderCallbackInfo 包含每个发言人的 RoomId、ProductUserId 和 EOS_RTCAudio_AudioBuffer。

音频缓冲本身包含交叉存取的16位示例，并定义了其包含的信道数量、示例率和示例计数。然后，再将此缓冲提交至语音转文本服务，以接收和显示匹配的文本表示。