Kyutai Pocket TTS — CPU에서 실행되는 스트리밍 음성 합성

Kyutai의 Pocket TTS는 GPU나 외부 TTS API 없이 CPU에서 실행하도록 설계한 Python 음성 합성 패키지다. 작은 FlowLM 텍스트·음성 생성 모델과 Mimi 오디오 코덱을 묶어 24kHz 오디오를 스트리밍하고, 사전 정의 음성·로컬/원격 참조 오디오 기반 음성 복제·다국어 설정·CLI·FastAPI 서버를 제공한다.

개요

프로젝트 성격: MIT 라이선스의 Python 패키지/CLI. 저장소 설명은 “A TTS that fits in your CPU (and pocket)”이며, README는 GPU 버전 PyTorch 없이 CPU에서 실행된다고 설명한다.
모델 규모: README가 약 100M parameters라고 제시한다. 이 수치를 별도로 파라미터 카운트해 검증하지는 않았다.
출력: 기본 Mimi 설정은 1채널, 24,000Hz, 12.5Hz latent frame rate다. TTSModel.sample_rate는 설정의 Mimi sample rate를 반환한다.
생성 형태: 전체 오디오를 반환하는 generate_audio()와 디코드되는 청크를 순차적으로 내보내는 generate_audio_stream()을 모두 제공한다.
지원 언어: 영어, 프랑스어, 독일어, 포르투갈어, 이탈리아어, 스페인어 설정이 있고, 일부 언어에는 24l(24-layer) preview 설정이 있다.
저장소 README 주장: 첫 오디오 청크까지 약 200ms, MacBook Air M4 CPU에서 약 6× real-time, 2 CPU cores 사용, 무한히 긴 입력 처리 등을 주요 특징으로 제시한다. 이 지표와 동작은 이번 ingest에서 재실행하지 않았다.

구조 — FlowLM + Mimi

고정 커밋의 TTSModel은 두 모델을 하나의 추론 흐름으로 조합한다.

텍스트를 SentencePiece tokenizer로 토큰화하고 FlowLM conditioner에 넣는다.
FlowLM transformer가 텍스트 조건과 음성 prompt를 이용해 오디오 latent를 autoregressive하게 생성한다. temperature, LSD decode steps, noise clamp, EOS threshold가 생성 파라미터다.
생성 latent를 Mimi quantizer/decoder로 변환한다.
latent 생성 스레드와 Mimi 디코더 스레드를 queue로 연결해 디코드되는 오디오 청크를 즉시 yield한다.
StreamingWAVWriter가 청크를 mono 16-bit PCM WAV로 기록하며, 종료 시 재생 안정성을 위해 200ms silence를 추가한다.

기본 english.yaml과 english_2026-04.yaml은 FlowLM transformer 6 layers, d_model=1024, 16 heads를 사용한다. french_24l.yaml과 german_24l.yaml 같은 preview 구성은 24 layers다. Mimi의 기본 설정은 SEANet encoder/decoder와 2-layer projected transformer를 사용한다.

텍스트 분할과 스트리밍

기본 MAX_TOKEN_PER_CHUNK는 50이다.
문장 부호(., !, ?)를 우선 경계로 사용하고, 너무 긴 문장은 쉼표·세미콜론·콜론으로 재분할한다.
짧은 입력에는 모델별 설정에 따라 공백 padding을 적용할 수 있다.
입력은 대문자로 시작하고 알phanumeric 문자로 끝나면 마침표를 붙이는 전처리를 거친다.
구현 주석은 긴 텍스트를 현재 단순 chunking으로 처리하며, 이전 청크 오디오를 teacher forcing하는 방식은 TODO라고 설명한다. 따라서 README의 “infinitely long”은 저장소가 제시하는 사용 방향이지, 이번 환경에서 검증한 무한 입력 보장이 아니다.
generate_audio_stream()은 thread-safe하지 않다고 문서화되어 있어 동시 생성에는 별도 model instance가 필요하다.

음성 prompt와 voice cloning

get_state_for_audio_prompt()는 참조 오디오를 Mimi로 인코딩하고 FlowLM speaker projection을 거쳐 KV cache 성격의 model state를 만든다. 이 상태를 여러 텍스트 생성에 재사용할 수 있다.

지원 입력 경로는 다음과 같다.

미리 정의된 voice 이름: alba, cosette, marius, javert, anna, vera 등
로컬 오디오 파일 또는 torch.Tensor
http://·https:// URL
hf:// Hugging Face 경로
export-voice로 저장한 .safetensors 상태 파일

