Speech To Speech: framework voice agent mã nguồn mở
/speech-to-speech
Speech To Speech là framework Python của Hugging Face, gắn kết bốn khối voice activity detection, speech-to-text, một LLM và text-to-speech thành một voice agent độ trễ thấp, nói theo giao thức WebSocket OpenAI Realtime. Nên dùng nếu bạn muốn một pipeline chạy local hoặc tự host, ghép từ các thành phần có thể thay thế cho nhau; nên bỏ qua nếu chỉ cần một bản demo giọng nói chạy trong năm phút mà không muốn chọn wheel CUDA cho backend TTS.
Speech To Speech Pipeline Là Gì?
Speech To Speech là một pipeline voice agent mã nguồn mở, xây quanh bốn giai đoạn có thể thay thế — voice activity detection, speech-to-text, một language model, và text-to-speech — mỗi giai đoạn chạy trên một thread riêng, nối với nhau qua queue. Toàn bộ chuỗi được expose qua một WebSocket API tương thích OpenAI Realtime, nên client viết cho giao thức Realtime gốc của OpenAI kết nối vào được mà không cần lớp transport riêng.
Các Tính Năng Chính
- ✓Chuỗi VAD -> STT -> LLM -> TTS, mỗi giai đoạn chạy trên một thread riêng và chuyển audio/text qua nhau bằng queue, với Silero VAD v5 xử lý việc nhận biết lượt nói.
- ✓WebSocket API tương thích OpenAI Realtime tại /v1/realtime, hỗ trợ cả WebSocket lẫn WebRTC nên các client Realtime có sẵn kết nối được mà không cần sửa gì.
- ✓Sáu backend STT để chọn qua flag --stt, gồm Parakeet TDT (mặc định), Whisper, Faster Whisper, Lightning Whisper MLX, MLX Audio Whisper và Paraformer.
- ✓Năm backend TTS qua flag --tts: Qwen3-TTS (mặc định), Kokoro-82M, Pocket TTS, ChatTTS và MMS TTS, với giá trị mặc định khác nhau giữa macOS và Linux/CUDA.
- ✓Phần LLM nói giao thức responses-api hoặc chat-completions của OpenAI, nên có thể trỏ vào OpenAI, HF Inference Providers, OpenRouter, hoặc một server vLLM/llama.cpp tự host.
- ✓Bốn chế độ chạy — realtime, local (micro và loa), raw-websocket, và socket (TCP) — phù hợp từ client WebRTC cho tới cặp micro/loa trần.
- ✓Flag tùy chọn --enable_llm_proxy expose LLM đang cấu hình thành một endpoint tương thích OpenAI thuần túy, để client chạy tóm tắt hay agent nền song song với phiên hội thoại giọng nói đang diễn ra.
- ✓Chế độ nhập audio trực tiếp (--stt none --llm_backend chat-completions) bỏ qua STT hoàn toàn, đưa thẳng audio đã cắt đoạn bởi VAD tới một model nhận audio đầu vào.
Các Trường Hợp Sử Dụng Điển Hình
- •Chạy một voice agent hoàn toàn offline bằng cách ghép STT và TTS local với một LLM chạy qua llama.cpp hoặc vLLM trên máy của bạn.
- •Thêm lớp hội thoại bằng giọng nói cho robot hoặc thiết bị nhúng — README nói pipeline này là backend hội thoại chạy production cho robot Reachy Mini.
- •Thử nghiệm với giao thức OpenAI Realtime mà không phải trả tiền cho model Realtime được host bởi OpenAI.
- •Chạy các tác vụ LLM nền, như tóm tắt hay đặt tiêu đề, song song với một phiên hội thoại giọng nói đang diễn ra, qua endpoint LLM proxy.
- •Đo độ trễ và chất lượng của các backend TTS ngay tại máy bằng script benchmark_tts.py có sẵn, trước khi chọn cấu hình mặc định.
Hướng Dẫn Cài Đặt
Speech To Speech cần Python 3.10 trở lên. Cài đặt cơ bản là `pip install speech-to-speech`, kéo theo Parakeet TDT cho STT, đường API tương thích OpenAI cho LLM, và Qwen3-TTS cho đầu ra giọng nói — dùng GGML trên các nền tảng không phải macOS, mlx-audio trên Apple Silicon, được chọn tự động qua platform marker trong pyproject.toml. Trên Linux, wheel mặc định của backend Qwen3-TTS GGML nhắm tới CUDA 12.8; nếu CUDA runtime trên máy bạn khác, cần cài một wheel `qwentts-cpp-python` cụ thể (CUDA 13.x, CUDA 12.4, hoặc bản CPU-only) từ Hugging Face wheelhouse trước khi cài package chính. Các backend tùy chọn đi kèm dưới dạng pip extras: `[kokoro]`, `[pocket]`, `[chattts]`, `[faster-whisper]`, `[whisper-mlx]`, `[paraformer]`, và `[mlx-lm]`. Muốn build từ source: `git clone https://github.com/huggingface/speech-to-speech.git`, `cd speech-to-speech`, `uv sync` — lệnh này cài package ở chế độ editable và đưa CLI `speech-to-speech` vào PATH.
Chạy Voice Agent
Quickstart chỉ gồm ba lệnh: set biến `OPENAI_API_KEY`, chạy `speech-to-speech`, và nó khởi động một server tương thích OpenAI Realtime tại `ws://localhost:8765/v1/realtime`, dùng Parakeet TDT cho STT và Qwen3-TTS cho đầu ra. Vậy là xong quickstart. Nếu build từ source, nói chuyện với nó bằng `python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765` ở một terminal thứ hai. Muốn giữ LLM chạy local? Serve Gemma 4 bằng `llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full`, rồi trỏ `speech-to-speech` vào đó bằng `--model_name` và `--responses_api_base_url`. Trên Mac, `speech-to-speech --local_mac_optimal_settings` chuyển sang MPS, MLX LM, và TTS qua mlx-audio chỉ với một flag. `--mode raw-websocket` cho bạn một client target tối giản (16 kHz, int16, mono PCM), còn `--mode socket` truyền PCM thô qua TCP thuần, không có xử lý ngắt lời hay sự kiện transcript. `docker compose up` (sau khi cài NVIDIA Container Toolkit) dựng luôn một server llama.cpp cùng TCP socket server trên các port 8080, 12345, và 12346.
Điểm Mạnh
- ✓Mỗi giai đoạn — VAD, STT, LLM, TTS — được thay bằng một flag CLI thay vì phải fork code, nên thử một backend khác chỉ là đổi một dòng lệnh.
- ✓Nói đúng giao thức OpenAI Realtime nghĩa là các SDK và client viết cho voice API của OpenAI kết nối được vào server tự host mà không cần viết lớp transport riêng.
- ✓Phần LLM không ràng buộc backend: trỏ vào một provider được host, HF Inference Providers, OpenRouter, hoặc một server vLLM/llama.cpp local, chỉ với cùng hai flag.
- ✓Docker Compose có sẵn ghép một server llama.cpp với chế độ socket TCP ngay từ đầu, cho một tham chiếu fully-local chạy được để copy lại.
- ✓Giấy phép Apache-2.0 giữ việc dùng thương mại và fork đơn giản.
Những Điều Cần Lưu Ý
- △Server realtime và LLM proxy tùy chọn của nó không có xác thực hay giới hạn tốc độ nào của riêng mình — README nói rõ bạn cần một mạng đáng tin cậy hoặc một gateway đứng trước, trước khi mở bất kỳ cái nào ra ngoài.
- △Wheel Qwen3-TTS GGML mặc định trên Linux bị khóa vào CUDA 12.8; máy nào khác phải tự tìm và cài wheel tương ứng từ một dataset Hugging Face riêng trước khi package chính import được.
- △Chế độ socket TCP cố tình tối giản: không xử lý ngắt lời, không có sự kiện transcript trực tiếp, không có sự kiện tool-call — nên không thể thay thế chế độ realtime nếu client của bạn cần những thứ đó.
- △Tùy chọn tăng cường audio của DeepFilterNet cần numpy<2, xung đột với yêu cầu numpy>=2 của Pocket TTS — không thể cài cả hai trong cùng một môi trường.
- △Các implementation cũ như MeloTTS đã bị chuyển vào `archive/` và không còn được nối vào CLI, nên nâng cấp một project từng phụ thuộc vào chúng đồng nghĩa với việc phải đổi backend.
Các Framework Voice Agent Thay Thế
Câu Hỏi Thường Gặp
Speech To Speech chạy bốn giai đoạn — voice activity detection, speech-to-text, một language model, và text-to-speech — mỗi giai đoạn trên một thread riêng, kết nối qua queue, tạo thành chuỗi VAD-STT-LLM-TTS được expose qua một WebSocket API tương thích OpenAI Realtime.
Speech To Speech hỗ trợ hai chế độ API tương thích OpenAI, responses-api và chat-completions, có thể trỏ vào OpenAI, HF Inference Providers, OpenRouter, hoặc một server vLLM/llama.cpp tự host, cùng inference local trong chính process qua Transformers trên CUDA/CPU và mlx-lm trên Apple Silicon.
Speech To Speech có thể chạy hoàn toàn local bằng cách kết hợp STT local (Parakeet TDT) và TTS local (Qwen3-TTS hoặc Kokoro-82M) với một LLM chạy qua llama.cpp, vLLM, Transformers, hoặc mlx-lm trên Apple Silicon, không cần gọi API bên ngoài nào.
Speech To Speech triển khai bộ sự kiện cốt lõi của OpenAI Realtime cho cả hai chiều — input_audio_buffer.append, session.update, conversation.item.create, response.create, và response.cancel ở chiều vào, cùng các sự kiện speech, transcription streaming, audio delta, và response.done ở chiều ra — nên các client OpenAI Realtime kết nối trực tiếp được vào nó.
Speech To Speech cần Python 3.10 trở lên. Backend Qwen3-TTS GGML mặc định nhắm tới CUDA 12.8 trên Linux, có các wheel riêng cho CUDA 13.x, CUDA 12.4, hoặc bản CPU-only, còn trên macOS thì chạy qua mlx-audio trên Apple Silicon.
Speech To Speech được phát hành theo giấy phép Apache-2.0, một giấy phép permissive cho phép dùng thương mại, chỉnh sửa, và phân phối lại.
Vấn Đề Speech To Speech Giải Quyết
Ghép voice activity detection, speech-to-text, một LLM và text-to-speech thành một vòng lặp hội thoại real-time chạy được nghĩa là tự tay nối bốn pipeline mã nguồn mở hoặc thương mại khác nhau lại, rồi tự lo threading và queue để một lượt suy luận LLM chậm không làm audio khựng lại. Speech To Speech dựng sẵn chuỗi đó và đặt một giao thức chuẩn — OpenAI Realtime API — ở phía trước, nên một client viết cho voice API của chính OpenAI chạy được luôn mà không cần viết lớp transport riêng.
Nên Dùng Speech To Speech Khi Nào — Và Khi Nào Nên Bỏ Qua
Nên thử Speech To Speech nếu bạn đang xây một giao diện giọng nói bằng Python và muốn các lớp STT, LLM, TTS luôn có thể thay thế được — nhất là khi kế hoạch là tự chạy LLM qua vLLM hoặc llama.cpp thay vì trả tiền theo token cho một API được host. Nên bỏ qua nếu bạn muốn một voice API được quản lý sẵn, không cần cấu hình: bạn vẫn phải tự chọn backend, khớp đúng phiên bản wheel CUDA trên Linux, và dựng lớp WebSocket transport mà client của bạn sẽ nói chuyện cùng.
Repo liên quan
speech-to-speech có đáng để bạn bỏ thời gian?
ChatGPT, Claude và Perplexity đều đọc được trang này. Hỏi thử xem họ nghĩ gì về speech-to-speech.