How carsonmulligan/local-voice-agent-language-teacher works
Project type and purpose
• This is a local, command-line language assistant tool. It captures audio, transcribes speech, sends text to a locally-hosted AI model, and returns spoken responses.
• Key use-cases: Spanish (primary) and Chinese assistants via separate module folders.
File structure
• Root script: bertosito_chat.py (orchestrator)
• Language folders:
· spanish/… various CLI implementations and broom_closet experiments
· chinese/… guanguan_v1.py
• Utility folders:
· voices/voiceCheck.py (audio device test)
· viz/… scripts for publishing docs
• Config and metadata: requirements.txt, .github/workflows, README.md
README insights
• Dependencies: whisper (openAI), edge-tts, ollama serving llama2-uncensored
• Runtime flow: audio recording → transcription → AI model call → TTS → playback
• Local services: ollama is a long-running local server on localhost:11434
A. Client Orchestrator (Python script bertosito_chat.py)
B. Audio Input Module (mic capture via Python audio library)
C. Whisper Transcription Module (Python interface to whisper)
D. AI Model Service (Ollama server hosting llama2-uncensored)
E. Text-to-Speech Module (edge-tts library)
F. Audio Playback Module (system audio output)
G. Language-specific extensions (spanish/, chinese/ folders)
Relationships & interactions
1. Microphone → Audio Input Module
2. Audio Input Module → Whisper Transcription Module → Transcribed Text
3. Transcribed Text → HTTP request → Ollama AI Model Service → AI-generated Text
4. AI-generated Text → Text-to-Speech Module → Audio File
5. Audio File → Audio Playback Module → Speaker
6. Loop back for next user utterance
• That the orchestrator script ties these steps together.
Architectural patterns & design principles
• Pipeline pattern: a linear flow of data through discrete processing stages
• Separation of concerns: each module handles one responsibility (capture, ASR, LLM, TTS, playback)
• Local microservice (Ollama) accessed via REST API
• Modular code: language-specific submodules live under their own directories
Technologies, frameworks, and libraries
• Python 3.x as the host language
• whisper (OpenAI) for ASR
• ollama server hosting llama-based models
• edge-tts for text-to-speech
• pydub or similar for audio I/O (implicit in requirements)
• shell scripts for setup in spanish/broom_closet (setup.sh)