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로 설치한다.

1brew install espeak-ng

설치 확인:

1espeak-ng --version

2단계: Python 가상환경 생성

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

1python3 -m venv kokoro-env2source kokoro-env/bin/activate

3단계: kokoro 패키지 설치

1pip install kokoro>=0.9.4 soundfile

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

1pip install sounddevice

4단계: PyTorch 설치 확인

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

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

Apple Silicon MPS 설정

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

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

1PYTORCH_ENABLE_MPS_FALLBACK=1 python my_tts_script.py

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

1import os2os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"3 4import torch5from kokoro import KPipeline6 7# MPS 디바이스 지정8device = "mps" if torch.backends.mps.is_available() else "cpu"9pipeline = KPipeline(lang_code='a', device=device)

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

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

기본 TTS 사용법

텍스트를 음성 파일로 저장

1import soundfile as sf2from kokoro import KPipeline3 4# 미국 영어 파이프라인 초기화5pipeline = KPipeline(lang_code='a')6 7text = "Hello! This is a test of the Kokoro TTS model running on a Mac."8 9# 음성 생성 (generator 방식)10generator = pipeline(text, voice='af_heart', speed=1.0)11 12for i, (graphemes, phonemes, audio) in enumerate(generator):13    sf.write(f'output_{i}.wav', audio, 24000)14    print(f"Segment {i} saved: {graphemes[:30]}...")15 16print("TTS 생성 완료!")

한국어 음성 생성

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

실시간 재생 (sounddevice 사용)

1import sounddevice as sd2import numpy as np3from kokoro import KPipeline4 5pipeline = KPipeline(lang_code='a')6text = "Kokoro TTS is running on Apple Silicon with MPS acceleration."7 8for _, _, audio in pipeline(text, voice='af_heart'):9    sd.play(audio, samplerate=24000)10    sd.wait()  # 재생 완료까지 대기

음성 선택 및 커스터마이징

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

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

영국 영어 음성 예시

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

재생 속도 조절

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

1# 느리게 (0.8배)2generator = pipeline(text, voice='af_heart', speed=0.8)3 4# 빠르게 (1.3배)5generator = pipeline(text, voice='af_heart', speed=1.3)

음성 혼합(Voice Blending)

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

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

자주 발생하는 오류 해결

오류 1: `espeak-ng` 관련 오류

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

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

1brew install espeak-ng

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

1which espeak-ng2# 출력 예: /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에서 실행한다.

1PYTORCH_ENABLE_MPS_FALLBACK=1 python my_script.py

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

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

1source kokoro-env/bin/activate2pip install kokoro>=0.9.4

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

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

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

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

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

1# HuggingFace CLI로 수동 다운로드2pip install huggingface_hub3huggingface-cli download hexgrad/Kokoro-82M

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

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

1pip install kokoro-onnx sounddevice onnxruntime

1from kokoro_onnx import Kokoro2 3kokoro = Kokoro("kokoro-v0_19.onnx", "voices.bin")4samples, sample_rate = kokoro.create(5    "Hello from Kokoro ONNX!",6    voice="af_bella",7    speed=1.0,8    lang="en-us"9)

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

개요

사전 요구사항

설치 방법

1단계: Homebrew로 espeak-ng 설치

2단계: Python 가상환경 생성

3단계: kokoro 패키지 설치

4단계: PyTorch 설치 확인

Apple Silicon MPS 설정

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

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

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

기본 TTS 사용법

텍스트를 음성 파일로 저장

한국어 음성 생성

실시간 재생 (sounddevice 사용)

음성 선택 및 커스터마이징

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

영국 영어 음성 예시

재생 속도 조절

음성 혼합(Voice Blending)

자주 발생하는 오류 해결

오류 1: `espeak-ng` 관련 오류

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

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

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

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

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

참고 링크

댓글

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

개요

사전 요구사항

설치 방법

1단계: Homebrew로 espeak-ng 설치

2단계: Python 가상환경 생성

3단계: kokoro 패키지 설치

4단계: PyTorch 설치 확인

Apple Silicon MPS 설정

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

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

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

기본 TTS 사용법

텍스트를 음성 파일로 저장

한국어 음성 생성

실시간 재생 (sounddevice 사용)

음성 선택 및 커스터마이징

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

영국 영어 음성 예시

재생 속도 조절

음성 혼합(Voice Blending)

자주 발생하는 오류 해결

오류 1: espeak-ng 관련 오류

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

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

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

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

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

참고 링크

댓글

오류 1: `espeak-ng` 관련 오류

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