Talk Buddy：本地运行的 AI 口语对话练习工具，支持 Claude / GPT / Gemini / Ollama

Practice real-world conversations with an AI partner — job interviews, client presentations, difficult meetings, delivering bad news — in a safe, private space where it's OK to stumble. Talk Buddy listens to you, responds out loud, and keeps a transcript you can review afterward.

Built for university students, especially those practising English as a second language.

What it does

You pick a scenario (or write your own), press the mic, and have a spoken conversation with the AI. When you're done you get a transcript and optional analysis of how it went.

Under the hood:

You speak → Speech recognition → AI thinks → Voice speaks back
           (Listening)            (AI Brain)   (Voice)

Everything runs on your computer. Your recordings and transcripts never leave your machine. You bring your own AI key (Anthropic, OpenAI, Gemini, Groq, or a local Ollama model) and choose how speech is handled — either a built-in offline engine or a cloud server.

Features

• Hold-to-speak conversations with spacebar or button — the AI responds out loud in real time
• Scenario library — pre-built scenarios for interviews, presentations, HR meetings, and more; create your own
• Practice packs — group scenarios into focused practice sessions
• Session history with transcripts and optional AI analysis
• Multiple AI providers — Anthropic (Claude), OpenAI (GPT), Google (Gemini), Groq, Ollama, or any custom endpoint
• Built-in offline speech — works without internet: Whisper runs inside the app (transformers.js), Piper speaks the replies. One-time model download, no server
• Cloud speech — connect to a Speaches server for higher-quality voices (Kokoro TTS, Faster Whisper STT)
• Audio turn cue — a subtle sound when it's your turn to speak (configurable: rise, click, or silent)
• Privacy-first — all data stored locally in SQLite; bring your own keys; nothing phoned home
• Cross-platform — macOS, Windows, Linux

Quick start

Download a release

1. Go to Releases
2. Download the installer for your platform (.dmg for Mac, .exe for Windows, .AppImage for Linux)
3. Open Talk Buddy, go to Settings → AI Brain, pick your AI provider, paste your key, and save
4. Pick a scenario and start talking

Or build from source

git clone https://github.com/michael-borck/talk-buddy.git
cd talk-buddy
npm install
npm run dev

No native build step is needed — the database uses node:sqlite, which ships inside Electron's bundled Node, so there's nothing to compile against Electron's ABI.

How it works

talk-buddy/
├── src/
│   ├── main/                  # Electron main process
│   │   ├── index.js           # App lifecycle, IPC handlers, provider bridges (in-app STT/TTS)
│   │   └── preload.js         # Context bridge exposing electronAPI to renderer
│   └── renderer/              # React application (Vite-bundled)
│       ├── App.tsx            # Router, sidebar, home page
│       ├── pages/             # Scenarios, Conversation, Settings, SessionHistory, etc.
│       ├── components/        # EditorialVoiceVisualizer, StatusFooter, cards, modals
│       ├── services/          # speaches.ts, chat.ts, wasmStt.ts, piperTts.ts, audioCues.ts, sqlite.ts
│       └── index.css          # Studio Calm design tokens + component classes
├── .github/workflows/
│   └── build.yml              # Release pipeline: builds the Electron app on
│                              #   macOS / Windows / Linux, publishes to GitHub Releases
├── docs/                      # In-app help documentation (markdown)
│   └── design/
│       └── studio-calm.md     # Design system spec for the Buddy suite
└── public/docs/               # Mirror of docs/ served by the app's help viewer

The conversation pipeline

1. You speak → browser captures audio via getUserMedia
2. Speech recognition → audio is sent to the speech server (built-in Whisper or cloud Speaches) via main-process IPC to bypass CORS
3. AI responds → the transcript is sent to your configured AI provider (Claude, GPT, Gemini, etc.) with the scenario's system prompt + conversation history
4. Voice speaks → the AI's text reply is sent to the TTS server, returned as audio, and played through an <audio> element. The voice visualizer animates with real audio amplitude from a Web Audio analyser.
5. Your turn → a configurable audio cue plays, the status flips to "your turn", and you can hold spacebar or the button to speak again

All speech traffic routes through the Electron main process (not the browser renderer) to avoid CORS issues with external servers.

Configuration

All settings are in the app's Settings page (the wrench icon in the sidebar). The five tabs:

Speech options

AI options

For hosted providers (Anthropic, OpenAI, Gemini, Groq), the server address is set automatically — you only need to paste your key and pick a model.

Data storage

All data stays on your computer in a single SQLite file:

Audio recordings are not stored — only the text transcripts survive. The mic blob is discarded after transcription.

Design

Talk Buddy uses Studio Calm, a design system built for ESL students practising high-stakes conversations. Warm paper background, clean sans-serif typography (Figtree), sage accent, generous whitespace, unhurried motion. Everything is designed to reduce anxiety and keep the focus on the conversation.

Studio Calm is shared across the Buddy suite (Talk Buddy, Study Buddy, Career Compass) with a per-app accent colour: sage for Talk Buddy, bluebell for Study Buddy, warm ochre for Career Compass. See docs/design/studio-calm.md for the full spec.

Development

npm install          # Install deps (no native build — node:sqlite is built in)
npm run dev          # Start Vite + Electron together (hot reload)
npm run build        # Vite production build (type-checks + bundles)
npm run electron:dist  # Package for current platform via electron-builder

In-app speech engines (optional download)

Both offline engines are built in: pick Settings → Listening/Voice → Built-in and click the download button. Whisper weights go to your user-data folder, and the Piper engine + Alan/Amy voices are fetched once — after that, speech works fully offline.

Part of the Buddy suite

Talk Buddy is one of three apps sharing the Studio Calm design system:

• Talk Buddy — practise conversations (you're here)
• Study Buddy — privacy-first personal tutor (planned)
• Career Compass — explore career paths (planned)

Documentation

• Design system spec — Studio Calm tokens, patterns, and migration plan
• Design mockup — interactive HTML preview (open in browser)
• In-app help — getting started, service setup, troubleshooting

License

MIT — see LICENSE.

Acknowledgments

• Electron — desktop framework
• React — UI framework
• Speaches — speech-to-text and text-to-speech server
• Ollama — local AI models
• Piper — offline voice synthesis (in-app engine)
• Figtree — the typeface

Inspiration

• Dexter (Apache 2.0) — Talk Buddy's streaming voice pipeline (token-level LLM streaming → sentence-chunked TTS → ordered audio playback with barge-in cancellation) was inspired by Dexter's Tauri-based architecture. No code was copied; the patterns were re-implemented in TypeScript for the Electron stack.