LiveKit Setup and Usage Guide

LiveKit Setup and Usage Guide

This guide covers the complete setup and usage of LiveKit integration with Voice Mode, including the LiveKit server, frontend management, and voice conversations.

Overview

Voice Mode now includes full LiveKit integration providing:

• LiveKit server management - Install, configure, and manage LiveKit server as a system service
• Voice Assistant Frontend - Web-based interface for voice conversations bundled with Voice Mode
• Service integration - Unified management alongside Whisper and Kokoro services
• Development and production support with proper service lifecycle management

Quick Start

1. Install LiveKit Server

# Install LiveKit server (automatically detects platform)
voice-mode livekit install

# Enable to start at boot/login
voice-mode livekit enable

# Start the server
voice-mode livekit start

2. Start Frontend

# Start the Voice Assistant Frontend
voice-mode frontend start

# Enable to start automatically
voice-mode frontend enable

# Open in browser
voice-mode frontend open

3. Access Voice Interface

1. Open http://localhost:3000 in your browser
2. Enter password: voicemode123 (default)
3. Join or create a room for voice conversations

Installation Details

LiveKit Server Installation

The voice-mode livekit install command:

• Downloads LiveKit server binary for your platform (macOS/Linux)
• Creates configuration file at ~/.voicemode/config/livekit.yaml
• Sets up systemd (Linux) or launchd (macOS) service files
• Configures development credentials for easy setup

Installation locations:

• macOS: /opt/homebrew/bin/livekit-server
• Linux: /usr/local/bin/livekit-server
• Config: ~/.voicemode/config/livekit.yaml
• Logs: ~/.voicemode/logs/livekit/

Frontend Installation

The frontend is bundled with Voice Mode and automatically installed. The system:

• Prioritizes bundled frontend in the Python package
• Falls back to external development locations if needed
• Automatically installs Node.js dependencies on first run
• Supports multiple package managers (pnpm, npm, yarn)

Configuration

LiveKit Server Configuration

Edit ~/.voicemode/config/livekit.yaml:

# LiveKit development configuration
port: 7880
rtc:
  port_range_start: 50000
  port_range_end: 50100

keys:
  devkey: secret

# Enable room auto-creation for development
room:
  auto_create: true

# Development logging
logging:
  level: info
  json: false

Frontend Configuration

Create ~/.voicemode/frontend/.env.local for custom settings:

# Custom password (optional)
LIVEKIT_ACCESS_PASSWORD=your_custom_password

# LiveKit server URL (if different)
LIVEKIT_SERVER_URL=ws://localhost:7880

Service Management

All LiveKit services integrate with Voice Mode's unified service management:

Server Commands

# Status and control
voice-mode livekit status
voice-mode livekit start
voice-mode livekit stop
voice-mode livekit restart

# Service management
voice-mode livekit enable    # Start at boot/login
voice-mode livekit disable   # Don't start automatically

# Logs
voice-mode livekit logs
voice-mode livekit logs --follow

Frontend Commands

# Status and control
voice-mode frontend status
voice-mode frontend start
voice-mode frontend stop

# Service management
voice-mode frontend enable
voice-mode frontend disable

# Utilities
voice-mode frontend open     # Open in browser
voice-mode frontend logs     # View logs
voice-mode frontend logs -f  # Follow logs

Service Integration

Both LiveKit and frontend services work with the unified service management:

# Using the service command
voice-mode service livekit status
voice-mode service frontend start
voice-mode service frontend enable

Usage Scenarios

Development Setup

For active development:

# Quick start everything
voice-mode livekit start
voice-mode frontend start

# Open the interface
voice-mode frontend open

Production Deployment

For persistent services:

# Install and enable all services
voice-mode livekit install
voice-mode livekit enable

voice-mode frontend enable

# Services now start automatically at boot/login
# Status check
voice-mode livekit status
voice-mode frontend status

Troubleshooting Setup

# Check all service status
voice-mode livekit status
voice-mode frontend status

# View logs for issues
voice-mode livekit logs --follow
voice-mode frontend logs --follow

# Restart services
voice-mode livekit restart
voice-mode frontend restart

Voice Conversations

Web Interface

1. Access: Navigate to http://localhost:3000
2. Authentication: Enter password (default: voicemode123)
3. Room Management: Create or join rooms for conversations
4. Voice Control: Click to start/stop recording and speaking

