Skip to main content

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.

​
Hamsa LiveKit Integration

A LiveKit integration 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

git clone https://github.com/hamsa-ai/hamsa_livekit.git
cd hamsa_livekit
pip install -e .

​
2. Configuration

Create a .env file: 
# 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

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

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

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 to get you there, and here to get you to the voices page on Hamsa Media.
DialectCodeSome of the Recommended Voices
PalestinianplsAmjad, Layan, Talin, Rema, Obida
LebaneselebCarla, Majd
JordanianjorLana, Omar, Nada
SyriansyrDalal, Mais
SaudiksaHiba, Saly, Fahd, Jasem
BahrainibahMazen, Hafsa
EmiratiuaeSalma, Dima
EgyptianegyMariam, Samir, Ali, Ahmed
IraqiirqAml, Fatma

​
πŸ“ Quick Examples

​
STT-Only Agent

session = AgentSession(
    stt=hamsa_livekit.STT(language="ar"),
    llm=None,
    tts=None,
    vad=silero.VAD.load(),
    turn_detection="vad",
)

​
TTS-Only Agent

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

# 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

# Basic run
python your_agent.py dev

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

​
πŸ†˜ Support