OmniVoice 🌍

OmniVoice는 600개 이상의 언어를 지원하는 최첨단(state-of-the-art) 대규모 다국어 제로샷 텍스트-음성 변환(TTS, Text-to-Speech) 모델입니다. 새로운 확산 언어 모델 스타일 아키텍처를 기반으로 구축되었으며, 우수한 추론 속도와 함께 고품질 음성을 생성하고 음성 복제(voice cloning) 및 음성 디자인(voice design)을 지원합니다.

목차: 주요 기능 | 설치 | 빠른 시작 | Python API | 명령줄 도구 | 학습 및 평가 | 토론/소통 | 인용

• 600개 이상 언어 지원: 제로샷 TTS 모델 중 가장 광범위한 언어 커버리지를 제공합니다 (전체 목록).
• 음성 복제 (Voice Cloning): 최고 수준의 음성 복제 품질을 자랑합니다.
• 음성 디자인 (Voice Design): 할당된 화자 속성(성별, 연령, 피치, 방언/억양, 속삭임 등)을 통해 목소리를 제어할 수 있습니다.
• 세밀한 제어 (Fine-grained Control): 비언어적 기호(예: [웃음])와 병음 또는 음소(phonemes)를 통한 발음 교정이 가능합니다.
• 빠른 추론 속도 (Fast Inference): RTF가 0.025까지 낮아져 실시간보다 40배 빠릅니다.
• Diffusion Language Model 스타일 아키텍처: 품질과 속도를 모두 제공하는 깔끔하고 간결하며 확장 가능한 디자인입니다.

설치 (Installation)

다음 방법 중 하나를 선택하세요: pip 또는 uv.

pip

충돌을 방지하기 위해 새로운 가상 환경(예: conda, venv 등) 사용을 권장합니다.

1단계: PyTorch 설치

# CUDA 버전에 맞춰 pytorch를 설치하세요. 예:
pip install torch==2.8.0+cu128 torchaudio==2.8.0+cu128 --extra-index-url https://download.pytorch.org/whl/cu128

다른 버전 설치는 PyTorch 공식 사이트를 참조하세요.

pip install torch==2.8.0 torchaudio==2.8.0

Intel Arc GPU(Alchemist 및 Battlemage 아키텍처)는 PyTorch의 XPU 백엔드를 통해 지원됩니다.

1. OS에 맞는 Intel GPU 드라이버를 설치하세요.

2. Intel의 wheel 인덱스에서 XPU 지원 PyTorch를 설치하세요:

pip install torch torchaudio --index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/

버전별 지침은 Intel의 PyTorch XPU 가이드를 참조하세요.

3. 백엔드가 작동하는지 확인하세요:

python -c "import torch; print(torch.xpu.is_available(), torch.xpu.device_count())"

참고 사항:

• flash_attn은 XPU에서 사용할 수 없으며, 모델이 자동으로 SDPA로 폴백(fallback)합니다.
• 패킹된 시퀀스(flex_attention)를 사용한 학습은 부분적인 XPU 지원을 가지며, 단일 GPU의 SDPA 학습은 작동해야 합니다.
• Arc A310 (Alchemist, 4 GB) 및 Arc Pro B50 (Battlemage, 16 GB)에서 테스트되었습니다.

2단계: OmniVoice 설치 (택일)

# PyPI에서 (안정 버전)
pip install omnivoice

...

uv

저장소(repository)를 클론하고 종속성을 동기화합니다:

git clone https://github.com/k2-fsa/OmniVoice.git
cd OmniVoice
uv sync

팁: uv sync --default-index "https://mirrors.aliyun.com/pypi/simple"를 사용하여 미러(mirror)를 사용할 수 있습니다.

빠른 시작 (Quick Start)

코딩 없이 OmniVoice를 사용해 보세요:

• 로컬 웹 UI 실행: omnivoice-demo --ip 0.0.0.0 --port 8001

• 또는 HuggingFace Space에서 직접 시도해 보세요.

• 또는 Google Colab에서 실행:

  
  Open In Colab

사전 학습된 모델을 다운로드할 때 HuggingFace 연결에 문제가 발생하면, 실행하기 전에 export HF_ENDPOINT="https://hf-mirror.com"을 설정하세요.

전체 사용법은 아래의 Python API 및 명령줄 도구 (Command-Line Tools) 섹션을 참조하세요.

Python API

OmniVoice는 세 가지 생성 모드를 지원합니다. 이 섹션의 모든 기능은 명령줄 도구 (command-line tools)를 통해서도 사용할 수 있습니다.

