Module livekit.plugins.lokutor

Lokutor plugin for LiveKit Agents: speech-to-text and text-to-speech.

See https://docs.lokutor.com for the API behind it.

Classes

class ChunkedStream (*,
tts: TTS,
input_text: str,
conn_options: APIConnectOptions)
Expand source code
class ChunkedStream(tts.ChunkedStream):
    """Non-streaming TTS synthesis.

    Sends the full text in a single WebSocket request and collects all
    audio before yielding it.
    """

    def __init__(self, *, tts: TTS, input_text: str, conn_options: APIConnectOptions) -> None:
        super().__init__(tts=tts, input_text=input_text, conn_options=conn_options)
        self._tts: TTS = tts
        self._opts = replace(tts._opts)

    async def _run(self, output_emitter: tts.AudioEmitter) -> None:
        request_id = utils.shortuuid()
        output_emitter.initialize(
            request_id=request_id,
            sample_rate=self._opts.sample_rate,
            num_channels=1,
            mime_type="audio/pcm",
        )

        try:
            async with self._tts._pool.connection(timeout=self._conn_options.timeout) as ws:
                request = _build_request(self._opts, self._input_text)
                await ws.send_str(json.dumps(request))
                await _receive_audio(
                    ws,
                    output_emitter,
                    request_id=request_id,
                    timeout=self._conn_options.timeout,
                )

                output_emitter.flush()
        except asyncio.TimeoutError:
            raise APITimeoutError() from None
        except APIError:
            # Preserve typed errors raised above (APIStatusError, provider
            # error) instead of collapsing them into APIConnectionError.
            raise
        except aiohttp.ClientResponseError as e:
            raise APIStatusError(
                message=e.message, status_code=e.status, request_id=None, body=None
            ) from None
        except Exception as e:
            # Keep only the exception type, and drop the cause: an aiohttp
            # transport error can carry the request URL, headers or a response
            # body, and `from e` would preserve all of it on __cause__ for any
            # telemetry that walks the chain.
            raise APIConnectionError(type(e).__name__) from None

Non-streaming TTS synthesis.

Sends the full text in a single WebSocket request and collects all audio before yielding it.

Ancestors

  • livekit.agents.tts.tts.ChunkedStream
  • abc.ABC
