STT-Assistant

STT Daemon

An always-on speech-to-text daemon that listens to a PulseAudio/PipeWire source, detects voice activity, and transcribes utterances to Spanish/English text, with a separate voice-assistant layer for commands and chat on top.

Overview

• Capture audio continuously from PulseAudio/PipeWire sources
• Preserve the start of speech with a pre-roll (ring) buffer, so the first phoneme is never cut when voice detection fires
• Segment utterances with configurable silence thresholds
• Transcribe each utterance with Faster-Whisper (multilingual: Spanish, English, or auto-detect)
• Output to stdout (human-readable) and/or JSONL files
• Run non-blocking with worker threads so audio keeps flowing during transcription
• Act on speech through the separate stt-assistant process (modes, commands, chat, tools, audit)

Architecture

Audio Source (PulseAudio)
    ↓
ParecCapture / SoundDeviceCapture
    ↓
Pre-roll Ring Buffer (VAD lookback)
    ↓
WebRTC-VAD (voice activity detection)
    ↓
FrameSegmenter (utterance boundaries)
    ↓
Queue (segment_queue)
    ↓
Faster-Whisper (transcription)
    ↓
TranscriptSink (stdout + transcripts/YYYY-MM-DD.jsonl) + EventPublisher
    ↓  publish-only UNIX socket ($XDG_RUNTIME_DIR/stt-daemon.sock)
stt-assistant  (subscribes; owns modes, command buffer, chat, LLM, tools)
    ↓  control socket ($XDG_RUNTIME_DIR/stt-assistant.sock)
stt-tui (viewer) / stt-ctl (hotkeys)              audit/YYYY-MM-DD.jsonl ←┘

The daemon never accepts input: it only transcribes and publishes. Everything stateful lives in the assistant, a separate process (see docs/ASSISTANT.md).

Prerequisites

System packages

• PulseAudio or PipeWire-Pulse: pactl, parec command-line tools

  • On Ubuntu/Debian: apt-get install pulseaudio-utils or apt-get install pipewire pipewire-pulse
  • On Fedora: dnf install pulseaudio-utils
  • On macOS: Install via Homebrew (though PulseAudio is Linux-first; the sounddevice backend is recommended on macOS)

• FFmpeg (optional, used by Faster-Whisper for format conversion)

  • On Ubuntu/Debian: apt-get install ffmpeg

Python

• Python 3.11+ (tested on 3.13.5)
• uv package manager (https://docs.astral.sh/uv/)

Installation

Clone the repo and install with uv:

# From the repo root (wherever you cloned it)
cd /path/to/STT-TTS

# Sync dependencies (installs into .venv)
uv sync

# (Optional) If you want to use the sounddevice backend (requires portaudio):
uv sync --extra portaudio

Quick Start

Copy the example config and edit as needed:

cp config.example.toml config.toml

Then launch the whole system with one command:

uv run stt-daemon up --with-tui

That supervises the daemon, the assistant, and the TUI together; quitting the TUI stops everything cleanly. The manual flow is the same three steps without the supervisor:

uv run stt-daemon setup       # create the virtual sink (interactive picker)
uv run stt-daemon run         # start listening and transcribing
uv run stt-daemon clear --yes # tear down the sink when done

See docs/CLI.md for every subcommand and docs/CONFIGURATION.md for the config reference.

Documentation

• docs/CONFIGURATION.md — annotated TOML reference for every config key.
• docs/AUDIO-SETUP.md — virtual sink creation and audio routing options.
• docs/CLI.md — stt-daemon subcommands and common overrides.
• docs/ASSISTANT.md — the assistant layer: modes, command flow, LLM, tools, audit.
• docs/OUTPUT.md — stdout, JSONL, and WAV output formats and fields.
• docs/TROUBLESHOOTING.md — common errors and how to fix them.
• docs/DEVELOPMENT.md — code structure, testing, linting, and packaging.
• docs/PYWHISPERCPP.md — building the pywhispercpp GPU backend from source.

Testing

Run the full suite with no audio hardware or live LLM required:

uv run pytest -v

See docs/DEVELOPMENT.md for what the tests cover.

References

• Faster-Whisper: https://github.com/SYSTRAN/faster-whisper
• WebRTC VAD: https://github.com/wiseman/py-webrtcvad
• PulseAudio: https://www.freedesktop.org/wiki/Software/PulseAudio/

License

This project is ISC-licensed. See LICENSE.md.

---

Made with ❤️ for Efren. Questions? Open an issue or reach out.