Copycat 은 한국어 노래 음성(wav)을 합성하는 올인원 스튜디오입니다.
네이티브 프로젝트 포맷은 .svsx(XML) 이며, OpenUtau .ustx 와
Synthesizer V .svp 를 가져오기, .ustx 로 내보내기 할 수 있습니다.
학습된 모델 가중치(
best.pt)는 코드와 별도 리포로 배포됩니다: Hugging Face →poralis/copycat(아래 "빠른 시작" 참고). 가중치에는 이 코드(PolyForm NC)와 함께 Acceptable Use 정책이 추가 적용됩니다.
-
패키지 설치 (추론 전용 — 가장 가벼움):
pip install -r requirements.txt(재생/seek 를 위해
sounddevice가 포함됩니다.) -
모델 가중치
best.pt를 이 폴더에 내려받습니다 (Hugging Faceporalis/copycat):pip install huggingface_hub huggingface-cli download poralis/copycat best.pt --local-dir .또는 웹에서 직접 받아 이 폴더에 둡니다.
-
실행:
python svs_studio.py기본값으로 같은 폴더의
best.pt,config.json, vocab 들을 자동으로 읽습니다.
실행하면 빈 프로젝트(트랙 1개) 로 시작합니다. 피아노롤 빈 곳을 더블클릭해 노트를
찍으면 바로 합성이 시작됩니다. 파일 메뉴에서 열기/저장(.svsx), USTX·SVP
가져오기 / USTX 내보내기 로 다른 포맷과 주고받고, "트랙 추가"/"MR 불러오기" 로
트랙을 늘립니다.
NSF-HiFiGAN 보코더는 최초 실행 시 HuggingFace(
choihkk/nsf-hifigan)에서 자동 다운로드되어~/.cache/nsf-hifigan/에 저장됩니다(인터넷 필요, 1회만). 보코더 가중치는 라이선스상 이 리포에 포함하지 않습니다.
모델 스택:
model.py— Copycat 음향 모델 (f0 피치곡선 입력, mel-GAN refiner 포함)gan_modules.py— refiner 모듈 (configgan.enabled=true일 때 로드)infer_api.py— 추론기 (notes → mel + f0)synth_api.py— NSF-HiFiGAN 보코더 래퍼 (mel + f0 → wav)phoneme_tokenizer.py— IPA 조음자질 토크나이저config.json,phoneme_vocab.json,style_vocab.json,speaker_vocab.json,ipa_features.json,speaker_stats.json
포맷 입출력 / 스튜디오:
svs_studio.py— tkinter 스튜디오 앱 (멀티트랙/스트리밍/MR/f0/다중선택)svs_ustx.py— 프로젝트 → wav 풀 파이프라인 (phrase 캐싱, crossfade)stream_engine.py— 스트리밍 합성 엔진 (백그라운드 합성 + 라이브 재생 + MR 믹스)ustx_io.py— 내부 IR +.ustx파서/내보내기svp_io.py— Synthesizer V.svp(JSON) 가져오기project_io.py— 네이티브.svsx(XML) 저장/열기render_svsx.py— GUI 없이.svsx→ wav 헤드리스 렌더 (음질 테스트/배치용)
기타:
test_sample.ustx/test_sample.svp— 검증용 샘플 (피치벤드·비브라토·detune 포함)FT/— 파인튜닝 툴킷 (자신의 데이터로 화자 추가/미세조정;FT/README.md참고)requirements.txt(추론) /requirements-dev.txt(파인튜닝·전처리 포함)
프로그램에서 직접:
from svs_ustx import USTXSynthesizer
s = USTXSynthesizer("best.pt", "config.json", vocab_dir=".")
audio, sr = s.synthesize_file("test_sample.ustx",
gender=1.0, style={"CLEAR":0.7,"HUSKY":0.3},
genre="BALLAD", speaker="SINGER_01")
s.save_wav(audio, "out.wav").svsx 프로젝트를 GUI 없이 렌더:
python render_svsx.py my_song.svsx # refiner ON (기본)
python render_svsx.py my_song.svsx --no-refiner # refiner OFF (A/B 비교)
| 포맷 | 역할 | 담는 정보 |
|---|---|---|
| .svsx (XML) | 네이티브 저장/열기 | 노트·포르타멘토·비브라토 + 자유 피치 그리기(f0 cent) + 조건(화자/성별/스타일·장르 혼합/속도) + 트랙 볼륨/뮤트 + MR 경로 |
| .ustx (YAML) | 가져오기/내보내기(OpenUtau) | 노트·포르타멘토·비브라토·템포·박자 |
| .svp (JSON) | 가져오기(Synthesizer V) | 노트·pitchDelta 피치 곡선·detune·비브라토·템포·박자 |
핵심: SV 의 '피치 그리기' 는 본 모델의 f0_cent_offset(cent 가산)과 같은 메커니즘이라,
SVP 의 pitchDelta 곡선은 가져오기 시 노트별 cent 편차로 변환되어 합성에 반영됩니다.
체크포인트(.pt) 대신 사전 export 된 ONNX 로 추론하는 대체 백엔드입니다(코드는 onnx/).
가속은 AMD/Intel/NVIDIA 공통(DirectML, CUDA 불필요).
-
acoustic ONNX 다운로드 (Hugging Face
poralis/copycat) →onnx/에 배치:huggingface-cli download poralis/copycat \ svs_encoder.onnx svs_encoder.onnx.data \ svs_decoder.onnx svs_decoder.onnx.data --local-dir onnx -
보코더 ONNX 로컬 생성 — NSF-HiFiGAN 보코더는 라이선스상 배포하지 않으므로 최초 1회 직접 export 합니다(HuggingFace 원본 가중치 자동 다운로드 후 변환):
pip install -r requirements-dev.txt python onnx/export_vocoder.py # onnx/nsf_hifigan.onnx 생성 -
실행:
pip install onnxruntime-directml python svs_studio.py --onnx # ONNX Runtime, CPU python svs_studio.py --onnx-dml # + DirectML
--onnx-dml은 encoder 그래프에만 DirectML 을 적용합니다. decoder/vocoder 는 동적 reshape 패턴에서 onnxruntime-directml 이 예외를 낼 수 있어 항상 CPU 로 고정됩니다 (자세한 내용은onnx/README.md).
- 음소 체계: vocab 은 순수 한글 호환 자모(ㄱㄴㄷ…ㅏㅓ…). 한글 가사를 그대로 쓰면 정확히 정렬됩니다. 영어/로마자 가사는 미지원(OOV) → 무음 처리.
- 기본 실행은 CPU. CUDA GPU 는
--device cuda. - 화자는 로드 시 첫 번째(SINGER_01)가 자동 선택됩니다. 콤보에서 변경하세요.
이 코드는 PolyForm Noncommercial License 1.0.0 을 따릅니다. 비영리 목적(개인 연구·학습·취미)으로는 자유롭게 사용·수정·배포할 수 있으나, 상업적 이용은 금지됩니다.
전체 조항은 LICENSE 참고.
본 프로젝트의 모델은 AI-Hub '다음색 가이드보컬 데이터' (dataSetSn=473)를 활용하여 학습되었습니다. 원본 데이터셋의 저작권은 한국지능정보사회진흥원(NIA) 및 데이터 구축 수행기관에 있으며, 이 리포에는 원본 데이터가 포함되어 있지 않습니다. 자세한 저작권 구조는 NOTICE.md 참고.
- ❌ 비윤리적 용도 사용 금지
- ❌ 타인 목소리 무단 사용(동의 없는 보이스클로닝) 금지
전문은 모델 리포의 ACCEPTABLE_USE.md 를 참고하세요.
기본적으로 상업적 이용은 금지되어 있습니다. 상업 라이선스 협의를 원하시면 subchanhee@gmail.com 으로 문의해 주세요.