class STT (*,
api_key: str | None = None,
language: NotGivenOr[STTLanguage | str] = NOT_GIVEN,
base_url: str = 'wss://api.lokutor.com',
http_session: aiohttp.ClientSession | None = None)
Expand source code
class STT(stt.STT):
    """Lokutor Speech-to-Text integration.

    One model for nine languages: English, Spanish, Catalan, Galician, Basque,
    Portuguese, French, Italian and German. The text comes back written out, with
    punctuation, casing, digits and e-mail addresses.

    Args:
        api_key: Lokutor API key. If not provided, reads from ``LOKUTOR_API_KEY``
            environment variable.
        language: Language code (e.g. ``"en"``, ``"es-ES"``). Send it whenever it is
            known: it keeps one-word replies reliable and sets how the text is
            written. Left unset, or a language the model does not serve, the
            language is detected.
        base_url: Base URL for the Lokutor API. Defaults to ``"wss://api.lokutor.com"``.
        http_session: Optional shared ``aiohttp.ClientSession``.
    """

    def __init__(
        self,
        *,
        api_key: str | None = None,
        language: NotGivenOr[STTLanguage | str] = NOT_GIVEN,
        base_url: str = DEFAULT_BASE_URL,
        http_session: aiohttp.ClientSession | None = None,
    ) -> None:
        super().__init__(
            capabilities=stt.STTCapabilities(
                streaming=True,
                interim_results=True,
                offline_recognize=True,
            ),
        )
        lokutor_api_key = api_key or os.environ.get("LOKUTOR_API_KEY")
        if not lokutor_api_key:
            raise ValueError(
                "Lokutor API key is required, either as argument or set"
                " LOKUTOR_API_KEY environment variable"
            )
        self._opts = _STTOptions(
            api_key=lokutor_api_key,
            language=language if is_given(language) else None,
            base_url=base_url,
        )
        self._session = http_session

    @property
    def model(self) -> str:
        """Returns the model name ``"conv-2.0"``."""
        return STT_MODEL

    @property
    def provider(self) -> str:
        """Returns the provider name ``"Lokutor"``."""
        return "Lokutor"

    def _ensure_session(self) -> aiohttp.ClientSession:
        if not self._session:
            self._session = utils.http_context.http_session()
        return self._session

    async def _recognize_impl(
        self,
        buffer: AudioBuffer,
        *,
        language: NotGivenOr[str] = NOT_GIVEN,
        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
    ) -> stt.SpeechEvent:
        lang = _api_language(language if is_given(language) else self._opts.language)
        frame = rtc.combine_audio_frames(buffer)
        body: dict[str, str] = {
            "audio": base64.b64encode(frame.to_wav_bytes()).decode(),
            "format": "wav",
        }
        if lang:
            body["language"] = lang

        try:
            async with self._ensure_session().post(
                f"{_http_base(self._opts.base_url)}/stt/transcribe",
                json=body,
                headers={"X-API-Key": self._opts.api_key},
                timeout=aiohttp.ClientTimeout(total=conn_options.timeout),
            ) as resp:
                if resp.status != 200:
                    raise APIStatusError(
                        "Lokutor transcription failed",
                        status_code=resp.status,
                        request_id=None,
                        body=None,
                    )
                data = await resp.json()
        except asyncio.TimeoutError:
            raise APITimeoutError() from None
        except APIError:
            raise
        except Exception as e:
            # Keep only the exception type: a transport error can carry the request
            # URL, headers or a response body.
            raise APIConnectionError(type(e).__name__) from None

        return stt.SpeechEvent(
            type=stt.SpeechEventType.FINAL_TRANSCRIPT,
            request_id=utils.shortuuid("lokutor-"),
            alternatives=[
                stt.SpeechData(
                    # Without a requested language, the one the API reports (detected), if it serves it.
                    language=LanguageCode(
                        lang or _api_language(str(data.get("language") or "")) or "multi"
                    ),
                    text=str(data.get("text") or "").strip(),
                    start_time=0.0,
                    end_time=frame.duration,
                )
            ],
        )

    def stream(
        self,
        *,
        language: NotGivenOr[str] = NOT_GIVEN,
        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
    ) -> SpeechStream:
        """Create a streaming recognition session over ``WS /ws/stt``."""
        return SpeechStream(
            stt=self,
            conn_options=conn_options,
            language=language if is_given(language) else self._opts.language,
        )

Lokutor Speech-to-Text integration.

One model for nine languages: English, Spanish, Catalan, Galician, Basque, Portuguese, French, Italian and German. The text comes back written out, with punctuation, casing, digits and e-mail addresses.

Args

api_key
Lokutor API key. If not provided, reads from LOKUTOR_API_KEY environment variable.
language
Language code (e.g. "en", "es-ES"). Send it whenever it is known: it keeps one-word replies reliable and sets how the text is written. Left unset, or a language the model does not serve, the language is detected.
base_url
Base URL for the Lokutor API. Defaults to "wss://api.lokutor.com".
http_session
Optional shared aiohttp.ClientSession.

Ancestors

  • livekit.agents.stt.stt.STT
  • abc.ABC
  • EventEmitter
  • typing.Generic

Instance variables

prop model : str
Expand source code
@property
def model(self) -> str:
    """Returns the model name ``"conv-2.0"``."""
    return STT_MODEL

Returns the model name "conv-2.0".

prop provider : str
Expand source code
@property
def provider(self) -> str:
    """Returns the provider name ``"Lokutor"``."""
    return "Lokutor"

Returns the provider name "Lokutor".

Methods

def stream(self,
*,
language: NotGivenOr[str] = NOT_GIVEN,
conn_options: APIConnectOptions = APIConnectOptions(max_retry=3, retry_interval=2.0, timeout=10.0, liveness_timeout=6.0)) ‑> livekit.plugins.lokutor.stt.SpeechStream
Expand source code
def stream(
    self,
    *,
    language: NotGivenOr[str] = NOT_GIVEN,
    conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
) -> SpeechStream:
    """Create a streaming recognition session over ``WS /ws/stt``."""
    return SpeechStream(
        stt=self,
        conn_options=conn_options,
        language=language if is_given(language) else self._opts.language,
    )

Create a streaming recognition session over WS /ws/stt.

Inherited members