참조 오디오는 설정의 sample rate로 resample되고, truncate=True일 때 처음 30초로 잘린다. 음성 prompt 상태는 export_model_state()로 safetensors에 저장할 수 있으며, 이후에는 오디오를 다시 인코딩하지 않고 상태를 읽어 빠르게 재사용하는 경로가 제공된다.

고정 커밋의 코드에는 두 가지 모델-weight 경로가 있다.

기본 pocket-tts 모델: voice cloning weight 경로
pocket-tts-without-voice-cloning fallback: voice cloning weight를 받지 못할 때 사용하는 경로

코드는 voice cloning weight를 다운로드하지 못한 상태에서 custom audio를 사용하면 Hugging Face 모델 카드의 약관 동의와 uvx hf auth login이 필요하다고 안내한다. 따라서 README의 voice cloning 지원은 모든 환경에서 무조건 인증 없이 동작한다는 뜻이 아니다. 사전 계산된 catalog voice는 별도의 Hugging Face voice/state 경로를 사용한다.

Python API

from pocket_tts import TTSModel
import scipy.io.wavfile
 
model = TTSModel.load_model()
voice_state = model.get_state_for_audio_prompt("alba")
audio = model.generate_audio(voice_state, "Hello world, this is a test.")
scipy.io.wavfile.write("output.wav", model.sample_rate, audio.numpy())

공개 API는 다음 네 가지 축으로 정리된다.

TTSModel.load_model() — 언어 또는 로컬 YAML config를 읽고 Hugging Face weight를 로드
get_state_for_audio_prompt() — voice/audio conditioning을 model state로 변환
generate_audio() — 전체 오디오 tensor 반환
generate_audio_stream() — 청크 단위 생성
export_model_state() — voice conditioning state를 safetensors로 저장

load_model()은 language와 config를 동시에 받지 않으며, 둘 다 없으면 english를 기본값으로 사용한다. 기본 English config는 고정 커밋에서 temperature 0.3을 권장값으로 지정한다. 이 값은 이번 fixed commit의 변경 커밋 메시지와 config에 함께 기록되어 있다.

CLI와 로컬 서버

`generate`

uvx pocket-tts generate --text "Hello world" --output-path ./tts_output.wav
# 또는 pip/uv로 설치한 뒤
pocket-tts generate --text "Hello world" --voice alba

--language, --voice, --config, --temperature, --lsd-decode-steps, --eos-threshold, --frames-after-eos, --max-tokens, --device, --quantize를 지원한다. --text -는 stdin을 읽고, --output-path -는 WAV를 stdout으로 스트리밍한다.

`serve`

uvx pocket-tts serve

FastAPI/uvicorn 서버를 localhost:8000에 띄우고 브라우저 UI를 제공한다. 소스에 확인되는 endpoint는 다음과 같다.

GET / — 정적 웹 UI
GET /health — { "status": "healthy" }
POST /tts — text form field와 voice_url 또는 업로드 voice_wav를 받아 audio/wav chunked response 반환

서버는 모델을 전역으로 한 번 로드하고 요청마다 voice state를 선택한다. voice_url과 voice_wav는 상호 배타적이며, 둘 다 없으면 언어별 기본 voice를 선택한다. HTTP endpoint의 CORS 허용 origin은 소스에 명시적으로 제한되어 있다.

`export-voice`

pocket-tts export-voice voice.wav voice.safetensors
pocket-tts generate --voice voice.safetensors --text "Hello"

오디오를 voice embedding이라고 부르지만 구현상 저장하는 것은 생성에 재사용하는 KV-cache 성격의 state다. 문서와 CLI는 오디오의 처음 30초만 처리한다고 설명한다.

동적 int8 양자화

TTSModel.load_model(quantize=True) 또는 CLI --quantize는 FlowLM의 attention과 FFN linear layer에 dynamic int8 quantization을 적용한다.

torchao가 작동하면 torchao backend를 사용한다.
그렇지 않으면 torch.ao.quantization fallback을 사용한다.
flow matching network와 Mimi VAE decoder는 float32로 남는다.
README/API docstring과 quantization 문서는 x86 FBGEMM에서 runtime memory 약 48% 감소, inference speed 약 27% 향상, WER 변화 없음이라고 기술한다.
저장소에는 quantized model이 silence/NaN이 아닌 audio를 내는지, CLI flag가 동작하는지 확인하는 테스트가 있으나 이 ingest에서 실제 실행하지 않았다.

설치·의존성

pyproject.toml 기준 요구사항은 다음과 같다.

Python >=3.10,<3.15
torch>=2.5.0 및 CPU PyTorch index 설정
numpy, pydantic, sentencepiece, beartype, safetensors
typer, fastapi, uvicorn, python-multipart, scipy, einops
huggingface_hub, requests
optional soundfile — WAV 이외 오디오 포맷
optional torchao — 최적화된 quantization backend

