# 실시간 음성 변환기 (Windows 게임PC) 마이크로 말하면 고른 목소리 모델로 바꿔서 바로 내보냅니다. 디스코드나 게임에서 그 목소리로 말할 수 있습니다. 목소리 모델은 `consent-recorder` 로 동의받아 모은 녹음으로 이 PC 에서 직접 학습합니다 (RVC v2). - 엔진: [Applio](https://github.com/IAHispano/Applio) (MIT, RVC 학습 · 실시간 변환). `scripts/install.ps1` 에 커밋을 고정해 둠 - 기준 PC: RTX 5070 Ti 16GB (Blackwell) · DDR5 128GB · Ryzen 9 9950X3D · Windows 11 - torch 2.11 + CUDA 12.8 (RTX 50 시리즈 지원). NVIDIA 드라이버 580 이상 - 디스크: 설치 약 8GB(Python · torch · 엔진 기본 모델) + 모델마다 약 80MB + 학습 중간 파일. 예시 모델까지 만들면 15GB 정도 여유를 두세요 ## 설치 — `VoiceChangerSetup.exe` 하나만 1. `VoiceChangerSetup.exe` 를 **더블클릭**해서 실행합니다 (관리자 권한 확인 창이 뜹니다). "관리자 권한으로 실행" 이나 관리자 터미널로 시작하면 앱 파일을 복사하지 않고 안내만 합니다 (고른 폴더는 내 계정 권한으로만 다루기 때문). 2. **설치할 폴더**를 고릅니다. 기본값은 `C:\VoiceChanger` 이고, 다른 드라이브(`D:\...`)나 한글 · 띄어쓰기가 들어간 경로도 됩니다. 비어 있는 폴더나 새 폴더만 됩니다 (다른 파일이 든 폴더는 거절합니다). 바탕 화면 · 문서 아래(예: `바탕 화면\VoiceChanger`)도 됩니다. OneDrive 로 동기화되는 폴더를 고르면 한 번 더 묻습니다. 앱 · Python · 엔진 · torch · 목소리 모델 · 설정 · 학습 파일 · 캐시 · 임시 파일이 **모두 이 폴더 안에만** 저장됩니다. 설치하면서 약 8GB 를 내려받고 모델을 만들수록 늘어나므로 15GB 이상 비어 있는 드라이브를 고르세요. 3. 설치 프로그램이 마이크마다 변환 모듈을 붙이고(윈도우 소리가 1~2초 끊김), 검은 창에서 Python 3.12 · 엔진(Applio) · torch(CUDA 12.8) · 엔진 기본 모델(rmvpe · contentvec · 사전학습 가중치 · ffmpeg)을 그 폴더로 내려받습니다. 10~20분 걸립니다. 마지막에 `GPU 확인: NVIDIA GeForce RTX 5070 Ti (sm_120)` 가 나오면 정상입니다. 4. 시작 메뉴의 **음성 변환기**로 실행합니다. 가상 오디오 장치(VB-CABLE 등)는 필요 없습니다. 변환기가 내 마이크에서 나가는 소리를 직접 바꿔 주므로, 디스코드 · 게임의 입력 장치는 **평소 쓰던 마이크 그대로** 두면 됩니다. - 내려받다가 끊기면 설치 폴더의 `install.bat` 을 실행합니다. 받은 곳부터 이어서 받습니다. - 권한: 관리자 권한 · 오디오 서비스가 실행하는 마이크 모듈(`apo\`) · `mic-apo.ps1` · 제거 프로그램은 `C:\Program Files\VoiceChanger` 에 설치합니다 (관리자만 고칠 수 있음). 고른 폴더는 관리자 권한으로 건드리지 않습니다. 앱 파일 복사(`installer\deploy.ps1`)와 엔진 내려받기(`install.ps1`)는 설치를 시작한 사용자 권한으로 합니다. 바탕 화면처럼 상위가 사용자 소유인 폴더는 설치 도중 다른 곳을 가리키는 정션으로 바꿔칠 수 있어서, 관리자 권한으로 그 경로를 다루면 엉뚱한 곳이 바뀔 수 있기 때문입니다. v1.0.1 까지 관리자 소유로 잠가 둔 설치 폴더는 설치 프로그램이 이전 실행 파일만 지우고 `<폴더>.old` 로 비켜 둔 뒤(`installer\legacy.ps1`, 상위가 관리자 소유일 때만) 모델 · 설정 · Python · 엔진을 새 폴더로 옮깁니다. - 폴더 밖에 남는 것은 윈도우가 관리하는 항목뿐입니다: 시작 메뉴 바로 가기, 프로그램 제거 목록, 마이크 모듈 등록(레지스트리). 사용자 폴더(`%APPDATA%` · `%LOCALAPPDATA%` · `%TEMP%` · `.cache`)에는 아무것도 쓰지 않습니다. - 제거: 설정 → 앱 → 음성 변환기 → 제거. 마이크 설정을 원래대로 되돌리고 `C:\Program Files\VoiceChanger` 를 지웁니다. 고른 폴더(앱 · 모델 · 녹음 · 설정)는 남기므로 필요 없으면 직접 지웁니다 (내 계정 폴더라 관리자 권한 없이 지울 수 있음). ### 마이크 모듈은 어떻게 동작하나 윈도우는 마이크 소리를 앱에 넘기기 전에 오디오 처리 모듈(APO, Equalizer APO 와 같은 방식)을 거칩니다. 설치 프로그램이 `C:\Program Files\VoiceChanger\apo\VoiceChangerAPO.dll` 을 각 마이크의 처리 단계에 붙입니다 (`scripts\mic-apo.ps1`, 바꾼 값의 원래 값은 같은 곳의 `apo\mic-apo-backup.json`, v1.0.1 까지 고른 폴더의 `apo\` 에 있던 백업은 설치 프로그램이 이 자리로 옮기고 mic-apo.ps1 이 값을 검증). 통화 앱(디스코드 등)이 여는 통화(Communications) 모드 스트림에도 붙도록 기본 · 통화 · 음성 · 미디어 모드로 등록합니다. 드라이버가 이미 모드 목록을 갖고 있으면 그 목록을 그대로 둡니다. - 변환기가 꺼져 있으면 아무것도 하지 않습니다. 원래 목소리가 그대로 나갑니다 - 변환을 켜면 고른 마이크의 소리를 변환기로 넘기고, 바뀐 목소리를 대신 내보냅니다. 바뀐 소리가 아직 없을 때는 무음이라 원래 목소리가 새지 않습니다 - 변환기가 꺼지거나 멈추면 1.5초 안에 원래 목소리로 돌아갑니다 - 그 마이크를 쓰는 모든 앱(디스코드 · 게임 · 녹음기)에 바뀐 목소리가 갑니다 - 윈도우 소리 설정에서 마이크의 **오디오 향상**을 끄면 모듈이 빠집니다. 설치할 때 켜 두지만, 직접 끄면 변환이 안 됩니다 - 새로 꽂은 마이크나 드라이버를 업데이트한 마이크는 변환기 화면의 **마이크 다시 연결**을 누릅니다 ## 변환하기 — 음성 변환기 1. 목소리 모델을 고릅니다. 직접 학습한 모델이 위에, 예시 모델이 아래에 나옵니다. 2. **내 목소리 성별**을 고르면 성별이 다른 모델은 음높이를 ±12반음(한 옥타브)으로 자동으로 맞춥니다. 슬라이더로 더 맞출 수 있고, 켜 둔 채로 바꿔도 바로 적용됩니다. 3. **마이크**에서 내 마이크를 고릅니다. 디스코드 입력 장치도 같은 마이크로 둡니다. 4. 내 귀로 확인하려면 **내 귀로 듣기**를 켜고 헤드셋을 고릅니다. 5. **▶ 변환 시작**. 처음에는 모델을 불러오느라 몇 초 걸립니다. 아래에 처리 시간(ms)이 나옵니다. - 지연: 보통(0.25초)이 기본입니다. RTX 5070 Ti 는 낮음(0.13초)도 됩니다. 소리가 끊기면 한 단계 올리세요. - 잡음 무시: 이 크기(dB)보다 작은 소리는 변환하지 않습니다. 키보드 소리가 들어가면 올리세요. - 설정은 `config\settings.json` 에 저장돼 다음에 그대로 열립니다. ## 녹음할 서버 정하기 — 녹음 서버 녹음 봇(동의 사이트 https://vc.tkrmagid.kr)이 어느 디스코드 서버에서 녹음할지 앱에서 켜고 끕니다. 1. 동의 사이트에 운영자 디스코드 계정으로 로그인해서 **앱 연결 키 만들기**를 누르고 키를 복사합니다 (한 번만 보입니다. 새로 만들면 예전 키는 못 씁니다). 2. 앱의 **녹음 서버…** 버튼 → 사이트 주소(기본값 그대로)와 앱 연결 키를 넣고 **불러오기**. 3. 녹음할 서버만 체크하고 **저장**. 끈 서버에서는 봇이 바로 나가고 더는 따라 들어가지 않습니다. - 켠 서버에서도 녹음에 동의하고 그 서버를 녹음할 서버로 고른 사람의 목소리만 녹음합니다 (각자 사이트에서 고름). - 사이트 주소와 키는 `config\record-servers.json` 에 저장됩니다. ## 목소리 모델 학습 — `train.bat` 동의 사이트 서버에서 학습 데이터를 꺼냅니다 (동의 중인 사람만 꺼내짐): ```bash cd consent-recorder npm run cli -- export <디스코드 아이디> ./dataset_<이름> # 48kHz 모노 wav, -18 LUFS + 리미터 ``` 그 폴더를 게임PC 로 옮기고: ```bat train.bat D:\dataset_승한 "승한" male train.bat D:\dataset_지원 "지원" female --epochs 300 ``` - 순서: 자르기 → 음높이(rmvpe) · 특징(contentvec) 뽑기 → 학습(기본 200 epoch, batch 8) → 검색 인덱스 → `models\<아이디>\` 에 넣기 - 녹음은 최소 10분, 좋게는 20~30분. 10분보다 짧으면 경고하고, 1분보다 짧으면 학습하지 않습니다 - export 결과가 아닌 녹음이면 `--normalize` 를 붙입니다. javis_bot · 겜녹이와 같은 기준(-18 LUFS + 리미터)으로 맞춥니다 - 학습 중간 파일은 `training\`, 평준화한 녹음은 `datasets\` 에 남습니다. 다 끝나면 지워도 됩니다 동의를 철회한 사람의 모델은 `models\<아이디>` 폴더와 `training\<아이디>` 폴더를 지웁니다. 녹음 서버의 녹음은 철회할 때 자동으로 지워지지만, 이 PC 에 옮긴 녹음 폴더와 모델은 직접 지워야 합니다. ## 한국어 예시 모델 — `examples.bat` 공개 데이터셋으로 예시 모델 4개를 이 PC 에서 학습합니다. RTX 5070 Ti 기준 몇 시간 걸리니 한 번만 돌리면 됩니다. | 모델 | 데이터 | 라이선스 | |------|--------|----------| | 예시 여성 1 (KSS) | KSS Dataset, 성우 1명, 44.1kHz → 48kHz 모델 | CC BY-NC-SA 4.0 (비상업) | | 예시 남성 1 · 남성 2 · 여성 2 (Zeroth 화자 번호) | Zeroth-Korean (OpenSLR 40), 16kHz → 32kHz 모델 | CC BY 4.0 | - 화자마다 녹음 20분을 씁니다. KSS 는 약 540MB, Zeroth 는 10GB 압축 파일을 흘려 읽다가 필요한 화자가 모이면 멈춥니다 - Zeroth 원본이 16kHz 라 Zeroth 예시는 KSS 예시보다 고음이 덜 또렷합니다 - 실존 인물(연예인 등) 목소리 모델은 넣지 않았습니다. 예시도 데이터셋 라이선스 범위(비상업, 출처 표기) 안에서만 쓰세요 ## 폴더 ``` VoiceChanger.exe 실행기 (env\Scripts\pythonw.exe app\voice_changer.py 를 띄움, 소스 launcher\launcher.c) install.bat 엔진 내려받기 · 이어 받기 (scripts\install.ps1, 설치 프로그램도 이것을 실행) train.bat 학습 (app\train.py) examples.bat 예시 모델 (app\examples.py) app\ 화면 · 학습 · 모델 목록 · 마이크 모듈 연결(mic_bridge.py) · 녹음 서버(record_servers.py) 코드 apo\ 마이크 모듈 VoiceChangerAPO.dll 과 소스 (vcapo.cpp, 주고받는 규약 vccore.h) * scripts\mic-apo.ps1 마이크 모듈 붙이기 · 떼기 (관리자) * models\<아이디>\ model.pth · model.index · info.json(이름 · 성별 · 출처 · 라이선스) config\ 설정 · 마이크 모듈 백업 cache\ 임시 파일 · torch · huggingface · matplotlib 등 라이브러리 캐시 (지워도 됨) engine\ env\ tools\ 설치하면 생기는 폴더 (엔진 · Python · uv) uninstall\ 제거 프로그램 * ``` `*` 표시는 설치 프로그램으로 설치하면 고른 폴더가 아니라 `C:\Program Files\VoiceChanger` 에 들어갑니다 (zip 으로 풀어 쓰면 같은 폴더). ## 배포 파일 만들기 ```bash voice-changer/scripts/build-release.sh # 리눅스 mingw: VoiceChanger.exe · VoiceChangerAPO.dll 빌드 → dist/payload, dist/voice-changer-win.zip ``` ```powershell powershell -ExecutionPolicy Bypass -File installer\build.ps1 # Windows + Inno Setup 6: dist\payload → dist\VoiceChangerSetup.exe ``` Inno Setup 은 리눅스 wine 에서 돌지 않아(32비트 프로그램이 wine wow64 에서 죽음) Windows 에서 빌드합니다. ## 테스트 ```bash python -m unittest discover -s voice-changer/tests # 마이크 모듈 C 코드를 gcc 로 컴파일해 파이썬 쪽과 맞물려 봄 (soxr · numpy 필요) ```