livekit-plugins-faseeh 0.1.5

LiveKit Agents plugin for Arabic text-to-speech with Faseeh AI.

Faseeh Plugin for LiveKit Agents

This plugin provides Arabic text-to-speech capabilities using Faseeh AI for LiveKit Agents.

Installation

From PyPI (once published)

pip install livekit-plugins-faseeh

From Source

git clone https://github.com/yourusername/livekit-plugins-faseeh.git
cd livekit-plugins-faseeh
pip install -e .

Quick Start

Basic Usage

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_dotenv()

class ArabicAssistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="أنت مساعد صوتي ذكي يتحدث العربية."
        )

server = AgentServer()

@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
    # Create Faseeh TTS instance
    faseeh_tts = faseeh.TTS(
        voice_id="ar-hijazi-female-2",
        model="faseeh-mini-v1-preview",
        stability=0.6,
    )

    session = AgentSession(
        stt=deepgram.STT(language="ar"),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=faseeh_tts,  # Use Faseeh for Arabic TTS
        vad=silero.VAD.load(),
    )

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

    # Greet in Arabic
    await session.generate_reply(
        instructions="رحب بالمستخدم وقدم المساعدة."
    )

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

Run the Agent

# Set environment variables
export FASEEH_API_KEY=your-api-key
export OPENAI_API_KEY=your-openai-key

# Run in development mode
python agent.py dev

See the examples/ directory for more complete examples including bilingual support, noise cancellation, and dynamic voice switching.

Configuration

Environment Variables

Set your Faseeh API key:

export FASEEH_API_KEY=your_api_key_here

TTS Options

The TTS class accepts the following parameters:

• voice_id (str): Voice ID to use. Default: "ar-hijazi-female-2"
• model (str): Model to use. Options:
  • "faseeh-v1-preview" - Full model
  • "faseeh-mini-v1-preview" - Faster, lighter model (default)
• stability (float): Voice stability from 0.0 to 1.0. Higher values produce more consistent output. Default: 0.5
• api_key (str, optional): API key. If not provided, uses FASEEH_API_KEY environment variable
• base_url (str, optional): Custom API base URL
• http_session (aiohttp.ClientSession, optional): Custom HTTP session

Update Options

You can update TTS options dynamically:

faseeh_tts.update_options(
    voice_id="ar-hijazi-female-2",
    model="faseeh-v1-preview",
    stability=0.7,
)

Streaming Mode

For real-time applications, use streaming mode:

# Create streaming instance
stream = faseeh_tts.stream()

# Push text incrementally
stream.push_text("مرحبا ")
stream.push_text("كيف حالك")

# Flush and end input
stream.flush()
stream.end_input()

# Receive audio chunks as they're generated
async for event in stream:
    # Process audio frames in real-time
    if hasattr(event, "frame"):
        audio_frame = event.frame

Features

• ✅ Arabic text-to-speech synthesis
• ✅ Multiple voice options
• ✅ Adjustable voice stability
• ✅ Two model options (standard and mini)
• ✅ 24kHz PCM16 audio output
• ✅ Both streaming and non-streaming modes
• ✅ Low-latency streaming for real-time applications

Models

Model	Description
faseeh-v1-preview	Full-featured model with highest quality
faseeh-mini-v1-preview	Faster, lighter model for low-latency applications

Error Handling

The plugin handles the following error codes:

• 400: Bad request (invalid parameters)
• 401: Unauthorized (invalid API key)
• 402: Payment required (insufficient wallet balance)
• 403: Forbidden (model not enabled for account)
• 404: Model or voice not found
• 429: Rate limit exceeded

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For issues or questions:

• Plugin Issues: GitHub Issues
• Faseeh AI: [e-mail]
• LiveKit: https://docs.livekit.io

Acknowledgments

• Faseeh AI for providing the Arabic TTS API
• LiveKit for the Agents framework

License

Apache License 2.0 - see LICENSE file for details