F5-TTS 설치 및 사용 가이드 (Mac)

개요

이 가이드는 Mac(Apple Silicon, M1~M4) 환경에서 F5-TTS를 설치하고 사용하는 방법을 다룬다. Apple Silicon Mac에서는 두 가지 접근 방식을 사용할 수 있다.

f5-tts-mlx (권장): Apple의 MLX 프레임워크 기반으로 Metal GPU를 완전 활용. Apple Silicon에 최적화된 구현체.
f5-tts (공식 PyTorch): PyTorch MPS 백엔드를 통한 공식 구현. 호환성이 넓고 원본과 동일한 기능 제공.

사전 요구사항

macOS: Ventura(13) 이상 권장
Python: 3.10 이상 (3.11 권장)
RAM: 최소 8GB, 16GB 이상 권장
저장공간: 기본 모델 약 2GB, 전체 환경 포함 시 5GB 이상
Homebrew: ffmpeg 설치를 위해 필요
Conda 또는 venv: 가상환경 관리 권장

설치 방법

방법 1: f5-tts-mlx (Apple Silicon 권장)

MLX 프레임워크를 사용하는 Apple Silicon 전용 최적화 구현이다. M3 Max MacBook Pro 기준 약 4초 내에 음성 생성이 가능하다.

1# 가상환경 생성 및 활성화2python -m venv f5-tts-env3source f5-tts-env/bin/activate4 5# f5-tts-mlx 설치6pip install f5-tts-mlx7 8# ffmpeg 설치 (오디오 처리에 필요)9brew install ffmpeg

방법 2: 공식 f5-tts (PyTorch MPS)

공식 구현체를 Mac PyTorch 환경에서 실행하는 방법이다.

1# Conda 가상환경 생성 (Python 3.11 권장)2conda create -n f5-tts python=3.113conda activate f5-tts4 5# ffmpeg 설치6conda install ffmpeg7 8# PyTorch 설치 (Mac용 — CPU/MPS 지원)9pip install torch torchaudio10 11# f5-tts 설치12pip install f5-tts

훈련이나 파인튜닝이 필요한 경우 소스 코드에서 설치한다.

1git clone https://github.com/SWivid/F5-TTS.git2cd F5-TTS3pip install -e .

Apple Silicon MPS 설정

PyTorch는 macOS 12.3 이상에서 MPS(Metal Performance Shaders) 백엔드를 지원한다. 공식 f5-tts는 실행 시 자동으로 MPS 장치를 감지하므로 별도 설정 없이 GPU 가속이 적용된다.

MPS 사용 여부를 Python에서 직접 확인하는 방법:

1import torch2 3if torch.backends.mps.is_available():4    device = torch.device("mps")5    print("MPS 사용 가능 — Apple Silicon GPU 가속 활성화")6elif torch.cuda.is_available():7    device = torch.device("cuda")8else:9    device = torch.device("cpu")10    print("CPU 모드로 실행 (느릴 수 있음)")11 12print(f"사용 장치: {device}")

기본 TTS 사용법

f5-tts-mlx 사용

1# 기본 텍스트 음성 변환2python -m f5_tts_mlx.generate \3  --text "안녕하세요, F5-TTS로 생성한 음성입니다."4 5# 출력 파일 지정6python -m f5_tts_mlx.generate \7  --text "Hello, this is a test." \8  --output output.wav9 10# 메모리 절약을 위한 4비트 양자화 모드11python -m f5_tts_mlx.generate \12  --text "Hello world." \13  --q 4

공식 f5-tts CLI 사용

1# 기본 실행 (내장 기본 설정 사용)2f5-tts_infer-cli3 4# Gradio 웹 UI 실행 (브라우저에서 http://127.0.0.1:7860 접속)5f5-tts_infer-gradio6 7# 커스텀 설정 파일 사용8f5-tts_infer-cli -c custom.toml

제로샷 음성 복제

3~10초 분량의 참조 오디오를 제공하면 해당 화자의 음색으로 새로운 텍스트를 음성 합성한다.

참조 오디오 전처리

ffmpeg를 사용하여 참조 오디오를 F5-TTS 입력 형식(모노, 24kHz)으로 변환한다.

1ffmpeg -i input_audio.wav \2  -ac 1 \3  -ar 24000 \4  -sample_fmt s16 \5  -t 10 \6  reference.wav

f5-tts-mlx로 음성 복제

1python -m f5_tts_mlx.generate \2  --text "복제된 목소리로 말할 텍스트" \3  --ref-audio reference.wav \4  --ref-text "참조 오디오에서 실제로 말하는 내용"

공식 f5-tts CLI로 음성 복제

1f5-tts_infer-cli \2  --model F5TTS_v1_Base \3  --ref_audio reference.wav \4  --ref_text "참조 오디오에서 실제로 말하는 내용" \5  --gen_text "생성할 새로운 텍스트"

Python API로 음성 복제 (f5-tts-mlx)

1from f5_tts_mlx.generate import generate2import soundfile as sf3 4audio = generate(5    text="복제된 목소리로 합성할 텍스트입니다.",6    ref_audio_path="reference.wav",7    ref_audio_text="참조 오디오에서 말하는 내용",8)9 10sf.write("output.wav", audio, samplerate=24000)11print("음성 생성 완료: output.wav")

CLI 사용법 (공식 f5-tts 심화)

멀티 스피커 (다중 화자) 생성

여러 화자의 음성을 한 번에 생성하는 멀티 스피커 모드:

1f5-tts_infer-cli \2  -c src/f5_tts/infer/examples/multi/story.toml

모델 선택

F5-TTS는 두 가지 모델 아키텍처를 제공한다.

1# F5-TTS (DiT + ConvNeXt V2 기반, 기본값 — 권장)2f5-tts_infer-cli --model F5TTS_v1_Base3 4# E2-TTS (Flat-UNet Transformer 기반, 원본 논문 재현)5f5-tts_infer-cli --model E2TTS_Base

자주 발생하는 오류 해결

ImportError: No module named 'xxx'

필수 패키지가 누락된 경우다. 가상환경이 활성화되어 있는지 확인하고 재설치한다.

1# 가상환경 확인2which python  # f5-tts-env 경로가 표시되어야 함3 4# 재설치5pip install --upgrade f5-tts-mlx6# 또는7pip install --upgrade f5-tts

MPS 관련 오류 (RuntimeError: MPS backend out of memory)

MPS 메모리 부족 오류 발생 시 양자화 모드를 사용하거나 배치 크기를 줄인다.

1# 4비트 양자화로 메모리 사용량 대폭 절감2python -m f5_tts_mlx.generate --text "텍스트" --q 43 4# 8비트 양자화 (품질과 메모리 균형)5python -m f5_tts_mlx.generate --text "텍스트" --q 8

ffmpeg 관련 오류 (FileNotFoundError: ffmpeg not found)

ffmpeg가 설치되지 않은 경우다.

1brew install ffmpeg2 3# 설치 확인4ffmpeg -version

모델 다운로드 실패 (ConnectionError / TimeoutError)

모델 가중치는 Hugging Face에서 자동 다운로드된다. 네트워크 문제 발생 시 수동 다운로드를 시도한다.

1# Hugging Face CLI로 수동 다운로드2pip install huggingface_hub3huggingface-cli download SWivid/F5-TTS --local-dir ./models

boto3/botocore 반복 다운로드 오류 (Apple Silicon)

Apple Silicon에서 boto3 관련 루프 오류 발생 시:

1pip install --upgrade boto3 botocore2pip cache purge3pip install f5-tts

개요