MagnetismHeroes/docs/qwen-voice-register.md

한국어 Qwen 음성 자산 기록

현재 상태: 로컬 GPU 음성 생성과 파일 검사를 완료했습니다. 발음·어절 잘림·음색 적합성은 아직 직접 듣고 검수하지 않았습니다. 게임에 연결한 파일은 초안이며 최종 음성으로 승인한 파일이 아닙니다. 효과음과 배경음악은 사용자가 나중에 추가하기로 했습니다.

출처와 이용조건

• 확인 날짜: 2026-10-05 한국 시간. 공식 Qwen3-TTS 저장소, 모델 카드를 확인했습니다.
• 모델: Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice, 고정 revision 0c0e3051f131929182e2c023b9537f8b1c68adfe, 한국어/Sohee. 기존 conda 환경 qwen3-tts를 재사용했습니다. 가중치·토크나이저·프로세서 전체 snapshot은 저장소 밖에 캐시하며 게임에는 포함하지 않습니다.
• 모델 카드는 Apache-2.0을 선언하고, 설치된 qwen-tts 0.1.1에는 Apache-2.0 코드 라이선스가 포함되어 있습니다. 실제 모델 카드와 코드 라이선스 원문은 SourceAssets/Audio/Voice/licenses/에 보존했습니다. 공개된 이용조건을 기록한 것이며 생성 음성의 독점권을 주장하지 않습니다.
• 공유 프로필에는 정확한 지시문·seed 42·생성 인자·장치·dtype·attention을 기록하고 기기별 캐시 절대경로를 넣지 않았습니다. 초기 지시문: 5~7세 아이에게 이야기하듯 따뜻하고 밝게, 천천히 또렷하게 읽어 주세요. 숫자는 정확하게 읽고 과장된 비명이나 웃음소리는 넣지 마세요.

실제 환경과 생성 증거

기존 CPU torch를 설치된 torchaudio 2.11.0과 버전이 맞는 공식 torch==2.11.0+cu128 wheel로 교체했습니다. torch의 직접 요구조건 setuptools<82를 충족하도록 setuptools 83.0.0만 81.0.0으로 변경했습니다. 환경 재생성이나 무관한 패키지 일괄 업그레이드는 하지 않았습니다.

실제 환경은 Python 3.12.15, qwen-tts 0.1.1, torch 2.11.0+cu128, torchaudio 2.11.0+cpu, transformers 4.57.3, soundfile 0.14.0, huggingface-hub 0.36.2입니다. CUDA 12.8 / NVIDIA GeForce RTX 4080 SUPER에서 CUDA 제곱·합 연산 결과 140을 확인했습니다. torch CUDA·qwen-tts·torchaudio import가 성공했고 SDPA/bfloat16으로 실제 GPU 추론이 성공했습니다. FlashAttention과 SoX는 설치하지 않았습니다.

첫 표본 회차 20261004T161148012934Z_47f3a009에서 count_01/count_04/count_07/count_10/guide_collect를 생성했습니다. 모델 로딩 3.214초, GPU 최대 할당 메모리 4,232,247,296바이트, 원본 출력 24,000 Hz 모노 FLOAT WAV입니다. 클립별 길이·프레임 수·생성 시간·SHA-256은 해당 회차 manifest에 기록했습니다.

확대 회차 20261004T161231511126Z_aa20f404에서는 대본·프로필·파일 해시가 같은 이전 다섯 클립을 재사용하고 나머지 숫자와 guide_count를 실제 생성했습니다. manifest에는 원래 생성 회차와 파일, 실제 인자와 모델 기본값, 환경, 해시, 클립별 결과를 기록했습니다. 생성 성공과 파일 검사 성공을 발음 합격으로 해석하지 않습니다.

후속 GPU 확인은 실제 모델 장치 cuda:0, 로딩 2.976초, 생성 1.826초, 최대 할당 메모리 4,227,715,072바이트, 24,000 Hz / 13,440프레임 / 0.56초를 확인했습니다. 해당 증거와 파형은 무시된 검사 산출물 artifacts/verification/FirstSlice/Voice/gpu-probe.json 및 gpu-probe.wav에 있습니다.

게임 연결용 초안

초안 경로는 Assets/MagnetismHeroes/UnityRuntime/Presentation/Audio/Voice/입니다. 원본 FLOAT WAV는 보존하고 실제 polyphase 리샘플링으로 44,100 Hz 모노 PCM16 편집본을 만들었습니다. 발화 구간은 잘라내지 않았습니다. edited/<runId>/selection.json에서 원본 해시와 편집본·게임 파일 해시를 연결합니다. 기존 게임 파일과 새 편집본 내용이 다르면 제작 도구는 기존 파일을 덮어쓰지 않습니다.

