stackchan-mcp 0.10.0__tar.gz → 0.11.0__tar.gz

{stackchan_mcp-0.10.0 → stackchan_mcp-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.10.0
+Version: 0.11.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
@@ -41,6 +41,10 @@ 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-irodori
+Requires-Dist: httpx>=0.27; extra == 'tts-irodori'
+Requires-Dist: miniaudio>=1.59; extra == 'tts-irodori'
+Requires-Dist: opuslib>=3; extra == 'tts-irodori'
 Provides-Extra: tts-voicevox
 Requires-Dist: httpx>=0.27; extra == 'tts-voicevox'
 Requires-Dist: opuslib>=3; extra == 'tts-voicevox'

{stackchan_mcp-0.10.0 → stackchan_mcp-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.10.0"
+version = "0.11.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"
@@ -51,7 +51,7 @@ dependencies = [
 [project.optional-dependencies]
 # Phase 4 TTS — see Issue #70.
 # Concrete engines (VOICEVOX, Irodori) consume these libraries:
-#   * httpx     — VOICEVOX HTTP engine client
+#   * httpx     — VOICEVOX / Irodori 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
@@ -63,6 +63,17 @@ tts = [
 tts-voicevox = [
     "stackchan-mcp[tts]",
 ]
+# Irodori is an external HTTP synthesis service that returns MP3 (see
+# Issue #286). On top of the base `[tts]` extra (httpx + opuslib) it adds
+# `miniaudio` to decode the MP3 response to PCM. miniaudio is a small,
+# self-contained C extension (MIT) with prebuilt wheels for Windows,
+# macOS (x86_64 + arm64), and Linux, so it installs without a system
+# audio library — unlike a ffmpeg/libav binding — which keeps the
+# Windows wheel path (and the CI windows-smoke job) simple.
+tts-irodori = [
+    "stackchan-mcp[tts]",
+    "miniaudio>=1.59",
+]
 
 # Phase 4 STT — see Issue #91.
 # The base `stt` extra carries `opuslib` for decoding the device's

{stackchan_mcp-0.10.0 → stackchan_mcp-0.11.0}/stackchan_mcp/ownership.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import json
+import math
 import os
 import socket
+import subprocess
 import sys
 import uuid
 from datetime import datetime, timezone
@@ -13,6 +15,8 @@ from typing import Literal, TypedDict
 
 LOCK_DIR = Path.home() / ".stackchan-mcp"
 LOCK_PATH = LOCK_DIR / "owner.lock"
+PROC_START_TOLERANCE_SECONDS = 2.0
+_PROC_ROOT = Path("/proc")
 
 
 LockMode = Literal["stdio", "streamable-http"]
@@ -29,6 +33,7 @@ class LockInfo(_BaseLockInfo, total=False):
     mode: LockMode
     http_endpoint: str | None
     started_by: str | None
+    proc_start_epoch: float
 
 
 class OwnershipError(RuntimeError):
@@ -65,6 +70,101 @@ def is_pid_alive(pid: int) -> bool:
     return True
 
 
+def get_process_start_time(pid: int) -> float | None:
+    """Return the kernel-reported process start time as epoch seconds.
+
+    Supported on Linux (``/proc``) and macOS (``ps lstart``). On other
+    platforms — notably Windows — this returns ``None``, so the identity
+    check is skipped and stale-lock detection falls back to the PID-only
+    liveness check (the pre-#253 behavior). Windows process-identity
+    verification is deferred per Issue #253's acceptance criteria.
+    """
+    if pid <= 0:
+        return None
+    if sys.platform.startswith("linux"):
+        return _get_process_start_time_linux(pid)
+    if sys.platform == "darwin":
+        return _get_process_start_time_macos(pid)
+    return None
+
+
+def _get_process_start_time_linux(pid: int) -> float | None:
+    try:
+        stat_text = (_PROC_ROOT / str(pid) / "stat").read_text(encoding="utf-8")
+        proc_stat_text = (_PROC_ROOT / "stat").read_text(encoding="utf-8")
+        ticks_per_second = os.sysconf("SC_CLK_TCK")
+    except (OSError, ValueError):
+        return None
+
+    if not isinstance(ticks_per_second, int) or ticks_per_second <= 0:
+        return None
+
+    try:
+        after_comm = stat_text.rsplit(")", 1)[1].strip()
+        fields = after_comm.split()
+        start_ticks = int(fields[19])
+    except (IndexError, ValueError):
+        return None
+
+    boot_time: int | None = None
+    for line in proc_stat_text.splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[0] == "btime":
+            try:
+                boot_time = int(parts[1])
+            except ValueError:
+                return None
+            break
+    if boot_time is None:
+        return None
+
+    return float(boot_time) + (float(start_ticks) / float(ticks_per_second))
+
+
+def _get_process_start_time_macos(pid: int) -> float | None:
+    env = os.environ.copy()
+    env["LC_ALL"] = "C"
+    try:
+        result = subprocess.run(
+            ["ps", "-o", "lstart=", "-p", str(pid)],
+            capture_output=True,
+            check=False,
+            env=env,
+            text=True,
+        )
+    except OSError:
+        return None
+
+    output = result.stdout.strip()
+    if not output:
+        return None
+
+    line = output.splitlines()[0].strip()
+    try:
+        started = datetime.strptime(line, "%a %b %d %H:%M:%S %Y")
+    except ValueError:
+        return None
+    return started.timestamp()
+
+
+def _coerce_proc_start_epoch(value: object) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    proc_start_epoch = float(value)
+    if not math.isfinite(proc_start_epoch):
+        return None
+    return proc_start_epoch
+
+
+def _process_identity_matches(pid: int, expected_start: float | None) -> bool:
+    if expected_start is None:
+        return True
+    actual_start = get_process_start_time(pid)
+    if actual_start is None:
+        return True
+    return abs(actual_start - expected_start) <= PROC_START_TOLERANCE_SECONDS
+
+
 def _is_pid_alive_windows(pid: int) -> bool:
     import ctypes
     import ctypes.wintypes
@@ -152,6 +252,11 @@ def read_lock(path: Path = LOCK_PATH) -> LockInfo | None:
         if started_by is None or isinstance(started_by, str):
             info["started_by"] = started_by
 
+    if "proc_start_epoch" in raw:
+        proc_start_epoch = _coerce_proc_start_epoch(raw["proc_start_epoch"])
+        if proc_start_epoch is not None:
+            info["proc_start_epoch"] = proc_start_epoch
+
     return info
 
 
@@ -178,10 +283,11 @@ def acquire_lock(
 ) -> LockInfo:
     """Acquire the ownership lock. Raise OwnershipError on refuse.
 
-    The default stdio-mode call writes the original #177 lock shape so
-    older lock readers and ``stackchan-mcp --check`` output remain
-    compatible. Daemon transports can attach optional metadata for
-    diagnostics without changing the atomic hardlink claim.
+    The default stdio-mode call writes the original #177 lock base fields
+    plus additive process identity metadata. Older lock readers remain
+    compatible because the new field is optional JSON. Daemon transports
+    can attach optional metadata for diagnostics without changing the
+    atomic hardlink claim.
     """
     if mode not in ("stdio", "streamable-http"):
         raise ValueError(f"unsupported lock mode: {mode!r}")
@@ -195,25 +301,39 @@ def acquire_lock(
         existing = read_lock(path)
         if existing is not None:
             if is_pid_alive(existing["pid"]):
-                raise OwnershipError(
-                    "stackchan-mcp: device already owned by "
-                    f"{existing['owner_id']} "
-                    f"(pid {existing['pid']}, since {existing['start_ts']})"
+                if _process_identity_matches(
+                    existing["pid"], existing.get("proc_start_epoch")
+                ):
+                    raise OwnershipError(
+                        "stackchan-mcp: device already owned by "
+                        f"{existing['owner_id']} "
+                        f"(pid {existing['pid']}, since {existing['start_ts']})"
+                    )
+                print(
+                    "stackchan-mcp: removed stale lock from recycled pid "
+                    f"{existing['pid']}",
+                    file=sys.stderr,
+                )
+            else:
+                print(
+                    "stackchan-mcp: removed stale lock from dead pid "
+                    f"{existing['pid']}",
+                    file=sys.stderr,
                 )
-            print(
-                f"stackchan-mcp: removed stale lock from dead pid {existing['pid']}",
-                file=sys.stderr,
-            )
             path.unlink(missing_ok=True)
         elif path.exists():
             path.unlink()
 
+        pid = os.getpid()
+        proc_start_epoch = get_process_start_time(pid)
         info: LockInfo = {
             "owner_id": owner_id,
-            "pid": os.getpid(),
+            "pid": pid,
             "start_ts": _now_iso(),
             "host": socket.gethostname(),
         }
+        if proc_start_epoch is not None:
+            info["proc_start_epoch"] = proc_start_epoch
         if mode != "stdio":
             info["mode"] = mode
         if http_endpoint is not None:
@@ -246,8 +366,9 @@ def release_lock_if_owner(info: LockInfo, path: Path = LOCK_PATH) -> bool:
     """Remove the lock file only if it still belongs to ``info``.
 
     Returns ``True`` if the lock was removed, ``False`` if the on-disk
-    lock has a different ``owner_id`` / ``pid`` / ``start_ts`` or no
-    longer exists. This is the owner-scoped counterpart to
+    lock has a different ``owner_id`` / ``pid`` / ``start_ts`` /
+    ``proc_start_epoch`` or no longer exists. This is the owner-scoped
+    counterpart to
     :func:`release_lock` and is intended for cleanup paths (``finally``
     blocks, ``atexit.register``) where the caller may have lost ownership
     between claim and cleanup — for example after the gateway exited and
@@ -263,6 +384,12 @@ def release_lock_if_owner(info: LockInfo, path: Path = LOCK_PATH) -> bool:
         or existing.get("start_ts") != info.get("start_ts")
     ):
         return False
+    if (
+        "proc_start_epoch" in existing
+        and "proc_start_epoch" in info
+        and existing["proc_start_epoch"] != info["proc_start_epoch"]
+    ):
+        return False
     try:
         path.unlink()
         return True

{stackchan_mcp-0.10.0 → stackchan_mcp-0.11.0}/stackchan_mcp/stdio_server.py

@@ -493,6 +493,14 @@ async def _dispatch_mcp_tool(
             "self.robot.check_vm_en",
             {},
         ),
+        "gateway_config_get": (
+            "self.gateway_config.get",
+            {},
+        ),
+        "gateway_config_set": (
+            "self.gateway_config.set",
+            arguments,
+        ),
         "set_avatar": (
             "self.display.set_avatar",
             arguments,
@@ -537,6 +545,26 @@ async def _dispatch_mcp_tool(
             "self.led.clear",
             {},
         ),
+        "port_b_ws2812_init": (
+            "self.port_b.ws2812.init",
+            arguments,
+        ),
+        "port_b_ws2812_set_pixel": (
+            "self.port_b.ws2812.set_pixel",
+            arguments,
+        ),
+        "port_b_ws2812_set_strip": (
+            "self.port_b.ws2812.set_strip",
+            {"colors": json.dumps(arguments.get("colors", []))},
+        ),
+        "port_b_ws2812_refresh": (
+            "self.port_b.ws2812.refresh",
+            {},
+        ),
+        "port_b_ws2812_clear": (
+            "self.port_b.ws2812.clear",
+            {},
+        ),
         "i2c_scan": (
             "self.i2c.scan",
             {},
@@ -745,6 +773,77 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                 ),
                 inputSchema={"type": "object", "properties": {}},
             ),
+            Tool(
+                name="gateway_config_get",
+                description=(
+                    "Read the device's NVS-backed WebSocket gateway "
+                    "connection settings. Returns url, fallback_url, "
+                    "token_set (never the token value), forced_keys, "
+                    "force_mode, discovery_enabled, and connected_url when "
+                    "the current WebSocket candidate is connected. Empty url "
+                    "enables mDNS discovery when firmware discovery support "
+                    "is compiled in and the primary URL is not forced; "
+                    "fallback_url is tried after discovery and is suitable "
+                    "for an out-of-LAN relay. forced_keys lists any of url, "
+                    "fallback_url, and token that a non-empty Kconfig default "
+                    "overrides at connect time; force_mode=true means at "
+                    "least one key is forced."
+                ),
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="gateway_config_set",
+                description=(
+                    "Update the device's NVS-backed WebSocket gateway "
+                    "connection settings. Optional string fields: url, "
+                    "fallback_url, token; at least one must be provided. "
+                    "Passing an empty string clears that key. Leave url "
+                    "empty to enable mDNS discovery on the next reconnect "
+                    "when firmware discovery support is compiled in and the "
+                    "primary URL is not forced; fallback_url is tried after "
+                    "discovery and is suitable for an out-of-LAN relay. The "
+                    "change is persisted but does not disconnect, reconnect, "
+                    "or reboot the device; it takes effect on the next "
+                    "reconnect. forced_keys lists any of url, fallback_url, "
+                    "and token that a non-empty Kconfig default overrides at "
+                    "connect time; force_mode=true means at least one key is "
+                    "forced, so updates to those keys are ignored until a "
+                    "non-force build is flashed."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "url": {
+                            "type": "string",
+                            "description": (
+                                "Primary NVS WebSocket URL. Empty string "
+                                "clears websocket.url, which enables mDNS "
+                                "discovery on the next reconnect when "
+                                "discovery is compiled in and the primary URL "
+                                "is not forced."
+                            ),
+                        },
+                        "fallback_url": {
+                            "type": "string",
+                            "description": (
+                                "Fallback NVS WebSocket URL. Tried after "
+                                "discovery and suitable for an out-of-LAN "
+                                "relay. Empty string clears "
+                                "websocket.fallback_url."
+                            ),
+                        },
+                        "token": {
+                            "type": "string",
+                            "description": (
+                                "Bearer token stored in NVS and sent to the "
+                                "gateway. Empty string clears the token. The "
+                                "token value is never returned by "
+                                "gateway_config_get."
+                            ),
+                        },
+                    },
+                },
+            ),
             Tool(
                 name="set_avatar",
                 description=(
@@ -1029,19 +1128,157 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                 description="Turn off all 12 RGB LEDs on the StackChan base.",
                 inputSchema={"type": "object", "properties": {}},
             ),
+            Tool(
+                name="port_b_ws2812_init",
+                description=(
+                    "Initialize a WS2812-compatible LED strip connected to "
+                    "Port B (CoreS3 HY2.0-4P digital OUTPUT, GPIO 9). "
+                    "led_count is the number of LEDs in the strip (1..256). "
+                    "Repeated calls with the same led_count are no-ops; a "
+                    "different led_count rebuilds the strip handle. Port B "
+                    "outputs 3.3 V CMOS data on GPIO 9; older strict 5 V "
+                    "WS2812 variants may require a level shifter."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "led_count": {
+                            "type": "integer",
+                            "description": "Number of LEDs in the strip (1..256).",
+                            "minimum": 1,
+                            "maximum": 256,
+                        },
+                    },
+                    "required": ["led_count"],
+                },
+            ),
+            Tool(
+                name="port_b_ws2812_set_pixel",
+                description=(
+                    "Set one LED in the Port B WS2812 strip buffer. Call "
+                    "port_b_ws2812_init first. index is 0..255, with the "
+                    "effective range bounded by led_count. r, g, and b are "
+                    "0..255. By default the color is buffered only; pass "
+                    "refresh=true to latch it immediately, or call "
+                    "port_b_ws2812_refresh after several buffered updates. "
+                    "Port B outputs 3.3 V CMOS data on GPIO 9; older strict "
+                    "5 V WS2812 variants may require a level shifter."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "index": {
+                            "type": "integer",
+                            "description": "LED index (0..255).",
+                            "minimum": 0,
+                            "maximum": 255,
+                        },
+                        "r": {
+                            "type": "integer",
+                            "description": "Red 0..255.",
+                            "minimum": 0,
+                            "maximum": 255,
+                        },
+                        "g": {
+                            "type": "integer",
+                            "description": "Green 0..255.",
+                            "minimum": 0,
+                            "maximum": 255,
+                        },
+                        "b": {
+                            "type": "integer",
+                            "description": "Blue 0..255.",
+                            "minimum": 0,
+                            "maximum": 255,
+                        },
+                        "refresh": {
+                            "type": "boolean",
+                            "description": "True to latch the update immediately.",
+                            "default": False,
+                        },
+                    },
+                    "required": ["index", "r", "g", "b"],
+                },
+            ),
+            Tool(
+                name="port_b_ws2812_set_strip",
+                description=(
+                    "Set multiple LEDs in the Port B WS2812 strip and refresh "
+                    "immediately. Call port_b_ws2812_init first. colors is an "
+                    "array of [r,g,b] integer triples applied from LED index 0; "
+                    "up to led_count entries are written, extras are ignored, "
+                    "and missing trailing entries preserve the previous buffer. "
+                    "The firmware validates the full payload before writing. "
+                    "Port B outputs 3.3 V CMOS data on GPIO 9; older strict "
+                    "5 V WS2812 variants may require a level shifter."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "colors": {
+                            "type": "array",
+                            "description": (
+                                "Array of [r,g,b] triples, each integer 0..255."
+                            ),
+                            "items": {
+                                "type": "array",
+                                "items": {
+                                    "type": "integer",
+                                    "minimum": 0,
+                                    "maximum": 255,
+                                },
+                                "minItems": 3,
+                                "maxItems": 3,
+                            },
+                            "minItems": 1,
+                            "maxItems": 256,
+                        },
+                    },
+                    "required": ["colors"],
+                },
+            ),
+            Tool(
+                name="port_b_ws2812_refresh",
+                description=(
+                    "Refresh the Port B WS2812 strip, latching the current "
+                    "buffered colors out on CoreS3 HY2.0-4P digital OUTPUT "
+                    "GPIO 9. Call port_b_ws2812_init first. Use this after "
+                    "one or more port_b_ws2812_set_pixel calls made with "
+                    "refresh=false. Port B outputs 3.3 V CMOS data; older "
+                    "strict 5 V WS2812 variants may require a level shifter."
+                ),
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="port_b_ws2812_clear",
+                description=(
+                    "Turn off every LED in the Port B WS2812 strip and "
+                    "refresh immediately on CoreS3 HY2.0-4P digital OUTPUT "
+                    "GPIO 9. Call port_b_ws2812_init first. This clears the "
+                    "driver's per-pixel buffer. Port B outputs 3.3 V CMOS "
+                    "data; older strict 5 V WS2812 variants may require a "
+                    "level shifter."
+                ),
+                inputSchema={"type": "object", "properties": {}},
+            ),
             Tool(
                 name="say",
                 description=(
                     "Speak the given text on the device speaker via gateway-side "
-                    "TTS (Phase 4, Issue #70). The gateway synthesises audio, "
-                    "encodes it to Opus, and pushes frames over the existing "
-                    "WebSocket — the device firmware does not change. Engine is "
-                    "selectable via 'voice' (default 'voicevox'). "
-                    "NOTE: this build ships the framework only; concrete engines "
-                    "(VOICEVOX, Irodori) land in follow-up PRs and require the "
-                    "matching optional extra (e.g. "
-                    "'pip install stackchan-mcp[tts-voicevox]'). Calling this tool "
-                    "before an engine is registered returns a clear error."
+                    "TTS. The gateway synthesises audio, encodes it to Opus, "
+                    "and pushes frames over the existing WebSocket; the device "
+                    "firmware does not change. Engine is selectable via 'voice' "
+                    "(default 'voicevox'). If the text contains a supported "
+                    "expression emoji, say first switches the avatar face in the "
+                    "same call: happy (😊 😄 😀 😁 🙂 😆 🥰 😍 😋 🤗), "
+                    "sad (😢 😭 😞 😔 ☹️ 🙁 😿), surprised (😲 😮 😯 😱 🤯), "
+                    "embarrassed (😳 😅 🫣), thinking (🤔 🧐 💭). The first "
+                    "mapped emoji wins; unmapped emoji do not change the face, "
+                    "and emoji never select 'off'. Irodori keeps emoji in the "
+                    "TTS input so they can act as voice-style cues. Engines "
+                    "without emoji-style support, including VOICEVOX, strip all "
+                    "emoji before synthesis; if stripping leaves empty text, the "
+                    "face change is still attempted and speech is skipped."
                 ),
                 inputSchema={
                     "type": "object",

{stackchan_mcp-0.10.0 → stackchan_mcp-0.11.0}/stackchan_mcp/tts/__init__.py

@@ -48,7 +48,14 @@ def _register_voicevox() -> None:
     get_registry().register(VoicevoxEngine())
 
 
+def _register_irodori() -> None:
+    from .irodori import IrodoriEngine
+
+    get_registry().register(IrodoriEngine())
+
+
 _try_register(_register_voicevox, "voicevox")
+_try_register(_register_irodori, "irodori")
 
 
 __all__ = [

{stackchan_mcp-0.10.0 → stackchan_mcp-0.11.0}/stackchan_mcp/tts/base.py

@@ -29,6 +29,11 @@ class TTSEngine(ABC):
     #: Concrete subclasses must override with a non-empty string.
     name: str = ""
 
+    #: Whether the engine natively interprets emoji as voice-style cues.
+    #: Engines that leave this false receive emoji-stripped text from
+    #: the orchestrator.
+    supports_emoji_style: bool = False
+
     @abstractmethod
     async def synthesize(self, text: str, **opts: Any) -> bytes:
         """Synthesise ``text`` into 16 kHz mono PCM (signed 16-bit LE).

stackchan_mcp-0.11.0/stackchan_mcp/tts/emoji_expression.py

@@ -0,0 +1,80 @@
+"""Emoji-driven avatar expression helpers for ``say`` text."""
+
+from __future__ import annotations
+
+import re
+
+
+EMOJI_FACE_GROUPS: dict[str, tuple[str, ...]] = {
+    "happy": ("😊", "😄", "😀", "😁", "🙂", "😆", "🥰", "😍", "😋", "🤗"),
+    "sad": ("😢", "😭", "😞", "😔", "☹️", "🙁", "😿"),
+    "surprised": ("😲", "😮", "😯", "😱", "🤯"),
+    "embarrassed": ("😳", "😅", "🫣"),
+    "thinking": ("🤔", "🧐", "💭"),
+}
+
+_EMOJI_TO_FACE: dict[str, str] = {
+    emoji: face
+    for face, emojis in EMOJI_FACE_GROUPS.items()
+    for emoji in emojis
+}
+_MAPPED_EMOJIS = tuple(
+    sorted(_EMOJI_TO_FACE, key=lambda emoji: len(emoji), reverse=True)
+)
+
+_EMOJI_BASE = (
+    "["
+    "\u00a9\u00ae"
+    "\u2600-\u27bf"
+    "\U0001f000-\U0001faff"
+    "]"
+)
+_EMOJI_MODIFIER = "[\ufe0f\U0001f3fb-\U0001f3ff]*"
+_EMOJI_SEQUENCE_RE = re.compile(
+    f"(?:[0-9#*]\ufe0f?\u20e3|"
+    f"{_EMOJI_BASE}{_EMOJI_MODIFIER}"
+    f"(?:\u200d{_EMOJI_BASE}{_EMOJI_MODIFIER})*)"
+)
+_EMOJI_RESIDUE_RE = re.compile("[\ufe0f\u200d\U0001f3fb-\U0001f3ff\u20e3]")
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+def detect_emoji_face(text: str) -> str | None:
+    """Return the face mapped from the first supported emoji in ``text``."""
+    best_index: int | None = None
+    best_emoji: str | None = None
+
+    for emoji in _MAPPED_EMOJIS:
+        index = text.find(emoji)
+        if index < 0:
+            continue
+        if (
+            best_index is None
+            or index < best_index
+            or (
+                index == best_index
+                and best_emoji is not None
+                and len(emoji) > len(best_emoji)
+            )
+        ):
+            best_index = index
+            best_emoji = emoji
+
+    if best_emoji is None:
+        return None
+    return _EMOJI_TO_FACE[best_emoji]
+
+
+def contains_emoji(text: str) -> bool:
+    """Return whether ``text`` contains any Unicode emoji-like sequence."""
+    return _EMOJI_SEQUENCE_RE.search(text) is not None
+
+
+def strip_emoji_for_plain_tts(text: str) -> str:
+    """Remove emoji for engines that do not interpret them as style cues."""
+    if not contains_emoji(text):
+        return text
+
+    stripped = _EMOJI_SEQUENCE_RE.sub(" ", text)
+    stripped = _EMOJI_RESIDUE_RE.sub(" ", stripped)
+    return _WHITESPACE_RE.sub(" ", stripped).strip()