# Livekit Integration

Async Voice API integrates with **LiveKit Agents** via the official `livekit-plugins-asyncai` [plugin](https://github.com/livekit/agents/tree/main/livekit-plugins/livekit-plugins-asyncai/livekit/plugins/asyncai), enabling **low-latency, streaming text-to-speech** for real-time voice agents.

This integration is **streaming-first** and optimized for conversational and real-time playback scenarios.

---

## Features

* Real-time **streaming TTS**
* Low time-to-first-byte (TTFB)
* Natural, human-like voices
* Designed for LiveKit Agents lifecycle
* Automatic connection cleanup and reconnection handling

---

## Prerequisites

* Async Voice API account
* Async API key
* LiveKit Agents project (JS/TS or Python)
* Node.js or Python runtime

---

## Installation

### JavaScript / TypeScript

```bash
npm install livekit-agents livekit-plugins-asyncai
# or
pnpm add livekit-agents livekit-plugins-asyncai
# or
yarn add livekit-agents livekit-plugins-asyncai
```

### Python

```bash
pip install livekit-agents livekit-plugins-asyncai
```

---

## Configuration

### Environment variable

```bash
export ASYNCAI_API_KEY="YOUR_ASYNCAI_API_KEY"
```
---
## Usage

### JavaScript / TypeScript

```ts
import { Agent } from "livekit-agents";
import { tts } from "livekit-plugins-asyncai";

const agent = new Agent({
  tts: tts.TTS({
    apiKey: process.env.ASYNCAI_API_KEY!,
  }),
});
```

### Python

```py
import os
from livekit.agents import Agent
from livekit.plugins.asyncai import tts

agent = Agent(
    tts=tts.AsyncAITTS(
        api_key=os.environ["ASYNC_API_KEY"],
    )
)
```

---

## Streaming-only behavior

The Async LiveKit TTS provider **supports streaming only**.

If a non-streaming synthesis method is used, the provider will raise:

```text
AsyncAI TTS supports streaming only; use tts.stream().
```

This behavior is intentional and ensures optimal latency and real-time playback.

---

## Connection lifecycle & error handling

* WebSocket connections are managed by the LiveKit Agents lifecycle
* Connections are closed automatically on agent shutdown
* Safe reconnects are handled in case of transient errors
* Improved exception handling is inherited from the base LiveKit TTS service

---

## Troubleshooting

* Ensure `ASYNCAI_API_KEY` is set and valid
* Verify outbound network access to Async endpoints
* Check version compatibility between:

  * `livekit-agents`
  * `livekit-plugins-asyncai`

---

## Summary

Async Voice API provides a **streaming-first, low-latency** TTS [integration for LiveKit Agents](https://github.com/livekit/agents/tree/main/livekit-plugins/livekit-plugins-asyncai/livekit/plugins/asyncai), purpose-built for real-time voice and conversational AI systems.