ID	길이	상태
count_01	0.56초	T2 필수 초안, 청취 미검수
guide_collect	2.00초	T2 필수 초안, 청취 미검수
guide_count	3.60초	T2 필수 초안, 청취 미검수
count_02,03,04,06,07,08,09,10	0.48~1.44초	이후 계수용 초안, 청취 미검수
count_05	9.12초	긴 공백과 후반 소리의 이상 후보로 게임 연결에서 제외

count_05의 전체 원본과 편집 후보는 원인 확인을 위해 보존했습니다. 숫자 한 단어가 2초보다 길면 초안 내보내기를 차단합니다. 이 기준은 검수 필요 신호이며 자동 발음 검사가 아닙니다. 같은 프로필로 특정 클립을 다시 만들 때는 --ids count_05 --regenerate를 사용하며 이전 회차를 보존합니다.

동일 프로필·seed 42로 count_05만 다시 생성한 회차 20261004T162201751189Z_a400364e에서도 9.12초 출력이 재현되었습니다. 실제 cuda:0 모델 로딩 2.974초, 추론 22.271초, 최대 GPU 할당 4,386,499,584바이트였습니다. 생성 자체는 성공했지만 정상 초안으로 채택하지 않았고 두 회차의 원본을 모두 보존했습니다. 파일 길이만으로 발음 합격을 선언하지 않으며, 이후 직접 청취한 뒤 같은 모델·목소리 범위에서 지시문·생성 설정을 검토해야 합니다.

검증 명령과 결과

모든 명령은 기존 환경의 Python 또는 conda run --no-capture-output -n qwen3-tts로 실행합니다. 아래 명령의 실행 위치는 프로젝트 루트입니다.

python -m unittest discover -s tools/audio -p 'test_*.py' -v
python tools/audio/generate_voice.py --catalog SourceAssets/Audio/Voice/voice-catalog.json --profile SourceAssets/Audio/Voice/qwen-profile.json --ids count_01,count_04,count_07,count_10,guide_collect
python tools/audio/generate_voice.py --catalog SourceAssets/Audio/Voice/voice-catalog.json --profile SourceAssets/Audio/Voice/qwen-profile.json
python tools/audio/generate_voice.py --catalog SourceAssets/Audio/Voice/voice-catalog.json --profile SourceAssets/Audio/Voice/qwen-profile.json --validate-only --manifest SourceAssets/Audio/Voice/generated/20261004T161231511126Z_aa20f404/manifest.json

초기 RED는 생성기 모듈이 없어 종료 코드 1이었습니다. 최종 GREEN에서는 동작 검증 테스트 10개가 종료 코드 0으로 통과했습니다. 잘못된 카탈로그, 현재 대본·프로필과 부분 검사 범위, 실패하거나 비정상적인 WAV, 누락·손상 WAV, 대본·설정 변경, 해시 변조, 이전 원본 보존, 리샘플링, 다른 게임 파일 덮어쓰기 거부, 긴 숫자 출력 차단, 특정 클립만 새 회차로 생성하는 동작을 검사합니다.

첫 표본 생성·확대 생성·검사 전용 명령은 각각 종료 코드 0이었습니다. --validate-only는 모델을 로딩하거나 다운로드하지 않습니다. ID를 생략하면 현재 T2 필수 세 클립 전체를 검사하고, --ids를 지정하면 선택 범위를 결과에 기록합니다. 생성한 열두 클립을 모두 지정한 파일·이력 검사는 종료 코드 0이었지만 count_05의 별도 음질 문제는 합격으로 처리하지 않았습니다. 잘못된 ID missing은 해당 ID를 포함한 오류와 종료 코드 1을 반환했습니다. 마지막 pip check는 종료 코드 0으로 충돌이 없었습니다.

실제 후속 로그는 구현 worktree의 artifacts/verification/FirstSlice/Voice/ 아래 python-tests.log, validate-all-generated.log, validate-invalid-id.log입니다. 산출물은 Git에서 제외하고 원본 manifest와 선택 파일 해시는 추적합니다.

Unity .meta는 통합 후 실제 Editor import로 생성해야 하며 직접 작성하지 않았습니다. 남은 검수는 선택한 각 발화를 듣고 검수자·날짜·승인 해시를 기록하는 작업, count_05 및 이후 안내 음성 검수, Android 빌드의 음성 큐·믹스 재생 확인입니다.