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.5api_key(str, optional): API key. If not provided, usesFASEEH_API_KEYenvironment variablebase_url(str, optional): Custom API base URLhttp_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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Support
For issues or questions:
- Plugin Issues: GitHub Issues
- Faseeh AI: apps@actualize.pro
- LiveKit: https://docs.livekit.io
Acknowledgments
License
Apache License 2.0 - see LICENSE file for details
Metadata
Release files for livekit-plugins-faseeh 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| livekit_plugins_faseeh-0.1.5.tar.gz | 12.1 kB | Without provenance | Details for livekit_plugins_faseeh-0.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| livekit_plugins_faseeh-0.1.5-py3-none-any.whl | Python 3 | none | any | Details for livekit_plugins_faseeh-0.1.5-py3-none-any.whl |
Total release size: 26.0 kB
Release files / livekit_plugins_faseeh-0.1.5.tar.gz
| Download URL | livekit_plugins_faseeh-0.1.5.tar.gz |
|---|---|
| Size | 12.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cb9a1d64bcbb89e03ee997e8613a537c7fafcaa48a104cf2724671143753a6ec
|
|
BLAKE2b-256 checksum How to use checksums |
75cc9978bcc06f1b9c881c57d4bca6aa42848e5a6686bed02f05bdd55396b4e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Release files / livekit_plugins_faseeh-0.1.5-py3-none-any.whl
| Download URL | livekit_plugins_faseeh-0.1.5-py3-none-any.whl |
|---|---|
| Size | 13.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8b4d830e84d53b636cacffb55c3e8bfb0839c8d66ba466c0e107725d510540e5
|
|
BLAKE2b-256 checksum How to use checksums |
7f529f2154978788b54b54682c2804af2ceb07eaca554a787ba9d2ecfefdd678
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Security for livekit-plugins-faseeh 0.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.