pipecat-lokutor 0.1.0__tar.gz

pipecat_lokutor-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+*.egg-info/
+dist/
+build/
+.uv/

pipecat_lokutor-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2024-2026, Lokutor AI
+Copyright (c) 2024-2026, Daily
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pipecat_lokutor-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: pipecat-lokutor
+Version: 0.1.0
+Summary: Lokutor TTS integration for Pipecat
+Project-URL: Homepage, https://github.com/lokutor-ai/pipecat-lokutor
+Project-URL: Source, https://github.com/lokutor-ai/pipecat-lokutor
+Author-email: Lokutor AI <your-email@lokutor.com>
+License: BSD-2-Clause
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pipecat>=0.0.86
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+# Pipecat Lokutor TTS
+
+Lokutor text-to-speech integration for [Pipecat](https://github.com/pipecat-ai/pipecat).
+
+## Installation
+
+```bash
+pip install pipecat-lokutor
+```
+
+Or with uv:
+
+```bash
+uv add pipecat-lokutor
+```
+
+## Usage
+
+```python
+from pipecat_lokutor import LokutorTTSService
+
+tts = LokutorTTSService(
+    api_key="your_api_key",
+    voice_id="F1",
+    params=LokutorTTSService.InputParams(
+        language="en",
+        speed=1.0,
+        steps=5,
+        visemes=False,
+    ),
+)
+```
+
+### Pipecat Pipeline
+
+```python
+from pipecat.pipeline.pipeline import Pipeline
+
+pipeline = Pipeline([
+    transport.input(),
+    stt,
+    llm,
+    tts,
+    transport.output(),
+])
+```
+
+## Voices
+
+| Voice | Description |
+|-------|-------------|
+| M1-M5 | Male voices |
+| F1-F5 | Female voices |
+
+## Supported Languages
+
+EN, ES, FR, PT, KO
+
+## Example
+
+See `examples/groq-stt-groq-llm-lokutor-tts.py` for a full example using Groq STT + Groq LLM + Lokutor TTS.
+
+```bash
+# Install dependencies
+uv sync
+
+# Set environment variables
+export GROQ_API_KEY="your_groq_api_key"
+export LOKUTOR_API_KEY="your_lokutor_api_key"
+
+# Run the example
+python examples/groq-stt-groq-llm-lokutor-tts.py -t webrtc
+```
+
+Then open `http://localhost:7860/client/`.
+
+## Compatibility
+
+Tested with Pipecat v0.0.86+.
+
+## License
+
+BSD 2-Clause License. See `LICENSE` for details.

pipecat_lokutor-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Pipecat Lokutor TTS
+
+Lokutor text-to-speech integration for [Pipecat](https://github.com/pipecat-ai/pipecat).
+
+## Installation
+
+```bash
+pip install pipecat-lokutor
+```
+
+Or with uv:
+
+```bash
+uv add pipecat-lokutor
+```
+
+## Usage
+
+```python
+from pipecat_lokutor import LokutorTTSService
+
+tts = LokutorTTSService(
+    api_key="your_api_key",
+    voice_id="F1",
+    params=LokutorTTSService.InputParams(
+        language="en",
+        speed=1.0,
+        steps=5,
+        visemes=False,
+    ),
+)
+```
+
+### Pipecat Pipeline
+
+```python
+from pipecat.pipeline.pipeline import Pipeline
+
+pipeline = Pipeline([
+    transport.input(),
+    stt,
+    llm,
+    tts,
+    transport.output(),
+])
+```
+
+## Voices
+
+| Voice | Description |
+|-------|-------------|
+| M1-M5 | Male voices |
+| F1-F5 | Female voices |
+
+## Supported Languages
+
+EN, ES, FR, PT, KO
+
+## Example
+
+See `examples/groq-stt-groq-llm-lokutor-tts.py` for a full example using Groq STT + Groq LLM + Lokutor TTS.
+
+```bash
+# Install dependencies
+uv sync
+
+# Set environment variables
+export GROQ_API_KEY="your_groq_api_key"
+export LOKUTOR_API_KEY="your_lokutor_api_key"
+
+# Run the example
+python examples/groq-stt-groq-llm-lokutor-tts.py -t webrtc
+```
+
+Then open `http://localhost:7860/client/`.
+
+## Compatibility
+
+Tested with Pipecat v0.0.86+.
+
+## License
+
+BSD 2-Clause License. See `LICENSE` for details.

pipecat_lokutor-0.1.0/pipecat_lokutor/__init__.py

@@ -0,0 +1,6 @@
+from .tts import LokutorTTSService, LokutorTTSSettings
+
+__all__ = [
+    "LokutorTTSService",
+    "LokutorTTSSettings",
+]

pipecat_lokutor-0.1.0/pipecat_lokutor/tts.py

@@ -0,0 +1,270 @@
+#
+# Copyright (c) 2024-2026, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+import asyncio
+import json
+from dataclasses import dataclass
+from typing import AsyncGenerator, Optional
+
+from loguru import logger
+from pydantic import BaseModel
+from websockets.asyncio.client import connect as websocket_connect
+from websockets.protocol import State
+
+from pipecat.frames.frames import (
+    ErrorFrame,
+    Frame,
+    TTSAudioRawFrame,
+    TTSStartedFrame,
+    TTSStoppedFrame,
+)
+from pipecat.services.settings import TTSSettings
+from pipecat.services.tts_service import WebsocketTTSService
+from pipecat.transcriptions.language import Language
+from pipecat.utils.tracing.service_decorators import traced_tts
+
+
+@dataclass
+class LokutorTTSSettings(TTSSettings):
+    """Settings for Lokutor TTS service."""
+
+    pass
+
+
+class LokutorTTSService(WebsocketTTSService):
+    """Lokutor TTS service implementation."""
+
+    Settings = LokutorTTSSettings
+    _settings: LokutorTTSSettings
+
+    class InputParams(BaseModel):
+        """Input parameters for Lokutor TTS such as speed and language."""
+
+        language: Optional[Language] = None
+        speed: Optional[float] = 1.0
+        steps: Optional[int] = 5
+        visemes: Optional[bool] = False
+
+    SUPPORTED_VOICES = {"M1", "M2", "M3", "M4", "M5", "F1", "F2", "F3", "F4", "F5"}
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        voice_id: str = "F1",
+        sample_rate: int = 44100,
+        params: Optional[InputParams] = None,
+        settings: Optional[LokutorTTSSettings] = None,
+        base_url: str = "wss://api.lokutor.com/ws",
+        **kwargs,
+    ):
+        if voice_id not in self.SUPPORTED_VOICES:
+            raise ValueError(f"Invalid voice_id '{voice_id}'")
+
+        self._api_key = api_key
+        self._voice_id = voice_id
+        self._params = params or self.InputParams()
+
+        default_settings = self.Settings(
+            model=None,
+            voice=self._voice_id,
+            language=None,
+        )
+
+        if params is not None and settings is None:
+            default_settings.language = params.language
+
+        if settings is not None:
+            default_settings.apply_update(settings)
+
+        super().__init__(
+            push_start_frame=True,
+            push_stop_frames=True,
+            pause_frame_processing=True,
+            sample_rate=sample_rate,
+            settings=default_settings,
+            **kwargs,
+        )
+
+        self._sample_rate = sample_rate
+        self._base_url = base_url
+        self._websocket = None
+        self._receive_task = None
+
+    async def _connect(self):
+        await super()._connect()
+
+        try:
+            await self._connect_websocket()
+        except Exception as e:
+            raise ConnectionError(f"Failed to connect to Lokutor: {e}") from e
+
+        if self._websocket and not self._receive_task:
+            self._receive_task = self.create_task(self._receive_task_handler(self._report_error))
+
+    async def _disconnect(self):
+        await super()._disconnect()
+
+        if self._receive_task:
+            await self.cancel_task(self._receive_task)
+            self._receive_task = None
+
+        await self._disconnect_websocket()
+
+    async def _connect_websocket(self):
+        if self._websocket and self._websocket.state is State.OPEN:
+            return
+
+        logger.debug("Connecting to Lokutor")
+        url = f"{self._base_url}?api_key={self._api_key}"
+        self._websocket = await websocket_connect(url)
+
+        await self._call_event_handler("on_connected")
+
+    async def _disconnect_websocket(self):
+        try:
+            await self.stop_all_metrics()
+            if self._websocket:
+                logger.debug("Disconnecting from Lokutor")
+                await self._websocket.close()
+        except Exception as exc:
+            await self.push_error(error_msg=f"Unknown error occurred: {exc}", exception=exc)
+        finally:
+            self._websocket = None
+            await self._call_event_handler("on_disconnected")
+
+    async def _receive_messages(self):
+        """Keep the websocket connection alive.
+
+        Lokutor uses request-response (send request, receive audio), not streaming.
+        All message handling happens in run_tts(). This method just keeps the
+        background receive task alive to maintain the persistent connection.
+        """
+        try:
+            while True:
+                await asyncio.sleep(1)
+        except asyncio.CancelledError:
+            pass
+
+    def _get_websocket(self):
+        if self._websocket is None:
+            raise ConnectionError("Lokutor websocket not connected")
+        return self._websocket
+
+    def can_generate_metrics(self) -> bool:
+        return True
+
+    @traced_tts
+    async def run_tts(self, text: str, context_id: str) -> AsyncGenerator[Frame, None]:
+        logger.debug(f"{self}: Generating TTS [{text}]")
+
+        await self.start_tts_usage_metrics(text)
+        yield TTSStartedFrame(context_id=context_id)
+
+        try:
+            if not self._websocket or self._websocket.state is State.CLOSED:
+                await self._connect()
+
+            request = {
+                "text": text,
+                "voice": self._voice_id,
+                "speed": self._params.speed,
+                "steps": self._params.steps,
+                "visemes": self._params.visemes,
+            }
+            if self._params.language:
+                lokutor_lang = language_to_lokutor_language(self._params.language)
+                if lokutor_lang:
+                    request["lang"] = lokutor_lang
+
+            request_json = json.dumps(request)
+            logger.debug(f"Sending request to Lokutor: {request_json}")
+
+            await self.start_ttfb_metrics()
+            await self._get_websocket().send(request_json)
+            logger.debug("Request sent to Lokutor, waiting for first response...")
+
+            first_audio_received = False
+            while True:
+                try:
+                    logger.debug("Waiting for message from Lokutor...")
+                    message = await asyncio.wait_for(self._get_websocket().recv(), timeout=10.0)
+                    logger.debug(
+                        f"Received message from Lokutor: {type(message)} {len(message) if isinstance(message, bytes) else message[:100]}"
+                    )
+                    if isinstance(message, str):
+                        try:
+                            data = json.loads(message)
+                            if isinstance(data, dict):
+                                msg_type = data.get("type")
+                                if msg_type == "eos":
+                                    logger.debug("Received EOS from Lokutor")
+                                    break
+                                elif msg_type == "error":
+                                    error_msg = data.get("message", "Unknown error")
+                                    logger.error(f"Lokutor error: {error_msg}")
+                                    yield ErrorFrame(error=f"Lokutor error: {error_msg}")
+                                    break
+                            elif isinstance(data, list):
+                                logger.debug(f"Received viseme data: {len(data)} visemes")
+                        except json.JSONDecodeError:
+                            logger.warning(f"Received unknown text message: {message}")
+                    else:
+                        logger.debug(f"Received audio data: {len(message)} bytes")
+                        if not first_audio_received:
+                            logger.debug("First audio chunk received - stopping TTFB metrics")
+                            await self.stop_ttfb_metrics()
+                            first_audio_received = True
+                        yield TTSAudioRawFrame(message, self.sample_rate, 1)
+                except asyncio.TimeoutError:
+                    logger.error("Timeout waiting for Lokutor response")
+                    yield ErrorFrame(error="Timeout waiting for Lokutor response")
+                    break
+                except Exception as e:
+                    logger.error(f"Error receiving from Lokutor: {e}")
+                    yield ErrorFrame(error=f"Error receiving from Lokutor: {e}")
+                    break
+
+        except ConnectionError as e:
+            logger.error(f"{self} exception: {e}")
+            yield ErrorFrame(error=f"Unknown error occurred: {e}")
+        except Exception as e:
+            logger.error(f"{self} exception: {e}")
+            yield ErrorFrame(error=f"Unknown error occurred: {e}")
+        finally:
+            logger.debug(f"{self}: Finished TTS [{text}]")
+            if not first_audio_received:
+                await self.stop_ttfb_metrics()
+            yield TTSStoppedFrame(context_id=context_id)
+
+
+def language_to_lokutor_language(language):
+    if isinstance(language, Language):
+        mapping = {
+            Language.EN: "en",
+            Language.ES: "es",
+            Language.FR: "fr",
+            Language.PT: "pt",
+            Language.KO: "ko",
+        }
+        return mapping.get(language)
+    if hasattr(language, "value"):
+        return language.value
+    return str(language)
+
+
+def lokutor_language_to_language(language):
+    if not isinstance(language, str):
+        return None
+
+    mapping = {
+        "en": Language.EN,
+        "es": Language.ES,
+        "fr": Language.FR,
+        "pt": Language.PT,
+        "ko": Language.KO,
+    }
+    return mapping.get(language)

pipecat_lokutor-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "pipecat-lokutor"
+version = "0.1.0"
+description = "Lokutor TTS integration for Pipecat"
+readme = "README.md"
+license = { text = "BSD-2-Clause" }
+authors = [
+    { name = "Lokutor AI", email = "your-email@lokutor.com" },
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pipecat>=0.0.86",
+    "websockets>=12.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pipecat_lokutor"]
+
+[tool.hatch.build.targets.sdist]
+packages = ["src/pipecat_lokutor"]
+
+[project.urls]
+Homepage = "https://github.com/lokutor-ai/pipecat-lokutor"
+Source = "https://github.com/lokutor-ai/pipecat-lokutor"