initial commit

Author: PaulAsjes

src/elevenlabs/speech_engine/__init__.py

@@ -0,0 +1,27 @@
+"""ElevenLabs Speech Engine SDK module."""
+
+from .resource import SpeechEngineResource
+from .server import SpeechEngineServer
+from .session import SpeechEngineSession
+from .types import (
+    CLOSE,
+    DISCONNECTED,
+    ERROR,
+    INIT,
+    USER_TRANSCRIPT,
+    ConversationMessage,
+    WebSocketLike,
+)
+
+__all__ = [
+    "ConversationMessage",
+    "SpeechEngineResource",
+    "SpeechEngineServer",
+    "SpeechEngineSession",
+    "WebSocketLike",
+    "CLOSE",
+    "DISCONNECTED",
+    "ERROR",
+    "INIT",
+    "USER_TRANSCRIPT",
+]

src/elevenlabs/speech_engine/resource.py

@@ -0,0 +1,65 @@
+"""SpeechEngineResource — client-facing handle for a speech engine instance."""
+
+import typing
+
+from .server import SpeechEngineServer
+from .session import SpeechEngineSession
+from .types import WebSocketLike
+
+
+class SpeechEngineResource:
+    """Represents a speech engine instance.
+
+    Returned by ``await client.speech_engine.get("seng_123")``.
+
+    Use :meth:`serve` to start a standalone WebSocket server, or
+    :meth:`create_session` to wrap an existing WebSocket for custom
+    server integration (FastAPI, Starlette, etc.).
+
+    Example::
+
+        engine = await elevenlabs.speech_engine.get("seng_123")
+
+        async def on_transcript(transcript, session):
+            stream = await openai.responses.create(...)
+            await session.send_response(stream)
+
+        await engine.serve(
+            port=3001,
+            debug=True,
+            on_transcript=on_transcript,
+        )
+    """
+
+    def __init__(
+        self,
+        engine_id: str,
+        client_options: typing.Any = None,
+    ) -> None:
+        self.engine_id = engine_id
+        self._options = client_options
+
+    async def serve(
+        self,
+        *,
+        port: int = 3001,
+        debug: bool = False,
+        **handlers: typing.Any,
+    ) -> None:
+        """Start a standalone WebSocket server.  Blocks until stopped."""
+        server = SpeechEngineServer(port=port, debug=debug, **handlers)
+        await server.serve()
+
+    def create_session(
+        self,
+        ws: WebSocketLike,
+        *,
+        debug: bool = False,
+    ) -> SpeechEngineSession:
+        """Wrap *ws* in a :class:`SpeechEngineSession`.
+
+        Use this for custom server integration (e.g. FastAPI, Starlette).
+        Wire handlers via :meth:`~SpeechEngineSession.on` then ``await
+        session.run()``.
+        """
+        return SpeechEngineSession(ws, debug=debug)

src/elevenlabs/speech_engine/server.py

@@ -0,0 +1,75 @@
+"""SpeechEngineServer — standalone WebSocket server for Speech Engine."""
+
+import asyncio
+import logging
+import typing
+
+from .session import SpeechEngineSession, _wire_handlers
+from .types import WebSocketLike
+
+logger = logging.getLogger("elevenlabs.speech_engine")
+
+
+class SpeechEngineServer:
+    """Standalone WebSocket server that produces :class:`SpeechEngineSession`
+    instances for each incoming connection from the ElevenLabs Speech Engine
+    API.
+
+    Example::
+
+        server = SpeechEngineServer(
+            port=3001,
+            debug=True,
+            on_transcript=handle_transcript,
+        )
+        await server.serve()
+    """
+
+    def __init__(
+        self,
+        *,
+        port: int = 3001,
+        debug: bool = False,
+        **handlers: typing.Any,
+    ) -> None:
+        self._port = port
+        self._debug = debug
+        self._handlers = handlers
+        self._stop_event = asyncio.Event()
+        self._server = None  # type: typing.Any
+
+    def handle_connection(self, ws: WebSocketLike) -> SpeechEngineSession:
+        """Wrap *ws* in a :class:`SpeechEngineSession` with the server's
+        handlers wired up.
+
+        Use this when you manage your own WebSocket server and want to wrap
+        individual connections.  The returned session's :meth:`run` must
+        still be awaited by the caller.
+        """
+        session = SpeechEngineSession(ws, debug=self._debug)
+        _wire_handlers(session, self._handlers)
+        return session
+
+    async def serve(self) -> None:
+        """Start the WebSocket server.  Blocks until :meth:`stop` is called."""
+        import websockets  # noqa: E402 — keep import lazy
+
+        async def _handler(websocket: typing.Any, *_args: typing.Any) -> None:
+            session = self.handle_connection(websocket)
+            await session.run()
+
+        self._server = await websockets.serve(  # type: ignore[attr-defined]
+            _handler,
+            "",
+            self._port,
+        )
+        logger.debug("speech engine server listening on port %d", self._port)
+        try:
+            await self._stop_event.wait()
+        finally:
+            self._server.close()
+            await self._server.wait_closed()
+
+    async def stop(self) -> None:
+        """Signal the server to shut down gracefully."""
+        self._stop_event.set()