scitex 2.14.0__py3-none-any.whl → 2.15.2__py3-none-any.whl

scitex/audio/__init__.py

@@ -6,12 +6,12 @@
 """
 SciTeX Audio Module - Text-to-Speech with Multiple Backends
 
-Fallback order: pyttsx3 -> gtts -> elevenlabs
+Fallback order: elevenlabs -> gtts -> pyttsx3
 
 Backends:
-    - pyttsx3: System TTS (offline, free, uses espeak/SAPI5)
-    - gtts: Google TTS (free, requires internet)
     - elevenlabs: ElevenLabs (paid, high quality)
+    - gtts: Google TTS (free, requires internet)
+    - pyttsx3: System TTS (offline, free, uses espeak/SAPI5)
 
 Usage:
     import scitex
@@ -145,8 +145,8 @@ __all__ = [
     "FALLBACK_ORDER",
 ]
 
-# Fallback order: pyttsx3 (offline/free) -> gtts (free) -> elevenlabs (paid)
-FALLBACK_ORDER = ["pyttsx3", "gtts", "elevenlabs"]
+# Fallback order: elevenlabs (best quality) -> gtts (free) -> pyttsx3 (offline)
+FALLBACK_ORDER = ["elevenlabs", "gtts", "pyttsx3"]
 
 
 def available_backends() -> List[str]:
@@ -173,8 +173,8 @@ def available_backends() -> List[str]:
     if ElevenLabsTTS:
         import os
 
-        api_key = os.environ.get("ELEVENLABS_API_KEY") or os.environ.get(
-            "ELEVENLABS_API_KEY_SCITEX_AUDIO"
+        api_key = os.environ.get("SCITEX_AUDIO_ELEVENLABS_API_KEY") or os.environ.get(
+            "ELEVENLABS_API_KEY"
         )
         if api_key:
             backends.append("elevenlabs")
@@ -264,69 +264,20 @@ _default_tts: Optional[BaseTTS] = None
 _default_backend: Optional[str] = None
 
 
-def speak(
+def _speak_local(
     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,
     **kwargs,
 ) -> Optional[str]:
-    """Convert text to speech with automatic fallback.
-
-    Fallback order: pyttsx3 -> gtts -> elevenlabs
-
-    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).
-        **kwargs: Additional backend options.
-
-    Returns:
-        Path to audio file if output_path specified, else None.
-
-    Examples:
-        import scitex
-
-        # Simple (auto-selects with fallback)
-        scitex.audio.speak("Hello!")
-
-        # Faster speech (pyttsx3)
-        scitex.audio.speak("Hello", rate=200)
-
-        # Faster speech (gtts with pydub)
-        scitex.audio.speak("Hello", backend="gtts", speed=1.5)
-
-        # Specific backend (no fallback)
-        scitex.audio.speak("Hello", backend="pyttsx3", fallback=False)
-
-        # Different language (gTTS)
-        scitex.audio.speak("Bonjour", backend="gtts", voice="fr")
-
-        # Save to file
-        scitex.audio.speak("Test", output_path="/tmp/test.mp3")
-    """
+    """Local TTS playback (original implementation)."""
     global _default_tts, _default_backend
 
-    # Stop any previously running speech first
-    stop_speech()
-
-    # Pass rate to kwargs for pyttsx3
-    if rate is not None:
-        kwargs["rate"] = rate
-
-    # Pass speed to kwargs for gtts
-    if speed is not None:
-        kwargs["speed"] = speed
+    # Note: stop_speech() removed - FIFO locking handles queuing
+    # Call stop_speech() explicitly if you want to interrupt current audio
 
     # If specific backend requested without fallback
     if backend and not fallback:
@@ -364,7 +315,6 @@ def speak(
         return str(result) if result else None
     except Exception as e:
         if fallback:
-            # Try other backends
             result, used_backend, errors = _try_speak_with_fallback(
                 text=text,
                 voice=voice,
@@ -381,6 +331,124 @@ def speak(
         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,
+) -> Optional[str]:
+    """Convert text to speech with smart local/remote switching.
+
+    Modes:
+        - local: Always use local TTS backends
+        - remote: Always forward to relay server
+        - auto: Try remote first, fall back to local (default)
+
+    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:
+        Path to audio file if output_path specified, else None.
+
+    Environment Variables:
+        SCITEX_AUDIO_MODE: Default mode ('local', 'remote', 'auto')
+        SCITEX_AUDIO_RELAY_URL: Relay server URL for remote mode
+
+    Examples:
+        import scitex
+
+        # Simple (auto mode - tries remote, falls back to local)
+        scitex.audio.speak("Hello!")
+
+        # Force local playback
+        scitex.audio.speak("Hello", mode="local")
+
+        # Force remote relay
+        scitex.audio.speak("Hello", mode="remote")
+
+        # Faster speech (gtts with pydub)
+        scitex.audio.speak("Hello", backend="gtts", speed=1.5)
+    """
+    from ._branding import get_mode, get_relay_url
+    from ._relay import is_relay_available, relay_speak
+
+    # Pass rate/speed to kwargs
+    if rate is not None:
+        kwargs["rate"] = rate
+    if speed is not None:
+        kwargs["speed"] = speed
+
+    # 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:
+            raise RuntimeError(
+                "Remote mode requires SCITEX_AUDIO_RELAY_URL or "
+                "SCITEX_AUDIO_RELAY_HOST to be set"
+            )
+        result = relay_speak(
+            text=text,
+            backend=backend,
+            voice=voice,
+            rate=rate or 150,
+            speed=speed or 1.5,
+            play=play,
+            **kwargs,
+        )
+        return result.get("saved_to") if result.get("success") else None
+
+    # Auto mode: try remote first, fall back to local
+    if effective_mode == "auto":
+        relay_url = get_relay_url()
+        if relay_url and is_relay_available():
+            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 result.get("saved_to")
+            except Exception:
+                pass  # Fall through to local
+
+    # Local mode (or fallback from auto)
+    return _speak_local(
+        text=text,
+        backend=backend,
+        voice=voice,
+        play=play,
+        output_path=output_path,
+        fallback=fallback,
+        **kwargs,
+    )
+
+
 def start_mcp_server():
     """Start the MCP server for audio."""
     from .mcp_server import main

scitex/audio/_branding.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Configuration constants for scitex.audio.
+
+Provides environment variable helpers and default values for the audio module.
+"""
+
+import os
+from typing import Optional
+
+# Fixed branding (scitex.audio is part of scitex, not rebranded)
+BRAND_NAME = "scitex.audio"
+BRAND_ALIAS = "audio"
+ENV_PREFIX = "SCITEX_AUDIO"
+
+# Default port: 31293 (SCITEX port scheme: 3129X where X=3 for audio)
+DEFAULT_PORT = 31293
+DEFAULT_HOST = "0.0.0.0"
+
+
+def get_env(key: str, default: Optional[str] = None) -> Optional[str]:
+    """Get environment variable with SCITEX_AUDIO_ prefix.
+
+    Args:
+        key: Variable name without prefix (e.g., "PORT", "HOST", "MODE")
+        default: Default value if not found
+
+    Returns
+    -------
+        Environment variable value or default
+
+    Examples
+    --------
+        get_env("PORT")  # Checks SCITEX_AUDIO_PORT
+        get_env("MODE", "local")  # With default
+    """
+    return os.environ.get(f"SCITEX_AUDIO_{key}", default)
+
+
+def get_port() -> int:
+    """Get configured port number."""
+    port_str = get_env("PORT", str(DEFAULT_PORT))
+    return int(port_str)
+
+
+def get_host() -> str:
+    """Get configured host."""
+    return get_env("HOST", DEFAULT_HOST)
+
+
+def get_mode() -> str:
+    """Get audio mode: 'local', 'remote', or 'auto'.
+
+    - local: Always play locally (direct TTS)
+    - remote: Always forward to relay server
+    - auto: Try local first, fall back to remote
+    """
+    return get_env("MODE", "auto").lower()
+
+
+def get_ssh_client_ip() -> Optional[str]:
+    """Get IP address of SSH client if running in SSH session.
+
+    Extracts client IP from SSH_CLIENT or SSH_CONNECTION env vars.
+    Returns None if not in SSH session.
+    """
+    # SSH_CLIENT format: "client_ip client_port server_port"
+    ssh_client = os.environ.get("SSH_CLIENT", "")
+    if ssh_client:
+        parts = ssh_client.split()
+        if parts:
+            return parts[0]
+
+    # SSH_CONNECTION format: "client_ip client_port server_ip server_port"
+    ssh_connection = os.environ.get("SSH_CONNECTION", "")
+    if ssh_connection:
+        parts = ssh_connection.split()
+        if parts:
+            return parts[0]
+
+    return None
+
+
+def _check_relay_reachable(url: str, timeout: float = 1.0) -> bool:
+    """Quick check if relay URL is reachable."""
+    import socket
+    import urllib.parse
+
+    try:
+        parsed = urllib.parse.urlparse(url)
+        host = parsed.hostname or "localhost"
+        port = parsed.port or DEFAULT_PORT
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        result = sock.connect_ex((host, port))
+        sock.close()
+        return result == 0
+    except Exception:
+        return False
+
+
+def get_relay_url() -> Optional[str]:
+    """Get relay server URL for remote mode.
+
+    Priority:
+    1. SCITEX_AUDIO_RELAY_URL env var
+    2. SCITEX_AUDIO_RELAY_HOST env var + port
+    3. localhost:31293 (SSH reverse tunnel - if reachable)
+    4. Auto-detect from SSH_CLIENT (if in SSH session)
+
+    Returns URL like 'http://192.168.1.100:31293' or None.
+    """
+    url = get_env("RELAY_URL")
+    if url:
+        return url.rstrip("/")
+
+    # Build from host/port if relay host is set
+    relay_host = get_env("RELAY_HOST")
+    if relay_host:
+        relay_port = get_env("RELAY_PORT", str(DEFAULT_PORT))
+        return f"http://{relay_host}:{relay_port}"
+
+    # Check localhost first (SSH reverse tunnel)
+    localhost_url = f"http://localhost:{DEFAULT_PORT}"
+    if _check_relay_reachable(localhost_url):
+        return localhost_url
+
+    # Auto-detect from SSH client IP
+    ssh_client_ip = get_ssh_client_ip()
+    if ssh_client_ip:
+        return f"http://{ssh_client_ip}:{DEFAULT_PORT}"
+
+    return None
+
+
+def get_mcp_server_name() -> str:
+    """Get the MCP server name."""
+    return "scitex-audio"
+
+
+def get_mcp_instructions() -> str:
+    """Get MCP server instructions."""
+    return """\
+scitex.audio - Text-to-Speech with Multiple Backends
+
+Backends (fallback order): elevenlabs -> gtts -> pyttsx3
+
+## Quick Start
+```python
+from scitex.audio import speak
+speak("Hello, world!")  # Auto-selects backend
+speak("Fast", backend="gtts", speed=1.5)
+```
+
+## MCP Tools
+- **speak**: Convert text to speech
+- **list_backends**: Show available TTS backends
+- **check_audio_status**: Check WSL audio connectivity
+- **announce_context**: Announce current directory and git branch
+
+## Remote Audio Relay
+Run locally: `scitex audio serve -t http --port 31293`
+Remote agents connect via HTTP to play audio on local speakers.
+
+## Environment Variables
+- SCITEX_AUDIO_MODE: 'local', 'remote', or 'auto' (default: auto)
+- SCITEX_AUDIO_RELAY_URL: Remote relay server URL
+- SCITEX_AUDIO_PORT: Server port (default: 31293)
+"""
+
+
+__all__ = [
+    "BRAND_NAME",
+    "BRAND_ALIAS",
+    "ENV_PREFIX",
+    "DEFAULT_PORT",
+    "DEFAULT_HOST",
+    "get_env",
+    "get_port",
+    "get_host",
+    "get_mode",
+    "get_relay_url",
+    "get_ssh_client_ip",
+    "get_mcp_server_name",
+    "get_mcp_instructions",
+]

