Files
voice_copy/voice-changer/README.md
EJClaw c1d9242b81 voice-changer installer 1.0.4: refuse admin-token deploy; do not carry over the v1.0.2 uninstall log
Review/arbiter REVISE on 85f5782:
- If the installer is started elevated ("Run as administrator", admin terminal), ExecAsOriginalUser is
  elevated too, so deploy.ps1 copied into the user's folder and ran its scripts with admin rights.
  deploy.ps1 now checks the real token first (WindowsPrincipal.IsInRole(Administrator)) and exits 33
  before touching any path; the installer explains to start it by double-click. The post-install launch
  only runs when deploy succeeded (Check: DeployDone).
- v1.0.2 and later share AppId and uninstall dir, and the default UninstallLogMode=append kept v1.0.2's
  entries for files in the user's folder, which the elevated uninstaller would delete through a junction.
  UninstallLogMode=overwrite starts a fresh log. Since pre-existing folders are then not recorded as
  created, the uninstaller removes Program Files\VoiceChanger's apo\ scripts\ payload\ itself and launches
  a detached `rmdir` for the then-empty uninstall\ and install folder (Program Files only).

Windows 11 VM, Inno 6.7.4, AppVersion 1.0.4 (final build):
- A: setup started from an elevated process with /DATADIR=<Desktop>\VCA: deploy exit 33, the folder was
  never created, no shortcuts; REFUSED_BEFORE_WRITE PASS.
- L: deploy.ps1 under the logged-on user's limited token (Administrators deny-only) copies the app,
  folder owned by the user.
- C (control): v1.0.2 on Desktop -> v1.0.3, unins000.dat mentions Desktop\VC2; folder swapped for a junction
  to admin-only C:\vctarget, uninstall deletes the target's same-named files (FAIL, the bug).
- B: v1.0.2 on Desktop -> 1.0.4: unins000.dat no longer mentions it; same swap + uninstall: target files and
  SDDL unchanged (PASS); Program Files\VoiceChanger fully removed.
- R: fresh -> reinstall -> uninstall: Program Files\VoiceChanger fully removed; FxProperties restored.
- python unittest: 16 run, 2 skipped (tkinter missing).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 23:04:18 +09:00

143 lines
12 KiB
Markdown

# 실시간 음성 변환기 (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 필요)
```