stackchan-mcp 0.4.0__tar.gz → 0.6.0__tar.gz

{stackchan_mcp-0.4.0 → stackchan_mcp-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.4.0
+Version: 0.6.0
 Summary: Two-faced MCP gateway for StackChan (xiaozhi-esp32): bridges stdio MCP clients to the ESP32 over WebSocket + HTTP.
 Project-URL: Homepage, https://github.com/kisaragi-mochi/stackchan-mcp
 Project-URL: Repository, https://github.com/kisaragi-mochi/stackchan-mcp
@@ -27,6 +27,20 @@ Requires-Dist: mcp>=1.0
 Requires-Dist: pydantic>=2
 Requires-Dist: python-dotenv
 Requires-Dist: websockets>=12
+Provides-Extra: stt
+Requires-Dist: opuslib>=3; extra == 'stt'
+Provides-Extra: stt-faster-whisper
+Requires-Dist: faster-whisper>=1.0; extra == 'stt-faster-whisper'
+Requires-Dist: opuslib>=3; extra == 'stt-faster-whisper'
+Provides-Extra: stt-openai
+Requires-Dist: openai>=1.0; extra == 'stt-openai'
+Requires-Dist: opuslib>=3; extra == 'stt-openai'
+Provides-Extra: tts
+Requires-Dist: httpx>=0.27; extra == 'tts'
+Requires-Dist: opuslib>=3; extra == 'tts'
+Provides-Extra: tts-voicevox
+Requires-Dist: httpx>=0.27; extra == 'tts-voicevox'
+Requires-Dist: opuslib>=3; extra == 'tts-voicevox'
 Description-Content-Type: text/markdown
 
 # gateway
@@ -191,6 +205,16 @@ Same shape, under `mcpServers`.
 | `set_mouth(state)` | Mouth shape (`closed` / `half` / `open` / `e` / `u`), one-shot, held until next call |
 | `set_mouth_sequence(steps)` | Queue and play a list of `{shape, duration_ms}` steps locally for TTS lip-sync. The firmware walks the queue without per-step network RTT. Calling `set_mouth`, `set_avatar`, or this tool again interrupts the in-flight sequence; autonomous blink is paused while a sequence is playing. |
 | `check_vm_en` | Read PY32 VM EN GPIO state (servo power supply diagnostic) |
+| `set_led(index, r, g, b)` | Set one of the 12 base RGB LEDs by index (`0..11`); channels `0..255`. Updates immediately. |
+| `set_all_leds(r, g, b)` | Set all 12 base RGB LEDs to the same color. Updates immediately. |
+| `set_leds(colors)` | Batch-set the first N LEDs from a `[[r,g,b], ...]` array (1..12 entries). Single I2C burst + one latch — use this for animations / multi-color patterns instead of N individual `set_led` calls. Trailing LEDs (beyond `len(colors)`) keep their previous color. Validation is atomic: a malformed entry rejects the whole call without mutating any LED. |
+| `clear_leds` | Turn all 12 base RGB LEDs off. |
+
+The 12 base LEDs are 12× WS2812C wired to the PY32L020 IO expander
+(expander pin 13, not an ESP32 GPIO), so all four LED tools share the
+PY32 I2C bus with the servo-power and Si12T touch paths. If the PY32
+init fails at boot, the LED tools degrade with `available=false`
+instead of cascading errors.
 
 The mapping from these names to ESP32-side `self.*` MCP tools is in
 `stackchan_mcp/stdio_server.py`.

{stackchan_mcp-0.4.0 → stackchan_mcp-0.6.0}/README.md

@@ -160,6 +160,16 @@ Same shape, under `mcpServers`.
 | `set_mouth(state)` | Mouth shape (`closed` / `half` / `open` / `e` / `u`), one-shot, held until next call |
 | `set_mouth_sequence(steps)` | Queue and play a list of `{shape, duration_ms}` steps locally for TTS lip-sync. The firmware walks the queue without per-step network RTT. Calling `set_mouth`, `set_avatar`, or this tool again interrupts the in-flight sequence; autonomous blink is paused while a sequence is playing. |
 | `check_vm_en` | Read PY32 VM EN GPIO state (servo power supply diagnostic) |
+| `set_led(index, r, g, b)` | Set one of the 12 base RGB LEDs by index (`0..11`); channels `0..255`. Updates immediately. |
+| `set_all_leds(r, g, b)` | Set all 12 base RGB LEDs to the same color. Updates immediately. |
+| `set_leds(colors)` | Batch-set the first N LEDs from a `[[r,g,b], ...]` array (1..12 entries). Single I2C burst + one latch — use this for animations / multi-color patterns instead of N individual `set_led` calls. Trailing LEDs (beyond `len(colors)`) keep their previous color. Validation is atomic: a malformed entry rejects the whole call without mutating any LED. |
+| `clear_leds` | Turn all 12 base RGB LEDs off. |
+
+The 12 base LEDs are 12× WS2812C wired to the PY32L020 IO expander
+(expander pin 13, not an ESP32 GPIO), so all four LED tools share the
+PY32 I2C bus with the servo-power and Si12T touch paths. If the PY32
+init fails at boot, the LED tools degrade with `available=false`
+instead of cascading errors.
 
 The mapping from these names to ESP32-side `self.*` MCP tools is in
 `stackchan_mcp/stdio_server.py`.

{stackchan_mcp-0.4.0 → stackchan_mcp-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.4.0"
+version = "0.6.0"
 description = "Two-faced MCP gateway for StackChan (xiaozhi-esp32): bridges stdio MCP clients to the ESP32 over WebSocket + HTTP."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -32,6 +32,40 @@ dependencies = [
     "aiohttp>=3",
 ]
 
+[project.optional-dependencies]
+# Phase 4 TTS — see Issue #70.
+# Concrete engines (VOICEVOX, Irodori) consume these libraries:
+#   * httpx     — VOICEVOX HTTP engine client
+#   * opuslib   — Opus encoding for the device's audio decoder
+# `tts-voicevox` is a no-op alias provided so users can declare intent
+# explicitly; the VOICEVOX engine itself is an external HTTP process and
+# adds no Python dependencies of its own.
+tts = [
+    "httpx>=0.27",
+    "opuslib>=3",
+]
+tts-voicevox = [
+    "stackchan-mcp[tts]",
+]
+
+# Phase 4 STT — see Issue #91.
+# The base `stt` extra carries `opuslib` for decoding the device's
+# inbound Opus frames. Concrete engines live behind their own extras
+# so users only pull in the heavy ML dependencies they actually need.
+#   * faster-whisper — local Whisper via CTranslate2 (default, MIT)
+#   * openai         — OpenAI Whisper API client (cloud)
+stt = [
+    "opuslib>=3",
+]
+stt-faster-whisper = [
+    "stackchan-mcp[stt]",
+    "faster-whisper>=1.0",
+]
+stt-openai = [
+    "stackchan-mcp[stt]",
+    "openai>=1.0",
+]
+
 [project.urls]
 Homepage = "https://github.com/kisaragi-mochi/stackchan-mcp"
 Repository = "https://github.com/kisaragi-mochi/stackchan-mcp"

stackchan_mcp-0.6.0/stackchan_mcp/audio_stream.py

@@ -0,0 +1,151 @@
+"""Opus audio frame handling for the gateway <-> device link.
+
+Outbound (TTS) frames are produced by
+:mod:`stackchan_mcp.tts.audio_utils` and pushed here to the connected
+ESP32 via :meth:`stackchan_mcp.esp32_client.ESP32Manager.send_audio_frame`.
+
+The inbound side (STT pipeline, Phase 4 / Issue #91) is now wired:
+binary frames coming up from the device land in
+:func:`handle_audio_frame`, which buffers them into a module-level
+recording slot when one is active. The
+:mod:`stackchan_mcp.stt.orchestrator` opens the slot via
+:func:`start_recording` before sending ``listen.start`` to the device
+and closes it via :func:`stop_recording` after the capture window;
+outside an active recording, inbound frames are still discarded.
+
+The recording slot is intentionally a module-level singleton: the
+device's :class:`stackchan_mcp.esp32_client.ESP32Manager` only manages
+one connection, and the STT orchestrator serialises ``listen()`` calls
+through :attr:`ESP32Manager.listen_lock`, so concurrent captures
+cannot race the buffer. If multi-device support lands later, this
+should move onto the connection object.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Iterable
+
+if TYPE_CHECKING:
+    from .esp32_client import ESP32Manager
+
+logger = logging.getLogger(__name__)
+
+
+# --- Recording slot (inbound STT capture) ---------------------------------
+#
+# A single capture at a time is enforced by the orchestrator's
+# ``listen_lock``; this module only owns the buffer itself.
+
+_recording_session_id: str | None = None
+_recording_frames: list[bytes] = []
+
+
+def start_recording(session_id: str) -> None:
+    """Open a fresh recording slot for ``session_id``.
+
+    Any frames already buffered are discarded so a previous call that
+    crashed before ``stop_recording`` cannot leak into the next
+    capture. The orchestrator wraps start/stop in a try/finally to
+    guarantee the slot is closed even on error.
+    """
+    global _recording_session_id, _recording_frames
+    if _recording_session_id is not None:
+        # Defensive: the lock should prevent this, but if it ever
+        # fires we leak no audio — just log loudly so the regression
+        # is visible.
+        logger.warning(
+            "start_recording called while session=%s was still active; "
+            "dropping %d buffered frames",
+            _recording_session_id,
+            len(_recording_frames),
+        )
+    _recording_session_id = session_id
+    _recording_frames = []
+
+
+def stop_recording() -> list[bytes]:
+    """Close the recording slot and return the buffered Opus frames.
+
+    Returns an empty list if no recording was active. The slot is
+    cleared whether or not frames were captured so the next call to
+    :func:`start_recording` starts clean.
+    """
+    global _recording_session_id, _recording_frames
+    frames = _recording_frames
+    _recording_session_id = None
+    _recording_frames = []
+    return frames
+
+
+def is_recording() -> bool:
+    """Return ``True`` when a recording slot is currently open."""
+    return _recording_session_id is not None
+
+
+async def handle_audio_frame(data: bytes, session_id: str) -> None:
+    """Process an incoming binary Opus frame from the device.
+
+    When a recording slot is active (see :func:`start_recording`) AND
+    the frame belongs to the recording's session, appends the frame
+    to the in-memory buffer for later decoding by the STT
+    orchestrator. Frames from a different session — typical during
+    a connection swap, where the old WebSocket handler is still
+    draining incoming bytes after :meth:`ESP32Connection.disconnect`
+    has been called on the main task — are dropped so they cannot
+    bleed into the new connection's capture buffer.
+
+    Outside of an active recording the frame is logged at debug
+    level and discarded; the device may emit audio on its own (e.g.
+    after an autonomous wake-word detection) and the gateway has no
+    STT pipeline running for those frames yet.
+    """
+    if _recording_session_id is None:
+        logger.debug(
+            "audio_frame session=%s bytes=%d (discarded — no active recording)",
+            session_id,
+            len(data),
+        )
+        return
+    if _recording_session_id != session_id:
+        # A different connection is sending audio while a recording
+        # for this session is in flight. This happens when ESP32
+        # reconnects: ``ESP32Manager._handler`` swaps in a new
+        # ``ESP32Connection`` and marks the old one disconnected,
+        # but the old socket's ``async for message in ws`` loop can
+        # still drain a frame or two before the close lands. Letting
+        # those into the buffer would corrupt the new session's
+        # transcription, so drop them here.
+        logger.debug(
+            "audio_frame session=%s bytes=%d (discarded — does not match "
+            "recording session=%s)",
+            session_id,
+            len(data),
+            _recording_session_id,
+        )
+        return
+    _recording_frames.append(data)
+    logger.debug(
+        "audio_frame session=%s bytes=%d buffered (recording active)",
+        session_id,
+        len(data),
+    )
+
+
+async def push_opus_frames(
+    esp32: ESP32Manager,
+    frames: Iterable[bytes],
+) -> int:
+    """Push Opus frames to the connected ESP32.
+
+    Returns the number of frames sent so the caller can report this to
+    the MCP client. Raises :class:`ConnectionError` (via
+    :meth:`ESP32Manager.send_audio_frame`) if the device disconnects
+    mid-stream — the orchestrator turns that into a clean MCP error
+    rather than letting it bubble up as a stack trace.
+    """
+    sent = 0
+    for frame in frames:
+        await esp32.send_audio_frame(frame)
+        sent += 1
+    return sent

{stackchan_mcp-0.4.0 → stackchan_mcp-0.6.0}/stackchan_mcp/cli.py

@@ -16,6 +16,7 @@ import asyncio
 import errno
 import logging
 import os
+import platform
 import shutil
 import socket
 import subprocess
@@ -377,6 +378,56 @@ def _load_dotenv() -> None:
     load_dotenv()
 
 
+# Default Homebrew prefixes that ship libopus.dylib on macOS. Apple
+# Silicon installs default to ``/opt/homebrew``; Intel Macs use
+# ``/usr/local``. Keeping both keeps the helper portable across
+# contributor machines.
+_HOMEBREW_LIB_DIRS = ("/opt/homebrew/lib", "/usr/local/lib")
+
+
+def _ensure_libopus_findable() -> None:
+    """Make libopus reachable to opuslib's ``ctypes.find_library`` on macOS.
+
+    ``opuslib.api`` calls ``ctypes.util.find_library("opus")`` at
+    import time. On macOS that walks ``DYLD_LIBRARY_PATH`` plus a
+    couple of system-default directories — but not Homebrew's
+    ``/opt/homebrew/lib`` (Apple Silicon) or ``/usr/local/lib`` (Intel),
+    so a vanilla ``brew install opus`` lands a working libopus that
+    opuslib still cannot find. Users then see ``Could not find Opus
+    library`` even though the dylib is on disk.
+
+    Prepend any Homebrew-style lib directories that exist so the next
+    ``find_library`` call (triggered by the lazy ``import opuslib``
+    inside :func:`audio_utils.encode_opus_frames`) succeeds. We
+    deliberately *prepend* and skip duplicates so an explicit
+    ``DYLD_LIBRARY_PATH`` set by the operator (e.g. for a custom build
+    of libopus) keeps priority. No-op on non-macOS hosts.
+    """
+    if platform.system() != "Darwin":
+        return
+
+    existing = os.environ.get("DYLD_LIBRARY_PATH", "")
+    paths: list[str] = [p for p in existing.split(":") if p]
+
+    prepended: list[str] = []
+    for candidate in _HOMEBREW_LIB_DIRS:
+        if candidate in paths:
+            continue
+        if not os.path.isdir(candidate):
+            continue
+        prepended.append(candidate)
+
+    if not prepended:
+        return
+
+    os.environ["DYLD_LIBRARY_PATH"] = ":".join(prepended + paths)
+    logger.debug(
+        "Prepended Homebrew lib dirs to DYLD_LIBRARY_PATH so opuslib "
+        "can find libopus: %s",
+        prepended,
+    )
+
+
 def _run_preflight() -> int:
     """Run preflight diagnostics. Returns the desired process exit code.
 
@@ -387,6 +438,7 @@ def _run_preflight() -> int:
     warns about a missing ``STACKCHAN_TOKEN``.
     """
     _load_dotenv()
+    _ensure_libopus_findable()
 
     issues = 0
     print(f"stackchan-mcp {__version__} preflight")
@@ -527,6 +579,7 @@ def main(argv: list[str] | None = None) -> None:
         sys.exit(_run_preflight())
 
     _load_dotenv()
+    _ensure_libopus_findable()
 
     logging.basicConfig(
         level=logging.INFO,

{stackchan_mcp-0.4.0 → stackchan_mcp-0.6.0}/stackchan_mcp/esp32_client.py

@@ -14,8 +14,10 @@ import uuid
 from typing import Any
 
 import websockets
+import websockets.exceptions
 from websockets.asyncio.server import ServerConnection
 
+from .audio_stream import handle_audio_frame
 from .protocol import HelloResponse, make_mcp_message, parse_jsonrpc_response
 
 logger = logging.getLogger(__name__)
@@ -36,6 +38,13 @@ class ESP32Connection:
         self._pending: dict[int, asyncio.Future[dict[str, Any]]] = {}
         self._connected = True
         self._initialized = False
+        # Device-declared WebSocket protocol version (from the hello
+        # message). Defaults to 1, which matches the firmware's default
+        # (firmware/main/protocols/websocket_protocol.h: ``version_ = 1``)
+        # and the audio framing this gateway emits today (raw Opus
+        # payload). v2/v3 add a BinaryProtocol header that this gateway
+        # does not yet wrap — see Issue follow-up to #70.
+        self.protocol_version: int = 1
 
     @property
     def connected(self) -> bool:
@@ -142,6 +151,89 @@ class ESP32Connection:
             method = payload.get("method", "")
             logger.info("ESP32 notification: %s", method)
 
+    async def _ws_send(self, payload: bytes | str) -> None:
+        """Send a payload, translating websockets errors to ConnectionError.
+
+        The ``websockets`` library raises its own exception hierarchy
+        (``ConnectionClosed`` and friends), which is *not* a subclass
+        of the built-in :class:`ConnectionError`. Without translation
+        the orchestrator's ``except ConnectionError`` filter — and the
+        MCP handler's ``except RuntimeError`` filter — would let those
+        errors leak as raw tracebacks into the MCP transport, breaking
+        the say() tool's clean error JSON contract on mid-stream
+        disconnect.
+        """
+        try:
+            await self._ws.send(payload)
+        except (
+            websockets.exceptions.ConnectionClosed,
+            OSError,
+        ) as exc:
+            # Mark the connection dead so subsequent calls fail fast
+            # rather than each one re-discovering the broken socket.
+            self.disconnect()
+            raise ConnectionError(f"WebSocket send failed: {exc}") from exc
+
+    async def send_audio_frame(self, opus_frame: bytes) -> None:
+        """Send a single Opus frame to the ESP32 as a WebSocket binary frame.
+
+        The device's ``OnData`` handler (firmware/main/protocols/
+        websocket_protocol.cc) treats every binary frame as an Opus
+        audio payload to feed into its decoder, so this method is the
+        TTS pipeline's egress point.
+        """
+        if not self._connected:
+            raise ConnectionError("ESP32 not connected")
+        await self._ws_send(opus_frame)
+
+    async def send_tts_state(self, state: str) -> None:
+        """Send a TTS state notification (``start`` / ``stop`` / ...).
+
+        The device's :func:`Application::OnIncomingJson` translates
+        ``{"type":"tts","state":"start"}`` into
+        :data:`kDeviceStateSpeaking`, which is the gate for
+        :func:`OnIncomingAudio` pushing packets into the decode queue
+        (see ``firmware/main/application.cc``). Without bracketing the
+        audio frames in start/stop, the device drops them on the floor
+        and the speaker stays silent — the TTS tool returns success
+        without anything actually playing.
+        """
+        if not self._connected:
+            raise ConnectionError("ESP32 not connected")
+        message = {
+            "session_id": self.session_id,
+            "type": "tts",
+            "state": state,
+        }
+        await self._ws_send(json.dumps(message))
+
+    async def send_listen_state(self, state: str, mode: str = "manual") -> None:
+        """Send a listen state notification (``start`` / ``stop``).
+
+        Server-driven counterpart to the device's existing
+        :func:`Protocol::SendStartListening` (Issue #91). The
+        firmware's :func:`Application::OnIncomingJson` dispatches
+        ``state: "start"`` to :func:`Application::StartListening` and
+        ``state: "stop"`` to :func:`Application::StopListening`.
+
+        ``mode`` is currently accepted only for ``state="start"`` and is
+        carried on the wire for forward-compatibility — the firmware
+        accepts but ignores it in Phase 1 because
+        :func:`HandleStartListeningEvent` unconditionally enters
+        ``kListeningModeManualStop`` (the gateway controls the stop
+        boundary explicitly).
+        """
+        if not self._connected:
+            raise ConnectionError("ESP32 not connected")
+        message: dict[str, Any] = {
+            "session_id": self.session_id,
+            "type": "listen",
+            "state": state,
+        }
+        if state == "start":
+            message["mode"] = mode
+        await self._ws_send(json.dumps(message))
+
     def disconnect(self) -> None:
         """Mark connection as disconnected."""
         self._connected = False
@@ -167,6 +259,32 @@ class ESP32Manager:
         self._init_tasks: list[asyncio.Task] = []
         self._vision_url: str = ""
         self._vision_token: str = ""
+        # Per-device serialisation for TTS send sequences. Acquired by
+        # the orchestrator around the entire start → frames → stop
+        # block so concurrent ``say()`` invocations cannot interleave
+        # their Opus frames on the same WebSocket or overlap their
+        # ``tts.start``/``tts.stop`` notifications (which would yank
+        # the firmware out of ``kDeviceStateSpeaking`` mid-utterance
+        # and silently drop the remaining audio). The lock is scoped
+        # to the manager because the manager owns the device today —
+        # if multi-device support lands later, the lock should move
+        # onto :class:`ESP32Connection` instead.
+        self._tts_lock = asyncio.Lock()
+        # Inbound STT capture (Issue #91) shares the TTS lock rather
+        # than running on a separate one. The firmware's
+        # ``HandleStartListeningEvent`` aborts any in-flight TTS when
+        # a listen.start arrives mid-speaking (state ==
+        # ``kDeviceStateSpeaking`` → ``AbortSpeaking`` →
+        # ``SetListeningMode(kListeningModeManualStop)``), so two
+        # operations on the same device's audio path would
+        # otherwise step on each other: a ``listen()`` could yank a
+        # ``say()`` out of speaking mid-utterance, or a ``say()``
+        # could start streaming TTS frames into the buffer a
+        # concurrent ``listen()`` is capturing. Treating the audio
+        # path as a single resource makes the device's state machine
+        # observable from gateway code; if a full-duplex contract
+        # ever lands later the lock can split again.
+        self._listen_lock = self._tts_lock
 
     @property
     def device_connected(self) -> bool:
@@ -176,6 +294,26 @@ class ESP32Manager:
     def connection(self) -> ESP32Connection | None:
         return self._connection
 
+    @property
+    def tts_lock(self) -> asyncio.Lock:
+        """Per-device lock guarding the TTS send sequence.
+
+        See :attr:`_tts_lock` for the rationale; the orchestrator wraps
+        the start → frames → stop block in ``async with`` on this lock.
+        """
+        return self._tts_lock
+
+    @property
+    def listen_lock(self) -> asyncio.Lock:
+        """Per-device lock guarding the STT capture sequence.
+
+        See :attr:`_listen_lock` for the rationale; the orchestrator
+        wraps the entire ``listen.start`` → wait → ``listen.stop``
+        block in ``async with`` on this lock so two concurrent
+        ``listen()`` calls cannot share the inbound recording slot.
+        """
+        return self._listen_lock
+
     async def start(
         self,
         host: str = "0.0.0.0",
@@ -246,7 +384,14 @@ class ESP32Manager:
         try:
             async for message in ws:
                 if isinstance(message, bytes):
-                    # Binary = audio frame, ignore for now
+                    # Binary = audio frame. Forward to the audio_stream
+                    # module which buffers it for STT capture (Issue
+                    # #91) when a recording slot is open, or discards
+                    # it otherwise. Only protocol v1 is supported on
+                    # the inbound side today; the orchestrator gates
+                    # listen() on protocol_version=1 so v2/v3 frames
+                    # cannot reach this point with recording active.
+                    await handle_audio_frame(message, session_id)
                     continue
 
                 try:
@@ -265,6 +410,27 @@ class ESP32Manager:
                         await ws.close()
                         return
 
+                    # Capture the device's WebSocket protocol version
+                    # so callers (e.g. the TTS pipeline) can decide
+                    # whether their wire format is compatible. The
+                    # firmware accepts raw Opus only on v1; v2/v3 wrap
+                    # the payload in a BinaryProtocol header.
+                    raw_version = data.get("version", 1)
+                    try:
+                        connection.protocol_version = int(raw_version)
+                    except (TypeError, ValueError):
+                        connection.protocol_version = 1
+                    if connection.protocol_version != 1:
+                        logger.warning(
+                            "ESP32 negotiated WebSocket protocol "
+                            "version=%s; the gateway emits raw Opus "
+                            "binary frames matching v1 only. TTS "
+                            "calls (say) will be blocked at the "
+                            "orchestrator until v2/v3 BinaryProtocol "
+                            "header wrapping is implemented",
+                            connection.protocol_version,
+                        )
+
                     # Send hello response
                     resp = HelloResponse(session_id=session_id)
                     await ws.send(resp.model_dump_json())
@@ -323,6 +489,40 @@ class ESP32Manager:
             return None, {"code": -32000, "message": "ESP32 not initialized"}
         return await self._connection.call_tool(name, arguments)
 
+    async def send_audio_frame(self, opus_frame: bytes) -> None:
+        """Push a single Opus frame to the connected device.
+
+        Used by the TTS pipeline to deliver synthesised audio. Raises
+        :class:`ConnectionError` if no device is currently attached so
+        the orchestrator can surface a clean error to the MCP client
+        instead of silently dropping audio.
+        """
+        if not self._connection or not self._connection.connected:
+            raise ConnectionError("No ESP32 device connected")
+        await self._connection.send_audio_frame(opus_frame)
+
+    async def send_tts_state(self, state: str) -> None:
+        """Send a TTS state notification (``start`` / ``stop`` / ...).
+
+        Required around audio frame egress so the device transitions
+        into ``kDeviceStateSpeaking`` and back; see
+        :meth:`ESP32Connection.send_tts_state` for the full rationale.
+        """
+        if not self._connection or not self._connection.connected:
+            raise ConnectionError("No ESP32 device connected")
+        await self._connection.send_tts_state(state)
+
+    async def send_listen_state(self, state: str, mode: str = "manual") -> None:
+        """Send a listen state notification to put the device into /
+        out of listening mode (Issue #91).
+
+        See :meth:`ESP32Connection.send_listen_state` for the wire
+        format and the firmware-side dispatch.
+        """
+        if not self._connection or not self._connection.connected:
+            raise ConnectionError("No ESP32 device connected")
+        await self._connection.send_listen_state(state, mode=mode)
+
     def get_status(self) -> dict[str, Any]:
         """Get current connection status."""
         if not self._connection or not self._connection.connected: