저지연(low-latency)의 완전 모듈형 음성 에이전트 파이프라인: VAD -> STT -> LLM -> TTS이며, OpenAI Realtime 호환 WebSocket API를 통해 제공됩니다. 모든 구성 요소는 교체 가능합니다. LLM 슬롯은 OpenAI 호환 프로토콜을 사용하므로, 호스팅된 제공업체, HF Inference Providers, 또는 완전한 로컬 및 오픈 스택을 위해 자체 하드웨어의 vLLM 또는 llama.cpp 서버를 가리킬 수 있습니다.

이 파이프라인은 수천 대의 Reachy Mini 로봇을 위한 대화 백엔드로 프로덕션 환경에서 실행됩니다.

pip install speech-to-speech
export OPENAI_API_KEY=...
speech-to-speech

이는 ws://localhost:8765/v1/realtime에서 OpenAI Realtime 호환 서버를 시작하며,

로컬 STT를 위한 Parakeet TDT, OpenAI 호환 LLM, 그리고 로컬 음성 출력을 위한 Qwen3-TTS를 사용합니다.

소스 체크아웃 상태에서, 두 번째 터미널을 통해 대화해 보세요:

python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765

LLM을 자신의 머신에 유지하고 싶으신가요? llama.cpp로 Gemma 4를 서빙하세요:

llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full

그런 다음 OpenAI 호환 LLM 백엔드를 해당 서버로 지정하세요:

speech-to-speech \
--model_name "ggml-org/gemma-4-E4B-it-GGUF" \
--responses_api_base_url "http://127.0.0.1:8080/v1" \
...

어떠한 OpenAI Realtime 호환 클라이언트도 연결할 수 있습니다. 프로토콜에 대해서는 Realtime API를, 제공업체 및 로컬 서버 옵션에 대해서는 LLM 백엔드를 참조하세요.

• 작동 원리 (How it works)
• 설치 (Installation)
• 지원되는 구성 요소 (Supported components)
• 실행 모드 (Run modes)
• Realtime API
• LLM 백엔드 (LLM backends)
• 다국어 지원 (Multi-language support)
• Pocket TTS
• CLI 레퍼런스 (CLI reference)
• 기여하기 (Contributing)
• Star history
• 인용 (Citations)

이 파이프라인은 각각 자신의 스레드에서 실행되고 큐(queue)로 연결된 4개 구성 요소의 캐스케이드(cascade)입니다:

음성 활동 감지 (Voice Activity Detection, VAD): Silero VAD v5가 음성 경계와 발화 전환 (turn-taking)을 감지합니다.
음성-텍스트 변환 (Speech to Text, STT): 사용자의 발화를 전사하며, 선택적으로 실시간 부분 전사 (live partial transcripts)를 제공합니다.
언어 모델 (Language Model, LLM): 응답을 생성하며, 텍스트와 도구 호출 (tool calls)을 스트리밍합니다.
텍스트-음성 변환 (Text to Speech, TTS): 오디오를 합성하여 클라이언트로 다시 스트리밍합니다.

모든 단계에는 CLI 플래그를 통해 선택할 수 있는 교체 가능한 여러 백엔드 (backends)가 있습니다. 코드는 Transformers 및 Hugging Face Hub를 통해 사용할 수 있는 모델에 중점을 두어 쉽게 수정할 수 있도록 설계되었습니다.

Python 3.10 이상이 필요합니다.

pip install speech-to-speech

기본 설치는 표준 실시간 경로를 포함합니다:

• STT를 위한 Parakeet TDT
• 언어 모델을 위한 OpenAI 호환 API
• 음성 출력을 위한 Qwen3-TTS (macOS가 아닌 플랫폼에서는 기본적으로 GGML 백엔드를 사용하며, Apple Silicon에서는 mlx-audio를 사용함) - 로컬 오디오 및 실시간 서버 모드

macOS 및 non-macOS 종속성은 pyproject.toml의 플랫폼 마커를 통해 자동으로 해결됩니다.

Linux의 경우, Qwen3-TTS GGML 백엔드는 faster-qwen3-tts[ggml]에서 제공됩니다. PyPI의 기본 qwentts-cpp-python 휠 (wheel)은 CUDA 12.8을 대상으로 합니다. 만약 사용자의 기기에 해당 휠이 요구하는 CUDA 12 런타임이 없다면, speech-to-speech를 설치하기 전에 Hugging Face wheelhouse에서 일치하는 휠을 설치하세요:

# CUDA 13.x
pip install "qwentts-cpp-python==0.3.1+cu130" \
-f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu130
...

GGML 대신 이전의 CUDA-graphs 구현을 사용하려면 --qwen3_tts_backend torch를 전달하세요.

추가 백엔드는 pip extras로 설치할 수 있습니다:

pip install "speech-to-speech[kokoro]" # non-macOS에서 Kokoro-82M TTS 사용
pip install "speech-to-speech[pocket]" # Pocket TTS
pip install "speech-to-speech[chattts]" # ChatTTS
...

MeloTTS를 포함하여 더 이상 권장되지 않는 (Deprecated) 구현들은 archive/에 있으며, 더 이상 CLI에 연결되어 있지 않습니다.

