🎥 Akool Avatar LiveKit Demo

A stunning real-time AI avatar conversation application powered by LiveKit, Akool, and OpenAI. Features a modern, responsive UI with glassmorphism design and seamless video streaming.

✨ Features

• 🤖 AI-Powered Avatar - Interactive conversations with Akool's realistic avatars
• 🎙️ Voice Conversations - Real-time voice chat using OpenAI Realtime API
• 🎨 Beautiful Modern UI - Glassmorphism design with gradient effects
• 📱 Fully Responsive - Works seamlessly on desktop, tablet, and mobile
• 👥 Multi-Participant - Support for multiple participants in the room
• ⚡ Real-Time Communication - Low-latency video/audio streaming via LiveKit

---

📑 Table of Contents

• 🎥 Akool Avatar LiveKit Demo
  • ✨ Features
  • 📑 Table of Contents
  • 📋 Prerequisites
    • 1️⃣ LiveKit Setup
      • Create a LiveKit Account
      • Create a LiveKit Project
      • Get Your API Credentials
      • Install LiveKit CLI (Optional but Recommended)
    • 2️⃣ Akool Setup
      • Create an Akool Account
      • Get Your Akool Credentials
    • 3️⃣ OpenAI Setup
      • Create an OpenAI Account
      • Get Your API Key
    • 4️⃣ Node.js & npm Setup
      • Install Node.js
      • Verify Installation
    • 5️⃣ Python & uv Setup
      • Install Python
      • Install uv (Modern Python Package Manager)
  • 🚀 Quick Start
    • 1. Clone the Repository
    • 2. Configure Environment Variables
    • 3. Install Dependencies
    • 4. Run the Application
    • 5. Open Your Browser
  • 🎨 What You'll Experience
    • Landing Page
    • Room View
    • Interaction
  • 📁 Project Structure
  • 🔧 Configuration
    • Change Avatar
    • Change Voice
    • Customize UI Colors
  • 🐛 Troubleshooting
    • "Can't find uv command"
    • "Python version not found"
    • "Failed to connect to LiveKit"
    • "Akool avatar not appearing"
    • "No audio/video in browser"
    • "Agent process fails to start"
  • 📚 Additional Resources
    • Detailed Guides
  • 🔐 Security Notes
  • 🚀 Production Deployment
  • 🤝 Contributing
  • 📄 License
  • 🙏 Acknowledgments
  • 💬 Support

---

📋 Prerequisites

Before you begin, you'll need to set up several accounts and install necessary tools.

1️⃣ LiveKit Setup

Create a LiveKit Account

1. Visit LiveKit Cloud
2. Click "Sign Up" and create your account
3. Confirm your email address

Create a LiveKit Project

1. After signing in, you'll see the dashboard
2. Click "Create Project" or "New Project"
3. Give your project a name (e.g., "akool-avatar-demo")
4. Choose a region closest to you for best performance
5. Click "Create"

Get Your API Credentials

1. In your project dashboard, navigate to Settings → API Keys
2. You'll see your credentials:
   • WebSocket URL: wss://your-project.livekit.cloud (or ws://localhost:7880 for local)
   • API Key: Starts with API...
   • API Secret: Long secret string
3. Important: Keep these credentials secure! Never commit them to public repositories

💡 Tip: For local development, you can optionally run a local LiveKit server. See LiveKit Server Setup for details.

Install LiveKit CLI (Optional but Recommended)

The LiveKit CLI is useful for testing and debugging:

macOS:

brew install livekit

Linux:

curl -sSL https://get.livekit.io/cli | bash

Windows: Download from LiveKit Releases

Verify Installation:

livekit-cli --version

Run Local Server (Optional):

livekit-server --dev

This starts a local LiveKit server with default credentials:

• URL: ws://localhost:7880
• API Key: devkey
• API Secret: secret

---

2️⃣ Akool Setup

Create an Akool Account

1. Visit Akool.com
2. Sign up for an account
3. Complete the verification process
4. Navigate to the API section in your dashboard

Get Your Akool Credentials

1. Go to API Settings or Developer Settings
2. Generate or copy your:
   • Client ID
   • Client Secret
   • API URL: Usually https://api.akool.com
3. Note your available Avatar IDs - you'll need one for the agent

📝 Note: Akool may require account approval for API access. Contact their support if needed.

---

3️⃣ OpenAI Setup

Create an OpenAI Account

1. Visit OpenAI Platform
2. Sign up or sign in
3. Add a payment method (required for API access)

Get Your API Key

1. Navigate to API Keys
2. Click "Create new secret key"
3. Give it a name (e.g., "livekit-avatar")
4. Copy the key immediately - you won't be able to see it again!
5. Store it securely

⚠️ Important: The OpenAI Realtime API requires a paid account with credits.

---

4️⃣ Node.js & npm Setup

Install Node.js

The client requires Node.js 18+ (LTS version recommended).

macOS:

# Using Homebrew
brew install node

# Or download from nodejs.org

Linux (Ubuntu/Debian):

# Using NodeSource
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows: Download the installer from nodejs.org

Verify Installation

node --version  # Should show v18.x.x or higher
npm --version   # Should show 9.x.x or higher

---

5️⃣ Python & uv Setup

Install Python

The agent requires Python 3.13+.

macOS:

# Using Homebrew
brew install [email protected]

# Or download from python.org

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3.13 python3.13-venv python3-pip

Windows: Download from python.org

Verify Installation:

python3 --version  # Should show 3.13.x or higher

Install uv (Modern Python Package Manager)

uv is a blazingly fast Python package manager that replaces pip and virtualenv.

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify Installation:

uv --version

Add to PATH (if needed):

After installation, you may need to restart your terminal or add uv to your PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.cargo/bin:$PATH"

---

🚀 Quick Start

1. Clone the Repository

git clone <your-repo-url>
cd livekit-demo

2. Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your credentials:

# LiveKit Configuration
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
LIVEKIT_ROOM=akool-demo-room

# Akool Configuration
AKOOL_CLIENT_ID=your_akool_client_id
AKOOL_CLIENT_SECRET=your_akool_client_secret
AKOOL_API_URL=https://api.akool.com

# OpenAI Configuration
OPENAI_API_KEY=sk-your_openai_api_key

3. Install Dependencies

Python Dependencies:

First, create a virtual environment (optional but recommended):

# Create a virtual environment with uv
uv venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

Then install dependencies:

uv sync

💡 Note: uv sync will automatically create a virtual environment if one doesn't exist, but creating it explicitly gives you more control.

Client Dependencies:

cd client
npm install
cd ..

4. Run the Application

Option A: Using the Start Script (Easiest)

Run everything with a single command:

bash start.sh

This automatically starts the main server (token server + agent).

Option B: Single Command (Main Server)

The main server automatically spawns the agent:

uv run main.py

This starts:

• Token server on http://localhost:5050
• LiveKit agent automatically

Option C: Separate Processes (Development)

Terminal 1 - Token Server:

uv run token_server.py

Terminal 2 - Agent:

uv run agent.py dev

Start the Client:

In a new terminal:

cd client
npm run dev

5. Open Your Browser

Visit http://localhost:5173

Click "Join Avatar Session" to connect!

---

🎨 What You'll Experience

Landing Page

• Stunning purple/blue gradient background
• Glassmorphism card with smooth animations
• One-click connection to avatar session
• Real-time error handling

Room View

• Featured Avatar Display: Large, centered video of the Akool avatar
• Connection Status: Live indicator showing connection state
• Participant Grid: Other room participants shown below
• Easy Controls: Leave button to exit the session

Interaction

• Speak naturally - the avatar responds in real-time
• See your microphone input visualized
• Watch the avatar's lip-sync and expressions
• Smooth, low-latency communication

