使用语音接口

Preview Only

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

如需使用语音接口,你应当:

  1. 回顾和决定你想在游戏中使用的集成方法

  2. 研究语音示例(CC#),了解在产品中使用Voice接口的方法。

  3. 将语音接口集成到应用程序中:

    1. 配置客户端政策

    2. 根据所选集成方法集成Voice接口。

  4. 回顾针对语音接口的最佳实践语音指标使用限制

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

  • 请求和刷新房间令牌

  • 在用户进入或离开大厅时加入和离开语音房间

使用 有可信服务器的语音时,你需要:

  • 代表用户在其服务器上请求令牌

  • 让游戏客户端执行调用以刷新令牌

  • 让游戏客户端执行调用,以加入或离开语音房间

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

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

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

EOS_RTCAdminQueryJoinRoomTokenEOS_RTCAdminQueryJoinRoomToken是一项异步操作,完成后(参阅EOS_RTCAdmin_QueryJoinRoomTokenCompleteCallbackInfo)可为你提供媒体服务器URL和`QueryId`,以便检索令牌。

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

你可以从回调内部使用EOS_RTCAdmin_CopyUserTokenByIndexEOS_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_AddNotifyParticipantStatusChangedEOS_RTC_RemoveNotifyParticipantStatusChanged

在玩家加入房间前设置此通知,可为玩家推送房间内每位成员的通知。如果玩家在其他人之后进入房间,则他能了解到房间里的现有成员情况。

玩家加入房间时也会收到通知,但离开房间时不会收到通知。使用EOS_RTC_AddNotifyDisconnectedEOS_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_SetAudioOutputSettingsOptionsEOS_RTCAudio_SetAudioInputSettingsOptions 中的 Volume 字段,使用与"音频设备选择"相同的功能,从而调节输入和输出音量。

该音量字段字段的取值范围是 0100

  • 对于输出音量来说,0 表示静音,50 表示未修改,100 表示2倍增益。

  • 对于输入音量来说,可产生效果的唯一数值是 0(静音)。除 0 以外的任何数值均不会使音量发生任何变化。

禁言

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

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

如需将你自己禁言,使用EOS_RTCAudio_UpdateSending

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

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

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

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

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

远程禁言(可信服务器方法)

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

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

踢出参与者

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

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

发言状态变更

为了直观地显示个体玩家当前是否在发言,你可以使用 EOS_RTCAudio_AddNotifyParticipantUpdatedEOS_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 包含每个发言人的 RoomIdProductUserIdEOS_RTCAudio_AudioBuffer

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