termux-tts 1.5.0 → 1.5.2

package/termux_tts/control/models.py

@@ -1,151 +0,0 @@
-"""
-termux_tts.control.models
-ModelRegistry 연동 — TTS 모델 + Voice 분리 관리.
-
-TTS 특이사항:
-  - model_id:  "dsp-ko", "piper-ko", "fastspeech-ko" 등 엔진/언어 조합
-  - voice_id:  "ko-speaker-01", "en-speaker-01" 등 화자 ID (모델에 종속)
-  - 내장 엔진(dsp/native)은 파일 없이도 항상 사용 가능 → missing 상태로 표기 금지
-  - ONNX 모델은 파일 존재만으로 installed 처리 금지 → Registry 기반
-"""
-from __future__ import annotations
-
-import os
-import time
-from pathlib import Path
-from typing import Any
-
-from ameva_component import ModelRegistry
-from ameva_component.manifest import ModelState
-
-COMPONENT_ID = "termux-tts"
-
-# ------------------------------------------------------------------
-# 내장(Built-in) 엔진 정의 — 파일 불필요, 항상 사용 가능
-# ------------------------------------------------------------------
-
-# format: {model_id: {description, engine, voices, backend_key}}
-BUILTIN_MODELS: dict[str, dict[str, Any]] = {
-    "dsp-ko": {
-        "model_id": "dsp-ko",
-        "description": "Pure Parametric DSP Formant Synthesizer (Korean, zero-dependency)",
-        "engine": "dsp",
-        "format": "builtin",
-        "language": "ko",
-        "voices": [
-            {"voice_id": "ko-default", "description": "Default Korean DSP voice", "language": "ko"},
-        ],
-        "state": ModelState.ACTIVE.value,   # 내장 엔진은 항상 사용 가능
-    },
-    "dsp-en": {
-        "model_id": "dsp-en",
-        "description": "Pure Parametric DSP Formant Synthesizer (English, zero-dependency)",
-        "engine": "dsp",
-        "format": "builtin",
-        "language": "en",
-        "voices": [
-            {"voice_id": "en-default", "description": "Default English DSP voice", "language": "en"},
-        ],
-        "state": ModelState.ACTIVE.value,
-    },
-    "native-system": {
-        "model_id": "native-system",
-        "description": "Android System Native Voice (Samsung/Google TTS bridge)",
-        "engine": "native",
-        "format": "builtin",
-        "language": "ko,en",
-        "voices": [
-            {"voice_id": "system-default", "description": "Android system TTS voice", "language": "ko,en"},
-        ],
-        "state": ModelState.ACTIVE.value,
-    },
-}
-
-
-class TTSModelRegistry:
-    """
-    ModelRegistry를 감싸는 TTS 전용 레지스트리.
-
-    내장 엔진(dsp, native)은 파일 없이도 항상 사용 가능하며,
-    ONNX 모델만 ModelRegistry를 통해 상태를 추적합니다.
-    """
-
-    def __init__(self, registry_dir: Path | None = None) -> None:
-        self._reg = ModelRegistry(COMPONENT_ID, registry_dir=registry_dir)
-
-    # ------------------------------------------------------------------
-    # 전체 목록 조회
-    # ------------------------------------------------------------------
-
-    def list_all(self) -> list[dict]:
-        """
-        모든 모델 레코드를 반환합니다.
-        - 내장 엔진: BUILTIN_MODELS에서 직접 반환
-        - ONNX 모델: ModelRegistry에서 실제 상태 조회
-        """
-        result: list[dict] = list(BUILTIN_MODELS.values())
-        # Registry에서 외부 ONNX 모델 추가
-        for rec in self._reg.list_all():
-            result.append(self._enrich_onnx_record(rec))
-        return result
-
-    def list_voices_for_model(self, model_id: str) -> list[dict]:
-        """특정 model_id의 voice 목록을 반환합니다."""
-        if model_id in BUILTIN_MODELS:
-            return BUILTIN_MODELS[model_id].get("voices", [])
-        rec = self._reg.get(model_id)
-        if rec is None:
-            return []
-        return rec.get("voices", [])
-
-    def get(self, model_id: str) -> dict | None:
-        """단일 모델 레코드를 반환합니다. 없으면 None."""
-        if model_id in BUILTIN_MODELS:
-            return BUILTIN_MODELS[model_id]
-        rec = self._reg.get(model_id)
-        if rec is None:
-            return None
-        return self._enrich_onnx_record(rec)
-
-    def get_state(self, model_id: str) -> ModelState | None:
-        """모델 상태를 반환합니다. 없으면 None."""
-        if model_id in BUILTIN_MODELS:
-            return ModelState.ACTIVE
-        rec = self._reg.get(model_id)
-        if rec is None:
-            return None
-        try:
-            return ModelState(rec.get("state", "missing"))
-        except ValueError:
-            return None
-
-    # ------------------------------------------------------------------
-    # 상태 변경
-    # ------------------------------------------------------------------
-
-    def set_onnx_active(self, model_id: str) -> None:
-        """ONNX 모델을 active 상태로 변경합니다."""
-        self._reg.set_state(model_id, ModelState.ACTIVE)
-
-    def set_onnx_inactive(self, model_id: str) -> None:
-        """ONNX 모델을 inactive 상태로 변경합니다."""
-        self._reg.set_state(model_id, ModelState.INACTIVE)
-
-    def record_onnx_install(self, model_id: str, manifest, verified_at: float) -> None:
-        """ONNX 모델 설치 완료를 기록합니다."""
-        self._reg.record_install(model_id, manifest, verified_at)
-
-    def set_onnx_state(self, model_id: str, state: ModelState, *, last_error: str | None = None) -> None:
-        """ONNX 모델 상태를 직접 갱신합니다."""
-        self._reg.set_state(model_id, state, last_error=last_error)
-
-    # ------------------------------------------------------------------
-    # 내부 헬퍼
-    # ------------------------------------------------------------------
-
-    def _enrich_onnx_record(self, rec: dict) -> dict:
-        """ONNX 레코드에 engine/voices 필드가 없으면 기본값을 추가합니다."""
-        enriched = dict(rec)
-        enriched.setdefault("engine", "onnx")
-        enriched.setdefault("voices", [])
-        return enriched