scitex/audio/_mcp/__init__.py

@@ -2,3 +2,35 @@
 # File: __init__.py
 """MCP server components."""
 
+from .handlers import (
+    announce_context_handler,
+    check_audio_status_handler,
+    clear_audio_cache_handler,
+    generate_audio_handler,
+    list_audio_files_handler,
+    list_backends_handler,
+    list_voices_handler,
+    play_audio_handler,
+    speak_handler,
+    speech_queue_status_handler,
+)
+from .speak_handlers import (
+    speak_local_handler,
+    speak_relay_handler,
+)
+
+__all__ = [
+    "speak_handler",
+    "speak_local_handler",
+    "speak_relay_handler",
+    "generate_audio_handler",
+    "list_backends_handler",
+    "list_voices_handler",
+    "play_audio_handler",
+    "list_audio_files_handler",
+    "clear_audio_cache_handler",
+    "check_audio_status_handler",
+    "speech_queue_status_handler",
+    "announce_context_handler",
+]
+

scitex/audio/_mcp/handlers.py

@@ -36,6 +36,37 @@ def _get_audio_dir() -> Path:
     return audio_dir
 
 
+def _get_signature() -> str:
+    """Get signature string with hostname, project, and branch."""
+    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}")
+
+    return ". ".join(parts) + ". "
+
+
 async def generate_audio_handler(
     text: str,
     backend: str | None = None,
@@ -89,16 +120,16 @@ async def generate_audio_handler(
 async def list_backends_handler() -> dict:
     """List available TTS backends."""
     try:
-        from .. import available_backends
+        from .. import FALLBACK_ORDER, available_backends
 
         backends = available_backends()
 
         info = []
-        for b in ["gtts", "elevenlabs", "pyttsx3"]:
+        for b in FALLBACK_ORDER:
             available = b in backends
             desc = {
-                "gtts": "Google TTS - Free, requires internet",
                 "elevenlabs": "ElevenLabs - Paid, high quality",
+                "gtts": "Google TTS - Free, requires internet",
                 "pyttsx3": "System TTS - Offline, uses espeak/SAPI5",
             }
             info.append(
@@ -109,11 +140,18 @@ async def list_backends_handler() -> dict:
                 }
             )
 
+        # Determine actual default based on FALLBACK_ORDER
+        default = None
+        for b in FALLBACK_ORDER:
+            if b in backends:
+                default = b
+                break
+
         return {
             "success": True,
             "backends": info,
             "available": backends,
-            "default": backends[0] if backends else None,
+            "default": default,
         }
 
     except Exception as e:
@@ -267,13 +305,25 @@ async def speak_handler(
     fallback: bool = True,
     agent_id: str | None = None,
     wait: bool = True,
+    signature: bool = False,
 ) -> dict:
-    """Convert text to speech with fallback."""
+    """Convert text to speech with fallback.
+
+    Args:
+        signature: If True, prepend hostname/project/branch to text.
+    """
     try:
         from .. import speak as tts_speak
 
         loop = asyncio.get_event_loop()
 
+        # Prepend signature if requested
+        final_text = text
+        sig = None
+        if signature:
+            sig = _get_signature()
+            final_text = sig + text
+
         output_path = None
         if save:
             timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
@@ -281,7 +331,7 @@ async def speak_handler(
 
         def do_speak():
             return tts_speak(
-                text=text,
+                text=final_text,
                 backend=backend,
                 voice=voice,
                 rate=rate,
@@ -300,6 +350,9 @@ async def speak_handler(
             "played": play,
             "timestamp": datetime.now().isoformat(),
         }
+        if signature:
+            result["signature"] = sig
+            result["full_text"] = final_text
         if result_path:
             result["path"] = str(result_path)