class SpeechStream (*,
stt: STT,
conn_options: APIConnectOptions,
language: str | None)
Expand source code
class SpeechStream(stt.SpeechStream):
    """Streaming recognition: interim transcripts while the user speaks, a final one
    when the server sees the utterance end."""

    def __init__(
        self,
        *,
        stt: STT,
        conn_options: APIConnectOptions,
        language: str | None,
    ) -> None:
        super().__init__(stt=stt, conn_options=conn_options, sample_rate=_SAMPLE_RATE)
        self._stt: STT = stt
        self._api_lang = _api_language(language)
        self._language = LanguageCode(self._api_lang or "multi")
        self._speaking = False
        self._request_id = ""
        self._input_done = False
        self._done = False
        self._audio_sent = 0.0
        self._audio_reported = 0.0
        # Audio position (seconds into this stream) where the last final transcript ended: the earliest
        # the next utterance can start. The server sends no word timings.
        self._utterance_floor = 0.0

    async def _connect_ws(self) -> aiohttp.ClientWebSocketResponse:
        try:
            return await asyncio.wait_for(
                self._stt._ensure_session().ws_connect(
                    f"{self._stt._opts.base_url}/ws/stt",
                    max_msg_size=0,
                    # The monitor answers pings and probes an idle socket, so a half-open
                    # connection fails within conn_options.liveness_timeout.
                    autoping=False,
                    # In a header, not the query string, so the key stays out of
                    # exception messages, tracing and access logs.
                    headers={"X-API-Key": self._stt._opts.api_key},
                ),
                self._conn_options.timeout,
            )
        except asyncio.TimeoutError:
            raise APITimeoutError() from None
        except aiohttp.WSServerHandshakeError as e:
            # 401 bad key, 402 no balance: final. 429, the account's concurrent sessions in use, is
            # retryable (APIStatusError's rule): a reconnect's old session is likely about to be released.
            raise APIStatusError(
                "Lokutor STT refused the connection",
                status_code=e.status,
                request_id=None,
                body=None,
            ) from None
        except Exception as e:
            raise APIConnectionError(type(e).__name__) from None

    async def _run(self) -> None:
        # A retry starts on a new connection, which knows nothing of an utterance the last one cut off: end
        # it for the consumer, and let the new connection's first transcript open its own.
        if self._speaking:
            self._event_ch.send_nowait(
                stt.SpeechEvent(type=stt.SpeechEventType.END_OF_SPEECH, request_id=self._request_id)
            )
        self._speaking = False
        self._request_id = ""
        self._input_done = False
        self._done = False
        # start_time_offset restarts at this connection's first frame (restart_provider_clock), so
        # transcript times count from here too. The last connection's usage was reported when it ended.
        self._audio_sent = 0.0
        self._audio_reported = 0.0
        self._utterance_floor = 0.0
        ws = await self._connect_ws()
        try:
            monitor = utils.aio.WebSocketMonitor(
                ws, liveness_timeout=self._conn_options.liveness_timeout
            )
            await ws.send_str(json.dumps({"language": self._api_lang}))
            await asyncio.wait_for(self._await_ready(monitor), self._conn_options.timeout)

            send_task = asyncio.create_task(self._send_task(ws))
            recv_task = asyncio.create_task(self._recv_task(monitor))
            try:
                await asyncio.wait({send_task, recv_task}, return_when=asyncio.FIRST_COMPLETED)
                if send_task.done():
                    send_task.result()
                    # Input has ended: the last final transcript and "done" must follow within the
                    # timeout. A live stream waits on the caller for as long as it lasts; this
                    # bounds only the wait for a server that stops answering after "end".
                    await asyncio.wait_for(recv_task, self._conn_options.timeout)
                else:
                    recv_task.result()
            finally:
                await utils.aio.gracefully_cancel(send_task, recv_task)
        except asyncio.TimeoutError:
            raise APITimeoutError() from None
        except aiohttp.ClientError as e:
            # A send on a socket that dropped mid-stream raises before the receiver sees the close;
            # as a connection error it is retried like any other drop.
            raise APIConnectionError(type(e).__name__) from None
        finally:
            self._report_usage()
            await ws.close()

    async def _await_ready(self, monitor: utils.aio.WebSocketMonitor) -> None:
        while True:
            msg = await monitor.receive()
            if msg.type != aiohttp.WSMsgType.TEXT:
                raise APIConnectionError("Lokutor STT closed before it was ready")
            try:
                data = json.loads(msg.data)
            except json.JSONDecodeError:
                continue
            if not isinstance(data, dict):
                continue
            if data.get("type") == "error":
                raise APIStatusError(
                    "Lokutor STT rejected the session",
                    status_code=-1,
                    request_id=None,
                    body=None,
                    retryable=False,
                )
            if data.get("type") == "status" and data.get("data") == "ready":
                self._note_language(data.get("lang"))
                return

    async def _send_task(self, ws: aiohttp.ClientWebSocketResponse) -> None:
        async for data in self._input_ch:
            # A flush needs nothing here: the server ends an utterance on its own pause.
            if isinstance(data, rtc.AudioFrame):
                audio = data.data.tobytes()
                if audio:
                    self._audio_sent += data.samples_per_channel / data.sample_rate
                    await ws.send_bytes(audio)
        self._input_done = True
        await ws.send_str(json.dumps({"type": "end"}))

    async def _recv_task(self, monitor: utils.aio.WebSocketMonitor) -> None:
        while True:
            msg = await monitor.receive()
            if msg.type in (
                aiohttp.WSMsgType.CLOSED,
                aiohttp.WSMsgType.CLOSE,
                aiohttp.WSMsgType.CLOSING,
            ):
                # Only "done" ends a stream: a close before it, even after end_input(), may have
                # lost the last final transcript.
                if self._done:
                    return
                raise APIConnectionError("Lokutor STT closed before it finished")
            if msg.type == aiohttp.WSMsgType.ERROR:
                raise APIConnectionError("Lokutor STT connection failed")
            if msg.type != aiohttp.WSMsgType.TEXT:
                continue
            try:
                data = json.loads(msg.data)
            except json.JSONDecodeError:
                logger.debug("Ignoring a non-JSON frame from Lokutor STT")
                continue
            if not isinstance(data, dict):
                continue
            kind = data.get("type")
            if kind == "error":
                # Not the provider's message: it may echo customer content.
                raise APIStatusError(
                    "Lokutor STT returned an error",
                    status_code=-1,
                    request_id=None,
                    body=None,
                    retryable=False,
                )
            if kind == "status" and data.get("data") == "done":
                self._done = True
                return
            if kind == "transcript":
                self._mark_provider_progress()
                self._note_language(data.get("lang"))
                self._on_transcript(
                    str(data.get("data") or "").strip(), data.get("isFinal") is True
                )

    def _note_language(self, lang: object) -> None:
        # With no language requested, label transcripts with the one the server reports, if it
        # serves it; "multi" otherwise.
        if not self._api_lang and isinstance(lang, str) and _api_language(lang):
            self._language = LanguageCode(_api_language(lang))

    def _on_transcript(self, text: str, final: bool) -> None:
        if not text:
            # An empty final after interims (a cough, noise) still closes the utterance they opened.
            if final and self._speaking:
                self._end_utterance()
            return
        if not self._speaking:
            self._speaking = True
            self._request_id = utils.shortuuid("lokutor-")
            self._event_ch.send_nowait(stt.SpeechEvent(type=stt.SpeechEventType.START_OF_SPEECH))
        self._event_ch.send_nowait(
            stt.SpeechEvent(
                type=(
                    stt.SpeechEventType.FINAL_TRANSCRIPT
                    if final
                    else stt.SpeechEventType.INTERIM_TRANSCRIPT
                ),
                request_id=self._request_id,
                alternatives=[
                    stt.SpeechData(
                        language=self._language,
                        text=text,
                        start_time=self.start_time_offset + self._utterance_floor,
                        end_time=self.start_time_offset + self._audio_sent,
                    )
                ],
            )
        )
        if final:
            self._end_utterance()

    def _end_utterance(self) -> None:
        self._event_ch.send_nowait(
            stt.SpeechEvent(type=stt.SpeechEventType.END_OF_SPEECH, request_id=self._request_id)
        )
        self._report_usage()
        self._utterance_floor = self._audio_sent
        self._speaking = False
        self._request_id = ""

    def _report_usage(self) -> None:
        duration = self._audio_sent - self._audio_reported
        if duration <= 0:
            return
        self._audio_reported = self._audio_sent
        self._event_ch.send_nowait(
            stt.SpeechEvent(
                type=stt.SpeechEventType.RECOGNITION_USAGE,
                recognition_usage=stt.RecognitionUsage(audio_duration=duration),
            )
        )