음성 복제 (Voice Cloning)

짧은 참조 오디오에서 목소리를 복제하세요. ref_audio와 ref_text를 제공해야 합니다:

from omnivoice import OmniVoice
import soundfile as sf
import torch
...

세션 간 클론된 음성 재사용

참조 오디오를 한 번 인코딩하여 결과 프롬프트(prompt)를 저장하고, 이후 세션에서는 오디오 로드/자동 전사 단계를 건너뛸 수 있습니다:

prompt = model.create_voice_clone_prompt(
    ref_audio="ref.wav", ref_text="참조 오디오의 전사본입니다."
)
...

팁(Tips)

• 3~10초 분량의 참고 오디오 클립을 사용하세요. 오디오가 길어질수록 추론 속도가 느려지고 복제 품질이 저하될 수 있습니다.

• 표준 발음을 위해서는 대상 음성과 동일한 언어의 참고 오디오를 사용하세요. 교차 언어 음성 복제(즉, 참고 오디오와 대상 음성이 다른 언어인 경우)에서는 생성된 음성에 참고 오디오가 속한 언어의 억양이 반영됩니다.

• 아라비아 숫자의 결과를 개선하려면 먼저 단어로 정규화하는 것이 좋습니다 (예: "123" → "one hundred twenty-three"). generate() 함수에 normalize_text=True를 전달하여 이를 자동으로 수행할 수 있습니다(선택적 사용; pip install "omnivoice[tn]"으로 추가 설치해야 하며, 이 패키지는 WeTextProcessing을 가져옵니다):

  복사

  # "I have 2345 apples."는 자릿수별로 읽히지 않고 올바르게 읽힙니다.
  audio = model.generate(text="I have 2345 apples.", normalize_text=True)
  

  1

  2

  3

  중국어와 영어는 WeTextProcessing을 사용하며, 다른 언어의 정수는 num2words로 대체됩니다. 인라인 제어 구문([laughter], [B EY1 S], 병음 억양 마커)은 유지됩니다. macOS(Apple Silicon)에서는 pynini에 wheel이 없으므로 먼저 conda install -c conda-forge pynini를 통해 설치해야 합니다.

더 많은 팁은 docs/tips.md를 참조하세요.

음성 디자인 (Voice Design)

화자 속성을 사용하여 원하는 목소리를 설명하면 참고 오디오가 필요하지 않습니다.
지원되는 속성: 성별 (남성/여성), 나이 (아동부터 노년까지),
음높이 (매우 낮음 ~ 매우 높음), 스타일 (속삭임), 영어 억양
(미국식, 영국식 등), 그리고 중국어 방언 (사천화, 산시화 등).
속성들은 쉼표로 구분되며 카테고리 전반에 걸쳐 자유롭게 조합할 수 있습니다.

