Getting Started Overview
This guide takes you from zero to a working voice assistant. By the end, you'll have a real-time conversational AI application running locally.
Learning Path
| Guide | What You'll Learn |
|---|---|
| Installation | Install packages and dependencies |
| Backend Quickstart | Run the server with cloud providers |
| Web Client Quickstart | Connect a browser and speak to your assistant |
| Tool Calling | Give your assistant custom capabilities |
| Local-Only Stack | Run entirely locally without cloud APIs |
What You'll Build
By the end of the quickstarts, you'll have:
- A working voice server that processes speech, generates responses, and synthesizes audio
- A browser client that captures your microphone and plays assistant responses
- Custom tools that let your assistant perform actions like checking the weather
- Optionally, a fully local stack for privacy-sensitive applications
Prerequisites
Required
| Requirement | Version | Check Command |
|---|---|---|
| Node.js | 20+ | node --version |
| npm | 9+ | npm --version |
For Cloud Path (Recommended for Getting Started)
You'll need API keys for at least one provider per capability:
| Capability | Provider Options |
|---|---|
| LLM | OpenAI, Anthropic, Google Gemini |
| Speech-to-Text | OpenAI Whisper |
| Text-to-Speech | OpenAI TTS, ElevenLabs |
Quickest setup: An OpenAI API key covers all three capabilities.
For Local Path (No Cloud Dependencies)
| Component | Software |
|---|---|
| LLM | Ollama with llama3.2 or similar |
| Speech-to-Text | Faster-Whisper Server |
| Text-to-Speech | Piper |
Two Paths
Choose your approach:
Cloud Path (Start Here)
Best for: Quick setup, production deployments, highest quality
Pros:
- Fastest setup (minutes)
- Best quality models
- No local GPU required
Cons:
- Requires API keys
- Ongoing API costs
- Data sent to cloud providers
Local Path
Best for: Privacy, offline use, development without API costs
Pros:
- Complete privacy
- No API costs
- Works offline
Cons:
- Longer setup
- Requires decent CPU/GPU
- Smaller model selection
Quick Reference
Environment Variables
# Cloud providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
ELEVENLABS_API_KEY=...
# Local providers (defaults shown)
OLLAMA_BASE_URL=http://localhost:11434
FASTER_WHISPER_URL=http://localhost:9000
PIPER_URL=http://localhost:5002
Default Ports
| Service | Default Port |
|---|---|
| LLMRTC Backend | 8787 |
| Ollama | 11434 |
| Faster-Whisper | 9000 |
| Piper | 5002 |
Running the Examples
After completing the quickstarts, try the included examples:
Vite Demo (Full-Featured)
Source: examples/vite-demo
cd examples/vite-demo
npm install
npm run dev
Features: Audio visualization, transcript display, tool calling UI
Minimal Example (80 Lines)
Source: examples/minimal
cd examples/minimal
npm install
npm run dev
A bare-bones implementation showing the essential code.
Troubleshooting Setup
Node.js Version Issues
# Check version
node --version
# If < 20, use nvm to upgrade
nvm install 20
nvm use 20
API Key Problems
Verify your key works:
# Test OpenAI key
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
Port Conflicts
If port 8787 is in use:
# Find what's using the port
lsof -i :8787
# Or use a different port
PORT=9000 npm start
Next Steps
Ready to start? Begin with installation: