Beseda

Voice conversations with your coding agent. Say “Alice, …” (in Russian, “Вика, …”) and talk to an AI agent in English or Russian, right from the terminal: speech recognition and synthesis run locally on your Mac, the agent works in the current folder.

Русская версия

▶ The same conversation with sound (MP4) (Russian). The user's phrases are spoken by a second Silero voice instead of a microphone; recognition, the pi agent and the answers are the real app. Long waits in the GIF are shortened.

microphone → Silero VAD + GigaAM or whisper.cpp (local) → brain: pi agent, Codex or DeepSeek → TTS: Silero (local) → speakers

Status: alpha. macOS on Apple Silicon only. Russian (default) and English; more languages are a TOML file away.

Features

• Wake word, like a smart speaker. Only phrases addressed to «Вика» reach the model; after an answer you can keep talking without the wake word, «стоп» ends the conversation, «подожди» gives you time to think.
• Local speech. GigaAM for Russian (0.1–0.3 s per phrase) or whisper.cpp on the Mac GPU for recognition, Silero for synthesis: from the first word of the answer to sound in 0.1–0.25 s.
• Pluggable brains. The pi coding agent (reads and edits files, runs commands), Codex or a plain DeepSeek chat; adding another agent is one class.
• Works with music or a video playing. macOS echo cancellation (the one FaceTime uses) removes the sound of the speakers from the microphone; other apps keep their volume.
• Observability. Every session writes a log with a per-turn latency timeline: recognition, first token, first audio, tool calls.
• Dialog recording. The whole conversation as one WAV, with the real pauses.

Requirements

• macOS on Apple Silicon, Python 3.12+, uv, brew install portaudio
• For --tts edge: brew install ffmpeg
• For the default brain: npm install -g @earendil-works/pi-coding-agent with a DeepSeek key configured in pi. For --brain codex: the Codex CLI signed in with codex login; the model comes from ~/.codex/config.toml unless --model is set. For --brain deepseek: the DEEPSEEK_API_KEY environment variable.

Install

brew install portaudio
uv tool install beseda

Models download on first launch into ~/.beseda/models/ (GigaAM ~890 MB for Russian or Whisper small ~490 MB for English, Silero ~145 MB, VAD ~1 MB).

Use

cd ~/some/project   # the agent works in the current folder
beseda                      # Russian
beseda --language en        # English

The table shows the Russian phrases; the English pack has its own (“Alice, …”, “hold on”, “that's all”).

Keys: Space turns the microphone on/off, Esc interrupts the answer, q quits.

The microphone is off while the assistant speaks, so it never hears itself; interrupting by voice isn't supported yet. The macOS microphone indicator stays on while Beseda runs: the stream must stay open to hear the wake word.

Configuration

Any option can be set in ~/.beseda/config.toml; command-line flags win.

language = "ru"           # ru | en | your own pack
brain = "pi"              # pi | codex | deepseek
model = "deepseek/deepseek-v4-flash"
stt = "gigaam"            # gigaam (Russian) | small | turbo
vocabulary = ["JavaScript", "DeepSeek"]
tts = "silero"            # silero | edge | say
voice = "baya"
wake-word = "вика"        # default comes from the language pack; "" answers everything
follow-up = 8
hold = 120
record = true             # or a file path
log-days = 14

See beseda --help for the full list.

Languages

Everything that depends on the spoken language lives in a language pack, a TOML file: Whisper's language and style prompt, the voice prompt for the model, the wake word and its grammatical endings, stop and hold phrases, default TTS voices and the Silero model, and the terminal UI strings.

Built-in packs: ru (default) and en. To change a pack or add a language, put a file into ~/.beseda/languages/: ru.toml there overrides the built-in one, de.toml adds German (beseda --language de). Copy a built-in pack as a starting point; every key is required.

Speech recognition

Each language pack picks a default stt: GigaAM for Russian, Whisper small for English.

Whisper keeps the techniques from Vadic, checked on real dialogs: loudness normalization before recognition, Whisper's own VAD (without it a cough becomes «Спасибо.», which is a stop phrase), a style prompt for punctuation plus your vocabulary for terms, greedy decoding at temperature 0. GigaAM takes no prompt, so vocabulary applies to Whisper only.

Models other apps already downloaded (VoiceInk, Vadic) are reused.

Speech synthesis

Silero's Russian model skips digits and Latin letters, so the Russian voice prompt asks the model to write numbers and names in Russian words. Compare the voices by ear: beseda-samples [--language en] writes the same phrase in every voice to ~/Downloads/beseda-tts-samples/.

Logs and recordings

Each session logs to ~/.beseda/logs/beseda-<time>.log; logs older than log-days are deleted on start.

grep summary ~/.beseda/logs/*.log | tail      # latency per turn: stt, llm_first_token, tts_first_audio, voice_to_voice
grep -E 'ERROR|WARNING' ~/.beseda/logs/*.log   # incidents

--debug adds every pi event. --record saves the dialog to ~/Downloads/beseda-<time>.wav on exit.

Security

With the default pi brain the agent has full access: it reads and writes files and runs shell commands in the current folder, by voice. With codex it runs commands without asking in Codex's workspace-write sandbox: it can change the current folder but not the rest of the disk, and commands have no network. Recognition makes mistakes. Run Beseda only in folders where that is acceptable, and keep them under version control.

Privacy

• Recognition, synthesis with silero or say, logs and recordings stay on your Mac.
• What you say to the assistant (after the wake word) is sent to the LLM provider: DeepSeek by default, OpenAI with codex.
• With tts = "edge" the answers are sent to Microsoft.
• Logs contain the full text of your dialogs, including phrases that weren't addressed to the assistant; they are kept for log-days days.

Model licenses

Beseda's code is MIT, and no models are bundled: they download to your machine on first use.

• Silero TTS (default voice): CC BY-NC-SA 4.0, non-commercial use only. For commercial use pick say or edge, or obtain a license from Silero.
• GigaAM, Whisper models and the Silero VAD used by whisper.cpp: MIT.
• Edge TTS uses an unofficial endpoint of the Microsoft Edge read-aloud service and may stop working.

Extending

• A brain (beseda/brains.py) yields ("text", …), ("tool", …), ("error", …) events and supports abort(); register it in BRAINS.
• A TTS engine (beseda/tts.py) subclasses PcmEngine with render(text) -> PCM; register it in TTS_ENGINES and list its voices under [voices] in each language pack.
• A language is a TOML file, see Languages.

Development

uv sync
uv run pytest
uv tool install --editable .   # the beseda command picks up code changes; add --force after dependency changes
uv run python scripts/demo.py  # re-record docs/demo-ru.gif and .mp4; --language en for the English one (needs brew install agg ffmpeg)
git tag vX.Y.Z && git push origin vX.Y.Z   # release: CI tests and publishes to PyPI (the tag must match the version in pyproject.toml)

License

MIT