scitex 2.13.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

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

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+# 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

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+# Timestamp: "2025-12-27 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/_mcp.handlers.py
+# ----------------------------------------
+
+"""Utility handlers for the scitex-audio MCP server."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from datetime import datetime
+from pathlib import Path
+
+__all__ = [
+    "speak_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",
+]
+
+
+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
+
+
+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,
+    voice: str | None = None,
+    output_path: str | None = None,
+    return_base64: bool = False,
+) -> dict:
+    """Generate audio file without playing."""
+    try:
+        from .. import speak as tts_speak
+
+        loop = asyncio.get_event_loop()
+
+        if not output_path:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            output_path = str(_get_audio_dir() / f"tts_{timestamp}.mp3")
+
+        def do_generate():
+            return tts_speak(
+                text=text,
+                backend=backend,
+                voice=voice,
+                play=False,
+                output_path=output_path,
+                fallback=True,
+            )
+
+        result_path = await loop.run_in_executor(None, do_generate)
+
+        result = {
+            "success": True,
+            "path": str(result_path),
+            "text": text,
+            "backend": backend,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+        if result_path.exists():
+            result["size_kb"] = round(result_path.stat().st_size / 1024, 2)
+
+        if return_base64 and result_path.exists():
+            with open(result_path, "rb") as f:
+                result["base64"] = base64.b64encode(f.read()).decode()
+
+        return result
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def list_backends_handler() -> dict:
+    """List available TTS backends."""
+    try:
+        from .. import FALLBACK_ORDER, available_backends
+
+        backends = available_backends()
+
+        info = []
+        for b in FALLBACK_ORDER:
+            available = b in backends
+            desc = {
+                "elevenlabs": "ElevenLabs - Paid, high quality",
+                "gtts": "Google TTS - Free, requires internet",
+                "pyttsx3": "System TTS - Offline, uses espeak/SAPI5",
+            }
+            info.append(
+                {
+                    "name": b,
+                    "available": available,
+                    "description": desc.get(b, ""),
+                }
+            )
+
+        # 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": default,
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def list_voices_handler(backend: str = "gtts") -> dict:
+    """List available voices for a backend."""
+    try:
+        from .. import get_tts
+
+        loop = asyncio.get_event_loop()
+
+        def do_list():
+            tts = get_tts(backend)
+            return tts.get_voices()
+
+        voices = await loop.run_in_executor(None, do_list)
+
+        return {
+            "success": True,
+            "backend": backend,
+            "voices": voices,
+            "count": len(voices),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def play_audio_handler(path: str) -> dict:
+    """Play an audio file."""
+    try:
+        from ..engines.base import BaseTTS
+
+        path_obj = Path(path)
+        if not path_obj.exists():
+            return {"success": False, "error": f"File not found: {path}"}
+
+        loop = asyncio.get_event_loop()
+
+        def do_play():
+            BaseTTS._play_audio(None, path_obj)
+
+        await loop.run_in_executor(None, do_play)
+
+        return {
+            "success": True,
+            "played": str(path_obj),
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def list_audio_files_handler(limit: int = 20) -> dict:
+    """List generated audio files."""
+    try:
+        audio_dir = _get_audio_dir()
+        if not audio_dir.exists():
+            return {"success": True, "files": [], "count": 0}
+
+        audio_files = sorted(
+            list(audio_dir.glob("*.mp3")) + list(audio_dir.glob("*.wav")),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )[:limit]
+
+        files = []
+        for f in audio_files:
+            files.append(
+                {
+                    "name": f.name,
+                    "path": str(f),
+                    "size_kb": round(f.stat().st_size / 1024, 2),
+                    "created": datetime.fromtimestamp(f.stat().st_mtime).isoformat(),
+                }
+            )
+
+        total_size = sum(f.stat().st_size for f in audio_dir.glob("*.*"))
+
+        return {
+            "success": True,
+            "files": files,
+            "count": len(files),
+            "total_size_mb": round(total_size / (1024 * 1024), 2),
+            "audio_dir": str(audio_dir),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def clear_audio_cache_handler(max_age_hours: float = 24) -> dict:
+    """Clear audio cache."""
+    try:
+        audio_dir = _get_audio_dir()
+        if not audio_dir.exists():
+            return {"success": True, "deleted": 0}
+
+        deleted = 0
+        now = datetime.now()
+
+        for f in list(audio_dir.glob("*.mp3")) + list(audio_dir.glob("*.wav")):
+            try:
+                if max_age_hours == 0:
+                    f.unlink()
+                    deleted += 1
+                else:
+                    mtime = datetime.fromtimestamp(f.stat().st_mtime)
+                    age_hours = (now - mtime).total_seconds() / 3600
+                    if age_hours > max_age_hours:
+                        f.unlink()
+                        deleted += 1
+            except Exception:
+                pass
+
+        return {
+            "success": True,
+            "deleted": deleted,
+            "max_age_hours": max_age_hours,
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def check_audio_status_handler() -> dict:
+    """Check WSL audio connectivity and available playback methods."""
+    try:
+        from .. import check_wsl_audio
+
+        status = check_wsl_audio()
+        status["success"] = True
+        status["timestamp"] = datetime.now().isoformat()
+        return status
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def speak_handler(
+    text: str,
+    backend: str | None = None,
+    voice: str | None = None,
+    rate: int = 150,
+    speed: float = 1.5,
+    play: bool = True,
+    save: bool = False,
+    fallback: bool = True,
+    agent_id: str | None = None,
+    wait: bool = True,
+    signature: bool = False,
+) -> dict:
+    """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")
+            output_path = str(_get_audio_dir() / f"tts_{timestamp}.mp3")
+
+        def do_speak():
+            return tts_speak(
+                text=final_text,
+                backend=backend,
+                voice=voice,
+                rate=rate,
+                speed=speed,
+                play=play,
+                output_path=output_path,
+                fallback=fallback,
+            )
+
+        result_path = await loop.run_in_executor(None, do_speak)
+
+        result = {
+            "success": True,
+            "text": text,
+            "backend": backend,
+            "played": play,
+            "timestamp": datetime.now().isoformat(),
+        }
+        if signature:
+            result["signature"] = sig
+            result["full_text"] = final_text
+        if result_path:
+            result["path"] = str(result_path)
+
+        return result
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def speech_queue_status_handler() -> dict:
+    """Get current speech queue status."""
+    try:
+        from .cross_process_lock import get_queue_status
+
+        status = get_queue_status()
+        status["success"] = True
+        return status
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def announce_context_handler(include_full_path: bool = False) -> dict:
+    """Announce current working directory and git branch."""
+    try:
+        import os
+        import subprocess
+
+        cwd = os.getcwd()
+        dir_name = cwd if include_full_path else os.path.basename(cwd)
+
+        branch = None
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                capture_output=True,
+                text=True,
+                cwd=cwd,
+            )
+            if result.returncode == 0:
+                branch = result.stdout.strip()
+        except Exception:
+            pass
+
+        if branch:
+            text = f"Working in {dir_name}, on branch {branch}"
+        else:
+            text = f"Working in {dir_name}"
+
+        speak_result = await speak_handler(text=text, speed=1.5)
+
+        return {
+            "success": True,
+            "directory": dir_name,
+            "branch": branch,
+            "announced": text,
+            "speak_result": speak_result,
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# EOF