Vocalyx
Real-time voice assistant: Speech-to-Text (STT) → GPT → Text-to-Speech (TTS). Install with pip install vocalyx. Run vocalyx-stt, vocalyx-tts, and vocalyx in three terminals.
Install
pip install vocalyx
Requirements: Python 3.10+, system dependencies portaudio and ffmpeg, microphone and audio output.
Architecture and flow
All components live in the vocalyx package and talk over WebSockets:
[Microphone] → vocalyx (client)
↓
STT server (RealtimeSTT) ← control + data WebSockets
↓
vocalyx (client) receives transcribed text
↓
TTS server (GPT + Soprano TTS) ← single WebSocket
↓
vocalyx (client) plays audio → [Speakers]
- vocalyx-stt – STT server. Listens on two ports: control (commands) and data (audio + transcriptions).
- vocalyx-tts – TTS server. Listens on one port. Receives text, streams GPT response, synthesizes with Soprano, streams audio back.
- vocalyx – Client. Captures mic, sends audio to STT; receives text, sends to TTS; receives and plays TTS audio.
Ports (defaults)
| Component | Role | Default URL / Port |
|---|---|---|
| STT server | Control WebSocket | ws://localhost:8011 |
| STT server | Data WebSocket | ws://localhost:8012 |
| TTS server | WebSocket | ws://localhost:8013 |
The client uses these URLs by default. You can override them with --control, --data, and --tts-url when running vocalyx, and with -c/-d when running vocalyx-stt. The TTS server binds to localhost and the port above (no CLI port flag in the current release).
Models used
| Role | Model / service | Notes |
|---|---|---|
| STT | RealtimeSTT (Faster Whisper, CTranslate2) | Main model default: tiny.en. Real-time model default: tiny. Configurable via -m, -r. |
| LLM | OpenAI GPT (streaming) | Default: gpt-3.5-turbo. Used for assistant replies. Requires OPENAI_API_KEY. |
| TTS | Soprano TTS | On-device, 80M params. Default: backend=auto, device=auto, cache_size_mb=100, decoder_batch_size=1. Output: 32 kHz mono float32. |
Configuration
Environment
Create a .env in the directory from which you run the processes (or set the variable in the shell):
OPENAI_API_KEY– Required for the TTS server (GPT). Get it from OpenAI API keys.
TTS server (vocalyx-tts)
- Host / port:
localhost:8013(hardcoded in code). - GPT: System prompt and model are sent by the client per request (default prompt “motivational assistant”.", default model:
gpt-3.5-turbo). Temperature is0.7. - Soprano: Loaded once at startup;
backend="auto",device="auto",cache_size_mb=100,decoder_batch_size=1.
STT server (vocalyx-stt)
Key options (run vocalyx-stt --help for full list):
| Option | Default | Description |
|---|---|---|
-c, --control |
8011 | Control WebSocket port. |
-d, --data |
8012 | Data WebSocket port. |
-m, --model |
tiny.en |
Main Whisper model size or path (e.g. base, small, large-v2). |
-r, --rt-model |
tiny |
Real-time transcription model size. |
-l, --lang |
en |
Language code. |
-i, --input-device |
1 | Audio input device index. |
--device |
cuda |
cuda or cpu. |
--compute_type |
default |
CTranslate2 compute type. |
--silero_sensitivity |
0.05 | VAD sensitivity (0–1). |
--webrtc_sensitivity |
3 | WebRTC VAD (0–3). |
--end_of_sentence_detection_pause |
0.45 | Silence (seconds) to treat as end of sentence. |
-D, --debug |
off | Debug logging. |
Client (vocalyx)
| Option | Default | Description |
|---|---|---|
--control |
ws://localhost:8011 |
STT control WebSocket URL. |
--data |
ws://localhost:8012 |
STT data WebSocket URL. |
--tts-url |
ws://localhost:8013 |
TTS WebSocket URL. |
--voice |
af_heart |
Voice name (Soprano may ignore). |
--speed |
1.0 | Playback speed. |
--system-prompt, --prompt |
You are a motivational assistant. |
LLM system prompt (persona/instructions). |
--model |
gpt-3.5-turbo |
OpenAI model (e.g. gpt-4, gpt-4o). |
-L, --list |
- | List audio devices and exit. |
-c, --continous |
true | Keep running and transcribing. |
Usage
- Set
OPENAI_API_KEY(e.g. in.env). - Start STT server, then TTS server, then client:
# Terminal 1
vocalyx-stt
# Terminal 2
vocalyx-tts
# Terminal 3
vocalyx
- Speak; the client shows “You” and “AI” and plays the assistant’s voice.
List microphone devices:
vocalyx --list
Use a different TTS URL or STT URLs if your servers run on other hosts/ports:
vocalyx --tts-url ws://otherhost:8013 --control ws://otherhost:8011 --data ws://otherhost:8012
Audio format (TTS)
Soprano TTS outputs 32 kHz, mono, float32. The client plays this directly (e.g. paFloat32, 32000 Hz, 1 channel). Do not convert to μ-law or int16 for playback or you may change pitch/tempo.
License
MIT
Metadata
Release files for vocalyx 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vocalyx-1.0.2.tar.gz | 23.4 kB | Without provenance | Details for vocalyx-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vocalyx-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for vocalyx-1.0.2-py3-none-any.whl |
Total release size: 46.2 kB
Release files / vocalyx-1.0.2.tar.gz
| Download URL | vocalyx-1.0.2.tar.gz |
|---|---|
| Size | 23.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b65f42cfc64049fdebe4c984a3f94d20286b8fb2880902246e7d14639f89434
|
|
BLAKE2b-256 checksum How to use checksums |
8a5abad85d39b2e5a3601ca9c01073e36b8a876e8e8d86ea17645d007b6352ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Release files / vocalyx-1.0.2-py3-none-any.whl
| Download URL | vocalyx-1.0.2-py3-none-any.whl |
|---|---|
| Size | 22.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
56d13dbfc7cb9f87a2f2ef6d17e91ee13f351ba138bf2a22c2ca8bbdbf641214
|
|
BLAKE2b-256 checksum How to use checksums |
59e23c86e512d3ae24f0a075250c8a9dba54e38005e957a79fa48829c7a13ea3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Security for vocalyx 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.