Streaming recognition: interim transcripts while the user speaks, a final one when the server sees the utterance end.

Args: sample_rate : int or None, optional The desired sample rate for the audio input. If specified, the audio input will be automatically resampled to match the given sample rate before being processed for Speech-to-Text. If not provided (None), the input will retain its original sample rate.

Ancestors

  • livekit.agents.stt.stt.RecognizeStream
  • abc.ABC
class SynthesizeStream (*,
tts: TTS,
conn_options: APIConnectOptions)
Expand source code
class SynthesizeStream(tts.SynthesizeStream):
    """Streaming TTS synthesis.

    The input is split into sentences and each sentence is one request on a
    pooled WebSocket, so audio starts at the first sentence and every sentence
    has its own prosody. A flush ends the current segment; the next text opens
    a new one.
    """

    def __init__(self, *, tts: TTS, conn_options: APIConnectOptions) -> None:
        super().__init__(tts=tts, conn_options=conn_options)
        self._tts: TTS = tts
        self._opts = replace(tts._opts)

    async def _run(self, output_emitter: tts.AudioEmitter) -> None:
        request_id = utils.shortuuid()
        output_emitter.initialize(
            request_id=request_id,
            sample_rate=self._opts.sample_rate,
            num_channels=1,
            mime_type="audio/pcm",
            stream=True,
        )

        sent_stream = self._tts._sentence_tokenizer.stream(language=self._opts.language)

        async def _input_task() -> None:
            try:
                async for data in self._input_ch:
                    if isinstance(data, self._FlushSentinel):
                        sent_stream.flush()
                        continue
                    sent_stream.push_text(data)
            finally:
                sent_stream.end_input()

        async def _synthesize_task() -> None:
            async with self._tts._pool.connection(timeout=self._conn_options.timeout) as ws:
                self._acquire_time = self._tts._pool.last_acquire_time
                self._connection_reused = self._tts._pool.last_connection_reused

                # A segment is open from its first sentence to the flush (or the end of the
                # input) that follows it; the tokenizer gives the sentences after a flush a
                # new segment id.
                segment_id: str | None = None
                async for ev in sent_stream:
                    text = ev.token.strip()
                    if not text:
                        continue
                    if ev.segment_id != segment_id:
                        if segment_id is not None:
                            output_emitter.end_segment()
                        segment_id = ev.segment_id
                        output_emitter.start_segment(segment_id=segment_id)

                    self._mark_started()
                    await ws.send_str(json.dumps(_build_request(self._opts, text)))
                    await _receive_audio(
                        ws,
                        output_emitter,
                        request_id=request_id,
                        timeout=self._conn_options.timeout,
                    )
                    output_emitter.flush()

                if segment_id is not None:
                    output_emitter.end_segment()

        tasks = [
            asyncio.create_task(_input_task()),
            asyncio.create_task(_synthesize_task()),
        ]
        try:
            await asyncio.gather(*tasks)
        except asyncio.TimeoutError:
            raise APITimeoutError() from None
        except APIError:
            # Preserve typed errors raised above instead of collapsing them
            # into a generic APIConnectionError.
            raise
        except aiohttp.ClientResponseError as e:
            raise APIStatusError(
                message=e.message, status_code=e.status, request_id=None, body=None
            ) from None
        except Exception as e:
            # Keep only the exception type, and drop the cause: an aiohttp
            # transport error can carry the request URL, headers or a response
            # body, and `from e` would preserve all of it on __cause__ for any
            # telemetry that walks the chain.
            raise APIConnectionError(type(e).__name__) from None
        finally:
            await utils.aio.cancel_and_wait(*tasks)
            await sent_stream.aclose()

