termux-tts 0.1.1 → 1.3.0

package/docs/guide.md

@@ -31,7 +31,7 @@ flowchart TD
     end
 
     subgraph Hardware_Probe ["하드웨어 진단 계층"]
-        Doctor[VulkanDoctor (vulkan_probe.py)] --> AVR[ameva-vulkan-runtime (12-Stage Probe)]
+        Doctor[VulkanDoctor (vulkan_probe.py)] --> AVR[ameva-runtime (12-Stage Probe)]
     end
 ```
 
@@ -42,7 +42,7 @@ flowchart TD
 2. **Option B (안드로이드 시스템 네이티브 음성 브릿지 - `NativeAndroidEngine`)**:
    - 삼성 보이스(Samsung Voice) 및 구글 음성 엔진(Google TTS)과 Termux IPC로 직접 통신하여 zero-download 오버헤드로 즉시 물리 스피커 발화를 수행합니다.
 3. **Vulkan GPU 진단 계층 (`VulkanDoctor`)**:
-   - `ameva-vulkan-runtime`의 12단계 자체 검증 엔진(V0~V11)을 바인딩하여 퀄컴 Adreno/ARM Mali GPU의 파이프라인 가용성을 실시간 판별합니다.
+   - `ameva-runtime`의 12단계 자체 검증 엔진(V0~V11)을 바인딩하여 퀄컴 Adreno/ARM Mali GPU의 파이프라인 가용성을 실시간 판별합니다.
 
 ---
 
@@ -66,7 +66,7 @@ fi
 
 # [2/4] Python SDK 및 CLI 설치 (Editable/Release Build)
 pip install --upgrade pip setuptools wheel
-pip install ameva-vulkan-runtime || true
+pip install ameva-runtime || true
 pip install --no-build-isolation -e .
 
 # [3/4] Node.js SDK 및 글로벌 npm CLI 심볼릭 링크
@@ -81,7 +81,7 @@ termux-tts doctor || true
 ### 2.2 패키지 빌드 메타데이터 (`setup.py` & `package.json`)
 - **Python Packaging (`setup.py`)**:
   - `console_scripts` 엔트리포인트를 통해 시스템 전역에 `termux-tts` CLI 명령어를 등록합니다.
-  - `numpy>=1.20.0` 및 `ameva-vulkan-runtime>=1.0.0`을 표준 종속성으로 선언합니다.
+  - `numpy>=1.20.0` 및 `ameva-runtime>=2.0.0`을 표준 종속성으로 선언합니다.
 - **Node.js Packaging (`package.json`)**:
   - `bin/cli.js`를 전역 실행 바이너리로 연결하고, CommonJS 기반 `index.js` 모듈을 제공합니다.
 
@@ -378,7 +378,7 @@ class NativeAndroidEngine:
 ---
 
 ### 3.6 하드웨어 진단 프로브 (`termux_tts/vulkan_probe.py`)
-공식 `ameva-vulkan-runtime` 패키지를 바인딩하여 12단계 하드웨어 정밀 진단을 구동합니다.
+공식 `ameva-runtime` 패키지를 바인딩하여 12단계 하드웨어 정밀 진단을 구동합니다.
 
 - **V0**: `libvulkan.so` 동적 로더 개방 여부
 - **V1~V3**: GPU 인스턴스 및 물리 디바이스(Adreno/Mali) 질의

package/docs/tts_guide.md

@@ -31,7 +31,7 @@ flowchart TD
     end
 
     subgraph Hardware_Probe ["하드웨어 진단 계층"]
-        Doctor[VulkanDoctor (vulkan_probe.py)] --> AVR[ameva-vulkan-runtime (12-Stage Probe)]
+        Doctor[VulkanDoctor (vulkan_probe.py)] --> AVR[ameva-runtime (12-Stage Probe)]
     end
 ```
 
@@ -42,7 +42,7 @@ flowchart TD
 2. **Option B (안드로이드 시스템 네이티브 음성 브릿지 - `NativeAndroidEngine`)**:
    - 삼성 보이스(Samsung Voice) 및 구글 음성 엔진(Google TTS)과 Termux IPC로 직접 통신하여 zero-download 오버헤드로 즉시 물리 스피커 발화를 수행합니다.
 3. **Vulkan GPU 진단 계층 (`VulkanDoctor`)**:
-   - `ameva-vulkan-runtime`의 12단계 자체 검증 엔진(V0~V11)을 바인딩하여 퀄컴 Adreno/ARM Mali GPU의 파이프라인 가용성을 실시간 판별합니다.
+   - `ameva-runtime`의 12단계 자체 검증 엔진(V0~V11)을 바인딩하여 퀄컴 Adreno/ARM Mali GPU의 파이프라인 가용성을 실시간 판별합니다.
 
 ---
 
@@ -66,7 +66,7 @@ fi
 
 # [2/4] Python SDK 및 CLI 설치 (Editable/Release Build)
 pip install --upgrade pip setuptools wheel
-pip install ameva-vulkan-runtime || true
+pip install ameva-runtime || true
 pip install --no-build-isolation -e .
 
 # [3/4] Node.js SDK 및 글로벌 npm CLI 심볼릭 링크
@@ -81,7 +81,7 @@ termux-tts doctor || true
 ### 2.2 패키지 빌드 메타데이터 (`setup.py` & `package.json`)
 - **Python Packaging (`setup.py`)**:
   - `console_scripts` 엔트리포인트를 통해 시스템 전역에 `termux-tts` CLI 명령어를 등록합니다.
-  - `numpy>=1.20.0` 및 `ameva-vulkan-runtime>=1.0.0`을 표준 종속성으로 선언합니다.
+  - `numpy>=1.20.0` 및 `ameva-runtime>=2.0.0`을 표준 종속성으로 선언합니다.
 - **Node.js Packaging (`package.json`)**:
   - `bin/cli.js`를 전역 실행 바이너리로 연결하고, CommonJS 기반 `index.js` 모듈을 제공합니다.
 
@@ -378,7 +378,7 @@ class NativeAndroidEngine:
 ---
 
 ### 3.6 하드웨어 진단 프로브 (`termux_tts/vulkan_probe.py`)
-공식 `ameva-vulkan-runtime` 패키지를 바인딩하여 12단계 하드웨어 정밀 진단을 구동합니다.
+공식 `ameva-runtime` 패키지를 바인딩하여 12단계 하드웨어 정밀 진단을 구동합니다.
 
 - **V0**: `libvulkan.so` 동적 로더 개방 여부
 - **V1~V3**: GPU 인스턴스 및 물리 디바이스(Adreno/Mali) 질의

package/install.sh

@@ -26,10 +26,10 @@ fi
 # 2. Python Toolchain & Package Installation (pip)
 echo "[2/4] Installing Python SDK and CLI via pip..."
 pip install --upgrade pip setuptools wheel
-if pip install ameva-vulkan-runtime 2>/dev/null; then
-    echo "  -> ameva-vulkan-runtime hardware diagnostics bound."
+if pip install ameva-runtime 2>/dev/null; then
+    echo "  -> ameva-runtime hardware diagnostics bound."
 else