DeepFilterNet에 관한 참고 사항: VAD에서 선택적인 오디오 향상 (audio enhancement)을 위해 사용되는 DeepFilterNet은 numpy<2를 필요로 하며,

numpy>=2를 필요로 하는 Pocket TTS와 충돌합니다.

Pocket TTS를 사용하지 않는 환경에서만 수동으로 설치하십시오.

git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
uv sync

이렇게 하면 패키지가 편집 가능 모드 (editable mode)로 설치되며 speech-to-speech CLI를 사용할 수 있게 됩니다.

export OPENAI_API_KEY=...
speech-to-speech

이는 다음 명령과 동일합니다:

speech-to-speech \
--thresh 0.6 \
--stt parakeet-tdt \
...

기본 모델은 OpenAI Responses API를 통한 gpt-5.4-mini입니다. --model_name으로 이를 재정의할 수 있으며, 다른 OpenAI 호환 제공업체나 서버를 위해 --responses_api_base_url을 설정할 수 있습니다.

speech-to-speech --local_mac_optimal_settings

선택적으로 특정 LLM과 함께 사용:

speech-to-speech \
--local_mac_optimal_settings \
--model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

이 설정은 다음과 같습니다:

• --device mps를 추가합니다.

모든 모델에 MPS를 사용합니다. - STT(Speech-to-Text)를 위해 Parakeet TDT를 설정합니다.

• LLM (Large Language Model) 백엔드로 MLX LM을 설정합니다.
• TTS (Text-to-Speech)를 위해 mlx-audio를 사용하는 Qwen3-TTS를 설정하며, 기본적으로 6bit MLX 변형(variant)을 사용합니다. - --mode local을 설정합니다.

macOS에서는 --tts pocket 및 --tts kokoro도 유효합니다.

로컬에서 MLX 양자화 변형(quantization variants)을 비교하려면:

python scripts/benchmark_tts.py \
--handlers qwen3 \
--iterations 3 \
...

WebSocket 모드로 파이프라인을 실행합니다:

speech-to-speech --mode websocket --ws_host 0.0.0.0 --ws_port 8765

클라이언트에서 다음 주소로 연결합니다:

ws://<server-ip>:8765.

16 kHz, int16, mono PCM 형식의 원시 오디오 바이트(raw audio bytes)를 전송하고 생성된 오디오 바이트를 다시 받습니다.

TCP 소켓 모드는 의도적으로 최소한의 기능만 제공합니다. 원시 PCM 오디오를 스트리밍하지만, 중단 처리(interruption handling), 실시간 전사 이벤트(live transcript events), 또는 도구 호출(tool-call) 이벤트를 포함한 전체 Realtime API 기능 세트는 제공하지 않습니다.

서버에서 파이프라인을 실행합니다:

speech-to-speech --mode socket --recv_host 0.0.0.0 --send_host 0.0.0.0

마이크 입력 및 재생을 처리하기 위해 로컬에서 클라이언트를 실행합니다:

python scripts/listen_and_play.py --host <서버의 IP 주소>

NVIDIA Container Toolkit을 설치한 후 다음을 실행합니다:

docker compose up

compose 파일은 Gemma 4를 사용하는 llama.cpp 서버를 시작하고, TCP 소켓 서버를 시작하며, 8080, 12345, 12346 포트를 노출합니다.

Realtime 모드는 OpenAI Realtime 프로토콜을 사용하여 WebSocket을 통해 오디오를 스트리밍하며, 실시간 전사(live transcription) 및 저지연 턴 테이킹(low-latency turn-taking)을 지원합니다. 서버는 /v1/realtime을 노출하며, OpenAI Realtime과 호환되는 모든 클라이언트가 연결할 수 있습니다:

from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8765/v1",
...

서버는 핵심 Realtime 이벤트 세트를 구현합니다: 인바운드(inbound)로는 input_audio_buffer.append, session.update, conversation.item.create, response.create, response.cancel을 지원하며, speech start/stop, 스트리밍 전사(streaming transcription), 오디오 델타(audio deltas), 도구 호출(tool calls), 그리고 response.done을 지원합니다.

아웃바운드(outbound). 전체 이벤트 참조, 아키텍처 및 설계 세부 사항은 Realtime Engine README에 기술되어 있습니다.

LLM은 파이프라인에서 연산 집약도가 가장 높고 지연 시간(latency)이 가장 긴 구성 요소입니다. 대규모 모델을 통한 단일 순전파(forward pass)가 전체 응답 시간을 지배할 수 있으므로, 하드웨어 및 지연 시간 예산에 맞는 적절한 백엔드(backend)를 선택하는 것이 중요합니다. 파이프라인은 다음을 지원합니다:

로컬 추론 (Local inference): CUDA / CPU에서는 transformers를, Apple Silicon에서는 mlx-lm을 사용합니다.
자체 호스팅 서버 (Self-hosted servers): responses-api 및 chat-completions를 사용하여 로컬 vLLM 또는 llama.cpp 서버를 가리킬 수 있습니다.
제공자 API (Provider APIs): 동일한 백엔드가 OpenAI, HF Inference Providers, OpenRouter 및 기타 OpenAI 호환 제공업체와 함께 작동합니다.