Streaming TTS synthesis.

The input is split into sentences and each sentence is one request on a pooled WebSocket, so audio starts at the first sentence and every sentence has its own prosody. A flush ends the current segment; the next text opens a new one.

Ancestors

  • livekit.agents.tts.tts.SynthesizeStream
  • abc.ABC
class TTS (*,
api_key: str | None = None,
voice: VoiceID | str = 'F1',
language: TTSLanguage | str | None = 'en',
base_url: str = 'wss://api.lokutor.com',
tokenizer: NotGivenOr[tokenize.SentenceTokenizer] = NOT_GIVEN,
http_session: aiohttp.ClientSession | None = None)
Expand source code
class TTS(tts.TTS):
    """Lokutor Text-to-Speech integration.

    Connects to the Lokutor WebSocket API to synthesize speech. Supports
    streaming and non-streaming synthesis with multiple voices and languages.

    Args:
        api_key: Lokutor API key. If not provided, reads from ``LOKUTOR_API_KEY``
            environment variable.
        voice: Voice slot to use, ``"F1"``-``"F5"`` or ``"M1"``-``"M5"``. Each
            language has its own native speaker in each slot. Defaults to ``"F1"``.
        language: Language code: ``"en"``, ``"es"``, ``"ca"``, ``"gl"``,
            ``"eu"``, ``"pt"``, ``"fr"``, ``"it"`` or ``"de"``. Any other value
            uses the English speakers. Defaults to ``"en"``.
        base_url: Base URL for the Lokutor API. Defaults to
            ``"wss://api.lokutor.com"``.
        tokenizer: Sentence tokenizer for streaming input. The agent pushes LLM
            token deltas; each sentence becomes one request so the prosody is
            per sentence. Defaults to ``tokenize.blingfire.SentenceTokenizer``.
        http_session: Optional shared ``aiohttp.ClientSession``. If not
            provided, a new session will be created.

    Note:
        Lokutor's TTS endpoint always returns audio at 44.1 kHz; the output
        sample rate is fixed and not configurable. The LiveKit pipeline
        resamples downstream if a different rate is required.
    """

    def __init__(
        self,
        *,
        api_key: str | None = None,
        voice: VoiceID | str = DEFAULT_VOICE_ID,
        language: TTSLanguage | str | None = "en",
        base_url: str = DEFAULT_BASE_URL,
        tokenizer: NotGivenOr[tokenize.SentenceTokenizer] = NOT_GIVEN,
        http_session: aiohttp.ClientSession | None = None,
    ) -> None:
        lokutor_api_key = api_key or os.environ.get("LOKUTOR_API_KEY")
        if not lokutor_api_key:
            raise ValueError(
                "Lokutor API key is required, either as argument or set"
                " LOKUTOR_API_KEY environment variable"
            )

        super().__init__(
            capabilities=tts.TTSCapabilities(
                streaming=True,
                aligned_transcript=False,
            ),
            sample_rate=DEFAULT_SAMPLE_RATE,
            num_channels=1,
        )

        self._opts = _TTSOptions(
            api_key=lokutor_api_key,
            voice=voice,
            language=language,
            base_url=base_url,
            sample_rate=DEFAULT_SAMPLE_RATE,
        )

        self._sentence_tokenizer = (
            tokenizer if is_given(tokenizer) else tokenize.blingfire.SentenceTokenizer()
        )
        self._session = http_session
        self._pool = utils.ConnectionPool[aiohttp.ClientWebSocketResponse](
            connect_cb=self._connect_ws,
            close_cb=self._close_ws,
            max_session_duration=300,
            mark_refreshed_on_get=True,
        )
        self._streams = weakref.WeakSet[SynthesizeStream]()

    @property
    def model(self) -> str:
        """Returns the model name ``"versa-2.0"``."""
        return TTS_MODEL

    @property
    def provider(self) -> str:
        """Returns the provider name ``"Lokutor"``."""
        return "Lokutor"

    async def _connect_ws(self, timeout: float) -> aiohttp.ClientWebSocketResponse:
        session = self._ensure_session()
        # Send the API key in a header rather than the URL query string so the
        # credential does not end up in exception messages, tracing, or
        # intermediary access logs.
        ws = await asyncio.wait_for(
            session.ws_connect(
                self._opts.get_ws_url(),
                max_msg_size=0,
                headers={"X-API-Key": self._opts.api_key},
            ),
            timeout,
        )
        return ws

    async def _close_ws(self, ws: aiohttp.ClientWebSocketResponse) -> None:
        await ws.close()

    def _ensure_session(self) -> aiohttp.ClientSession:
        if not self._session:
            self._session = utils.http_context.http_session()
        return self._session

    def prewarm(self) -> None:
        """Pre-warm the WebSocket connection pool."""
        self._pool.prewarm()

    def synthesize(
        self,
        text: str,
        *,
        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
    ) -> ChunkedStream:
        """Synthesize text to speech in a single request.

        Args:
            text: The text to synthesize.
            conn_options: Connection options for the request.

        Returns:
            A ``ChunkedStream`` that yields ``SynthesizedAudio`` events.
        """
        return ChunkedStream(tts=self, input_text=text, conn_options=conn_options)

    def stream(
        self, *, conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS
    ) -> SynthesizeStream:
        """Create a streaming TTS session.

        Args:
            conn_options: Connection options for the stream.

        Returns:
            A ``SynthesizeStream`` for streaming synthesis.
        """
        stream = SynthesizeStream(tts=self, conn_options=conn_options)
        self._streams.add(stream)
        return stream

    async def aclose(self) -> None:
        """Clean up all stream and connection resources."""
        for stream in list(self._streams):
            await stream.aclose()
        self._streams.clear()
        await self._pool.aclose()

