termux-tts 0.1.1

package/termux_tts/control/errors.py

@@ -0,0 +1,52 @@
+"""
+termux_tts.control.errors
+termux-tts 패키지 고유 오류 정의.
+
+공통 AmevaError 하위 클래스로 정의하여 render_from_exception()과 호환됩니다.
+"""
+from __future__ import annotations
+
+from ameva_component.exceptions import AmevaError
+
+
+class VoiceNotFound(AmevaError):
+    """요청한 voice_id가 Registry 또는 내장 목록에 없을 때."""
+
+    code = "VOICE_NOT_FOUND"
+    exit_code = 65
+
+    def __init__(self, voice_id: str, model_id: str | None = None) -> None:
+        where = f" in model '{model_id}'" if model_id else ""
+        super().__init__(
+            f"Voice '{voice_id}' not found{where}",
+            details={"voice_id": voice_id, "model_id": model_id},
+        )
+        self.voice_id = voice_id
+        self.model_id = model_id
+
+
+class EngineNotAvailable(AmevaError):
+    """요청한 엔진 백엔드(dsp/onnx/native)가 현재 환경에서 사용 불가능할 때."""
+
+    code = "ENGINE_NOT_AVAILABLE"
+    exit_code = 69
+
+    def __init__(self, engine_name: str, reason: str) -> None:
+        super().__init__(
+            f"Engine '{engine_name}' is not available: {reason}",
+            details={"engine_name": engine_name, "reason": reason},
+        )
+        self.engine_name = engine_name
+
+
+class ModelPathRequired(AmevaError):
+    """ONNX 엔진 사용 시 model_path가 없을 때."""
+
+    code = "MODEL_PATH_REQUIRED"
+    exit_code = 64
+
+    def __init__(self) -> None:
+        super().__init__(
+            "model_path is required for ONNX engine activation",
+            details={"hint": "Pass model_path in the activation request"},
+        )

package/termux_tts/control/instances.py

@@ -0,0 +1,137 @@
+"""
+termux_tts.control.instances
+InstanceRegistry 연동 — DSP / ONNX / Native 엔진을 각각 Instance로 표현.
+
+TTS Instance 정책:
+  - DSP 엔진   → instance_id = "tts-dsp"
+  - ONNX 엔진  → instance_id = "tts-onnx"
+  - Native 엔진 → instance_id = "tts-native"
+  - 각 엔진은 in-process ControlMode로 동작 (별도 Worker 프로세스 없음)
+  - active_jobs 측정 실패를 0으로 변환하지 않음 → None 반환 후 호출자가 처리
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ameva_component import InstanceRegistry
+from ameva_component.instance import ControlMode, InstanceState, InstanceStatus
+
+COMPONENT_ID = "termux-tts"
+
+# TTS 엔진별 고정 Instance ID
+INSTANCE_DSP    = "tts-dsp"
+INSTANCE_ONNX   = "tts-onnx"
+INSTANCE_NATIVE = "tts-native"
+
+ALL_INSTANCE_IDS = (INSTANCE_DSP, INSTANCE_ONNX, INSTANCE_NATIVE)
+
+
+def _make_default_instance(instance_id: str, model_id: str, backend: str) -> InstanceStatus:
+    """엔진별 기본 InstanceStatus를 생성합니다."""
+    return InstanceStatus(
+        instance_id=instance_id,
+        component_id=COMPONENT_ID,
+        model_id=model_id,
+        state=InstanceState.HOT,
+        active_jobs=0,
+        queue_depth=0,
+        max_concurrency=1,
+        backend=backend,
+        started_at=time.time(),
+        last_heartbeat=time.time(),
+        last_error=None,
+        control_mode=ControlMode.IN_PROCESS,
+        endpoint=None,
+    )
+
+
+class TTSInstanceRegistry:
+    """
+    InstanceRegistry를 감싸는 TTS 전용 레지스트리.
+
+    DSP/ONNX/Native 3개 엔진을 각각 독립 Instance로 추적합니다.
+    Registry 파일이 없으면 기본 InstanceStatus를 생성하여 등록합니다.
+    """
+
+    def __init__(self, registry_dir: Path | None = None) -> None:
+        self._reg = InstanceRegistry(COMPONENT_ID, registry_dir=registry_dir)
+        self._ensure_defaults()
+
+    # ------------------------------------------------------------------
+    # 초기화
+    # ------------------------------------------------------------------
+
+    def _ensure_defaults(self) -> None:
+        """레지스트리에 없는 엔진 Instance를 기본값으로 등록합니다."""
+        defaults = {
+            INSTANCE_DSP:    ("dsp-ko",        "dsp-cpu"),
+            INSTANCE_ONNX:   ("native-system",  "onnx-cpu"),   # 활성 모델이 없을 때 기본값
+            INSTANCE_NATIVE: ("native-system",  "android-native"),
+        }
+        for inst_id, (model_id, backend) in defaults.items():
+            if self._reg.get(inst_id) is None:
+                self._reg.register(_make_default_instance(inst_id, model_id, backend))
+
+    # ------------------------------------------------------------------
+    # 조회
+    # ------------------------------------------------------------------
+
+    def list_all(self) -> list[dict]:
+        """등록된 모든 Instance를 dict 목록으로 반환합니다."""
+        return [
+            inst.to_dict()
+            for inst in self._reg.list_all()
+        ]
+
+    def get(self, instance_id: str) -> InstanceStatus | None:
+        """단일 Instance 상태를 반환합니다. 없으면 None."""
+        return self._reg.get(instance_id)
+
+    def total_active_jobs(self) -> int | None:
+        """
+        전체 Instance의 active_jobs 합계를 반환합니다.
+        측정 실패 시 None — 0으로 변환 금지.
+        """
+        total = 0
+        any_read = False
+        for inst in self._reg.list_all():
+            any_read = True
+            total += inst.active_jobs
+        return total if any_read else None
+
+    # ------------------------------------------------------------------
+    # 상태 변경
+    # ------------------------------------------------------------------
+
+    def on_model_activated(self, instance_id: str, model_id: str, backend: str) -> None:
+        """모델 활성화 시 Instance model_id와 backend를 갱신합니다."""
+        inst = self._reg.get(instance_id)
+        if inst is None:
+            inst = _make_default_instance(instance_id, model_id, backend)
+        inst.model_id = model_id
+        inst.backend = backend
+        inst.state = InstanceState.HOT
+        inst.last_error = None
+        inst.last_heartbeat = time.time()
+        self._reg.register(inst)
+
+    def on_job_start(self, instance_id: str) -> None:
+        """Job 시작 시 active_jobs++."""
+        self._reg.increment_jobs(instance_id)
+
+    def on_job_end(self, instance_id: str) -> None:
+        """Job 종료 시 active_jobs-- (음수 방지)."""
+        self._reg.decrement_jobs(instance_id)
+
+    def on_engine_error(self, instance_id: str, error: str) -> None:
+        """엔진 오류 시 Instance 상태를 FAILED로 변경합니다."""
+        self._reg.update_state(instance_id, InstanceState.FAILED, last_error=error)
+
+    def on_heartbeat(self, instance_id: str) -> None:
+        """Heartbeat 갱신."""
+        self._reg.update_heartbeat(instance_id)
+
+    def update_state(self, instance_id: str, state: InstanceState, *, last_error: str | None = None) -> None:
+        """Instance 상태를 직접 변경합니다."""
+        self._reg.update_state(instance_id, state, last_error=last_error)

package/termux_tts/control/models.py

@@ -0,0 +1,151 @@
+"""
+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

