scitex 2.16.0__py3-none-any.whl → 2.16.2__py3-none-any.whl

scitex/audio/_mcp/speak_handlers.py

@@ -8,6 +8,7 @@ over audio playback location (server vs relay).
 from __future__ import annotations
 
 import asyncio
+import os
 from datetime import datetime
 from pathlib import Path
 
@@ -19,14 +20,16 @@ __all__ = [
 
 def _get_audio_dir() -> Path:
     """Get the audio output directory."""
-    import os
-
     base_dir = Path(os.getenv("SCITEX_DIR", Path.home() / ".scitex"))
     audio_dir = base_dir / "audio"
     audio_dir.mkdir(parents=True, exist_ok=True)
     return audio_dir
 
 
+# Import from common module
+from .._audio_check import check_local_audio_available as check_audio_sink_state
+
+
 def _get_signature() -> str:
     """Get signature string with hostname, project, and branch."""
     import os
@@ -74,7 +77,40 @@ async def speak_local_handler(
 
     Use when running Claude Code directly on your local machine.
     Audio plays on the machine where the MCP server is running.
+
+    Returns success=False if:
+    - SCITEX_AUDIO_MODE=remote (should use relay instead)
+    - Audio sink is SUSPENDED (no output device)
+    - Playback was requested but failed
     """
+    # Check if mode is set to remote - local playback should not be used
+    audio_mode = os.getenv("SCITEX_AUDIO_MODE", "").lower()
+    if audio_mode == "remote":
+        return {
+            "success": False,
+            "error": "SCITEX_AUDIO_MODE=remote but speak_local was called",
+            "reason": "Environment configured for remote audio playback",
+            "instructions": [
+                "Use speak_relay instead, or",
+                "Set SCITEX_AUDIO_MODE=local to enable local playback",
+            ],
+        }
+
+    # Check if audio sink is usable before attempting playback
+    if play:
+        sink_state = check_audio_sink_state()
+        if not sink_state["available"]:
+            return {
+                "success": False,
+                "error": f"Audio output not available: {sink_state['reason']}",
+                "sink_state": sink_state["state"],
+                "reason": sink_state["reason"],
+                "instructions": [
+                    "1. Connect speakers/headphones, or",
+                    "2. Set SCITEX_AUDIO_MODE=remote and configure relay server",
+                ],
+            }
+
     try:
         from .. import speak as tts_speak
         from .._cross_process_lock import AudioPlaybackLock
@@ -111,13 +147,22 @@ async def speak_local_handler(
             finally:
                 lock.release()
 
-        result_path = await loop.run_in_executor(None, do_speak)
+        speak_result = await loop.run_in_executor(None, do_speak)
+
+        # speak_result is a dict with: success, played, play_requested, backend, path, mode
+        actually_played = speak_result.get("played", False)
+
+        # Determine success: if play was requested, it must have actually played
+        success = True
+        if play and not actually_played:
+            success = False
 
         result = {
-            "success": True,
+            "success": success,
             "text": text,
-            "backend": backend,
-            "played": play,
+            "backend": speak_result.get("backend", backend),
+            "played": actually_played,
+            "play_requested": play,
             "played_on": "server",
             "agent_id": agent_id,
             "timestamp": datetime.now().isoformat(),
@@ -125,8 +170,11 @@ async def speak_local_handler(
         if signature:
             result["signature"] = sig
             result["full_text"] = final_text
-        if result_path:
-            result["path"] = str(result_path)
+        if speak_result.get("path"):
+            result["path"] = str(speak_result["path"])
+        if not success:
+            result["error"] = "Playback was requested but audio did not play"
+            result["reason"] = "No audio player succeeded or sink unavailable"
 
         return result
 

scitex/audio/_speak.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""Main speak() function with smart local/remote routing.
+
+This module provides the primary speak() function that intelligently
+routes audio to local or relay based on availability.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+__all__ = [
+    "speak",
+    "_speak_local",
+    "_try_speak_with_fallback",
+]
+
+
+def _try_speak_with_fallback(
+    text: str,
+    voice: Optional[str] = None,
+    play: bool = True,
+    output_path: Optional[str] = None,
+    **kwargs,
+) -> tuple:
+    """Try to speak with fallback through backends.
+
+    Returns:
+        (result_dict, backend_used, error_log)
+        result_dict has keys: path, played, success, play_requested
+    """
+    from . import FALLBACK_ORDER, available_backends, get_tts
+
+    backends = available_backends()
+    errors = []
+
+    for backend in FALLBACK_ORDER:
+        if backend not in backends:
+            continue
+
+        try:
+            tts = get_tts(backend, **kwargs)
+            result = tts.speak(
+                text=text,
+                voice=voice,
+                play=play,
+                output_path=output_path,
+            )
+            # result is now a dict with: path, played, success, play_requested
+            result["backend"] = backend
+            return (result, backend, errors)
+        except Exception as e:
+            errors.append(f"{backend}: {str(e)}")
+            continue
+
+    return (None, None, errors)
+
+
+def _speak_local(
+    text: str,
+    backend: Optional[str] = None,
+    voice: Optional[str] = None,
+    play: bool = True,
+    output_path: Optional[str] = None,
+    fallback: bool = True,
+    **kwargs,
+) -> dict:
+    """Local TTS playback (original implementation).
+
+    Returns:
+        Dict with keys: success, played, play_requested, backend, path (optional).
+    """
+    from . import get_tts
+
+    # If specific backend requested without fallback
+    if backend and not fallback:
+        tts = get_tts(backend, **kwargs)
+        result = tts.speak(text=text, voice=voice, play=play, output_path=output_path)
+        result["backend"] = backend
+        return result
+
+    # Use fallback logic
+    if fallback and backend is None:
+        result, used_backend, errors = _try_speak_with_fallback(
+            text=text, voice=voice, play=play, output_path=output_path, **kwargs
+        )
+        if result is None and errors:
+            raise RuntimeError("All TTS backends failed:\n" + "\n".join(errors))
+        return (
+            result if result else {"success": False, "played": False, "errors": errors}
+        )
+
+    # Specific backend with fallback enabled
+    try:
+        tts = get_tts(backend, **kwargs)
+        result = tts.speak(text=text, voice=voice, play=play, output_path=output_path)
+        result["backend"] = backend
+        return result
+    except Exception as e:
+        if fallback:
+            result, used_backend, errors = _try_speak_with_fallback(
+                text=text, voice=voice, play=play, output_path=output_path, **kwargs
+            )
+            if result is None:
+                raise RuntimeError(
+                    f"Primary backend '{backend}' failed: {e}\n"
+                    f"Fallback errors:\n" + "\n".join(errors)
+                )
+            return result
+        raise
+
+
+def speak(
+    text: str,
+    backend: Optional[str] = None,
+    voice: Optional[str] = None,
+    play: bool = True,
+    output_path: Optional[str] = None,
+    fallback: bool = True,
+    rate: Optional[int] = None,
+    speed: Optional[float] = None,
+    mode: Optional[str] = None,
+    **kwargs,
+) -> dict:
+    """Convert text to speech with smart local/remote switching.
+
+    Modes:
+        - local: Always use local TTS backends (fails if audio unavailable)
+        - remote: Always forward to relay server
+        - auto: Smart routing - prefers relay if local audio unavailable
+
+    Smart Routing (auto mode):
+        1. Checks if local audio sink is available (not SUSPENDED)
+        2. If local unavailable and relay configured, uses relay
+        3. If both unavailable, returns error with clear message
+
+    Fallback order (local): elevenlabs -> gtts -> pyttsx3
+
+    Args:
+        text: Text to speak.
+        backend: TTS backend ('pyttsx3', 'gtts', 'elevenlabs').
+                 Auto-selects with fallback if None.
+        voice: Voice name, ID, or language code.
+        play: Whether to play the audio.
+        output_path: Path to save audio file.
+        fallback: If True, try next backend on failure.
+        rate: Speech rate in words per minute (pyttsx3 only, default 150).
+        speed: Speed multiplier for gtts (1.0=normal, >1.0=faster, <1.0=slower).
+        mode: Override mode ('local', 'remote', 'auto'). Uses env if None.
+        **kwargs: Additional backend options.
+
+    Returns:
+        Dict with: success, played, play_requested, backend, path (if saved), mode.
+
+    Environment Variables:
+        SCITEX_AUDIO_MODE: Default mode ('local', 'remote', 'auto')
+        SCITEX_AUDIO_RELAY_URL: Relay server URL for remote mode
+    """
+    from ._audio_check import check_local_audio_available
+    from ._branding import get_mode, get_relay_url
+    from ._relay import is_relay_available, relay_speak
+
+    # Remove rate/speed from kwargs to avoid duplicate passing
+    kwargs.pop("rate", None)
+    kwargs.pop("speed", None)
+
+    # Determine mode
+    effective_mode = mode or get_mode()
+
+    # Remote mode: always use relay
+    if effective_mode == "remote":
+        relay_url = get_relay_url()
+        if not relay_url:
+            return {
+                "success": False,
+                "played": False,
+                "play_requested": play,
+                "mode": "remote",
+                "error": "SCITEX_AUDIO_RELAY_URL or SCITEX_AUDIO_RELAY_HOST not set",
+            }
+        result = relay_speak(
+            text=text,
+            backend=backend,
+            voice=voice,
+            rate=rate or 150,
+            speed=speed or 1.5,
+            play=play,
+            **kwargs,
+        )
+        return {
+            "success": result.get("success", False),
+            "played": result.get("success", False) and play,
+            "play_requested": play,
+            "mode": "remote",
+            "path": result.get("saved_to"),
+        }
+
+    # Auto mode: smart routing based on local audio availability
+    if effective_mode == "auto":
+        # Check local audio availability when playback requested
+        local_audio_ok = True
+        local_audio_info = None
+        if play:
+            local_audio_info = check_local_audio_available()
+            local_audio_ok = local_audio_info.get("available", True)
+
+        relay_url = get_relay_url()
+        relay_ok = relay_url and is_relay_available()
+
+        # Smart routing: prefer relay if local audio unavailable
+        if not local_audio_ok and relay_ok:
+            try:
+                result = relay_speak(
+                    text=text,
+                    backend=backend,
+                    voice=voice,
+                    rate=rate or 150,
+                    speed=speed or 1.5,
+                    play=play,
+                    **kwargs,
+                )
+                if result.get("success"):
+                    return {
+                        "success": True,
+                        "played": play,
+                        "play_requested": play,
+                        "mode": "remote",
+                        "path": result.get("saved_to"),
+                        "routing": f"relay (local: {local_audio_info.get('reason')})",
+                    }
+            except Exception:
+                pass  # Fall through to local
+
+        elif relay_ok:
+            # Both available, try relay first
+            try:
+                result = relay_speak(
+                    text=text,
+                    backend=backend,
+                    voice=voice,
+                    rate=rate or 150,
+                    speed=speed or 1.5,
+                    play=play,
+                    **kwargs,
+                )
+                if result.get("success"):
+                    return {
+                        "success": True,
+                        "played": play,
+                        "play_requested": play,
+                        "mode": "remote",
+                        "path": result.get("saved_to"),
+                    }
+            except Exception:
+                pass  # Fall through to local
+
+        # Local unavailable and no relay = failure
+        if not local_audio_ok and not relay_ok:
+            return {
+                "success": False,
+                "played": False,
+                "play_requested": play,
+                "mode": "local",
+                "error": f"Audio unavailable: {local_audio_info.get('reason')}",
+                "local_state": local_audio_info.get("state"),
+                "relay_configured": relay_url is not None,
+            }
+
+    # Local mode (explicit or fallback from auto)
+    if effective_mode == "local" and play:
+        local_audio_info = check_local_audio_available()
+        if not local_audio_info.get("available", True):
+            return {
+                "success": False,
+                "played": False,
+                "play_requested": play,
+                "mode": "local",
+                "error": f"Local audio unavailable: {local_audio_info.get('reason')}",
+                "local_state": local_audio_info.get("state"),
+            }
+
+    result = _speak_local(
+        text=text,
+        backend=backend,
+        voice=voice,
+        play=play,
+        output_path=output_path,
+        fallback=fallback,
+        **kwargs,
+    )
+    result["mode"] = "local"
+    return result
+
+
+# EOF

scitex/audio/mcp_server.py

@@ -76,7 +76,7 @@ if FASTMCP_AVAILABLE:
         return loop.run_until_complete(coro)
 
     @mcp.tool()
-    def speak(
+    def audio_speak(
         text: str,
         backend: Optional[str] = None,
         voice: Optional[str] = None,
@@ -86,93 +86,118 @@ if FASTMCP_AVAILABLE:
         save: bool = False,
         fallback: bool = True,
         agent_id: Optional[str] = None,
+        signature: bool = False,
     ) -> str:
         """[audio] Convert text to speech with fallback (pyttsx3 -> gtts -> elevenlabs).
 
-        NOTE: Plays on SERVER. For remote use, see speak_relay.
-        """
-        return audio_speak_local(
-            text=text, backend=backend, voice=voice, rate=rate,
-            speed=speed, play=play, save=save, fallback=fallback,
-            agent_id=agent_id,
-        )
+        Smart routing: Automatically uses relay when local audio unavailable.
 
-    @mcp.tool()
-    def audio_speak_local(
-        text: str,
-        backend: Optional[str] = None,
-        voice: Optional[str] = None,
-        rate: int = 150,
-        speed: float = 1.5,
-        play: bool = True,
-        save: bool = False,
-        fallback: bool = True,
-        agent_id: Optional[str] = None,
-    ) -> str:
-        """[audio] Convert text to speech on the LOCAL/SERVER machine.
+        Routing logic (mode=auto, default):
+        - If local audio sink is SUSPENDED and relay available -> uses relay
+        - If local audio available -> uses local
+        - If neither available -> returns error with instructions
 
-        Use when running Claude Code directly on your local machine.
-        Audio plays where MCP server runs.
+        Environment variables:
+        - SCITEX_AUDIO_MODE: 'local', 'remote', or 'auto' (default: auto)
+        - SCITEX_AUDIO_RELAY_URL: Relay server URL for remote playback
 
         Args:
             text: Text to convert to speech
             backend: TTS backend (pyttsx3, gtts, elevenlabs)
             voice: Voice/language
             rate: Speech rate (pyttsx3 only)
-            speed: Speed multiplier (gtts)
+            speed: Speed multiplier for gtts (default 1.5)
             play: Play audio (default True)
             save: Save to file (default False)
             fallback: Try next backend on failure
-            agent_id: Agent identifier
+            agent_id: Agent identifier for tracking
+            signature: Prepend hostname/project/branch to text
         """
-        from ._mcp.speak_handlers import speak_local_handler
-
-        result = _run_async(speak_local_handler(
-            text=text, backend=backend, voice=voice, rate=rate,
-            speed=speed, play=play, save=save, fallback=fallback,
-            agent_id=agent_id,
-        ))
-        return json.dumps(result, indent=2)
+        from ._cross_process_lock import AudioPlaybackLock
+        from ._speak import speak as tts_speak
 
-    @mcp.tool()
-    def audio_speak_relay(
-        text: str,
-        backend: Optional[str] = None,
-        voice: Optional[str] = None,
-        rate: int = 150,
-        speed: float = 1.5,
-        play: bool = True,
-        save: bool = False,
-        fallback: bool = True,
-        agent_id: Optional[str] = None,
-    ) -> str:
-        """[audio] Convert text to speech via RELAY server (remote playback).
-
-        Use when running on remote server (e.g., NAS) and want audio
-        on your local machine. REQUIRES relay server running locally.
-
-        Args:
-            text: Text to convert to speech
-            backend: TTS backend (pyttsx3, gtts, elevenlabs)
-            voice: Voice/language
-            rate: Speech rate (pyttsx3 only)
-            speed: Speed multiplier (gtts)
-            play: Play audio (default True)
-            save: Save to file (default False)
-            fallback: Try next backend on failure
-            agent_id: Agent identifier
-
-        Returns:
-            Success with playback info, or error with setup instructions
-        """
-        from ._mcp.speak_handlers import speak_relay_handler
+        try:
+            output_path = None
+            if save:
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                output_path = str(_get_audio_dir() / f"tts_{timestamp}.mp3")
+
+            # Prepend signature if requested
+            final_text = text
+            sig = None
+            if signature:
+                import os
+                import socket
+                import subprocess
+
+                hostname = socket.gethostname()
+                cwd = os.getcwd()
+                project = os.path.basename(cwd)
+                branch = None
+                try:
+                    result = subprocess.run(
+                        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                        capture_output=True, text=True, cwd=cwd, timeout=5,
+                    )
+                    if result.returncode == 0:
+                        branch = result.stdout.strip()
+                except Exception:
+                    pass
+                parts = [f"Hostname: {hostname}", f"Project: {project}"]
+                if branch:
+                    parts.append(f"Branch: {branch}")
+                sig = ". ".join(parts) + ". "
+                final_text = sig + text
+
+            # Acquire cross-process lock for FIFO audio playback
+            lock = AudioPlaybackLock()
+            lock.acquire(timeout=120.0)
+            try:
+                speak_result = tts_speak(
+                    text=final_text,
+                    backend=backend,
+                    voice=voice,
+                    rate=rate,
+                    speed=speed,
+                    play=play,
+                    output_path=output_path,
+                    fallback=fallback,
+                    # mode=None uses SCITEX_AUDIO_MODE env (default: auto)
+                )
+            finally:
+                lock.release()
+
+            result = {
+                "success": speak_result.get("success", False),
+                "text": text,
+                "backend": speak_result.get("backend", backend),
+                "played": speak_result.get("played", False),
+                "play_requested": play,
+                "mode": speak_result.get("mode", "unknown"),
+                "agent_id": agent_id,
+                "timestamp": datetime.now().isoformat(),
+            }
+
+            if signature:
+                result["signature"] = sig
+                result["full_text"] = final_text
+            if speak_result.get("path"):
+                result["path"] = str(speak_result["path"])
+            if speak_result.get("error"):
+                result["error"] = speak_result["error"]
+            if speak_result.get("routing"):
+                result["routing"] = speak_result["routing"]
+            if speak_result.get("local_state"):
+                result["local_state"] = speak_result["local_state"]
+
+            return json.dumps(result, indent=2)
 
-        result = _run_async(speak_relay_handler(
-            text=text, backend=backend, voice=voice, rate=rate,
-            speed=speed, play=play, save=save, fallback=fallback,
-            agent_id=agent_id,
-        ))
-        return json.dumps(result, indent=2)
+        except Exception as e:
+            return json.dumps({
+                "success": False,
+                "error": str(e),
+                "text": text,
+            }, indent=2)
 
     @mcp.tool()
     def list_backends() -> str:
@@ -256,8 +281,8 @@ if FASTMCP_AVAILABLE:
             else:
                 text = f"Working in {dir_name}"
 
-            # Speak the announcement using the speak tool
-            speak_result = speak(text=text)
+            # Speak the announcement using the unified audio_speak tool
+            speak_result = audio_speak(text=text)
 
             return json.dumps(
                 {