---

📁 Project Structure

livekit-demo/
├── agent.py              # LiveKit agent with Akool integration
├── main.py               # Main server (token + agent spawning)
├── token_server.py       # Standalone token server (alternative)
├── pyproject.toml        # Python dependencies
├── .env.example          # Environment variables template
├── client/               # React frontend
│   ├── src/
│   │   ├── App.tsx       # Main React component
│   │   ├── App.css       # Custom styles
│   │   └── main.tsx      # Entry point
│   ├── package.json      # Node dependencies
│   └── vite.config.ts    # Vite configuration
└── livekit-plugins-akool/  # Custom Akool plugin

---

🔧 Configuration

Change Avatar

Edit agent.py line 34:

avatar_config=akool.AvatarConfig(
    avatar_id="your_preferred_avatar_id"  # Change this
),

Change Voice

Edit agent.py line 21:

voice="alloy",  # Options: alloy, echo, fable, onyx, nova, shimmer

Customize UI Colors

Edit client/src/App.tsx to change the gradient colors, borders, and effects.

---

🐛 Troubleshooting

"Can't find uv command"

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Restart terminal or source your profile
source ~/.zshrc  # or ~/.bashrc

"Python version not found"

# Install specific Python version with uv
uv python install 3.13

"Failed to connect to LiveKit"

• Check your LIVEKIT_URL in .env
• Verify API credentials are correct
• Ensure LiveKit server is running (local or cloud)
• Check firewall/network settings

"Akool avatar not appearing"

• Verify Akool credentials in .env
• Check that the avatar_id in agent.py is valid
• Look for errors in the agent console
• Ensure you have API access enabled

"No audio/video in browser"

• Allow microphone permissions in your browser
• Use HTTPS for production (required for getUserMedia)
• Try Chrome/Edge for best WebRTC support
• Check browser console for errors

"Agent process fails to start"

# Check if uv is working
uv --version

# Check Python version
uv run python --version

# Check for errors in .env file
cat .env

---

📚 Additional Resources

• LiveKit Documentation: docs.livekit.io
• LiveKit Agents Guide: docs.livekit.io/agents
• Akool Documentation: akool.com/docs
• OpenAI Realtime API: platform.openai.com/docs
• React Documentation: react.dev
• Vite Documentation: vitejs.dev

Detailed Guides

For more detailed information, see:

• QUICKSTART.md - Quick start guide
• README_SETUP.md - Detailed setup and features
• IMPLEMENTATION_SUMMARY.md - Technical implementation details

---

🔐 Security Notes

1. Never commit .env files to version control
2. Use environment variables for all sensitive credentials
3. Rotate API keys regularly
4. Use HTTPS in production
5. Implement rate limiting for production deployments
6. Validate all user inputs on the server side

---

🚀 Production Deployment

For production deployment:

1. Use HTTPS: Required for browser media access
2. Environment Variables: Use proper secrets management
3. Process Manager: Use PM2, systemd, or Docker for the agent
4. CDN: Serve static assets via CDN
5. Monitoring: Set up logging and monitoring
6. Load Balancing: Scale horizontally if needed

Example with PM2:

# Install PM2
npm install -g pm2

# Start server
pm2 start main.py --interpreter uv

# Start client build
cd client && npm run build

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📄 License

This project is provided as-is for demonstration purposes. Check individual library licenses for production use.

---

🙏 Acknowledgments

• LiveKit - Real-time communication infrastructure
• Akool - AI avatar technology
• OpenAI - AI conversation capabilities
• React - UI framework
• Tailwind CSS - Styling framework

---

💬 Support

For issues and questions:

• Check the Troubleshooting section
• Review the detailed guides in the documentation folder
• Open an issue in the repository

---

Built with ❤️ using LiveKit, Akool, and OpenAI

🎉 Now go build something amazing!