# skulux/voicetral architecture

> Architecture diagram of the GitHub repository skulux/voicetral, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skulux/voicetral
- Repository: https://github.com/skulux/voicetral

## Overview

Voicetral is a voice-driven chatbot: it listens for speech, transcribes it, gets an Ollama response, synthesizes that response with Bark, and plays the audio. The main loop also loads and saves conversation history. Most orchestration and audio processing live in main.py; short_term_memory.py provides JSON-backed persistence. The README documents the end-to-end workflow, while the sampled main.py excerpt does not show every call between stages.

Main entry points: [`main.py`](https://github.com/skulux/voicetral/blob/main/main.py) (Main loop), [`config.ini`](https://github.com/skulux/voicetral/blob/main/config.ini) (Runtime settings), [`short_term_memory.py`](https://github.com/skulux/voicetral/blob/main/short_term_memory.py) (Conversation history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation"]
  node_runtime["Main loop<br/>[main.py]"]
  node_history[("Conversation history")]
  node_ollama["Ollama model"]
end

subgraph group_audio["Audio I/O"]
  node_capture["Speech capture<br/>[main.py]"]
  node_transcription["Speech transcription<br/>[main.py]"]
  node_bark["Bark synthesis<br/>[main.py]"]
  node_resample["Audio resampling<br/>[main.py]"]
  node_playback["Audio playback<br/>[main.py]"]
end

subgraph group_configuration["Configuration"]
  node_config["Runtime settings<br/>[config.ini]"]
end

node_user(("Speaker"))
node_microphone(("Microphone"))
node_speaker(("Audio output"))

node_user -->|"speaks into"| node_microphone
node_microphone -->|"provides audio"| node_capture
node_runtime -->|"listens via"| node_capture
node_capture -->|"transcribes audio"| node_transcription
node_transcription -->|"returns text"| node_runtime
node_runtime -->|"requests response"| node_ollama
node_runtime -->|"loads and saves"| node_history
node_config -->|"configures"| node_runtime
node_runtime -->|"synthesizes response"| node_bark
node_bark -->|"writes audio"| node_resample
node_resample -->|"provides resampled audio"| node_playback
node_playback -->|"plays audio"| node_speaker

click node_runtime "https://github.com/skulux/voicetral/blob/main/main.py"
click node_history "https://github.com/skulux/voicetral/blob/main/short_term_memory.py"
click node_config "https://github.com/skulux/voicetral/blob/main/config.ini"
click node_capture "https://github.com/skulux/voicetral/blob/main/main.py"
click node_transcription "https://github.com/skulux/voicetral/blob/main/main.py"
click node_bark "https://github.com/skulux/voicetral/blob/main/main.py"
click node_resample "https://github.com/skulux/voicetral/blob/main/main.py"
click node_playback "https://github.com/skulux/voicetral/blob/main/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime,node_history,node_ollama toneBlue
class node_capture,node_transcription,node_bark,node_resample,node_playback toneAmber
class node_config toneMint
class node_user,node_microphone,node_speaker toneIndigo
```

## Components

### Conversation

- [Main loop](https://github.com/skulux/voicetral/blob/main/main.py): `main.py`
- [Conversation history](https://github.com/skulux/voicetral/blob/main/short_term_memory.py): `short_term_memory.py`
- **Ollama model**

### Audio I/O

- [Speech capture](https://github.com/skulux/voicetral/blob/main/main.py): `main.py`
- [Speech transcription](https://github.com/skulux/voicetral/blob/main/main.py): `main.py`
- [Bark synthesis](https://github.com/skulux/voicetral/blob/main/main.py): `main.py`
- [Audio resampling](https://github.com/skulux/voicetral/blob/main/main.py): `main.py`
- [Audio playback](https://github.com/skulux/voicetral/blob/main/main.py): `main.py`

### Configuration

- [Runtime settings](https://github.com/skulux/voicetral/blob/main/config.ini): `config.ini`

### Other components

- **Speaker**
- **Microphone**
- **Audio output**

## Connections

- Speaker → Microphone: speaks into (evidence: `readme.md`)
- Microphone → Speech capture: provides audio (evidence: `main.py`)
- Main loop → Speech capture: listens via (evidence: `main.py`)
- Speech capture → Speech transcription: transcribes audio (evidence: `main.py`)
- Speech transcription → Main loop: returns text (evidence: `readme.md`)
- Main loop → Ollama model: requests response (evidence: `readme.md`)
- Main loop → Conversation history: loads and saves (evidence: `main.py`)
- Runtime settings → Main loop: configures (evidence: `readme.md`)
- Main loop → Bark synthesis: synthesizes response (evidence: `readme.md`)
- Bark synthesis → Audio resampling: writes audio (evidence: `main.py`)
- Audio resampling → Audio playback: provides resampled audio (evidence: `main.py`)
- Audio playback → Audio output: plays audio (evidence: `main.py`)
