# pipecat-plugins-faseeh

Pipecat plugin for [Faseeh](https://faseeh.ai) Arabic text-to-speech.

Build real-time Arabic conversational AI agents using [Pipecat](https://github.com/pipecat-ai/pipecat) with Faseeh's high-quality Arabic TTS voices.

## Installation

```bash
pip install pipecat-plugins-faseeh
```

## Configuration

Set your Faseeh API key as an environment variable:

```bash
export FASEEH_API_KEY="your-api-key"
```

Or pass it directly:

```python
tts = FaseehTTSService(api_key="your-api-key", aiohttp_session=session)
```

Get your API key at [app.faseeh.ai](https://app.faseeh.ai).

### Parameters

| Parameter   | Type   | Default                          | Description                        |
|-------------|--------|----------------------------------|------------------------------------|
| `api_key`   | str    | env `FASEEH_API_KEY`             | Faseeh API key                     |
| `voice_id`  | str    | `ar-hijazi-female-2`             | Voice identifier                   |
| `model`     | str    | `faseeh-v1-preview`              | TTS model                          |
| `stability` | float  | 0.5                              | Voice consistency (0.0-1.0)        |
| `speed`     | float  | 1.0                              | Speech rate (0.7-1.2)              |
| `base_url`  | str    | `https://api.faseeh.ai/api/v1`   | API base URL                       |

## Usage

```python
import aiohttp
from pipecat.pipeline.pipeline import Pipeline
from pipecat_plugins_faseeh import FaseehTTSService

async with aiohttp.ClientSession() as session:
    tts = FaseehTTSService(
        api_key="your-api-key",
        aiohttp_session=session,
        voice_id="ar-hijazi-female-2",
        model="faseeh-v1-preview",
        params=FaseehTTSService.InputParams(stability=0.5, speed=1.0),
    )

    # Add to your Pipecat pipeline
    pipeline = Pipeline([..., tts, ...])
```

### Runtime settings update

Change voice, model, speed, or stability mid-conversation:

```python
from pipecat.frames.frames import TTSUpdateSettingsFrame

await task.queue_frame(TTSUpdateSettingsFrame(settings={"voice_id": "ar-emirati-male-1"}))
await task.queue_frame(TTSUpdateSettingsFrame(settings={"speed": 1.1, "stability": 0.8}))
```

## Running the example

```bash
# Install dependencies
pip install pipecat-plugins-faseeh "pipecat-ai[daily,openai,deepgram,silero]" python-dotenv loguru

# Copy and fill in your API keys
cp .env.example .env

# Run
python examples/faseeh_tts_example.py
```

The example auto-creates a Daily room and logs the URL — open it in your browser to talk to the bot.

## Available voices

See the full voice library at [docs.faseeh.ai](https://docs.faseeh.ai).

## Pipecat compatibility

Tested with `pipecat-ai >= 0.0.100`.

## License

Apache 2.0

## Maintained by

[Actualize](https://actualize.ae)
