LiveKit Service Integration Design

LiveKit Service Integration Design

Overview

This document outlines the design for integrating LiveKit as a managed service in Voice Mode, similar to how Whisper and Kokoro are currently managed.

Architecture Overview

Voice Mode
├── CLI Commands
│   ├── voice-mode livekit install
│   ├── voice-mode livekit start/stop/status
│   └── voice-mode livekit uninstall
├── MCP Tools
│   ├── install_livekit()
│   ├── Extended service() tool
│   └── livekit_status()
└── Service Management
    ├── systemd/launchd templates
    ├── Health checks
    └── Auto-discovery

Installation Strategy

Binary Installation

1. macOS: Use brew install livekit (already available)
2. Linux: Use official install script: curl -sSL https://get.livekit.io | bash
3. Fallback: Direct binary download from GitHub releases

Service Location

• Install to: ~/.voicemode/services/livekit/
• Binary: ~/.voicemode/services/livekit/livekit-server
• Config: ~/.voicemode/services/livekit/livekit.yaml
• Logs: ~/.voicemode/logs/livekit/

Configuration

Dev Mode (Default)

# ~/.voicemode/services/livekit/livekit.yaml
port: 7880
rtc:
  port_range_start: 50000
  port_range_end: 60000
  use_external_ip: false
keys:
  devkey: secret
log_level: info

Environment Variables

LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret

Service Templates

systemd Template

[Unit]
Description=Voice Mode LiveKit Server
After=network.target

[Service]
Type=simple
ExecStart={LIVEKIT_BIN} --config {CONFIG_FILE} --dev
WorkingDirectory={WORKING_DIR}
ExecStartPost=/bin/sh -c 'while ! curl -sf http://127.0.0.1:{LIVEKIT_PORT}/health >/dev/null 2>&1; do echo "Waiting for LiveKit..."; sleep 1; done'
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

launchd Template

<dict>
    <key>Label</key>
    <string>com.voicemode.livekit</string>
    <key>ProgramArguments</key>
    <array>
        <string>{LIVEKIT_BIN}</string>
        <string>--config</string>
        <string>{CONFIG_FILE}</string>
        <string>--dev</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>

Implementation Plan

Phase 1: Core Installation

1. Create voice_mode/tools/services/livekit/install.py

   • Platform detection (macOS/Linux)
   • Binary installation (brew/curl/direct download)
   • Service file generation
   • Config file creation

2. Create voice_mode/tools/services/livekit/uninstall.py

   • Service removal
   • Binary cleanup
   • Config cleanup

Phase 2: Service Management

1. Extend voice_mode/tools/service.py

   • Add LiveKit support
   • Health check integration
   • Status reporting

2. Create service templates

   • voice_mode/templates/systemd/voicemode-livekit.service
   • voice_mode/templates/launchd/com.voicemode.livekit.plist

Phase 3: CLI Integration

1. Add to voice_mode/cli.py
   • Create @voice_mode_main_cli.group() for livekit
   • Add all subcommands (install, start, stop, etc.)

Phase 4: MCP Tools

1. Create/update MCP tools
   • install_livekit tool
   • Update existing service tool
   • Add livekit_status tool

Phase 5: Web Interface

1. Update web interface in docs/web/
   • Auto-detect local LiveKit server
   • Connection configuration
   • Fallback to cloud

Health Checks

LiveKit exposes health endpoints:

• /health - Basic health check
• / - Returns LiveKit version info

Auto-Discovery

Add to provider discovery:

• Check port 7880 for LiveKit server
• Verify with health endpoint
• Add to provider registry

Testing Strategy

1. Installation Testing

   • Test on macOS (brew)
   • Test on Linux (curl script)
   • Test fallback binary download

2. Service Testing

   • Start/stop/restart
   • Auto-start on boot
   • Log rotation

3. Integration Testing

   • Web interface connection
   • Token generation
   • Room creation

Migration from Previous Work

From the voice-mcp.tgz analysis:

• Reuse livekit-admin-mcp concepts for room management
• Adapt web interface from livekit/voice-assistant-frontend
• Use existing LiveKit documentation structure

Success Metrics

• One-command installation: voice-mode livekit install
• Service management parity with Whisper/Kokoro
• Web interface works locally
• TailScale remote access functional
• Graceful fallback to cloud LiveKit

Open Questions

1. Should we bundle the web interface or serve from docs/web/?
2. How to handle TURN server configuration for NAT traversal?
3. Should we auto-install during first converse if not present?

Next Steps

1. Start with install.py implementation
2. Test on both macOS and Linux
3. Create service templates
4. Integrate with CLI
5. Update documentation