-    echo "  -> ameva-vulkan-runtime optional hardware acceleration bridge skipped."
+    echo "  -> ameva-runtime optional hardware acceleration bridge skipped."
 fi
 pip install --no-build-isolation -e .
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termux-tts",
-  "version": "0.1.1",
+  "version": "1.3.0",
   "description": "On-device Text-to-Speech framework utilizing device resources (DSP Formant Vocoder, ONNX Neural Runtime & Android Native Voice)",
   "main": "index.js",
   "bin": {
@@ -23,7 +23,7 @@
   "author": "AMEVA Foundation",
   "license": "Apache-2.0",
   "dependencies": {
-    "ameva-vulkan-runtime": ">=1.0.0"
+    "@ameva/runtime": ">=2.1.0"
   },
   "engines": {
     "node": ">=16.0.0"

package/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "termux-tts"
-version = "1.1.3"
-description = "On-device Text-to-Speech framework utilizing device resources (DSP Formant Vocoder, ONNX Neural Runtime & Android Native Voice Bridge)"
+version = "1.3.0"
+description = "On-device 4-Tier Text-to-Speech framework utilizing device resources (DSP Formant Vocoder, C++ Sherpa-ONNX Neural, Android Native & Expressive)"
 readme = "README.pypi.md"
 requires-python = ">=3.10"
 license = { text = "Apache-2.0" }
@@ -25,6 +25,7 @@ classifiers = [
 ]
 dependencies = [
     "numpy>=1.20.0",
+    "ameva-component-sdk>=0.1.0,<2.0",
 ]
 
 [project.optional-dependencies]

package/setup.py

@@ -3,8 +3,8 @@ from setuptools import setup, find_packages
 
 setup(
     name="termux-tts",
-    version="1.1.3",
-    description="Ultra-Fast On-Device Dual-Engine Text-to-Speech Framework (Parametric Formant Acoustic Synthesizer & Android Native Voice Bridge)",
+    version="1.2.0",
+    description="Ultra-Fast On-Device 4-Tier Text-to-Speech Framework (DSP Synth, Android Native, C++ Sherpa-ONNX Neural & Expressive)",
     long_description=open("README.pypi.md", encoding="utf-8").read() if os.path.exists("README.pypi.md") else open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",
     author="AMEVA Foundation",
@@ -14,7 +14,7 @@ setup(
     python_requires=">=3.8",
     install_requires=[
         "numpy>=1.20.0",
-        "ameva-vulkan-runtime>=1.0.0",
+        "ameva-runtime>=2.0.0",
     ],
     extras_require={
         "onnx": ["onnxruntime>=1.15.0"],

package/termux_tts/__init__.py

@@ -1,47 +1,63 @@
-"""
-termux-tts: Production-Grade Dual-Engine TTS Framework for Android Termux.
-- Option A: Deep Learning VITS ONNX Neural Vocoder (Vulkan GPU Accelerated)
-- Option B: Android System Native Voice Engine Bridge (Samsung / Google Voice)
-"""
-
-from .engine import TTSEngine, load, doctor
-from .engine_native import NativeAndroidEngine, NativeResult
-from .engine_dsp import ParametricDSPEngine, DSPResult, QUALITY_PRESETS, DSPSynthesizer
-from .engine_onnx import ONNXNeuralEngine, ONNXResult
-from .tokenizer import PhoneticTokenizer, EXPRESSIVE_TAGS
-from .g2p_korean import KoreanG2PEngine, korean_text_to_phonemes
-from .audio import AudioBuffer
-from .exceptions import (
-    TTSError,
-    TTSModelLoadError,
-    TTSInferenceError,
-    VulkanInitializationError,
-    TTSAudioEncodingError,
-    TTSLanguageNotSupportedError
-)
-
-__version__ = "1.1.2"
-__all__ = [
-    "TTSEngine",
-    "load",
-    "doctor",
-    "ParametricDSPEngine",
-    "DSPSynthesizer",
-    "DSPResult",
-    "NativeAndroidEngine",
-    "NativeResult",
-    "ONNXNeuralEngine",
-    "ONNXResult",
-    "QUALITY_PRESETS",
-    "PhoneticTokenizer",
-    "KoreanG2PEngine",
-    "korean_text_to_phonemes",
-    "EXPRESSIVE_TAGS",
-    "AudioBuffer",
-    "TTSError",
-    "TTSModelLoadError",
-    "TTSInferenceError",
-    "VulkanInitializationError",
-    "TTSAudioEncodingError",
-    "TTSLanguageNotSupportedError"
-]
+"""
+termux-tts: Production-Grade 4-Tier TTS Framework for Android Termux.
+- Tier 1: Parametric DSP Formant Synthesizer Engine (0MB Zero-Dependency)
+- Tier 2: Android System Native Voice Engine Bridge (Samsung / Google Voice)
+- Tier 3: Authentic C++ Subprocess-Isolated Sherpa-ONNX Neural Vocoder (VITS Deep Learning)
+- Tier 4: Pure On-Device Expressive Emotional Synthesizer (Conversational Tags)
+"""
+
+from .engine import TTSEngine, load, doctor
+from .engine_native import NativeAndroidEngine, NativeResult
+from .engine_dsp import ParametricDSPEngine, DSPResult, QUALITY_PRESETS, DSPSynthesizer
+from .engine_sherpa import SherpaNeuralEngine, SherpaResult
+from .engine_vulkan import VulkanNeuralEngine, VulkanResult
+from .engine_expressive import ExpressiveEngine, ExpressiveResult
+from .installer import run_installation
+from .tokenizer import PhoneticTokenizer, EXPRESSIVE_TAGS
+from .g2p_korean import KoreanG2PEngine, korean_text_to_phonemes
+from .audio import AudioBuffer
+from .exceptions import (
+    TTSError,
+    TTSModelLoadError,
+    TTSInferenceError,
+    VulkanInitializationError,
+    TTSAudioEncodingError,
+    TTSLanguageNotSupportedError
+)
+
+# Backward-compatibility alias
+ONNXNeuralEngine = SherpaNeuralEngine
+ONNXResult = SherpaResult
+
+__version__ = "1.3.0"
+__all__ = [
+    "TTSEngine",
+    "load",
+    "doctor",
+    "ParametricDSPEngine",
+    "DSPSynthesizer",
+    "DSPResult",
+    "NativeAndroidEngine",
+    "NativeResult",
+    "SherpaNeuralEngine",
+    "SherpaResult",
+    "VulkanNeuralEngine",
+    "VulkanResult",
+    "ExpressiveEngine",
+    "ExpressiveResult",
+    "run_installation",
+    "ONNXNeuralEngine",
+    "ONNXResult",
+    "QUALITY_PRESETS",
+    "PhoneticTokenizer",
+    "KoreanG2PEngine",
+    "korean_text_to_phonemes",
+    "EXPRESSIVE_TAGS",
+    "AudioBuffer",
+    "TTSError",
+    "TTSModelLoadError",
+    "TTSInferenceError",
+    "VulkanInitializationError",
+    "TTSAudioEncodingError",
+    "TTSLanguageNotSupportedError"
+]

package/termux_tts/adapter.py

@@ -2,12 +2,21 @@
 termux_tts.adapter
 ===================
 AMEVA Component Protocol v1 — Orchestrator Adapter (v0.8.1 호환)
+
+P0-2: infer() fallback yield _not_supported → raise OperationNotSupported
+P0-4: except Exception → retryable 분류, 원본 오류 코드 보존
 """
 from __future__ import annotations
 
 from typing import Any, AsyncIterator
 
 from ameva_component.adapter_base import BaseOrchestratorAdapter
+from ameva_component.exceptions import (
+    ComponentError,
+    OperationNotSupported,
+    redact_details,
+    redact_text,
+)
 from termux_tts.control.component import TTSControl
 
 
@@ -15,12 +24,25 @@ class TTSOrchestratorAdapter(BaseOrchestratorAdapter):
     """TTS (Text-to-Speech) Orchestrator Adapter.
 
     합성은 파일 기반으로 수행됩니다.
-    infer()는 text를 받아 audio 파일 경로를 반환합니다.
+    infer(): text를 받아 audio 파일 경로를 반환합니다.
     요청 모델과 실행 모델이 다르면 fallback_used=True를 명시합니다.
     """
 
     COMPONENT_ID = "termux-tts"
 
+    _RETRYABLE_CODES: frozenset[str] = frozenset({
+        "REMOTE_TIMEOUT",
+        "MODEL_BUSY",
+        "TEMPORARY_RESOURCE_UNAVAILABLE",
+    })
+    _NON_RETRYABLE_CODES: frozenset[str] = frozenset({
+        "VOICE_NOT_FOUND",
+        "TEXT_TOO_LONG",
+        "UNSUPPORTED_LANGUAGE",
+        "OUTPUT_PATH_FORBIDDEN",
+        "ENCODING_FAILED",
+    })
+
     def __init__(self, control: TTSControl | None = None) -> None:
         self._control = control or TTSControl()
 
@@ -28,14 +50,14 @@ class TTSOrchestratorAdapter(BaseOrchestratorAdapter):
         """TTS synthesis: text → audio file path.
 
         request 키:
-            text (str): 합성할 텍스트 (필수)
+            text (str): 합성할 텍스트 (필수, 비어있으면 안 됨)
             voice_id (str): 목소리 ID (선택)
             model_id (str): 모델 ID (선택)
-            output_path (str): 출력 파일 경로 (선택, 없으면 임시 파일)
+            output_path (str): 출력 파일 경로 (선택)
 
         반환 프레임:
             {"type": "audio", "audio_path": str, "final": bool, "fallback_used": bool}
-            {"type": "error", "code": str, "message": str}
+            {"type": "error", "ok": False, "error": {...}}
         """
         text = request.get("text", "").strip()
         if not text:
@@ -52,46 +74,127 @@ class TTSOrchestratorAdapter(BaseOrchestratorAdapter):
             }
             return
 
-        if hasattr(self._control, "synthesize"):
-            try:
-                result = await self._control.synthesize(request)
-                audio_path = result.get("audio_path", "")
-                if not audio_path:
-                    yield {
-                        "type": "error",
-                        "ok": False,
-                        "error": {
-                            "code": "SYNTHESIS_FAILED",
-                            "message": "synthesize() returned no audio_path",
-                            "operation": "infer",
-                            "component_id": self.COMPONENT_ID,
-                            "retryable": True,
-                        },
-                    }
-                    return
-                yield {
-                    "type": "audio",
-                    "audio_path": audio_path,
-                    "final": True,
-                    "fallback_used": result.get("fallback_used", False),
-                    "requested_voice": result.get("requested_voice"),
-                    "executed_voice": result.get("executed_voice"),
-                    "ok": True,
-                }
-            except Exception as exc:
+        if not hasattr(self._control, "synthesize"):
+            # P0-2: fallback yield → raise
+            raise OperationNotSupported(operation="infer.synthesize", component_id=self.COMPONENT_ID)
+
+        try:
+            result = await self._control.synthesize(request)
+
+            if not isinstance(result, dict):
+                raise ValueError(f"synthesize() must return dict, got {type(result).__name__}")
+
+            if result.get("ok") is not True:
+                err_payload = result.get("error") if isinstance(result.get("error"), dict) else {}
                 yield {
                     "type": "error",
                     "ok": False,
                     "error": {
-                        "code": "SYNTHESIS_FAILED",
-                        "message": str(exc),
+                        "code": err_payload.get("code", "ADAPTER_RESULT_NOT_SUCCESS"),
+                        "message": err_payload.get("message", "synthesize() did not return ok=True"),
                         "operation": "infer",
                         "component_id": self.COMPONENT_ID,
-                        "retryable": True,
+                        "retryable": False,
+                        "details": {"result_keys": sorted(result.keys())},
                     },
                 }
-        else:
-            yield self._not_supported("infer.synthesize")
+                return
+
+            audio_path = result.get("audio_path")
+            if not audio_path:
+                raise ValueError("synthesize() result missing required field 'audio_path'")
+            if not isinstance(audio_path, str):
+                raise TypeError(f"synthesize() audio_path must be str, got {type(audio_path).__name__}")
+
+            yield {
+                "type": "audio",
+                "audio_path": audio_path,
+                "final": True,
+                "fallback_used": result.get("fallback_used", False),
+                "requested_voice": result.get("requested_voice"),
+                "executed_voice": result.get("executed_voice"),
+                "ok": True,
+            }
+
+        except ComponentError as component_err:
+            # HIGH 1: ComponentError public_message와 redact_details로 외부 노출 보안 격리
+            import logging
+            logging.getLogger(__name__).exception(
+                "TTS component operation failed",
+                extra={
+                    "component_id": self.COMPONENT_ID,
+                    "operation": "infer",
+                    "code": getattr(component_err, "code", "COMPONENT_ERROR"),
+                },
+            )
+            if hasattr(component_err, "to_public_dict"):
+                err_dict = component_err.to_public_dict()
+            else:
+                err_dict = {
+                    "code": getattr(component_err, "code", "COMPONENT_ERROR"),
+                    "message": redact_text(getattr(component_err, "public_message", "Component operation failed")),
+                    "retryable": getattr(component_err, "retryable", False),
+                    "details": redact_details(getattr(component_err, "details", {})),
+                }
+            yield {
+                "type": "error",
+                "ok": False,
+                "error": {
+                    **err_dict,
+                    "operation": "infer",
+                    "component_id": self.COMPONENT_ID,
+                    "retryable": self._classify_retryable(
+                        err_dict.get("code", ""), default=err_dict.get("retryable", False)
+                    ),
+                },
+            }
+
+        except (ValueError, TypeError) as contract_err:
+            # P0-3/4 & HIGH 1: 계약 위반 (str(contract_err) 직접 노출 금지, 내부 로그 격리)
+            import logging
+            logging.getLogger(__name__).exception("TTS contract validation error during infer: %s", contract_err)
+            yield {
+                "type": "error",
+                "ok": False,
+                "error": {
+                    "code": "ADAPTER_CONTRACT_ERROR",
+                    "message": "Adapter contract validation failed",
+                    "operation": "infer",
+                    "component_id": self.COMPONENT_ID,
+                    "retryable": False,
+                    "details": {
+                        "cause_type": type(contract_err).__name__,
+                        "operation": "infer",
+                    },
+                },
+            }
+
+        except Exception as unexpected_err:
+            import logging
+            logging.getLogger(__name__).exception("TTS adapter unexpected error during infer: %s", unexpected_err)
+            code = getattr(unexpected_err, "code", "ADAPTER_INTERNAL_ERROR")
+            yield {
+                "type": "error",
+                "ok": False,
+                "error": {
+                    "code": code if isinstance(code, str) else "ADAPTER_INTERNAL_ERROR",
+                    "message": "Unexpected adapter failure",
+                    "operation": "infer",
+                    "component_id": self.COMPONENT_ID,
+                    "retryable": False,
+                    "details": {
+                        "cause_type": type(unexpected_err).__name__,
+                        "operation": "infer",
+                    },
+                },
+            }
+
+    def _classify_retryable(self, code: str, *, default: bool = False) -> bool:
+        if code in self._RETRYABLE_CODES:
+            return True
+        if code in self._NON_RETRYABLE_CODES:
+            return False
+        return default
 
 
 def create_adapter() -> TTSOrchestratorAdapter:

package/termux_tts/audio.py

@@ -46,7 +46,8 @@ class AudioBuffer:
 
     def to_pcm16_bytes(self) -> bytes:
         """Convert float32 [-1.0, 1.0] samples into 16-bit signed integer bytes."""
-        clipped = np.clip(self.samples, -1.0, 1.0)
+        clean = np.nan_to_num(self.samples, nan=0.0, posinf=1.0, neginf=-1.0)
+        clipped = np.clip(clean, -1.0, 1.0)
         pcm16 = (clipped * 32767.0).astype(np.int16)
         return pcm16.tobytes()
 
@@ -64,6 +65,28 @@ class AudioBuffer:
         except Exception as e:
             raise TTSAudioEncodingError(f"Failed to encode WAV buffer: {e}") from e
 
+    def pad_silence(self, lead_in_ms: int = 200, lead_out_ms: int = 150) -> "AudioBuffer":
+        """Prepend and append true zero-amplitude silence to prevent Android DAC ramp-up clipping."""
+        lead_in_samples = int(self.sample_rate * (lead_in_ms / 1000.0))
+        lead_out_samples = int(self.sample_rate * (lead_out_ms / 1000.0))
+        zeros_in = np.zeros(lead_in_samples, dtype=np.float32)
+        zeros_out = np.zeros(lead_out_samples, dtype=np.float32)
+        padded = np.concatenate([zeros_in, self.samples, zeros_out])
+        return AudioBuffer(padded, sample_rate=self.sample_rate)
+
+    @classmethod
+    def from_wav_file(cls, filepath: str) -> "AudioBuffer":
+        """Load an AudioBuffer directly from a WAV file on disk."""
+        try:
+            with wave.open(filepath, "rb") as wf:
+                sr = wf.getframerate()
+                frames = wf.readframes(wf.getnframes())
+                pcm16 = np.frombuffer(frames, dtype=np.int16)
+                samples = (pcm16 / 32767.0).astype(np.float32)
+                return cls(samples, sample_rate=sr)
+        except Exception as e:
+            raise TTSAudioEncodingError(f"Failed to read WAV file '{filepath}': {e}") from e
+
     def save(self, filepath: str) -> str:
         """Save the audio buffer to a WAV file on disk."""
         wav_data = self.to_wav_bytes()