> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ko/docs/tools-and-integrations/eos-voice-chat.md).

# EOS 음성 채팅

Edgegap 전용 서버를 신뢰할 수 있는 음성 서버로 사용하여, Unreal Engine 게임의 매칭된 플레이어들에게 Epic Online Services 음성 채팅을 추가하세요.

이 가이드는 우리의 [Unreal Engine 샘플 프로젝트](https://github.com/edgegap/game-sample-unreal-engine-topdown) 다음과 함께 인게임 음성 채팅을 추가하는지 설명합니다: [EOS Voice](https://dev.epicgames.com/docs/epic-online-services/multiplayer/voice-and-rtc-interface/voice-interface/voice-overview) Epic Online Services에서 제공합니다. 매칭된 플레이어들은 [Edgegap 매치메이커](https://docs.edgegap.com/ko/learn/matchmaking.md) 음성 룸에서 팀원들과 대화하며, Edgegap의 전용 서버가 누가 어느 룸에 들어갈지 결정합니다.

음성 채팅은 **기본적으로 비활성화되어 있습니다** 샘플에서. 이를 활성화하기 전까지 게임은 다음에 설명된 대로 작동합니다: [탑다운 샘플](https://docs.edgegap.com/ko/docs/sample-projects/unreal-engine/top-down-sample.md).

{% hint style="success" %}
**먼저 다음부터 시작하는 것을 권장합니다:** [Unreal Engine](https://docs.edgegap.com/ko/unreal-engine.md) **진행하기 전에 게임 서버를 빌드하는 가이드를 참고하세요.**
{% endhint %}

## 🎙️ 작동 방식

여러분의 전용 서버는 EOS의 [신뢰된 서버](https://dev.epicgames.com/docs/epic-online-services/multiplayer/voice-and-rtc-interface/voice-interface/voice-overview#voice-with-a-trusted-server-application). 게임 클라이언트는 음성 룸을 생성할 수 있는 인증 정보를 절대 보유하지 않습니다.

### 1. 플레이어가 EOS에 로그인

게임 클라이언트가 기기 ID로 플레이어를 EOS에 로그인시키므로, 플레이어는 Epic 계정이 필요하지 않습니다. 그런 다음 서버에 Product User ID와 EOS ID 토큰을 보냅니다.

### 2. 서버가 플레이어를 확인

서버는 Epic의 공개 키로 ID 토큰을 검증하므로, 플레이어가 다른 사람의 ID를 주장할 수 없습니다. 또한 해당 토큰이 여러분의 EOS 배포용으로 발급되었는지도 확인합니다.

### 3. 서버가 룸을 선택

룸 이름은 매치에서 가져옵니다:

* 기본 룸은 매치메이커의 매치 ID(`MM_MATCH_ID`)를 따르거나, 수동으로 배포한 서버의 경우 배포 ID를 따릅니다,
* 팀 룸이 활성화된 경우(기본값, `bTeamRooms=True`), 각 팀은 매치와 팀 이름을 따서 명명된 고유한 룸을 갖게 됩니다.

서버는 각 플레이어의 팀을 다음에서 찾습니다: [환경 변수로 주입된 매치메이커 티켓](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#injected-variables) - 플레이어가 접속한 IP를 각 티켓의 IP와 대조하여 일치시키고, 티켓의 팀을 읽습니다. **클라이언트가 보낸 팀 정보는 절대 신뢰하지 않습니다.** 일치하는 티켓이 없는 플레이어(예: IP로 접속한 플레이어)는 매치 룸에 남습니다. `bTeamRooms=False` 를 설정하면 전체 매치를 하나의 룸에 넣을 수 있습니다.

### 4. 서버가 룸 토큰을 발급

서버는 다음에 요청합니다: [EOS Voice Web API](https://dev.epicgames.com/docs/web-api-ref/voice-web-api) 해당 플레이어를 위한 룸 토큰을 요청하면서, 플레이어의 IP를 전달해 EOS가 그 근처의 음성 서버를 사용하도록 합니다. 토큰은 해당 플레이어에게만 전송되며, 클라이언트는 엔진의 EOSVoiceChat 플러그인으로 룸에 참가합니다.

### 5. 서버가 나간 플레이어를 제거

플레이어가 서버를 떠나면 서버는 해당 플레이어를 음성 룸에서 제거하며, 그와 함께 토큰도 취소합니다. 게임 코드에서는 다음을 사용해 모든 사용자에게 특정 플레이어를 음소거할 수도 있습니다: `UEdgegapVoiceServerSubsystem::SetHardMuted`.

{% hint style="info" %}
게임 모드와 플레이어 컨트롤러는 변경되지 않습니다. 플레이어가 로그인할 때(`PostLogin`), 서버는 작은 복제 컴포넌트인 `UEdgegapVoiceComponent`를 해당 플레이어 컨트롤러에 추가합니다. 이 컴포넌트는 소유한 클라이언트에게만 복제되며 다음 `ServerRegisterVoice` 및 `ClientJoinVoiceRoom` RPC를 포함합니다.
{% endhint %}

서버는 EOS SDK 대신 HTTPS를 통해 EOS Web API를 호출하는데, EOS SDK는 Linux에서 음성을 지원하지 않기 때문입니다. 클라이언트 쪽은 EOSVoiceChat 플러그인이 있는 Windows와 Mac용으로 빌드됩니다.

| 파일                            | 기능                                              |
| ----------------------------- | ----------------------------------------------- |
| `EdgegapVoiceSettings.h`      | 켜기/끄기 스위치와 옵션, 다음에서: `DefaultGame.ini`          |
| `EdgegapVoiceClientSubsystem` | EOS 기기 ID 로그인, ID 토큰, 룸 참가 및 나가기                |
| `EdgegapVoiceComponent`       | 서버가 모든 플레이어에게 추가하며, 음성 RPC를 담당                  |
| `EdgegapVoiceServerSubsystem` | ID 토큰 검사, 룸 선택, EOS Voice Web API 호출, 로그아웃 시 제거 |

## ⚙️ 설정

### 1. EOS 클라이언트 생성

☑️ 다음에서 제품을 여세요 [Epic Developer Portal](https://dev.epicgames.com/portal), 그런 다음 **제품 설정**.

☑️ 탭에서 Product ID, Sandbox ID 및 Deployment ID를 기록해 두세요 **SDK 다운로드 및 자격 증명**.

☑️ 탭에서 두 개의 정책을 추가하세요 **클라이언트**, 아래에서 **클라이언트 정책**:

* **게임 클라이언트** - 유형 `GameClient`, **사용자 필수** 체크됨, Voice 권한은 필요 없음,
* **신뢰된 서버** - **사용자 지정 정책 생성**, **사용자 필수** 체크 해제됨, Voice 작업 포함 `createRoomToken`, `추방` 및 `음소거`.

☑️ 각 정책에 대해 하나의 클라이언트를 추가하고, 각 Client ID와 Client Secret을 기록해 두세요.

{% hint style="danger" %}
신뢰된 서버의 클라이언트는 배포 내의 어떤 룸에 대해서도 토큰을 생성할 수 있습니다. **게임 빌드에 절대 넣지 마세요.**
{% endhint %}

✅ 이제 다음 단계로 진행할 수 있습니다.

### 2. 게임 클라이언트 구성

☑️ 다음을 입력하세요 `[EOSVoiceChat]` 을 `MultiplayerGame/Config/UserEngine.ini` 에 제품, 샌드박스 및 배포 ID와 **게임 클라이언트의** ID와 비밀 키를 입력하세요. 이 파일은 git에서 무시되며 `DefaultEngine.ini`을 덮어쓰므로, 자격 증명이 버전 관리에 포함되지 않습니다.

☑️ 다음에서 음성을 활성화하세요 `MultiplayerGame/Config/UserGame.ini` (이 파일도 git에서 무시됩니다):

{% code collapsedlinecount="10" %}

```ini
[/Script/MultiplayerGame.EdgegapVoiceSettings]
bEnabled=True
```

{% endcode %}

✅ 이제 다음 단계로 진행할 수 있습니다.

### 3. 서버 구성

☑️ 다음 환경 변수를 여러분의 [앱 버전](https://app.edgegap.com/application-management/applications/list), 그리고 비밀 값은 숨김으로 표시하세요:

| 변수                         | 값                                                                   |
| -------------------------- | ------------------------------------------------------------------- |
| `EOS_VOICE_CLIENT_ID`      | 신뢰된 서버 Client ID                                                    |
| `EOS_VOICE_CLIENT_SECRET`  | 신뢰된 서버 Client Secret                                                |
| `EOS_VOICE_DEPLOYMENT_ID`  | EOS 배포 ID(이미 다음에 있으면 선택 사항 `DefaultEngine.ini`)                     |
| `EOS_VOICE_GAME_CLIENT_ID` | 게임 클라이언트의 Client ID, 선택 사항: 그러면 서버는 여러분의 게임 클라이언트에 발급된 ID 토큰만 허용합니다 |

이 값들을 설정하면 서버에서 음성이 활성화되므로 서버 이미지를 다시 빌드할 필요가 없습니다. 로컬에서 실행 중인 서버라면 다음을 `ServerClientId` 및 `ServerClientSecret` 을 `EdgegapVoiceSettings` 의 섹션에 `UserGame.ini` 대신 넣으세요.

✅ 이제 다음 단계로 진행할 수 있습니다.

### 4. 플레이

☑️ 서버와 클라이언트를 다시 패키징하고, 배포한 다음 플레이하세요. 매치메이커가 활성화되어 있으면 팀원들이 같은 룸을 공유합니다.

☑️ 입력하세요 `VoiceMute` 을 콘솔에 입력해 마이크를 음소거하거나 음소거 해제하세요.

🙌 축하합니다, 이제 플레이어들이 팀원들과 대화할 수 있습니다!

## 🧪 한 PC에서 두 클라이언트로 테스트하기

기기 ID는 Windows 사용자에게 속하므로, 같은 PC의 두 클라이언트는 동일한 EOS 플레이어로 로그인하게 됩니다. 두 번째 클라이언트의 명령줄에 `-EOSVoiceNewDeviceId` 를 추가해 새 신원을 부여하세요.

{% hint style="warning" %}
`-EOSVoiceNewDeviceId` 실행할 때마다 새 EOS 사용자를 생성합니다, **테스트용으로만 사용하세요**. 첫 번째 클라이언트가 로그인한 후에만 두 번째 클라이언트를 시작하세요 `Voice: EOS에 로그인됨` - 첫 번째 클라이언트가 아직 로그인 중인 동안 기기 ID를 바꾸면 두 클라이언트가 동일한 신원을 갖게 됩니다.
{% endhint %}

마이크에 대고 말하지 않고도 오디오가 흐르는지 확인하려면 다음으로 클라이언트를 시작하세요 `-ExecCmds="EOSVoiceChat.FakeAudioInputEnabled 1"` (개발 빌드). 테스트 신호를 보내며, 다른 클라이언트는 다음을 로그합니다 `Voice: <id>가 룸 <room>에서 말하기 시작함`.

매치메이커를 사용할 때 두 클라이언트는 서로 10초 이내에 대기열에 들어가야 합니다. 그렇지 않으면 `캐주얼` 프로필이 단독 매치를 시작합니다. 클라이언트는 서로 다른 속도로 시작하므로, 둘 다 같은 다음 값으로 실행하세요 `-FindMatchAt=<unix time>` (예: 2분 앞선 시각) `-FindMatch` - 각 클라이언트가 그 시점에 대기열에 들어갑니다.

{% hint style="info" %}
찾아볼 로그 줄(`LogEdgegapVoice`):

* 서버 - `Voice: 신뢰된 음성 서버 준비 완료`, 그런 다음 `Voice: <id>가 룸 <room>을 받음` 각 플레이어에 대해, 그리고 `Voice: <id> 제거됨` 플레이어가 떠날 때,
* 클라이언트 - `Voice: <id>로 EOS에 로그인됨`, `Voice: 룸 <room>에 참가함` 및 `Voice: <id>가 말하기 시작함`.
  {% endhint %}
