huggingface/speech-to-speech

개요

speech‑to‑speech 는 클라우드 API 키 없이 완전한 음성 어시스턴트를 로컬에서 실행할 수 있는 오픈소스 Python 패키지입니다. 음성 활동 감지, 음성-텍스트 변환, 언어 모델, 텍스트-음성 변환의 네 단계를 연결하며, 각 단계는 대체 모델로 교체할 수 있습니다. 기본 파이프라인은 Silero VAD, 전사를 위한 Parakeet TDT, Qwen‑3.5‑4B LLM, 오디오 출력을 위한 Qwen‑3 TTS를 사용합니다.

작동 방식

VAD – 말하기 시작과 끝을 감지하여 시스템이 언제 들어야 할지 결정합니다.
STT – 음성 턴을 텍스트로 변환합니다 (Parakeet, Whisper, Faster‑Whisper 등 많은 백엔드 지원).
LLM – 텍스트 응답을 생성하며 토큰과 선택적 도구 호출을 스트리밍합니다.
TTS – LLM의 응답을 음성으로 변환합니다 (기본 Qwen‑3‑TTS, 다양한 선택적 TTS 모델).

각 구성 요소는 자체 스레드에서 실행되고 큐를 통해 통신하므로, 어떤 부분이든 다른 모델이나 원격 서비스로 쉽게 교체할 수 있습니다.

주요 기능

완전 로컬 첫 실행 후 (인터넷 불필요).
OpenAI Realtime 프로토콜 호환 – 서버가 OpenAI의 Realtime 서비스와 동일한 WebSocket/WebRTC API를 사용하므로 기존 클라이언트를 자신의 머신에 연결할 수 있습니다.
크로스 플랫폼 지원: Apple Silicon (MLX 기반 모델), NVIDIA GPU (CUDA), 또는 CPU 전용 폴백.
확장 가능 – VAD, STT, LLM, TTS용 수십 개의 선택적 백엔드를 pip 엑스트라로 설치할 수 있습니다.
CLI 명령:
- speech-to-speech local – 서버와 마이크 클라이언트를 함께 실행.
- speech-to-speech serve – Realtime 서버만 시작.
- speech-to-speech talk – 패키지된 마이크/스피커 클라이언트를 임의 서버에 대해 실행.
Docker 지원으로 컨테이너화된 빠른 배포 가능.
선택적 비젬(viseme) 출력 아바타 입 모양 애니메이션용.

시작하기 (빠른 요약)

python3 -m venv .venv && source .venv/bin/activate
pip install speech-to-speech
speech-to-speech local   # 스피커와 마이크로 대화합니다

첫 실행 시 필요한 모델을 다운로드하고, 이후는 오프라인으로 작동합니다.

사용 대상

로보틱스 개발자 음성 지원 로봇 구축 (예: Reachy Mini 로봇은 이미 이 파이프라인 사용).
앱 개발자 클라우드 서비스 비용 없이 드롭인 음성 어시스턴트를 원하는 분.
연구자 모듈식 프레임워크에서 다양한 STT/LLM/TTS 조합을 실험하는 분.
프라이버시 중시 사용자 기기를 벗어나지 않는 음성 어시스턴트가 필요한 분.

알아둘 제한 사항

실시간 성능은 하드웨어에 따라 다릅니다. CPU 전용 머신에서는 LLM이 느릴 수 있습니다.
일부 선택적 구성 요소(예: DeepFilterNet)는 버전 충돌이 있어 수동 설치가 필요합니다.
서버는 인증을 강제하지 않습니다. 신뢰할 수 있는 네트워크 밖에 노출하는 경우 외부 게이트웨이가 필요합니다.

요약: speech‑to‑speech 는 OpenAI의 Realtime API를 모방하면서 선호하는 오픈소스 VAD, 음성 인식, 언어 모델, TTS 구성 요소를 원하는 대로 교체할 수 있는 즉시 실행 가능한 로컬 호스팅 음성 어시스턴트 스택을 제공합니다.