scitex 2.5.0__py3-none-any.whl → 2.7.3__py3-none-any.whl

scitex/audio/_tts.py

@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-11 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/_tts.py
+# ----------------------------------------
+
+"""
+Text-to-Speech implementation using ElevenLabs API.
+
+This module provides TTS functionality that can be used:
+1. Directly via the ElevenLabs Python SDK
+2. Via MCP server integration
+
+Environment Variables:
+    ELEVENLABS_API_KEY: Your ElevenLabs API key
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+__all__ = ["TTS", "speak"]
+
+
+@dataclass
+class TTSConfig:
+    """Configuration for TTS."""
+
+    voice_id: str = "21m00Tcm4TlvDq8ikWAM"  # Rachel (default)
+    voice_name: Optional[str] = None
+    model_id: str = "eleven_multilingual_v2"
+    stability: float = 0.5
+    similarity_boost: float = 0.75
+    style: float = 0.0
+    speed: float = 1.0
+    output_format: str = "mp3_44100_128"
+
+
+class TTS:
+    """Text-to-Speech using ElevenLabs API.
+
+    Examples:
+        # Basic usage
+        tts = TTS()
+        tts.speak("Hello, world!")
+
+        # With custom voice
+        tts = TTS(voice_name="Rachel")
+        tts.speak("Processing complete")
+
+        # Save to file without playing
+        tts.speak("Test", output_path="/tmp/test.mp3", play=False)
+    """
+
+    # Popular voice presets
+    VOICES = {
+        "rachel": "21m00Tcm4TlvDq8ikWAM",
+        "adam": "pNInz6obpgDQGcFmaJgB",
+        "antoni": "ErXwobaYiN019PkySvjV",
+        "bella": "EXAVITQu4vr4xnSDxMaL",
+        "domi": "AZnzlk1XvdvUeBnXmlld",
+        "elli": "MF3mGyEYCl7XYWbV9V6O",
+        "josh": "TxGEqnHWrfWFTfGW9XjX",
+        "sam": "yoZ06aMxZJJ28mfd3POQ",
+    }
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        voice_name: Optional[str] = None,
+        voice_id: Optional[str] = None,
+        **kwargs,
+    ):
+        """Initialize TTS.
+
+        Args:
+            api_key: ElevenLabs API key. Defaults to ELEVENLABS_API_KEY env var.
+            voice_name: Voice name (e.g., "Rachel", "Adam").
+            voice_id: Direct voice ID (overrides voice_name).
+            **kwargs: Additional config options (stability, speed, etc.)
+        """
+        self.api_key = api_key or os.environ.get("ELEVENLABS_API_KEY")
+        self.config = TTSConfig(**kwargs)
+
+        if voice_id:
+            self.config.voice_id = voice_id
+        elif voice_name:
+            self.config.voice_name = voice_name
+            normalized = voice_name.lower()
+            if normalized in self.VOICES:
+                self.config.voice_id = self.VOICES[normalized]
+
+        self._client = None
+
+    @property
+    def client(self):
+        """Lazy-load ElevenLabs client."""
+        if self._client is None:
+            try:
+                from elevenlabs.client import ElevenLabs
+
+                self._client = ElevenLabs(api_key=self.api_key)
+            except ImportError:
+                raise ImportError(
+                    "elevenlabs package not installed. "
+                    "Install with: pip install elevenlabs"
+                )
+        return self._client
+
+    def speak(
+        self,
+        text: str,
+        output_path: Optional[str] = None,
+        play: bool = True,
+        voice_name: Optional[str] = None,
+        voice_id: Optional[str] = None,
+    ) -> Optional[Path]:
+        """Convert text to speech and optionally play it.
+
+        Args:
+            text: Text to convert to speech.
+            output_path: Path to save audio file. Auto-generated if None.
+            play: Whether to play the audio after generation.
+            voice_name: Override voice name for this call.
+            voice_id: Override voice ID for this call.
+
+        Returns:
+            Path to the generated audio file, or None if only played.
+        """
+        # Determine voice
+        vid = voice_id or self.config.voice_id
+        if voice_name and not voice_id:
+            normalized = voice_name.lower()
+            vid = self.VOICES.get(normalized, vid)
+
+        # Generate audio
+        audio = self.client.text_to_speech.convert(
+            text=text,
+            voice_id=vid,
+            model_id=self.config.model_id,
+            voice_settings={
+                "stability": self.config.stability,
+                "similarity_boost": self.config.similarity_boost,
+                "style": self.config.style,
+                "speed": self.config.speed,
+            },
+            output_format=self.config.output_format,
+        )
+
+        # Determine output path
+        if output_path:
+            out_path = Path(output_path)
+        else:
+            suffix = ".mp3" if "mp3" in self.config.output_format else ".wav"
+            fd, tmp_path = tempfile.mkstemp(suffix=suffix, prefix="scitex_tts_")
+            os.close(fd)
+            out_path = Path(tmp_path)
+
+        # Write audio to file
+        with open(out_path, "wb") as f:
+            for chunk in audio:
+                f.write(chunk)
+
+        # Play if requested
+        if play:
+            self._play_audio(out_path)
+
+        return out_path if output_path else None
+
+    def _play_audio(self, path: Path) -> None:
+        """Play audio file using available system player.
+
+        Includes Windows fallback for WSL environments.
+        """
+        # Check if we're in WSL - if so, prefer Windows playback directly
+        # to avoid double playback issues with Linux audio hanging
+        if os.path.exists("/mnt/c/Windows"):
+            if self._play_audio_windows(path):
+                return
+            # Fall through to Linux players if Windows playback fails
+
+        players = [
+            ["mpv", "--no-video", str(path)],
+            ["ffplay", "-nodisp", "-autoexit", str(path)],
+            ["aplay", str(path)],
+            ["afplay", str(path)],  # macOS
+        ]
+
+        for player_cmd in players:
+            try:
+                subprocess.run(
+                    player_cmd,
+                    check=True,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=30,
+                )
+                return
+            except subprocess.TimeoutExpired:
+                # Audio playback hung, don't try more players
+                return
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                continue
+
+        print(f"Warning: No audio player found. Audio saved to: {path}")
+
+    def _play_audio_windows(self, path: Path) -> bool:
+        """Play audio via Windows PowerShell SoundPlayer (WSL fallback).
+
+        Uses headless SoundPlayer - no GUI popup.
+        """
+        import shutil
+        import tempfile
+
+        # Check if we're in WSL
+        if not os.path.exists("/mnt/c/Windows"):
+            return False
+
+        powershell = shutil.which("powershell.exe")
+        if not powershell:
+            return False
+
+        try:
+            # SoundPlayer only supports WAV, so convert if needed
+            wav_path = path
+            if path.suffix.lower() in ('.mp3', '.ogg', '.m4a'):
+                try:
+                    from pydub import AudioSegment
+                    fd, tmp_wav = tempfile.mkstemp(suffix='.wav', prefix='scitex_')
+                    os.close(fd)
+                    wav_path = Path(tmp_wav)
+                    audio = AudioSegment.from_file(str(path))
+                    audio.export(str(wav_path), format='wav')
+                except ImportError:
+                    pass
+
+            result = subprocess.run(
+                ["wslpath", "-w", str(wav_path)],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode != 0:
+                return False
+
+            windows_path = result.stdout.strip()
+
+            ps_command = f'''
+$player = New-Object System.Media.SoundPlayer
+$player.SoundLocation = "{windows_path}"
+$player.PlaySync()
+'''
+            subprocess.run(
+                [powershell, "-NoProfile", "-Command", ps_command],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=60,
+            )
+
+            # Clean up temp WAV
+            if wav_path != path and wav_path.exists():
+                try:
+                    wav_path.unlink()
+                except Exception:
+                    pass
+
+            return True
+
+        except Exception:
+            return False
+
+    def list_voices(self) -> list:
+        """List available voices from ElevenLabs."""
+        response = self.client.voices.get_all()
+        return [
+            {"name": v.name, "voice_id": v.voice_id, "labels": v.labels}
+            for v in response.voices
+        ]
+
+
+# Module-level convenience function
+_default_tts: Optional[TTS] = None
+
+
+def speak(
+    text: str,
+    voice: Optional[str] = None,
+    play: bool = True,
+    output_path: Optional[str] = None,
+    **kwargs,
+) -> Optional[Path]:
+    """Convenience function for quick TTS.
+
+    Args:
+        text: Text to speak.
+        voice: Voice name (e.g., "Rachel", "Adam").
+        play: Whether to play audio.
+        output_path: Optional path to save audio.
+        **kwargs: Additional TTS config options.
+
+    Returns:
+        Path to audio file if output_path specified, else None.
+
+    Examples:
+        import scitex
+
+        # Simple speak
+        scitex.audio.speak("Hello!")
+
+        # With specific voice
+        scitex.audio.speak("Processing complete", voice="Adam")
+
+        # Save without playing
+        scitex.audio.speak("Test", play=False, output_path="/tmp/test.mp3")
+    """
+    global _default_tts
+
+    if _default_tts is None or kwargs:
+        _default_tts = TTS(**kwargs)
+
+    return _default_tts.speak(
+        text=text,
+        voice_name=voice,
+        play=play,
+        output_path=output_path,
+    )
+
+
+# EOF

scitex/audio/engines/__init__.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-11 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/engines/__init__.py
+# ----------------------------------------
+
+"""
+TTS Engine Backends
+
+Fallback order: pyttsx3 -> gtts -> elevenlabs
+
+Engines:
+    - SystemTTS (pyttsx3): Offline, free, uses system TTS
+    - GoogleTTS (gtts): Free, requires internet
+    - ElevenLabsTTS: Paid, high quality
+"""
+
+from .base import BaseTTS, TTSBackend
+
+# Import engines (fail gracefully if dependencies missing)
+try:
+    from .pyttsx3_engine import SystemTTS
+except ImportError:
+    SystemTTS = None
+
+try:
+    from .gtts_engine import GoogleTTS
+except ImportError:
+    GoogleTTS = None
+
+try:
+    from .elevenlabs_engine import ElevenLabsTTS
+except ImportError:
+    ElevenLabsTTS = None
+
+__all__ = [
+    "BaseTTS",
+    "TTSBackend",
+    "SystemTTS",
+    "GoogleTTS",
+    "ElevenLabsTTS",
+]
+
+# EOF

scitex/audio/engines/base.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-11 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/engines/base.py
+# ----------------------------------------
+
+"""
+Base TTS class defining the common interface for all TTS backends.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import List, Optional
+
+__all__ = ["BaseTTS", "TTSBackend"]
+
+
+class TTSBackend:
+    """Enum-like class for TTS backend types."""
+
+    ELEVENLABS = "elevenlabs"
+    GTTS = "gtts"
+    PYTTSX3 = "pyttsx3"
+    EDGE = "edge"  # Future: edge-tts
+
+    @classmethod
+    def available(cls) -> List[str]:
+        """Return list of available backends."""
+        backends = []
+
+        # Check gTTS (always available if installed, needs internet)
+        try:
+            import gtts
+
+            backends.append(cls.GTTS)
+        except ImportError:
+            pass
+
+        # Check pyttsx3
+        try:
+            import pyttsx3
+
+            backends.append(cls.PYTTSX3)
+        except ImportError:
+            pass
+
+        # Check ElevenLabs
+        try:
+            import elevenlabs
+            import os
+
+            if os.environ.get("ELEVENLABS_API_KEY"):
+                backends.append(cls.ELEVENLABS)
+        except ImportError:
+            pass
+
+        return backends
+
+
+class BaseTTS(ABC):
+    """Abstract base class for TTS implementations."""
+
+    def __init__(self, **kwargs):
+        self.config = kwargs
+
+    @abstractmethod
+    def synthesize(self, text: str, output_path: str) -> Path:
+        """Synthesize text to audio file.
+
+        Args:
+            text: Text to convert to speech.
+            output_path: Path to save the audio file.
+
+        Returns:
+            Path to the generated audio file.
+        """
+        pass
+
+    @abstractmethod
+    def get_voices(self) -> List[dict]:
+        """Get available voices for this backend.
+
+        Returns:
+            List of voice dictionaries with 'name' and 'id' keys.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the backend name."""
+        pass
+
+    @property
+    def requires_api_key(self) -> bool:
+        """Whether this backend requires an API key."""
+        return False
+
+    @property
+    def requires_internet(self) -> bool:
+        """Whether this backend requires internet connection."""
+        return False
+
+    def speak(
+        self,
+        text: str,
+        output_path: Optional[str] = None,
+        play: bool = True,
+        voice: Optional[str] = None,
+    ) -> Optional[Path]:
+        """Synthesize and optionally play text.
+
+        Args:
+            text: Text to speak.
+            output_path: Optional path to save audio.
+            play: Whether to play the audio.
+            voice: Optional voice name/id.
+
+        Returns:
+            Path to audio file if output_path specified, else None.
+        """
+        import tempfile
+
+        # Determine output path
+        if output_path:
+            out_path = Path(output_path)
+        else:
+            suffix = ".mp3"
+            fd, tmp_path = tempfile.mkstemp(suffix=suffix, prefix="scitex_tts_")
+            import os
+
+            os.close(fd)
+            out_path = Path(tmp_path)
+
+        # Set voice if provided
+        if voice:
+            self.config["voice"] = voice
+
+        # Synthesize
+        result_path = self.synthesize(text, str(out_path))
+
+        # Play if requested
+        if play:
+            self._play_audio(result_path)
+
+        # Return path only if explicitly requested
+        if output_path:
+            return result_path
+
+        return None
+
+    def _play_audio(self, path: Path) -> None:
+        """Play audio file using available system player.
+
+        Includes Windows fallback for WSL environments where PulseAudio
+        may be unstable.
+        """
+        import os
+
+        # Check if we're in WSL - if so, prefer Windows playback directly
+        # to avoid double playback issues with Linux audio hanging
+        if os.path.exists("/mnt/c/Windows"):
+            if self._play_audio_windows(path):
+                return
+            # Fall through to Linux players if Windows playback fails
+
+        players = [
+            ["ffplay", "-nodisp", "-autoexit", str(path)],
+            ["mpv", "--no-video", str(path)],
+            ["aplay", str(path)],
+            ["afplay", str(path)],  # macOS
+        ]
+
+        for player_cmd in players:
+            try:
+                subprocess.run(
+                    player_cmd,
+                    check=True,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=30,
+                )
+                return
+            except subprocess.TimeoutExpired:
+                # Audio playback hung, don't try more players
+                return
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                continue
+
+        print(f"Warning: No audio player found. Audio saved to: {path}")
+
+    def _play_audio_windows(self, path: Path) -> bool:
+        """Play audio via Windows PowerShell SoundPlayer (WSL fallback).
+
+        This is useful when WSLg PulseAudio connection is unstable.
+        Uses System.Media.SoundPlayer which is headless (no GUI).
+
+        Args:
+            path: Path to audio file (in WSL filesystem)
+
+        Returns:
+            True if playback succeeded, False otherwise
+        """
+        import os
+        import shutil
+        import tempfile
+
+        # Check if we're in WSL
+        if not os.path.exists("/mnt/c/Windows"):
+            return False
+
+        # Check if powershell.exe is available
+        powershell = shutil.which("powershell.exe")
+        if not powershell:
+            return False
+
+        try:
+            # SoundPlayer only supports WAV, so convert if needed
+            wav_path = path
+            if path.suffix.lower() in ('.mp3', '.ogg', '.m4a'):
+                try:
+                    from pydub import AudioSegment
+                    # Create temp WAV file
+                    fd, tmp_wav = tempfile.mkstemp(suffix='.wav', prefix='scitex_')
+                    os.close(fd)
+                    wav_path = Path(tmp_wav)
+
+                    audio = AudioSegment.from_file(str(path))
+                    audio.export(str(wav_path), format='wav')
+                except ImportError:
+                    # pydub not available, try direct playback anyway
+                    pass
+
+            # Convert WSL path to Windows path
+            result = subprocess.run(
+                ["wslpath", "-w", str(wav_path)],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode != 0:
+                return False
+
+            windows_path = result.stdout.strip()
+
+            # Play using PowerShell's SoundPlayer (headless, no GUI)
+            ps_command = f'''
+$player = New-Object System.Media.SoundPlayer
+$player.SoundLocation = "{windows_path}"
+$player.PlaySync()
+'''
+            subprocess.run(
+                [powershell, "-NoProfile", "-Command", ps_command],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=60,
+            )
+
+            # Clean up temp WAV if created
+            if wav_path != path and wav_path.exists():
+                try:
+                    wav_path.unlink()
+                except Exception:
+                    pass
+
+            return True
+
+        except (subprocess.TimeoutExpired, subprocess.CalledProcessError, Exception):
+            return False
+
+
+# EOF