> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Live kit plugin

# Hamsa LiveKit Integration

A [LiveKit integration](https://github.com/hamsa-ai/hamsa_livekit) for Hamsa AI's advanced Arabic speech technology, providing state-of-the-art Speech-to-Text (STT) and Text-to-Speech (TTS) capabilities with support for multiple Arabic dialects.

## 🌟 Features

* **🎙️ Advanced Arabic STT**: High-accuracy speech recognition across Arabic dialects
* **🔊 Natural Arabic TTS**: Lifelike text-to-speech with 24 Arabic voices
* **🌍 Multi-Dialect Support**: 9 Arabic dialects supported
* **⚡ Real-time Processing**: Low-latency streaming for live conversations
* **🤖 LiveKit Agent Integration**: Seamless integration with LiveKit's agent framework

## 🚀 Installation

### 1. Clone the Repository

```bash theme={null}
git clone https://github.com/hamsa-ai/hamsa_livekit.git
cd hamsa_livekit
pip install -e .
```

### 2. Configuration

Create a `.env` file:

```env theme={null}
# LiveKit Configuration
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
LIVEKIT_URL=wss://your-project.livekit.cloud

# Hamsa AI Configuration
HAMSA_API_KEY=your_hamsa_api_key
```

## 🔧 Usage

### Basic LiveKit Agent with Hamsa

```python theme={null}
from dotenv import load_dotenv
from livekit import agents
from livekit.agents import AgentSession, Agent, RoomInputOptions
from livekit.plugins import openai, noise_cancellation, silero
import hamsa_livekit

load_dotenv()

class HamsaAssistant(Agent):
    def __init__(self) -> None:
        super().__init__(instructions="You are a helpful Arabic voice assistant.")

async def entrypoint(ctx: agents.JobContext):
    await ctx.connect()

    # Create agent session with Hamsa STT and TTS
    session = AgentSession(
        stt=hamsa_livekit.STT(language="ar"),
        llm=openai.LLM(model="gpt-4.1"),
        tts=hamsa_livekit.TTS(speaker="Lana", dialect="jor"),
        vad=silero.VAD.load(),
        turn_detection="vad",
    )

    await session.start(
        room=ctx.room,
        agent=HamsaAssistant(),
        room_input_options=RoomInputOptions(
            noise_cancellation=noise_cancellation.BVC(),
        ),
    )

    await session.generate_reply(
        instructions="Greet the user in Arabic and offer your assistance."
    )

if __name__ == "__main__":
    agents.cli.run_app(agents.WorkerOptions(entrypoint_fnc=entrypoint))
```

### Configuration Options

#### STT Configuration

```python theme={null}
stt = hamsa_livekit.STT(
    language="ar",                    # Arabic language code
    api_key=None,                    # Optional API key override
    base_url="...",                  # Optional base URL override
    http_session=None                # Optional HTTP session
)
```

#### TTS Configuration

```python theme={null}
tts = hamsa_livekit.TTS(
    speaker="Ali",                    # Voice speaker name (default: "Ali")
    dialect="pls",                   # Dialect code (default: "pls")
    mulaw=False,                     # μ-law encoding (default: False)
    sample_rate=16000,               # Audio sample rate (default: 16000)
    api_key=None,                    # Optional API key override
    base_url="...",                  # Optional base URL override
    word_tokenizer=None,             # Optional word tokenizer
    http_session=None                # Optional HTTP session
)
```

## 🎙️ Available Voices & Dialects

### Speakers (around 99 voices available)

Those are some voices examples and the the corresponding dialects in the below table:
`Amjad`, `Aml`, `Salma`, `Mariam`, `Dalal`, `Lana`, `Omar`, `Jasem`, `Samir`, `Carla`, `Nada`, `Mais`, `Fatma`, `Hiba`, `Ali`, `Layan`, `Saly`, `Mazen`, `Hafsa`, `Dima`, `Majd`, `Talin`, `Ahmed`, `Rema`, `Fahd`, `Rami`

You can get more voices from one of our platforms, on Hamsa Agents, click [here](https://agents.tryhamsa.com/app/voices) to get you there, and [here](https://media.tryhamsa.com/app/voices) to get you to the voices page on Hamsa Media.

### Dialects & Recommended Voices

| Dialect     | Code  | Some of the Recommended Voices   |
| ----------- | ----- | -------------------------------- |
| Palestinian | `pls` | Amjad, Layan, Talin, Rema, Obida |
| Lebanese    | `leb` | Carla, Majd                      |
| Jordanian   | `jor` | Lana, Omar, Nada                 |
| Syrian      | `syr` | Dalal, Mais                      |
| Saudi       | `ksa` | Hiba, Saly, Fahd, Jasem          |
| Bahraini    | `bah` | Mazen, Hafsa                     |
| Emirati     | `uae` | Salma, Dima                      |
| Egyptian    | `egy` | Mariam, Samir, Ali, Ahmed        |
| Iraqi       | `irq` | Aml, Fatma                       |

## 📝 Quick Examples

### STT-Only Agent

```python theme={null}
session = AgentSession(
    stt=hamsa_livekit.STT(language="ar"),
    llm=None,
    tts=None,
    vad=silero.VAD.load(),
    turn_detection="vad",
)
```

### TTS-Only Agent

```python theme={null}
session = AgentSession(
    stt=None,
    llm=openai.LLM(model="gpt-4.1"),
    tts=hamsa_livekit.TTS(speaker="Mariam", dialect="egy"),
    vad=silero.VAD.load(),
    turn_detection="vad",
)
```

### Custom Audio Settings

```python theme={null}
# High-quality TTS with custom sample rate
tts = hamsa_livekit.TTS(
    speaker="Amjad", 
    dialect="pls",
    sample_rate=24000,  # Higher quality
    mulaw=True          # μ-law encoding
)
```

## 🛠️ Running Your Agent

```bash theme={null}
# Basic run
python your_agent.py dev

# With specific room
python your_agent.py connect --room your-room-name --token your-token
```

## 🆘 Support

* **API Reference**: [docs.tryhamsa.com/api-reference/introduction](https://docs.tryhamsa.com/api-reference/introduction)
* **Email**: [support@tryhamsa.com](mailto:support@tryhamsa.com)