@@ -0,0 +1,13 @@
+"""
+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

@@ -0,0 +1,157 @@
+"""
+Unified 3-Tier Multi-Backend TTS Gateway for termux-tts:
+1. Pure Parametric DSP Formant Synthesizer Engine (ParametricDSPEngine - 0MB Zero-Dependency)
+2. Authentic ONNX Runtime Neural Vocoder Engine (ONNXNeuralEngine - Deep Learning)
+3. Android System Native Samsung/Google Voice Engine Bridge (NativeAndroidEngine)
+"""
+
+import os
+from typing import Optional, Union, Dict, Any
+
+from .exceptions import TTSInferenceError
+from .engine_native import NativeAndroidEngine, NativeResult
+from .engine_dsp import ParametricDSPEngine, DSPResult, QUALITY_PRESETS
+from .engine_onnx import ONNXNeuralEngine, ONNXResult
+
+class TTSEngine:
+    """Production Multi-Backend Gateway supporting DSP, ONNX, and Native speech engines."""
+
+    def __init__(
+        self,
+        model_path: Optional[str] = None,
+        language: str = "ko",
+        preset: str = "balanced",
+        device: str = "auto",
+        sample_rate: Optional[int] = None,
+        engine_type: str = "auto"
+    ):
+        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.sample_rate = sample_rate
+        self._is_closed = False
+
+        self.native_engine = NativeAndroidEngine(language=language)
+        self.synth_engine = self._resolve_synth_engine()
+
+    def _resolve_synth_engine(self):
+        if self.requested_engine_type == "onnx":
+            return ONNXNeuralEngine(
+                model_path=self.model_path,
+                language=self.language,
+                preset=self.preset,
+                device=self.requested_device,
+                sample_rate=self.sample_rate or 22050
+            )
+        elif self.requested_engine_type in ("dsp", "formant"):
+            return ParametricDSPEngine(
+                model_path=self.model_path,
+                language=self.language,
+                preset=self.preset,
+                device=self.requested_device,
+                sample_rate=self.sample_rate
+            )
+        elif self.requested_engine_type == "native":
+            return self.native_engine
+        elif self.requested_engine_type == "auto":
+            if self.model_path and os.path.isfile(self.model_path):
+                try:
+                    return ONNXNeuralEngine(
+                        model_path=self.model_path,
+                        language=self.language,
+                        preset=self.preset,
+                        device=self.requested_device,
+                        sample_rate=self.sample_rate or 22050
+                    )
+                except Exception:
+                    pass
+            return ParametricDSPEngine(
+                model_path=self.model_path,
+                language=self.language,
+                preset=self.preset,
+                device=self.requested_device,
+                sample_rate=self.sample_rate
+            )
+        else:
+            raise TTSInferenceError(
+                f"Unknown engine_type '{self.requested_engine_type}'. Available: ['auto', 'dsp', 'onnx', 'native']"
+            )
+
+    @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.native_engine, "binary", None)
+
+    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) -> Union[DSPResult, ONNXResult]:
+        """Synthesize text into speech audio buffer / WAV file (DSP or ONNX Engine)."""
+        if self._is_closed:
+            raise TTSInferenceError("Cannot synthesize: Engine session is closed.")
+        return self.synth_engine.synthesize(text, output=output, speed=speed, preset=preset)
+
+    def close(self) -> None:
+        self._is_closed = True
+        self.native_engine.close()
+        if hasattr(self.synth_engine, "close"):
+            self.synth_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 = "ko",
+    preset: str = "balanced",
+    device: str = "auto",
+    sample_rate: Optional[int] = None,
+    engine: str = "auto"
+) -> TTSEngine:
+    return TTSEngine(
+        model_path=model,
+        language=language,
+        preset=preset,
+        device=device,
+        sample_rate=sample_rate,
+        engine_type=engine
+    )
+
+def doctor() -> Dict[str, Any]:
+    try:
+        import ameva_vulkan_runtime as avr
+        from ameva_vulkan_runtime.adapters import TtsAdapter
+        doc = avr.Doctor()
+        rep = doc.run_self_test(verbose=False)
+        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"),
+            "status": "DIAGNOSED_VIA_AMEVA"
+        }
+    except Exception as e:
+        return {
+            "doctor_report": None,
+            "overall_success": False,
+            "passed_stages": 0,
+            "recommended_backend": "cpu_neon",
+            "error": str(e),
+            "status": "FALLBACK_CPU"
+        }
+