API Integration

LiveKit server provides REST API and WebSocket endpoints:

# List active rooms
curl -H "Authorization: Bearer <jwt_token>" \
     http://localhost:7880/twirp/livekit.RoomService/ListRooms \
     -H "Content-Type: application/json" -d '{}'

Generate JWT tokens for API access using development credentials:

• Key: devkey
• Secret: secret

Frontend Features

• Real-time voice conversations with AI agents
• Room-based communication supporting multiple participants
• Automatic room creation for quick setup
• Responsive web interface optimized for voice interactions
• WebRTC audio with LiveKit's optimized transport

Advanced Configuration

Custom Ports

To change default ports, edit configurations and restart services:

LiveKit server (~/.voicemode/config/livekit.yaml):

port: 8880  # Change from default 7880

Frontend (.env.local):

PORT=4000  # Change from default 3000

SSL/TLS Setup

For production deployments with SSL:

1. Configure reverse proxy (nginx, Apache)
2. Update frontend LIVEKIT_SERVER_URL to use wss://
3. Ensure LiveKit server accepts secure connections

Multiple Instances

Run multiple LiveKit instances:

# Custom config file
livekit-server --config /path/to/custom-config.yaml

# Different ports
# Edit config files to use different port ranges

Logs and Monitoring

Log Locations

• LiveKit server: ~/.voicemode/logs/livekit/livekit.log
• Frontend: ~/.voicemode/logs/frontend/frontend.log
• System services: journalctl --user -u voicemode-livekit.service

Health Checks

# Check if services are responding
curl -f http://localhost:7880/debug/info || echo "LiveKit not responding"
curl -f http://localhost:3000 || echo "Frontend not responding"

# Check process status
voice-mode livekit status
voice-mode frontend status

Performance Monitoring

Monitor resource usage:

# Service memory and CPU usage
voice-mode livekit status    # Shows memory/CPU
voice-mode frontend status   # Shows resource usage

# System monitoring
ps aux | grep livekit
ps aux | grep next-server    # Frontend process

Uninstallation

Remove Services

# Disable and stop services
voice-mode livekit disable
voice-mode livekit stop
voice-mode frontend disable

# Uninstall (removes binaries and configs)
voice-mode livekit uninstall
voice-mode livekit uninstall --remove-all-data  # Includes logs

Clean Removal

Complete cleanup:

# Remove all LiveKit data
rm -rf ~/.voicemode/logs/livekit/
rm -rf ~/.voicemode/config/livekit.yaml

# Remove frontend data  
rm -rf ~/.voicemode/logs/frontend/

# Remove service files (automatic on uninstall)

Integration with Voice Mode

MCP Tools

LiveKit services are available as MCP tools for AI agents:

• livekit_install / livekit_uninstall
• livekit_server_start / livekit_server_stop / livekit_server_status
• livekit_frontend_start / livekit_frontend_stop / livekit_frontend_status
• livekit_frontend_open / livekit_frontend_logs

Agent Integration

AI agents can manage LiveKit services programmatically and create voice conversation rooms for direct interaction.

Troubleshooting

Common Issues

Port already in use:

# Find conflicting process
lsof -ti :7880  # LiveKit
lsof -ti :3000  # Frontend

# Stop conflicting services
voice-mode livekit stop
voice-mode frontend stop

Permission denied:

# Fix service permissions (Linux)
systemctl --user daemon-reload
systemctl --user restart voicemode-livekit.service

# Fix binary permissions
sudo chmod +x /usr/local/bin/livekit-server

Frontend dependencies:

# Manual dependency install
cd ~/.voicemode/frontend  # or bundled location
npm install

# Check frontend logs
voice-mode frontend logs

Service won't start:

# Check service status
systemctl --user status voicemode-livekit.service
systemctl --user status voicemode-frontend.service

# View system logs
journalctl --user -u voicemode-livekit.service -f

Getting Help

1. Check logs first: voice-mode livekit logs and voice-mode frontend logs
2. Verify installation: voice-mode livekit status
3. Test connectivity: Access http://localhost:3000 and http://localhost:7880
4. Review configuration: Check ~/.voicemode/config/livekit.yaml

For additional support, include log outputs and system information when reporting issues.