Lokutor Text-to-Speech integration.

Connects to the Lokutor WebSocket API to synthesize speech. Supports streaming and non-streaming synthesis with multiple voices and languages.

Args

api_key
Lokutor API key. If not provided, reads from LOKUTOR_API_KEY environment variable.
voice
Voice slot to use, "F1"-"F5" or "M1"-"M5". Each language has its own native speaker in each slot. Defaults to "F1".
language
Language code: "en", "es", "ca", "gl", "eu", "pt", "fr", "it" or "de". Any other value uses the English speakers. Defaults to "en".
base_url
Base URL for the Lokutor API. Defaults to "wss://api.lokutor.com".
tokenizer
Sentence tokenizer for streaming input. The agent pushes LLM token deltas; each sentence becomes one request so the prosody is per sentence. Defaults to tokenize.blingfire.SentenceTokenizer.
http_session
Optional shared aiohttp.ClientSession. If not provided, a new session will be created.

Note

Lokutor's TTS endpoint always returns audio at 44.1 kHz; the output sample rate is fixed and not configurable. The LiveKit pipeline resamples downstream if a different rate is required.

Ancestors

  • livekit.agents.tts.tts.TTS
  • abc.ABC
  • EventEmitter
  • typing.Generic

Instance variables

prop model : str
Expand source code
@property
def model(self) -> str:
    """Returns the model name ``"versa-2.0"``."""
    return TTS_MODEL

