Skip to content

QUICKSTART.md

Latest commit

 

History

History
268 lines (206 loc) · 6.33 KB

QUICKSTART.md

File metadata and controls

268 lines (206 loc) · 6.33 KB
Raw

AetherOS Voice Assistant - Quick Start Guide

Prerequisites

  1. macOS with Homebrew installed
  2. Docker Desktop running
  3. PulseAudio installed: brew install pulseaudio
  4. Ollama installed and running: brew install ollama && ollama serve
  5. Ollama model downloaded: ollama pull llama3.1:8b

One-Command Start

./start_aether.sh

This script will:

  1. ✅ Start PulseAudio with TCP support
  2. ✅ Build Docker images (first time only)
  3. ✅ Start all Aether services
  4. ✅ Show live logs

Troubleshooting

Issue 1: PulseAudio Won't Start

Symptoms:

Connection failure: Connection refused
pa_context_connect() failed: Connection refused

Fix:

# Kill any stuck instances
pulseaudio --kill
killall pulseaudio

# Set module path
export PULSE_MODULE_PATH=/opt/homebrew/lib/pulseaudio/modules

# Start manually
pulseaudio --daemonize=no --exit-idle-time=-1 \
    --load="module-native-protocol-tcp auth-anonymous=1" \
    --load="module-coreaudio-device" &

# Verify it's running
pactl info

Issue 2: Wrong Microphone (iPhone/AirPlay)

Symptoms:

  • System uses iPhone mic instead of built-in Mac mic
  • Audio from wrong device

Fix:

# List available sources
./scripts/select_audio_input.sh

# Set built-in mic as default
pactl set-default-source coreaudio_input.0

# Verify
pactl info | grep "Default Source"

Disable Continuity Camera (Permanent Fix):

  1. System Settings → General → AirDrop & Handoff
  2. Turn OFF "iPhone Cellular Calls"
  3. Turn OFF "Continuity Camera"

Issue 3: WhisperBridge Not Running

Symptoms:

[WARN] WhisperBridge not running - audio data dropped

Possible Causes:

  1. Python script not found
  2. Whisper not installed
  3. Python dependencies missing

Fix:

# Rebuild Docker image
docker-compose down
docker-compose build --no-cache aether_voice
docker-compose up

# Check logs for script path
docker-compose logs aether_voice | grep "script"

Issue 4: Ollama Not Responding

Symptoms:

Cannot connect to Ollama: Connection refused

Fix:

# Start Ollama server
ollama serve

# In another terminal, verify model
ollama list

# Pull model if missing
ollama pull llama3.1:8b

# Test it
ollama run llama3.1:8b "Hello"

Issue 5: Slow Response / Multiple Requests

Symptoms:

  • Every word triggers separate LLM call
  • Overlapping TTS responses

Status: ✅ FIXED in latest version

The GPT agent now accumulates speech and waits 2 seconds of silence before processing.

Manual Testing

Test PulseAudio

# Check status
pactl info

# List sources
pactl list sources short

# Test recording (5 seconds)
parecord --channels=1 --rate=16000 --duration=5 test.wav

# Play it back
paplay test.wav

Test Docker Audio

# Start services
docker-compose up

# In another terminal, check voice node
docker-compose logs -f aether_voice

# Speak into microphone
# You should see transcriptions in logs

Test ROS2 Topics

# Enter voice container
docker exec -it aether_os-aether_voice-1 bash

# List topics
ros2 topic list

# Monitor voice transcriptions
ros2 topic echo /voice_text

# Monitor AI responses
ros2 topic echo /aether_response

System Architecture

┌─────────────┐
│   macOS     │
│  Built-in   │
│     Mic     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ PulseAudio  │
│ TCP:4713    │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────┐
│          Docker Container           │
│                                     │
│  ┌──────────────┐                  │
│  │ Voice Input  │                  │
│  │  (Whisper)   │                  │
│  └──────┬───────┘                  │
│         │ /voice_text              │
│         ▼                           │
│  ┌──────────────┐                  │
│  │  GPT Agent   │                  │
│  │   (Ollama)   │                  │
│  └──────┬───────┘                  │
│         │ /aether_response         │
│         ▼                           │
│  ┌──────────────┐                  │
│  │     TTS      │                  │
│  │  (Google)    │                  │
│  └──────┬───────┘                  │
│         │                           │
└─────────┼───────────────────────────┘
          │
          ▼
    ┌─────────┐
    │ Speaker │
    └─────────┘

Expected Behavior

  1. You speak: "Hello, how are you?"
  2. Whisper transcribes: Partial words appear in logs
  3. After 2 sec silence: GPT agent processes complete sentence
  4. Ollama responds: "I'm doing well, thank you for asking!"
  5. TTS speaks: You hear the response

Performance Tips

  1. Use smaller Whisper model for faster transcription:

    • Edit docker-compose.yml
    • Change WHISPER_MODEL=tiny (fastest) or base (balanced)

  2. Use smaller Ollama model for faster responses:

    • ollama pull llama3.1:8b (recommended)
    • Or ollama pull phi3:mini (faster, less capable)

  3. Adjust silence threshold for faster/slower response:

    • Edit src/aether_gpt_agent/scripts/aether_gpt_agent_node.py
    • Change self.silence_threshold = 2.0 (lower = faster, higher = more patient)

Stopping the System

Press Ctrl+C in the terminal running start_aether.sh

This will:

  1. Stop Docker containers
  2. Stop PulseAudio
  3. Clean up resources

Getting Help

Check logs:

# All services
docker-compose logs

# Specific service
docker-compose logs aether_voice
docker-compose logs aether_gpt_agent
docker-compose logs aether_tts

# Follow logs live
docker-compose logs -f

Next Steps

  • See VOICE_FLOW_FIX.md for technical details on speech accumulation
  • See VOICE_CONVERSATION_SETUP.md for full system documentation
  • See MACOS_AUDIO_SETUP.md for audio configuration details