package/termux_tts/control/status.py

@@ -1,13 +0,0 @@
-"""
-termux_tts.control.status — TTS 상태 파일 Writer + Heartbeat
-"""
-from __future__ import annotations
-from typing import Any
-from ameva_component.heartbeat import HeartbeatWriter
-
-
-class TTSStatusWriter(HeartbeatWriter):
-    """TTSControl 상태를 10초마다 상태 파일에 원자적으로 기록합니다."""
-
-    def __init__(self, control: Any) -> None:
-        super().__init__(control, name="tts")

package/termux_tts/engine.py

@@ -1,340 +0,0 @@
-"""
-Unified 4-Tier Multi-Backend TTS Gateway for termux-tts:
-- Tier 1: Pure Parametric DSP Formant Synthesizer Engine (ParametricDSPEngine - 0MB Zero-Dependency)
-- Tier 2: Android System Native Samsung/Google Voice Engine Bridge (NativeAndroidEngine - 0MB OS IPC)
-- Tier 3: Authentic C++ Isolated Sherpa-ONNX VITS Neural Vocoder (SherpaNeuralEngine - Deep Learning)
-- Tier 4: Pure On-Device Expressive Emotional Synthesizer (ExpressiveEngine - Conversational Tags)
-
-Strict Zero-Silent-Fallback Protocol:
-- If caller explicitly requests 'neural' and assets are missing -> Raise TTSModelLoadError (FAIL-FAST)
-- If caller explicitly requests 'native' and termux-api is missing -> Raise TTSInferenceError (FAIL-FAST)
-- Never swallow exceptions or mask failures with robotic buzzers without explicit instruction.
-"""
-from __future__ import annotations
-
-import logging
-import os
-from typing import Optional, Union, Dict, Any
-
-from .exceptions import TTSInferenceError, TTSModelLoadError, VulkanInitializationError
-from .engine_native import NativeAndroidEngine, NativeResult
-from .engine_sherpa import SherpaNeuralEngine, SherpaResult
-from .engine_vulkan import VulkanNeuralEngine, VulkanResult
-from .engine_expressive import ExpressiveEngine, ExpressiveResult
-from .engine_multilingual import MultilingualNeuralEngine, MultilingualResult
-from .script_classifier import MultilingualTokenizer
-from .hardware import (
-    resolve_device_backend,
-    bind_tts_hardware,
-    _resolve_ameva_runtime,
-    ERROR_AMEVA_TTS_E001,
-)
-
-logger = logging.getLogger("termux_tts.engine")
-
-
-QUALITY_PRESETS = {
-    "fast": {"sample_rate": 16000, "description": "16kHz Low Latency"},
-    "balanced": {"sample_rate": 22050, "description": "22.05kHz Standard Audio"},
-    "expressive": {"sample_rate": 24000, "description": "24kHz Expressive High Fidelity"},
-    "ultra": {"sample_rate": 44100, "description": "44.1kHz Studio Master"},
-}
-
-
-class TTSEngine:
-    """Production 4-Tier Multi-Backend Gateway supporting Synth, Native, Neural, and Expressive engines."""
-
-    def __init__(
-        self,
-        model_path: Optional[str] = None,
-        language: str = "ko",
-        preset: str = "balanced",
-        device: str = "auto",
-        threads: int = 4,
-        sample_rate: Optional[int] = None,
-        engine_type: str = "auto",
-        model_tier: Optional[str] = None,
-    ):
-        self.language = language.lower()
-        self.preset = preset.lower()
-        self.requested_device = device.lower()
-        self.requested_engine_type = engine_type.lower()
-        self.model_path = model_path
-        self.threads = threads
-        self.sample_rate = sample_rate
-        self.model_tier = model_tier
-        self._is_closed = False
-
-        # 1. Resolve effective device and engine_type via safe hardware gateway
-        self.device, effective_engine = resolve_device_backend(
-            self.requested_device, self.requested_engine_type
-        )
-        if self.requested_engine_type == "auto" and effective_engine != "auto":
-            self.requested_engine_type = effective_engine
-
-        self.backend = "auto"
-
-        # 2. Attempt ameva-runtime hardware binding if available
-        self._binding_plan = self._bind_hardware()
-
-        self.native_engine = NativeAndroidEngine(language=language)
-        self._multilingual_engine: Optional[MultilingualNeuralEngine] = None
-        self.synth_engine = self._resolve_synth_engine()
-
-    def _bind_hardware(self):
-        return bind_tts_hardware(self, self.requested_device)
-
-    def _resolve_synth_engine(self):
-        t = self.requested_engine_type
-        from .script_classifier import normalize_language_code
-        norm_lang = normalize_language_code(self.language)
-
-        # Extended Languages (hi, ru, ja, zh, es, fr, de, ar) route to MultilingualNeuralEngine
-        if norm_lang in ("hi", "ru", "ja", "zh", "es", "fr", "de", "ar"):
-            return self._get_multilingual_engine()
-
-        # Explicit Vulkan GPU MeloTTS Tier (Plan 1 NCNN Sliced / Plan 2 MNN Vulkan)
-        if t in ("melo", "melo_vulkan", "melo_ncnn", "melo_mnn") and (self.requested_device in ("vulkan", "gpu") or self.device == "vulkan"):
-            return VulkanNeuralEngine(
-                model_path=self.model_path,
-                language=self.language,
-                device=self.requested_device,
-                threads=self.threads,
-                sample_rate=self.sample_rate or 44100,
-                model_tier=self.model_tier,
-                model_type=t,
-            )
-
-        # Explicit Vulkan GPU Tier (Vulkan NCNN engine targets English Lessac)
-        if (t in ("vulkan", "gpu", "ncnn") or (self.requested_device in ("vulkan", "gpu") and t in ("neural", "vits", "auto"))) and norm_lang in ("en", "auto"):
-            try:
-                return VulkanNeuralEngine(
-                    model_path=self.model_path,
-                    language=self.language,
-                    device=self.requested_device,
-                    threads=self.threads,
-                    sample_rate=self.sample_rate or 22050,
-                    model_tier=self.model_tier,
-                    model_type="vits",
-                )
-            except (VulkanInitializationError, TTSModelLoadError) as err:
-                if t in ("vulkan", "gpu", "ncnn") or self.requested_device in ("vulkan", "gpu"):
-                    raise
-                logger.debug("Vulkan neural engine not ready, trying fallback: %s", err)
-
-        # Explicit Tier 3: Neural (Sherpa-ONNX CPU)
-        if t in ("neural", "onnx", "sherpa", "vits"):
-            return SherpaNeuralEngine(
-                model_path=self.model_path,
-                language=self.language,
-                device=self.requested_device,
-                threads=self.threads,
-                sample_rate=self.sample_rate or 22050,
-                model_type="vits",
-            )
-
-        # BigTech 3rd-Party Neural Speech Engines (StyleTTS2/Kokoro, MeloTTS, Supertonic)
-        elif t in ("kokoro", "melo", "supertonic"):
-            return SherpaNeuralEngine(
-                model_path=self.model_path,
-                language=self.language,
-                device=self.requested_device,
-                threads=self.threads,
-                sample_rate=self.sample_rate or 22050,
-                model_type=t,
-            )
-
-        # Explicit Tier 4: Expressive (Fail-Fast)
-        elif t in ("expressive", "chat", "conversational"):
-            return ExpressiveEngine(
-                model_path=self.model_path,
-                language=self.language,
-                device=self.requested_device,
-                threads=self.threads,
-                sample_rate=self.sample_rate or 22050,
-            )
-
-        # Explicit Multilingual / Code-Switching Tier
-        elif t in ("multilingual", "codeswitch", "hybrid"):
-            return self._get_multilingual_engine()
-
-        # Explicit Tier 2: Native
-        elif t == "native":
-            return self.native_engine
-
-        # Auto Mode (Zero-Silent-Fallback)
-        elif t == "auto":
-            # 1. Check if SherpaNeuralEngine assets exist
-            try:
-                return SherpaNeuralEngine(
-                    model_path=self.model_path,
-                    language=self.language,
-                    device=self.requested_device,
-                    threads=self.threads,
-                    sample_rate=self.sample_rate or 22050,
-                )
-            except TTSModelLoadError as err:
-                logger.info("Auto tier: Neural model assets not ready (%s). Probing native system voice...", err)
-
-            # 2. Check if NativeAndroidEngine is available
-            if self.native_engine.binary:
-                return self.native_engine
-
-            # 3. Fail-Fast: No silent robotic fallback
-            raise TTSModelLoadError(
-                "[FAIL-FAST] No TTS voice engine available. Neural speech model is not installed, "
-                "and native Android TTS engine is unavailable.\n"
-                "  To install official neural models automatically, run:\n"
-                "      termux-tts install\n"
-            )
-        else:
-            raise TTSInferenceError(
-                f"[FAIL-FAST] Unknown engine_type '{self.requested_engine_type}'. "
-                f"Available tiers: ['auto', 'native', 'neural', 'expressive', 'multilingual', 'kokoro', 'melo', 'supertonic']"
-            )
-
-    @property
-    def active_backend(self) -> str:
-        return getattr(self.synth_engine, "backend", "NATIVE_SYSTEM")
-
-    @property
-    def model_name(self) -> str:
-        return getattr(self.synth_engine, "model_name", "native-system-voice")
-
-    @property
-    def binary(self) -> Optional[str]:
-        return getattr(self.synth_engine, "binary", getattr(self.native_engine, "binary", None))
-
-    def _get_multilingual_engine(self) -> MultilingualNeuralEngine:
-        if self._multilingual_engine is None:
-            self._multilingual_engine = MultilingualNeuralEngine(
-                threads=self.threads,
-                device=self.device,
-                sample_rate=self.sample_rate or 22050,
-            )
-        return self._multilingual_engine
-
-    def speak(self, text: str, stream: Optional[str] = None) -> NativeResult:
-        """Speak text directly through physical Android speaker (Native Engine)."""
-        if self._is_closed:
-            raise TTSInferenceError("Cannot speak: Engine session is closed.")
-        return self.native_engine.speak(text, stream=stream)
-
-    def synthesize(
-        self,
-        text: str,
-        output: Optional[str] = None,
-        speed: float = 1.0,
-        preset: Optional[str] = None,
-        language: Optional[str] = None,
-        mode: str = "unified",
-    ) -> Union[SherpaResult, ExpressiveResult, NativeResult, MultilingualResult]:
-        """Synthesize text into speech audio buffer / WAV file with Zero-Config intelligent routing."""
-        if self._is_closed:
-            raise TTSInferenceError("Cannot synthesize: Engine session is closed.")
-
-        clean_text = text.strip() if text else ""
-        if not clean_text:
-            raise TTSInferenceError("Cannot synthesize empty text.")
-
-        from .script_classifier import normalize_language_code
-        target_lang = normalize_language_code(language or self.language)
-
-        # 1. If user explicitly pinned to OS Native voice, speak directly
-        if self.requested_engine_type == "native":
-            return self.native_engine.speak(clean_text)
-
-        # 2. Multilingual auto-detection:
-        # Route to MultilingualNeuralEngine if multiple languages are present in text
-        # or if caller specifically requested multilingual / hybrid engine.
-        detected_langs = MultilingualTokenizer.detect_languages(clean_text)
-        is_mixed_text = len(detected_langs) > 1
-
-        should_route_multilingual = (
-            (self.requested_engine_type in ("multilingual", "codeswitch", "hybrid")) or
-            (self.requested_engine_type == "auto" and (is_mixed_text or self._multilingual_engine is not None)) or
-            (is_mixed_text and self.requested_engine_type != "native") or
-            (target_lang in ("hi", "ru", "ja", "zh", "es", "fr", "de", "ar") and self.requested_engine_type != "native")
-        )
-
-        if should_route_multilingual:
-            multi_engine = self._get_multilingual_engine()
-            kwargs = {}
-            if target_lang != "auto":
-                kwargs["language"] = target_lang
-            return multi_engine.synthesize(
-                clean_text,
-                output=output,
-                speed=speed,
-                mode=mode,
-                **kwargs
-            )
-
-        # 4. Standard single-language engine
-        if hasattr(self.synth_engine, "synthesize"):
-            return self.synth_engine.synthesize(clean_text, output=output, speed=speed, preset=preset)
-        elif hasattr(self.synth_engine, "speak"):
-            return self.synth_engine.speak(clean_text)
-        raise TTSInferenceError(f"Selected engine '{type(self.synth_engine).__name__}' does not support synthesize.")
-
-    def close(self) -> None:
-        self._is_closed = True
-        self.native_engine.close()
-        if hasattr(self.synth_engine, "close"):
-            self.synth_engine.close()
-        if self._multilingual_engine is not None:
-            self._multilingual_engine.close()
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        self.close()
-
-
-def load(
-    model: Optional[str] = None,
-    language: str = "auto",
-    preset: str = "balanced",
-    device: str = "auto",
-    threads: int = 4,
-    sample_rate: Optional[int] = None,
-    engine: str = "auto",
-    tier: Optional[str] = None,
-) -> TTSEngine:
-    return TTSEngine(
-        model_path=model,
-        language=language,
-        preset=preset,
-        device=device,
-        threads=threads,
-        sample_rate=sample_rate,
-        engine_type=engine,
-        model_tier=tier,
-    )
-
-
-def doctor() -> Dict[str, Any]:
-    ameva_mod = _resolve_ameva_runtime()
-    if ameva_mod is not None:
-        try:
-            from ameva_runtime.adapters import TtsAdapter
-            adapter = TtsAdapter()
-            rep = adapter.resolve_diagnostic_report()
-            return {
-                "doctor_report": rep,
-                "overall_success": getattr(rep, "overall_success", False),
-                "passed_stages": getattr(rep, "passed_stages", 0),
-                "recommended_backend": getattr(rep, "recommended_backend", "cpu_neon"),
-                "status": "DIAGNOSED_VIA_AMEVA",
-            }
-        except Exception as e:
-            logger.debug("AMEVA Doctor invocation exception: %s", e)
-
-    return {
-        "doctor_report": None,
-        "overall_success": False,
-        "passed_stages": 0,
-        "recommended_backend": "cpu_neon",
-        "status": "NO_AMEVA_RUNTIME",
-    }