Using the Voice Interface

Preview
7 분 소요

아래 내용에서 다루는 호출은 구현에 활용 가능한 보이스 RTC API를 사용합니다. 보이스 웹 API에 대한 정보는 Web API 개요보이스 웹 API 문서를 참조하세요.

보이스 인터페이스를 사용하려면 다음을 수행해야 합니다.

  1. 게임에 사용할 통합 메서드를 검토하고 결정합니다.
  2. 보이스 샘플(CC#)을 살펴보고 보이스 인터페이스를 제품에 사용하는 방법을 알아봅니다.
  3. 보이스 인터페이스를 애플리케이션에 통합합니다.
    1. 클라이언트 정책을 환경설정합니다.
    2. 선택한 통합 메서드를 바탕으로 보이스 인터페이스를 통합합니다.
  4. 보이스 인터페이스의 모범 사례, 보이스 메트릭, 사용 제한을 검토합니다.

로비에 보이스 를 사용하는 경우 로비 인터페이스가 다음을 자동으로 처리합니다.

  • 방 토큰 요청 및 새로고침
  • 사용자가 로비에 들어오거나 로비를 나갈 때 보이스 방 입장 또는 퇴장

신뢰할 수 있는 서버에 보이스 를 사용하는 경우 다음을 수행해야 합니다.

  • 서버에서 사용자 대신 토큰 요청
  • 게임 클라이언트에 토큰 새로고침을 위한 호출 지시
  • 게임 클라이언트에 보이스 방 입장 또는 퇴장을 위한 호출 지시

방 입장을 위해 토큰 요청하기(신뢰할 수 있는 서버 메서드)

로비 인터페이스가 멤버를 위해 방 토큰을 자동으로 반환합니다.

신뢰할 수 있는 서버에 커스텀 구현을 사용하는 경우 플레이어가 미디어 서버에 개설된 방에 입장할 수 있도록 방 액세스를 관리하고 플레이어 토큰을 요청해야 합니다. 그렇게 하려면 EOS_RTCAdmin_QueryJoinRoomToken 을 사용합니다. 이 함수를 사용하려면 Voice:createRoomToken 정책 액션개발자 포털(Developer Portal) 에서 활성화해야 합니다.

EOS_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 필드에 추가하여 에코를 활성화할 수 있습니다. 그러면 미디어 서버가 사용자 오디오를 되돌려 보냅니다.

기본적으로 방에 입장할 때 오디오가 활성화됩니다. 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_AddNotifyDisconnectedEOS_RTC_RemoveNotifyDisconnected 를 사용합니다.

EOS_RTC_AddNotifyDisconnected토큰 만료를 탐지하는 데 사용되며 꼭 필요합니다.

오디오 디바이스 선택하기

명시적으로 변경되지 않으면 SDK는 운영 체제의 디폴트 입출력 오디오 디바이스를 사용합니다. 그러나 사용 가능한 입력 디바이스(마이크) 및 출력 디바이스(스피커) 목록을 요청하여 다른 옵션을 선택할 수 있습니다.

입력 디바이스의 경우 EOS_RTCAudio_GetAudioInputDevicesCount 를 호출하여 사용 가능한 입력 디바이스의 개수를 알 수 있으며 EOS_RTCAudio_GetAudioInputDeviceByIndex 를 호출하여 목록을 반복작업할 수 있습니다. 그 응답으로 EOS_RTCAudio_AudioInputDeviceInfo 는 디바이스를 고유하게 식별할 수 있는 DeviceId 를 제공합니다. 그런 다음 이 DeviceIdEOS_RTCAudio_SetAudioInputSettings 에 전달하여 사용할 디바이스를 선택할 수 있습니다.

이와 유사하게 출력 디바이스의 경우 EOS_RTCAudio_GetAudioOutputDevicesCount 를 호출하여 사용 가능한 출력 디바이스의 개수를 알 수 있으며 EOS_RTC_GetAudioOutputDeviceByIndex 를 호출하여 목록을 반복작업할 수 있습니다. 그 응답으로 EOS_RTCAudio_AudioOutputDeviceInfo 는 디바이스를 고유하게 식별할 수 있는 DeviceId 를 제공합니다. 그런 다음 이 DeviceIdEOS_RTCAudio_SetAudioOutputSettings 에 전달하여 사용할 디바이스를 선택할 수 있습니다.

사용 가능한 입출력 오디오 디바이스는 세션 도중에 바뀔 수도 있습니다. 예를 들어 사용자가 제품 실행 도중에 새 헤드셋을 연결하거나 연결 해제할 수도 있습니다. EOS_RTCAudio_AddNotifyAudioDevicesChanged 를 호출하여 사용 가능한 디바이스가 변경될 때마다 알림을 받을 수 있습니다.

사용 가능한 디바이스 변경 알림은 입력 디바이스 또는 출력 디바이스 간에 다르지 않습니다. 입출력 디바이스 목록을 다시 반복작업하고 제품 상태를 적절히 업데이트해야 합니다.

오디오 디바이스 변경 알림을 더 이상 받지 않으려는 경우 EOS_RTCAudio_RemoveNotifyAudioDevicesChanged 를 사용합니다.

볼륨 변경하기

오디오 디바이스를 선택할 때 사용한 것과 동일한 함수를 사용하여 EOS_RTCAudio_SetAudioOutputSettingsOptionsEOS_RTCAudio_SetAudioInputSettingsOptions 의 볼륨 필드로 입출력 볼륨을 변경할 수 있습니다.

이 볼륨 필드는 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_UpdateSendingEOS_RTCAudio_UpdateReceiving 을 사용하려면 방 알림을 먼저 등록해야 합니다.

원격 음소거를 사용하면 모든 멤버에게서 특정 플레이어가 음소거됩니다. 현재 이 기능은 신뢰할 수 있는 서버 통합에서만 지원됩니다.

원격 음소거하기(신뢰할 수 있는 서버 메서드)

로비 인터페이스 통합은 현재 원격 음소거(하드 음소거)를 지원하지 않습니다.

신뢰할 수 있는 서버 통합을 사용하는 경우 Voice:mute policy action 을 활성화하고 EOS_RTCAdmin_SetParticipantHardMuteRoomId , ProductUserId , mute 상태와 함께 호출할 수 있습니다. 이렇게 하면 모든 멤버에게서 방 안에 있는 특정 플레이어의 소리가 토글됩니다. 이때 로컬 음소거 상태는 영향을 미치지 않습니다.

참여자 강제 퇴장시키기

신뢰할 수 있는 서버 통합을 사용하는 경우 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 필드를 설정하여 원하는 행동을 선택할 수 있습니다.

실제 오디오 프레임(프레임 필드가 가리키는 데이터)만 수정할 수 있습니다. EOS_RTCAudio_AudioBuffer 의 나머지 필드는 수정하면 안 됩니다.

음성 텍스트 변환하기

보이스 자체는 현재 음성 텍스트 변환을 지원하지 않지만 오디오 버퍼를 가져와서 원하는 전사 서비스에 전송할 수 있습니다.

EOS_RTCAudio_AddNotifyAudioBeforeRender 를 사용하여 오디오 디바이스에서 렌더링되기 전에 오디오 버퍼를 가져옵니다. 그런 다음 EOS_RTCAudio_AddNotifyAudioBeforeRenderOptionsbUnmixedAudio 플래그를 사용하여 모든 발화자의 믹스된 오디오 채널을 변환할지 개별 발화자의 오디오 채널을 변환할지 선택할 수 있습니다.

EOS_RTCAudio_AudioBeforeRenderCallbackInfo 에는 각 발화자의 RoomId , ProductUserId , EOS_RTCAudio_AudioBuffer 가 포함됩니다.

오디오 버퍼 자체는 인터리브된 16비트 샘플을 포함하며 채널 수, 샘플 레이트, 포함된 샘플 수를 정의합니다. 그런 다음 이 버퍼는 음성 텍스트 변환 서비스에 제출되어 일치하는 텍스트 표현을 수신하고 표시합니다.