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

# LiveKit Plugin

> Integrate Munsit Arabic TTS with LiveKit voice agents

# Integrating Munsit with LiveKit Agents

This tutorial will guide you through integrating Munsit's Arabic text-to-speech into your LiveKit voice agents, enabling natural-sounding Arabic conversations in your real-time applications.

## Prerequisites

* A [Munsit AI](https://app.munsit.com/) account
* Python 3.9 or higher installed
* Basic familiarity with LiveKit Agents framework
* A LiveKit Cloud account (or self-hosted LiveKit server)

## API Key

Go to [Munsit - API Keys](https://app.munsit.com//en/api-keys), Generate an API key, then save it securely.

<Warning>
  Your API key is only shown once. Save it securely.
</Warning>

## Installation

Install the Munsit plugin for LiveKit Agents:

```bash theme={null}
pip install livekit-plugins-faseeh
```

For development or testing from source:

```bash theme={null}
git clone https://github.com/actualize-ae/livekit-plugins-faseeh.git
cd livekit-plugins-faseeh
pip install -e .
```

## Step 3: Set Up Your Environment

Create a `.env.local` file in your project directory to store your API keys securely:

```bash theme={null}
# Munsit Configuration
MUNSIT_API_KEY=your_MUNSIT_API_KEY_here

# LiveKit Configuration
LIVEKIT_URL=wss://your-livekit-server.com
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret

# LLM Configuration (for the agent's brain)
OPENAI_API_KEY=your_openai_api_key

# Optional: Deepgram for Arabic STT
DEEPGRAM_API_KEY=your_deepgram_api_key
```

## Step 4: Create Your First Arabic Voice Agent

Create a file called `arabic_agent.py`:

```python theme={null}
"""
Simple Arabic Voice Assistant using Munsit TTS
"""
from dotenv import load_dotenv
from livekit import agents
from livekit.agents import AgentServer, AgentSession, Agent
from livekit.plugins import silero, deepgram, openai, faseeh

# Load environment variables
load_dotenv(".env.local")


class ArabicAssistant(Agent):
    """Arabic-speaking voice assistant"""

    def __init__(self) -> None:
        super().__init__(
            instructions="""أنت مساعد صوتي ذكي يتحدث العربية بطلاقة.
            مهمتك مساعدة المستخدمين بالإجابة على أسئلتهم بطريقة واضحة ومفيدة.
            كن ودوداً ومحترماً في تعاملك."""
        )


# Create the agent server
server = AgentServer()


@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
    """Entry point for each agent session"""

    # Configure Munsit TTS
    faseeh_tts = faseeh.TTS(
        voice_id="ar-uae-male-1",           # Choose your voice
        model="faseeh-v1-preview",          # Use full model for best quality
        stability=0.75,                     # Balanced stability
        speed=1.0,                          # Normal speech speed (0.7-1.2)
    )

    # Create agent session with all components
    session = AgentSession(
        stt=openai.STT(),
        llm=openai.LLM(                     # Language model
            model="gpt-4o",
            temperature=0.7
        ),
        tts=faseeh_tts,                     # Munsit for Arabic speech
        vad=silero.VAD.load(),              # Voice activity detection
    )

    # Start the session
    await session.start(
        room=ctx.room,
        agent=ArabicAssistant()
    )

    # Generate initial greeting
    await session.generate_reply(
        instructions="رحب بالمستخدم باللغة العربية وقدم نفسك كمساعد ذكي جاهز للمساعدة."
    )


if __name__ == "__main__":
    agents.cli.run_app(server)
```

## Step 5: Run Your Agent

### Development Mode

For local testing with LiveKit's dev server:

```bash theme={null}
python arabic_agent.py dev
```

This will:

1. Start a local LiveKit server
2. Launch your agent
3. Provide a test URL you can open in your browser

### Production Mode

For deployment with your LiveKit Cloud or self-hosted server:

```bash theme={null}
python arabic_agent.py start
```

Make sure your LiveKit credentials are properly configured in `.env.local`.

## Step 6: Test Your Agent

1. Open the provided URL in your web browser
2. Allow microphone access when prompted
3. Speak in Arabic - the agent will respond using Munsit's natural-sounding voice
4. Try different questions to test the conversation flow

## Configuration Options

### Available Voice IDs

To choose a voice for your agent:

1. Visit the [Munsit Voice Library](https://app.munsit.com//en/voices)
2. Listen to different voices to find the one that best fits your use case
3. Click **"Copy Voice ID"** button next to your chosen voice
4. Use that voice ID in your code:

```python theme={null}
faseeh_tts = faseeh.TTS(
    voice_id="ar-uae-male-1",  # Paste the copied voice ID here
    model="faseeh-v1-preview",
    speed=1.0                  # Speech speed (0.7-1.2)
)
```

### Model Selection

Choose between two models based on your needs:

```python theme={null}
# Full model - Best quality, slightly higher latency
faseeh_tts = faseeh.TTS(
    model="faseeh-v1-preview",
    stability=0.75,
    speed=1.0
)

# Mini model - Faster, lower latency, good quality
faseeh_tts = faseeh.TTS(
    model="faseeh-mini-v1-preview",
    stability=0.75,
    speed=1.0
)
```

### Stability Parameter

The `stability` parameter controls voice consistency:

* **0.0 - 0.4**: More expressive, creative, but can hallucinate
* **0.5 - 0.7**: Balanced (recommended for most use cases)
* **0.8 - 1.0**: Very consistent, less variation

```python theme={null}
# Dynamic voice - More expressive
faseeh_tts = faseeh.TTS(stability=0.4, speed=1.0)

# Consistent voice - Professional applications
faseeh_tts = faseeh.TTS(stability=0.9, speed=1.0)
```

### Speed Parameter

The `speed` parameter controls speech rate:

* **0.7 - 0.9**: Slower speech (clearer for complex content)
* **1.0**: Normal speed (default)
* **1.1 - 1.2**: Faster speech (for quick responses)

```python theme={null}
# Slower speech - For clear enunciation
faseeh_tts = faseeh.TTS(stability=0.75, speed=0.8)

# Faster speech - For rapid delivery
faseeh_tts = faseeh.TTS(stability=0.75, speed=1.2)
```

### Dynamic Voice Switching

You can change voice settings during runtime:

```python theme={null}
# Start with one voice
faseeh_tts = faseeh.TTS(voice_id="ar-uae-male-1", speed=1.0)

# Switch to a different voice based on context
faseeh_tts.update_options(
    voice_id="ar-hijazi-female-2",
    stability=0.8,
    speed=1.0
)
```

## Advanced Features

### Bilingual Support

Create agents that can switch between Arabic and English:

```python theme={null}
class BilingualAssistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="""You are a bilingual AI assistant fluent in both Arabic and English.
            Automatically detect the user's language and respond in the same language.
            If the user speaks Arabic, respond in Arabic using natural expressions.
            If the user speaks English, respond in English."""
        )

@server.rtc_session()
async def bilingual_agent(ctx: agents.JobContext):
    session = AgentSession(
        stt=deepgram.STT(
            language="multi",  # Multi-language support
            model="nova-2-general"
        ),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=faseeh.TTS(
            voice_id="ar-uae-male-1",
            model="faseeh-v1-preview",
            speed=1.0
        ),
        vad=silero.VAD.load(),
    )

    await session.start(room=ctx.room, agent=BilingualAssistant())
```

### Streaming for Low Latency

Munsit supports streaming for real-time applications:

```python theme={null}
# Streaming is automatically enabled
# The agent will start speaking as soon as the first audio chunk is ready
faseeh_tts = faseeh.TTS(
    model="faseeh-mini-v1-preview",  # Mini model for even lower latency
    stability=0.6,
    speed=1.0
)
```

## Monitoring and Metrics

Track your agent's performance:

```python theme={null}
from livekit.agents.metrics import TTSMetrics
import logging

logger = logging.getLogger("faseeh_agent")

@session.on("metrics_collected")
def _on_metrics_collected(event):
    metrics = event.metrics

    if isinstance(metrics, TTSMetrics):
        logger.info(
            f"TTS Performance - "
            f"TTFB: {metrics.ttfb:.2f}s, "
            f"Audio Duration: {metrics.audio_duration:.2f}s"
        )
```

## Best Practices

### 1. API Key Security

✅ **DO:**

* Store API keys in `.env.local` (not committed to Git)
* Use environment variables in production
* Rotate keys periodically

❌ **DON'T:**

* Hardcode API keys in source code
* Commit `.env` files to version control
* Share API keys in chat or email

### 2. Stability Settings

* **Chatbots**: 0.6 - 0.8 (balanced and reliable)
* **Professional Applications**: 0.8 - 1.0 (very consistent)
* **Creative Content**: 0.3 - 0.5 (more expressive)

## Troubleshooting

### "Invalid API Key" Error

**Solution**: Double-check your API key in `.env.local`

```bash theme={null}
# Verify the key is set correctly
echo $MUNSIT_API_KEY
```

### "Payment Required" Error

**Solution**: Your Munsit account balance is low. Top up at [app.munsit.com](https://app.munsit.com/)

### "Rate Limit Exceeded"

**Solution**: You're sending too many requests. Implement rate limiting or contact Munsit support to increase your limits.

### No Audio Output

**Checklist:**

1. ✅ API key is valid
2. ✅ Network connection is stable
3. ✅ Microphone permissions are granted
4. ✅ Browser supports WebRTC
5. ✅ Firewall allows WebSocket connections

### Poor Audio Quality

**Solutions:**

* Switch to `faseeh-v1-preview` (full model)
* Increase stability to 0.8 or higher
* Check your network connection
* Ensure proper audio codec support

## Support

Need help?

* **Plugin Issues**: [GitHub Issues](https://github.com/actualize-ae/livekit-plugins-faseeh/issues)
* **Munsit Support**: [Schedule a Meeting](https://calendar.google.com/calendar/u/0/appointments/schedules/AcZssZ1fgxJD82YNieOXrhWQ1_SfuJLthGBx7YDy3AQhdtdS7brN5Y3ZH_OKHkeIwhBTnmTZqkKjSQVI)
* **LiveKit Support**: [LiveKit Community](https://livekit.io/community)

## License

This plugin is licensed under Apache License 2.0. See [LICENSE](https://github.com/actualize-ae/livekit-plugins-faseeh/blob/main/LICENSE) for details.