Kokoro-82M 설치 및 사용 가이드 (Mac)

개요

이 문서는 Mac(특히 Apple Silicon M1/M2/M3/M4) 환경에서 Kokoro-82M TTS 모델을 설치하고 사용하는 방법을 안내한다. Kokoro는 pip install kokoro 한 줄로 설치할 수 있으며, Apple Silicon의 Metal GPU(MPS)를 활용해 빠른 음성 생성이 가능하다.

---

사전 요구사항

항목	요구 사항
OS	macOS 12 Monterey 이상 권장
Python	3.9 이상 (3.11 또는 3.12 권장)
패키지 관리자	pip, 가상환경(venv 또는 conda) 권장
Homebrew	espeak-ng 설치에 필요
저장 공간	약 1~2GB (모델 가중치 포함)

Apple Silicon(M1/M2/M3/M4) Mac의 경우 PyTorch MPS 백엔드를 통해 GPU 가속을 사용할 수 있다. Intel Mac은 CPU 모드로 동작한다.

---

설치 방법

1단계: Homebrew로 espeak-ng 설치

Kokoro는 텍스트의 음소(phoneme) 변환에 espeak-ng를 사용한다. macOS에서는 apt-get 대신 Homebrew로 설치한다.

brew install espeak-ng

설치 확인:

espeak-ng --version

2단계: Python 가상환경 생성

시스템 Python과 충돌을 방지하기 위해 전용 가상환경을 만드는 것을 권장한다.

python3 -m venv kokoro-env
source kokoro-env/bin/activate

3단계: kokoro 패키지 설치

pip install kokoro>=0.9.4 soundfile

음성 파일 재생까지 하려면 sounddevice도 함께 설치한다.

pip install sounddevice

4단계: PyTorch 설치 확인

Kokoro 설치 시 PyTorch가 자동으로 함께 설치된다. Apple Silicon에서 MPS 지원 여부를 확인한다.

import torch
print(torch.backends.mps.is_available())  # True면 MPS 사용 가능

---

Apple Silicon MPS 설정

Apple Silicon Mac에서는 PyTorch의 MPS(Metal Performance Shaders) 백엔드를 사용해 GPU 가속을 활성화할 수 있다. 일부 연산은 MPS에서 지원되지 않아 CPU로 폴백(fallback)이 필요하므로, 반드시 아래 환경 변수를 설정해야 한다.

방법 1: 환경 변수로 스크립트 실행

PYTORCH_ENABLE_MPS_FALLBACK=1 python my_tts_script.py

방법 2: 스크립트 내에서 설정

import os
os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"

import torch
from kokoro import KPipeline

# MPS 디바이스 지정
device = "mps" if torch.backends.mps.is_available() else "cpu"
pipeline = KPipeline(lang_code='a', device=device)

방법 3: .env 파일 또는 셸 프로파일에 영구 설정

# ~/.zshrc 또는 ~/.bash_profile에 추가
export PYTORCH_ENABLE_MPS_FALLBACK=1

---

기본 TTS 사용법

텍스트를 음성 파일로 저장

import soundfile as sf
from kokoro import KPipeline

# 미국 영어 파이프라인 초기화
pipeline = KPipeline(lang_code='a')

text = "Hello! This is a test of the Kokoro TTS model running on a Mac."

# 음성 생성 (generator 방식)
generator = pipeline(text, voice='af_heart', speed=1.0)

for i, (graphemes, phonemes, audio) in enumerate(generator):
    sf.write(f'output_{i}.wav', audio, 24000)
    print(f"Segment {i} saved: {graphemes[:30]}...")

print("TTS 생성 완료!")

한국어 음성 생성

현재 v1.0 기준 한국어는 공식 지원 언어에 포함되어 있지 않다. 영어 등 지원 언어 목록을 확인 후 사용한다.

실시간 재생 (sounddevice 사용)

import sounddevice as sd
import numpy as np
from kokoro import KPipeline

pipeline = KPipeline(lang_code='a')
text = "Kokoro TTS is running on Apple Silicon with MPS acceleration."

for _, _, audio in pipeline(text, voice='af_heart'):
    sd.play(audio, samplerate=24000)
    sd.wait()  # 재생 완료까지 대기