Returns the model name "versa-2.0".

prop provider : str
Expand source code
@property
def provider(self) -> str:
    """Returns the provider name ``"Lokutor"``."""
    return "Lokutor"

Returns the provider name "Lokutor".

Methods

async def aclose(self) ‑> None
Expand source code
async def aclose(self) -> None:
    """Clean up all stream and connection resources."""
    for stream in list(self._streams):
        await stream.aclose()
    self._streams.clear()
    await self._pool.aclose()

Clean up all stream and connection resources.

def prewarm(self) ‑> None
Expand source code
def prewarm(self) -> None:
    """Pre-warm the WebSocket connection pool."""
    self._pool.prewarm()

Pre-warm the WebSocket connection pool.

def stream(self,
*,
conn_options: APIConnectOptions = APIConnectOptions(max_retry=3, retry_interval=2.0, timeout=10.0, liveness_timeout=6.0)) ‑> livekit.plugins.lokutor.tts.SynthesizeStream
Expand source code
def stream(
    self, *, conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS
) -> SynthesizeStream:
    """Create a streaming TTS session.

    Args:
        conn_options: Connection options for the stream.

    Returns:
        A ``SynthesizeStream`` for streaming synthesis.
    """
    stream = SynthesizeStream(tts=self, conn_options=conn_options)
    self._streams.add(stream)
    return stream

Create a streaming TTS session.

Args

conn_options
Connection options for the stream.

Returns

A SynthesizeStream for streaming synthesis.

def synthesize(self,
text: str,
*,
conn_options: APIConnectOptions = APIConnectOptions(max_retry=3, retry_interval=2.0, timeout=10.0, liveness_timeout=6.0)) ‑> livekit.plugins.lokutor.tts.ChunkedStream
Expand source code
def synthesize(
    self,
    text: str,
    *,
    conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
) -> ChunkedStream:
    """Synthesize text to speech in a single request.

    Args:
        text: The text to synthesize.
        conn_options: Connection options for the request.

    Returns:
        A ``ChunkedStream`` that yields ``SynthesizedAudio`` events.
    """
    return ChunkedStream(tts=self, input_text=text, conn_options=conn_options)

Synthesize text to speech in a single request.

Args

text
The text to synthesize.
conn_options
Connection options for the request.

Returns

A ChunkedStream that yields SynthesizedAudio events.

Inherited members