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

# LiveKit adapter reference

> Python adapters for SomyaLabs ASR and TTS in LiveKit Agents.

Save the following code as `somya_livekit.py` beside the `agent.py` from the
[LiveKit quickstart](https://docs.somya.ai/integrations/livekit.md). These adapters call the SomyaLabs
HTTP API; they are example code for your agent project, not a published plugin.

```python theme={null}
import base64
import io
import json
import wave
from uuid import uuid4

import httpx
from livekit import rtc
from livekit.agents import (
    APIConnectOptions,
    DEFAULT_API_CONNECT_OPTIONS,
    stt,
    tts,
)
from livekit.agents.types import NOT_GIVEN, NotGivenOr

SOMYA_BASE_URL = "https://api.somya.ai"


class SomyaSTT(stt.STT):
    def __init__(self, api_key: str):
        super().__init__(capabilities=stt.STTCapabilities(streaming=False, interim_results=False))
        self.api_key = api_key
        self.client = httpx.AsyncClient(timeout=120)

    @property
    def provider(self) -> str:
        return "somya"

    @property
    def model(self) -> str:
        return "vyasa"

    async def _recognize_impl(
        self,
        buffer,
        *,
        language: NotGivenOr[str] = NOT_GIVEN,
        conn_options: APIConnectOptions,
    ) -> stt.SpeechEvent:
        wav = rtc.combine_audio_frames(buffer).to_wav_bytes()
        response = await self.client.post(
            f"{SOMYA_BASE_URL}/v1/speech/transcriptions",
            headers={"X-API-Key": self.api_key},
            files={"audio": ("speech.wav", wav, "audio/wav")},
        )
        response.raise_for_status()
        data = response.json()["data"]
        return stt.SpeechEvent(
            type=stt.SpeechEventType.FINAL_TRANSCRIPT,
            request_id=data["request_id"],
            alternatives=[
                stt.SpeechData(
                    language=data.get("predicted_lang") or "und",
                    text=data["text"],
                )
            ],
        )

    async def aclose(self) -> None:
        await self.client.aclose()


class SomyaTTS(tts.TTS):
    def __init__(self, api_key: str, voice: str = "arjun"):
        super().__init__(
            capabilities=tts.TTSCapabilities(streaming=False),
            sample_rate=24000,
            num_channels=1,
        )
        self.api_key = api_key
        self.voice = voice
        self.client = httpx.AsyncClient(timeout=120)

    @property
    def provider(self) -> str:
        return "somya"

    @property
    def model(self) -> str:
        return "panini"

    def synthesize(
        self, text: str, *, conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS
    ) -> tts.ChunkedStream:
        return SomyaSpeech(tts=self, input_text=text, conn_options=conn_options)

    async def aclose(self) -> None:
        await self.client.aclose()


class SomyaSpeech(tts.ChunkedStream):
    async def _run(self, output_emitter: tts.AudioEmitter) -> None:
        async with self._tts.client.stream(
            "POST",
            f"{SOMYA_BASE_URL}/v1/speech/synthesize",
            headers={"X-API-Key": self._tts.api_key},
            json={"text": self.input_text, "voice": self._tts.voice},
        ) as response:
            response.raise_for_status()
            output_emitter.initialize(
                request_id=response.headers.get("X-Request-ID") or uuid4().hex,
                sample_rate=24000,
                num_channels=1,
                mime_type="audio/pcm",
                stream=False,
            )
            received_audio = False
            async for line in response.aiter_lines():
                if not line:
                    continue
                chunk = json.loads(line)
                # The final WAV contains the full utterance; do not play it twice.
                if chunk["is_final"] and received_audio:
                    break
                wav_bytes = base64.b64decode(chunk["chunk_b64"])
                with wave.open(io.BytesIO(wav_bytes), "rb") as wav:
                    if (wav.getnchannels(), wav.getsampwidth(), wav.getframerate()) != (1, 2, 24000):
                        raise ValueError("Expected 24 kHz, mono, 16-bit WAV from SomyaLabs")
                    output_emitter.push(wav.readframes(wav.getnframes()))
                received_audio = True
            output_emitter.flush()

```

## How the adapter works

`SomyaSTT` uploads a complete WAV utterance to
`POST /v1/speech/transcriptions`. Its `predicted_lang` becomes the LiveKit
transcript language. LiveKit's VAD waits for the end of speech before each ASR
request, so interim transcripts are not available.

`SomyaTTS` sends text and a voice slug to `POST /v1/speech/synthesize` and
reads the newline-delimited JSON response. Each `chunk_b64` is a self-contained
24 kHz mono WAV. The adapter extracts PCM audio for LiveKit. The final record
contains the full utterance, so it is skipped when earlier chunks were played.

Keep the SomyaLabs API key on the agent server. See [Authentication](https://docs.somya.ai/authentication.md),
[ASR](https://docs.somya.ai/models/asr.md), and [TTS](https://docs.somya.ai/models/tts.md) for the HTTP API details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.