---

음성 선택 및 커스터마이징

주요 음성 목록 (미국 영어)

음성 ID	성별	특징
af_heart	여성	따뜻하고 자연스러운 톤, 기본 추천
af_bella	여성	명료하고 전문적인 톤
af_sarah	여성	친근하고 밝은 톤
am_adam	남성	중후하고 안정적인 톤
am_puck	남성	캐주얼하고 자연스러운 톤

영국 영어 음성 예시

# 영국 영어 파이프라인
pipeline = KPipeline(lang_code='b')
generator = pipeline(text, voice='bf_emma')  # 영국 여성 음성

재생 속도 조절

speed 파라미터로 재생 속도를 조절한다. 기본값은 1.0이며, 범위는 0.5~2.0 정도가 권장된다.

# 느리게 (0.8배)
generator = pipeline(text, voice='af_heart', speed=0.8)

# 빠르게 (1.3배)
generator = pipeline(text, voice='af_heart', speed=1.3)

음성 혼합(Voice Blending)

두 가지 음성을 혼합해 새로운 음색을 만들 수 있다.

import torch
from kokoro import KPipeline

# 두 음성 가중치 파일 로드 후 혼합 (고급 사용)
# 자세한 방법은 공식 GitHub 참고

---

자주 발생하는 오류 해결

오류 1: espeak-ng 관련 오류

FileNotFoundError: [Errno 2] No such file or directory: 'espeak-ng'

해결: Homebrew로 espeak-ng를 설치한다.

brew install espeak-ng

설치 후에도 오류가 발생하면 경로 확인:

which espeak-ng
# 출력 예: /opt/homebrew/bin/espeak-ng

오류 2: MPS 관련 연산 미지원 오류

NotImplementedError: The operator 'aten::...' is not currently implemented for the MPS device.

해결: PYTORCH_ENABLE_MPS_FALLBACK=1 환경 변수를 설정한다. 이 변수가 설정되어 있으면 MPS에서 지원하지 않는 연산을 자동으로 CPU에서 실행한다.

PYTORCH_ENABLE_MPS_FALLBACK=1 python my_script.py

오류 3: ImportError: No module named 'kokoro'

해결: 가상환경이 활성화되어 있는지 확인하고 재설치한다.

source kokoro-env/bin/activate
pip install kokoro>=0.9.4

오류 4: 오디오 출력 없음 (soundfile 저장 시)

해결: 출력 경로가 올바른지, 디스크 여유 공간이 있는지 확인한다. 또한 생성된 audio 배열이 비어 있지 않은지 확인한다.

for i, (gs, ps, audio) in enumerate(generator):
    print(f"Audio shape: {audio.shape}, dtype: {audio.dtype}")
    if audio.size > 0:
        sf.write(f'output_{i}.wav', audio, 24000)

오류 5: 모델 다운로드 실패

HuggingFace에서 모델 가중치를 자동 다운로드할 때 네트워크 오류가 발생하면, 수동으로 다운로드 후 캐시 경로에 배치한다.

# HuggingFace CLI로 수동 다운로드
pip install huggingface_hub
huggingface-cli download hexgrad/Kokoro-82M

---

ONNX 런타임을 이용한 최적화 (선택 사항)

PyTorch 대신 ONNX Runtime을 사용하면 Apple Silicon에서 ARM64 최적화를 활용해 더 빠른 추론이 가능하다.

pip install kokoro-onnx sounddevice onnxruntime

from kokoro_onnx import Kokoro

kokoro = Kokoro("kokoro-v0_19.onnx", "voices.bin")
samples, sample_rate = kokoro.create(
    "Hello from Kokoro ONNX!",
    voice="af_bella",
    speed=1.0,
    lang="en-us"
)

ONNX 모델 파일은 HuggingFace 모델 저장소에서 별도로 다운로드해야 한다.

---

참고 링크

• Kokoro GitHub 공식 저장소
• HuggingFace 모델 페이지 (hexgrad/Kokoro-82M)
• PyPI kokoro 패키지
• HuggingFace 온라인 데모
• espeak-ng 공식 사이트
• PyTorch MPS 가속 문서