audio = model.generate(
    text="Hello, this is a test of zero-shot voice design.",
    instruct="female, low pitch, british accent",
...

참고: 이 모델은 주로 음성 복제 (voice cloning) 작업으로 훈련되었기 때문에, 음성 복제가 가장 안정적인 모드입니다. 음성 디자인은 중국어와 영어 데이터로만 훈련되었습니다. 다른 언어로 일반화할 수 있지만, 일부 저자원 언어나 예외적인 경우에는 불안정한 결과를 생성할 수 있습니다.

전체 속성 참조, 중국어 등가물 및 사용 팁은 docs/voice-design.md를 참고하세요.

자동 음성 (Auto Voice)

모델이 자동으로 목소리를 선택하도록 합니다:

audio = model.generate(text="This is a sentence without any voice prompt.")

생성 매개변수 (Generation Parameters)

위의 세 가지 모드는 모두 동일한 model.generate() API를 공유합니다. 키워드 인자(keyword arguments)를 통해 생성 동작을 추가로 제어할 수 있습니다:

audio = model.generate(
    text="...",
    num_step=32,  # 확산 단계 (diffusion steps) (더 빠른 추론의 경우 16)
...

더 자세한 제어 방법은 docs/generation-parameters.md를 참고하세요.

비언어적 및 발음 제어 (Non-Verbal & Pronunciation Control)

OmniVoice는 입력 텍스트 내에서 인라인 **비언어적 기호(non-verbal symbols)**와 **발음 교정(pronunciation correction)**을 지원합니다.

비언어적 기호: [laughter]와 같은 태그를 텍스트에 직접 삽입하여 표현적인 비언어적 소리를 추가할 수 있습니다.

audio = model.generate(text="[laughter] You really got me. I didn't see that coming at all.")

지원되는 태그: [laughter], [sigh], [confirmation-en], [question-en], [question-ah], [question-oh], [question-ei], [question-yi], [surprise-ah], [surprise-oh], [surprise-wa], [surprise-yo], [dissatisfaction-hnn].

발음 제어 (중국어): 성조 숫자와 함께 병음(pinyin)을 사용하여 특정 문자 발음을 교정합니다.

audio = model.generate(text="这批货物打ZHE2出售后他严重SHE2本了，再也经不起ZHE1腾了。")

발음 제어 (영어): 기본 영어 발음을 재정의하려면 CMU pronunciation dictionary를 사용하세요 (대문자, 대괄호 안에 표기).

audio = model.generate(text="He plays the [B EY1 S] guitar while catching a [B AE1 S] fish.")

커맨드라인 도구 (Command-Line Tools)

세 가지 CLI 진입점이 제공됩니다. 이 CLI 도구들은 Python API에서 사용 가능한 모든 기능(음성 복제, 음성 디자인, 자동 음성, 생성 매개변수 등)을 지원하며, 모두 명령줄 인수를 통해 제어할 수 있습니다.

데모 (Demo)

omnivoice-demo --ip 0.0.0.0 --port 8001

음성 복제 및 음성 디자인을 위한 웹 UI를 제공합니다. 모든 옵션은 omnivoice-demo --help를 참조하세요.

단일 추론 (Single Inference)

# 음성 복제 (Voice Cloning)
# ref_text는 생략 가능합니다 (Whisper가 ref_audio를 자동 전사하여 텍스트를 얻습니다).
omnivoice-infer \
...

배치 추론 (Batch Inference)

omnivoice-infer-batch는 대규모 TTS 작업을 위해 여러 GPU에 걸쳐 배치 추론을 분산할 수 있도록 설계되었습니다.

omnivoice-infer-batch \
    --model k2-fsa/OmniVoice \
    --test_list test.jsonl \
...

테스트 리스트는 각 줄이 JSON 객체인 JSONL 파일입니다:

{"id": "sample_001", "text": "Hello world", "ref_audio": "/path/to/ref.wav", "ref_text": "Reference transcript", "instruct": "female, british accent", "language_id": "en", "duration": 10.0, "speed": 1.0}

id와 text만 필수 필드입니다. ref_audio와 ref_text는 음성 복제 모드에서 사용됩니다. instruct는 음성 디자인 모드에서 사용됩니다. 참고 자료 오디오나 지침(instruct)이 제공되지 않으면, 모델은 무작위 음성으로 텍스트를 생성합니다.

language_id, duration, 그리고 speed는 선택 사항입니다. duration(초 단위)은 출력 길이를 고정하며, speed는 말하는 속도를 제어합니다. 만약 duration과 speed가 모두 제공되면, speed는 무시됩니다.

FlashInfer 가속 (FlashInfer Acceleration)

추론(Inference) 속도를 FlashInfer 커널을 사용하여 손실 없이 약 2~2.9배 가속할 수 있습니다 (CFG 조건부/비조건부 쌍에 대한 시퀀스 패킹, 통합된 RMSNorm/RoPE/GEMM 커널 및 선택적 CUDA 그래프 포함).

설치(Installation) (NVIDIA GPU; 사용 중인 CUDA 버전에 맞는 인덱스를 선택하세요. 예: PyTorch가 CUDA 12.8로 빌드된 경우 cu128):

pip install flashinfer-python==0.6.15.post1 "flashinfer-jit-cache==0.6.15.post1+cu128" \
    --extra-index-url https://flashinfer.ai/whl/cu128/

배치 추론 CLI를 사용한 사용법(Usage):

omnivoice-infer-batch \
    --model k2-fsa/OmniVoice \
    --test_list test.jsonl \
...

또는 Python API를 사용하는 방법:

from omnivoice.models.omnivoice_flashinfer import apply_flashinfer

model = OmniVoice.from_pretrained("k2-fsa/OmniVoice", device_map="cuda", dtype=torch.float16)
...

커널 실행 오버헤드가 지배적인 단일 스트림(batch=1) 사용에는 CUDA 그래프가 권장되며, 배치 크기가 4 이상인 경우에는 일반 FlashInfer 경로가 이미 가장 빠른 구성입니다.

벤치마크(Benchmark) (seed-tts zh 테스트 세트, 2020 샘플 / 3.3시간 오디오, 음성 복제, 단일 H100, fp16, num_step=32; omnivoice-infer-batch가 보고한 평균 RTF이며 ASR 검증 손실 없는 결과):