livekit-voice-assistant/Readme.md

A customizable voice assistant component built with LiveKit

# LiveKit Voice Assistant

A customizable voice assistant component built with LiveKit. This package provides an easy-to-use React component that integrates with LiveKit's voice API.

## Features

- 🎤 Voice Assistant UI with visualizer
- 🔊 Audio input/output handling
- 🔄 Connection management
- 🛠️ Customizable styling
- 🔌 Easy integration with Next.js
- 📋 Environment variable support

## Installation

```bash
npm install livekit-voice-assistant
# or
yarn add livekit-voice-assistant
```

## Environment Variables

Create a `.env.local` file in your project root with the following variables:

```
LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret
LIVEKIT_URL=wss://your-livekit-domain.com
NEXT_PUBLIC_CONN_DETAILS_ENDPOINT=/api/voice-assistant
```

## Server-Side Setup

### Next.js API Route (Pages Router)

Create an API route at `pages/api/voice-assistant.js`:

```javascript
import { nextApiHandler } from 'livekit-voice-assistant';

export default async function handler(req, res) {
  return nextApiHandler(req, res);
}
```

### Next.js App Router

Create an API route at `app/api/voice-assistant/route.ts`:

```typescript
import { nextAppRouteHandler } from 'livekit-voice-assistant';

export async function POST(req: Request) {
  return nextAppRouteHandler(req);
}
```

## Client-Side Usage

```jsx
import { VoiceAssistant } from 'livekit-voice-assistant';
import 'livekit-voice-assistant/dist/index.css';

export default function MyPage() {
  return (
    <div>
      <h1>My App</h1>
      
      {/* Basic usage */}
      <VoiceAssistant />
      
      {/* With custom props */}
      <VoiceAssistant 
        userName="John Doe"
        buttonText="Talk to AI"
        buttonClassName="my-custom-button"
        containerClassName="my-custom-container"
        onStateChange={(state) => console.log('State changed:', state)}
      />
    </div>
  );
}
```

## Advanced Configuration

### Customizing the API Endpoint

```jsx
<VoiceAssistant 
  connectionDetailsEndpoint="/api/my-custom-endpoint" 
/>
```

### Event Handlers

```jsx
<VoiceAssistant 
  onConnected={() => console.log('Connected!')}
  onDisconnected={() => console.log('Disconnected!')}
  onError={(error) => console.error('Error:', error)}
  onStateChange={(state) => console.log('State:', state)}
/>
```

### Custom Styling

The component comes with default styling, but you can customize it using the provided class names or by passing custom class names:

```jsx
<VoiceAssistant 
  buttonClassName="bg-blue-500 hover:bg-blue-600 text-white px-4 py-2 rounded"
  containerClassName="w-80 bg-gray-800 rounded-lg shadow-2xl"
/>
```

## API Reference

### VoiceAssistant Props

| Prop | Type | Description |
|------|------|-------------|
| `connectionDetailsEndpoint` | string | API endpoint for connection details |
| `userName` | string | User name to display |
| `agentId` | string | Agent ID for identification |
| `userId` | string | User ID for identification |
| `buttonText` | string | Custom button text |
| `buttonClassName` | string | Custom styles for the button |
| `containerClassName` | string | Custom styles for the container |
| `onError` | function | Callback when error occurs |
| `onConnected` | function | Callback when connected |
| `onDisconnected` | function | Callback when disconnected |
| `onStateChange` | function | Callback when state changes |

## Troubleshooting

### Agent Not Connecting

If you see the "It's quiet... too quiet" message, ensure:
1. Your LiveKit server is running
2. Your environment variables are correctly set
3. The agent is properly configured and running

### Microphone Permissions

If the microphone doesn't work, ensure your application has the proper permissions.

## License

MIT