패키지 entry point는 pocket-tts = pocket_tts.main:cli_app다. 소스는 import 시 torch.set_num_threads(1)을 호출하므로 README의 “2 CPU cores” 성능 주장과 실제 실행 환경의 thread/BLAS 설정은 별도로 측정해야 한다.

공식 확인과 해석의 분리

고정 커밋의 공식 문서·소스에서 확인한 내용

CPU 중심 실행, Python API/CLI/FastAPI server 구조
FlowLM + Mimi 기반 모델 조합과 24kHz 기본 오디오 설정
streaming generation, voice state cache/export, multilingual config
Hugging Face weight/voice 다운로드 경로와 voice cloning fallback
torchao/torch.ao dynamic int8 양자화 분기
README가 제시하는 100M parameter, 200ms first chunk, 약 6× M4 CPU 등의 수치
음성 사칭·동의 없는 voice cloning·기만적/불법 콘텐츠를 금지하는 README의 prohibited-use 문구

사용자 제공 정보

사용자는 https://github.com/kyutai-labs/pocket-tts 저장과 위키 정리만 요청했다.
기능, 성능, 라이선스에 대한 별도 사용자 주장은 제공되지 않았다.

이 노트의 해석

Pocket TTS의 핵심 위치는 대규모 GPU TTS 서버라기보다, 작은 로컬 CPU runtime에 streaming·voice state 재사용·단순한 HTTP adapter를 결합한 edge/on-device TTS에 가깝다. TTSModel이 model loading, voice conditioning, latent generation, Mimi decoding을 하나의 Python object로 감싸므로 애플리케이션에 직접 삽입하기 쉽다. 반대로 모델 weight·voice 파일은 외부 Hugging Face 상태와 약관에 의존하고, 긴 입력 chunking과 동시성은 별도 운영 설계가 필요하다.

GitHub fixed snapshot

GitHub REST API, main ref, git ls-remote, commit-pinned raw files를 2026-08-08 KST에 확인했다.

Repository: kyutai-labs/pocket-tts
Stars: 8,129 · forks: 825 · open issues: 75
Language: Python · license metadata: MIT · archived: false
Default branch: main
Fixed commit: d108410d23eef7e01db282f9442891162dbc3db6
Commit message: Default the English model's temperature to 0.3 (#223)
Commit date: 2026-07-16T12:42:04Z
README: 16,127 bytes
README download-byte SHA-256: 0505e9dbd4909421bbf131b28576e9e656385e7edd447d31fac075ce51518e17
Raw provenance body SHA-256: 9232d19879306818c0480af740c41ccbfffafb1cee33f754bee2e787db128641

아직 검증하지 않은 것

이번 노트는 고정 커밋의 GitHub metadata, recursive tree, README, API/CLI docs, package metadata, selected implementation/config/test files를 읽고 다운로드 바이트 hash를 계산해 작성했다. 다음은 실행하지 않았다.

pip install, uvx, dependency resolution, package build, import smoke test
Hugging Face model/voice weight 다운로드 및 인증
TTSModel.load_model(), audio generation, streaming output, WAV 품질·샘플레이트 실측
pocket-tts generate, serve, export-voice CLI 실행
FastAPI /health·/tts 서버 실행과 브라우저 UI 확인
torchao/torch.ao 실제 양자화 및 memory/speed/WER 측정
pytest, documentation examples, custom voice cloning, long-text behavior
README의 100M parameters·200ms·6× real-time·2 CPU cores 수치 재현
독립적인 모델 안전성·voice provenance·라이선스 적합성 감사

따라서 이 문서에서 “지원한다”는 표현은 해당 fixed commit의 문서·소스가 해당 경로를 정의한다는 뜻이며, 이 환경에서 설치·실행 성공을 재현했다는 뜻이 아니다.

출처 및 provenance

공식 저장소: kyutai-labs/pocket-tts
고정 커밋: d108410
README pinned raw: README.md
Python API: docs/API Reference/python-api.md
CLI docs: generate · serve · export-voice
모델 카드: kyutai/pocket-tts
음성 저장소: kyutai/tts-voices
Raw provenance: raw source: github-kyutai-labs-pocket-tts

description	CPU에서 실행되는 100M 파라미터·24kHz 스트리밍·음성 복제를 지원하는 Kyutai의 Python TTS.
tags	ai-models, tts, voice-ai, python, open-source
aliases	Pocket TTS, Kyutai Pocket TTS

LLM Wiki

탐색기