두 가지 API 백엔드를 사용할 수 있으며, 동일한 --responses_api_* 연결 플래그를 공유합니다:

--llm_backend responses-api (기본값)는 /v1/responses를 대상으로 합니다.
--llm_backend chat-completions는 /v1/chat/completions를 대상으로 합니다.

아래 예제는 로컬 STT를 위한 Parakeet TDT와 로컬 TTS를 위한 Qwen3-TTS를 서로 다른 LLM 백엔드와 결합하여 보여줍니다.

OpenAI Responses API를 구현하는 모든 제공업체 또는 서버와 함께 작동합니다. --responses_api_base_url을 엔드포인트로 지정하고 --model_name을 그에 맞게 설정하십시오:

# OpenAI
speech-to-speech \
--mode local \
...

# HF Inference Providers: Together를 통한 Qwen3.5-9B
speech-to-speech \
--mode local \
...

# HF Inference Providers: Groq를 통한 GPT-oss-20B
speech-to-speech \
--stt parakeet-tdt \
...

responses-api와 동일한 구성이며, 동일한 --responses_api_*를 재사용합니다.

연결 플래그 (connection flags)를 사용하지만, /v1/responses 대신 /v1/chat/completions와 통신합니다.

다음과 같은 경우에 이 방식을 권장합니다:

• 제공업체가 Responses 경로에서 chat_template_kwargs.enable_thinking을 무시하며, 추론 (reasoning)을 억제하기 위한 reasoning_effort 조절 노브 (knob)가 필요한 경우
• 서버의 Responses 스트리밍 도구 호출 (tool-call) 경로가 불안정한 반면, Chat Completions의 도구 호출 스트리밍은 안정적인 경우. 이는 일부 vLLM 빌드에서 유용합니다; #312를 참조하세요.

채팅 템플릿 (chat-template) 플래그가 효과가 없는 제공업체에서 추론을 비활성화하려면 --responses_api_reasoning_effort none을 추가하세요:

# 도구 호출 (tool calling) 기능이 있는 Qwen 모델을 서빙하는 vLLM
speech-to-speech \
--mode realtime \
...

# 낮은 음성 지연 시간 (voice latency)을 위해 추론을 비활성화한 상태로 Cerebras의 HF 라우터를 통해 Gemma 4 31B 사용
speech-to-speech \
--mode realtime \
...

Reachy Mini 로컬 대화 가이드에 나와 있는 것처럼, 마찰이 가장 적은 완전 로컬 설정을 위해 LLM을 별도의 llama.cpp 프로세스에서 실행하세요:

# 터미널 1: Gemma 4를 서빙하는 llama.cpp
lama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full

# 터미널 2: 해당 로컬 LLM 서버를 사용하는 speech-to-speech
speech-to-speech \
--mode realtime \
...

서버를 실행 중인 기기를 통해 직접 대화하고 싶을 때는 --mode realtime 대신 --mode local을 사용할 수 있습니다. 프로세스 내 (In-process) 로컬 백엔드는 Apple Silicon에서는 --llm_backend mlx-lm으로, CUDA / CPU에서는 --llm_backend transformers로 여전히 사용 가능합니다.

언어 지원 범위는 파이프라인 자체가 아니라 선택한 STT 및 TTS 백엔드에 따라 달라집니다:

페어링하는 STT, LLM, TTS가 모두 대상 언어를 지원하는지 확인하세요. 두 가지 사용 패턴이 있습니다:

단일 언어: --language를 대상 언어 코드로 설정합니다. 기본값은 en입니다.
언어 전환 (Language switching): --language auto로 설정합니다. STT가 각 음성 프롬프트의 언어를 감지하여 LLM으로 전달합니다. 선택 사항으로 --enable_lang_prompt를 추가할 수 있습니다.

..."Please reply to my message in ..."라는 지시어를 추가합니다. 기본값은 False입니다.

; 대규모 LLM은 보통 문맥으로부터 언어를 추론하지만, 명시적인 지시어는 더 작은 모델들에게 도움이 될 수 있습니다.

자동 언어 감지 (Automatic language detection):

speech-to-speech \
--stt parakeet-tdt \
--language auto \
...

단일 비영어 언어 설정, 이 예시에서는 중국어:

speech-to-speech \
--stt whisper-mlx \
--stt_model_name large-v3 \
...

두 명령 모두 --local_mac_optimal_settings 위에서도 작동합니다.

; 명시적인 --stt 플래그는 해당 설정이 지정하는 기본값을 무시(override)합니다.

Kyutai Labs의 Pocket TTS는 음성 복제 (voice cloning) 기능이 포함된 스트리밍 TTS를 제공합니다:

speech-to-speech \
--tts pocket \
--pocket_tts_voice jean \
...

사용 가능한 음성 프리셋 (voice presets): alba, marius, javert, jean, fantine, cosette, eponine, azelma. 커스텀 음성 파일 및 Hugging Face 경로도 사용할 수 있습니다.