termux-tts 0.1.1 → 1.1.5

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.1.5] - 2026-09-05
+
+### Changed
+- Synchronized install.sh hardware diagnostics binding to ameva-runtime.
+- Modernized 12-stage hardware diagnostic bridge and documentation architecture diagrams.
+
+---
+
+## [1.1.4] - 2026-09-05
+
+### Changed
+- Migrated hardware acceleration dependency to unified `ameva-runtime>=2.0.0` and `@ameva/runtime>=2.0.0`.
+- Synchronized Python and npm package versions to v1.1.4.
+

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.1.5",
   "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.0.0"
   },
   "engines": {
     "node": ">=16.0.0"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "termux-tts"
-version = "1.1.3"
+version = "1.1.5"
 description = "On-device Text-to-Speech framework utilizing device resources (DSP Formant Vocoder, ONNX Neural Runtime & Android Native Voice Bridge)"
 readme = "README.pypi.md"
 requires-python = ">=3.10"
@@ -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,7 +3,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="termux-tts",
-    version="1.1.3",
+    version="1.1.5",
     description="Ultra-Fast On-Device Dual-Engine Text-to-Speech Framework (Parametric Formant Acoustic Synthesizer & Android Native Voice Bridge)",
     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",
@@ -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

@@ -20,7 +20,7 @@ from .exceptions import (
     TTSLanguageNotSupportedError
 )
 
-__version__ = "1.1.2"
+__version__ = "1.1.5"
 __all__ = [
     "TTSEngine",
     "load",

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/cli.py

@@ -1,82 +1,82 @@
-"""
-Command-Line Interface for termux-tts:
-- termux-tts synth : Option A Deep Learning Neural Synthesis to File
-- termux-tts speak : Option B Android System Native Immediate Voice Output
-- termux-tts doctor: 12-Stage Vulkan GPU Hardware Diagnostics
-"""
-
-import argparse
-from .engine import load, doctor
-
-def main():
-    parser = argparse.ArgumentParser(
-        prog="termux-tts",
-        description="Termux Neural & Native Text-to-Speech Engine"
-    )
-    subparsers = parser.add_subparsers(dest="command", help="Sub-commands")
-
-    # 1. Synth (Option A: DSP Formant or ONNX Neural Vocoder to File)
-    synth_parser = subparsers.add_parser("synth", help="Synthesize text to audio WAV file (DSP / ONNX)")
-    synth_parser.add_argument("-t", "--text", required=True, help="Input text to synthesize")
-    synth_parser.add_argument("-o", "--output", default="output.wav", help="Output WAV filepath")
-    synth_parser.add_argument("-l", "--lang", default="ko", help="Language code (ko, en)")
-    synth_parser.add_argument("-e", "--engine", default="auto", choices=["auto", "dsp", "onnx"], help="Synthesis engine (dsp=zero-dependency, onnx=deep learning)")
-    synth_parser.add_argument("-m", "--model", default=None, help="Path to .onnx model file (required for onnx engine)")
-    synth_parser.add_argument("-p", "--preset", default="balanced", choices=["fast", "balanced", "expressive", "ultra"])
-    synth_parser.add_argument("-d", "--device", default="auto", choices=["auto", "gpu", "vulkan", "cpu"])
-    synth_parser.add_argument("-s", "--speed", type=float, default=1.0, help="Speech speed multiplier (0.5 to 2.0)")
-
-    # 2. Speak (Option B: Native Samsung/Google System Voice)
-    speak_parser = subparsers.add_parser("speak", help="Speak text directly through device speaker (Option B: Native)")
-    speak_parser.add_argument("-t", "--text", required=True, help="Input text to speak")
-    speak_parser.add_argument("-l", "--lang", default="ko", help="Language code (ko, en)")
-    speak_parser.add_argument("-s", "--stream", default="MUSIC", help="Audio stream (MUSIC, NOTIFICATION, ALARM)")
-
-    # 3. Doctor (Diagnostics)
-    subparsers.add_parser("doctor", help="Run 12-stage Vulkan GPU hardware diagnostics")
-
-    # ── AMEVA Component Protocol v1 ─────────────────────────────────────────
-    _protocol_available = False
-    try:
-        from ameva_component.cli_support import build_protocol_subcommands
-        build_protocol_subcommands(subparsers)
-        _protocol_available = True
-    except ImportError:
-        pass
-    # ────────────────────────────────────────────────────────────────────────
-
-    args = parser.parse_args()
-
-    if args.command == "synth":
-        with load(model=args.model, language=args.lang, preset=args.preset, device=args.device, engine=args.engine) as engine:
-            res = engine.synthesize(args.text, output=args.output, speed=args.speed)
-            print(f"[SUCCESS] Synthesized via {res.backend} ({res.model_name}) -> {args.output}")
-            print(f"  Duration: {res.duration_sec:.2f}s | Elapsed: {res.elapsed_ms:.1f}ms | RTF: {res.rtf:.4f}x")
-
-    elif args.command == "speak":
-        with load(language=args.lang) as engine:
-            res = engine.speak(args.text, stream=args.stream)
-            print(f"[SUCCESS] Spoken via {res.engine_name} on stream {args.stream} ({res.elapsed_ms:.1f}ms)")
-
-    elif args.command == "doctor":
-        diag = doctor()
-        print("=" * 60)
-        print("   TERMUX-TTS 12-STAGE VULKAN HARDWARE DIAGNOSTICS")
-        print("=" * 60)
-        for k, v in diag.items():
-            print(f"  - {k:30s}: {v}")
-        print("=" * 60)
-
-    elif args.command in ("component", "model", "instance") and _protocol_available:
-        from ameva_component.cli_support import dispatch_protocol
-        from termux_tts.control import TTSControl
-        dispatch_protocol(args, TTSControl())
-    elif args.command in ("component", "model", "instance"):
-        print("[ERROR] ameva-component-sdk not installed.", file=sys.stderr)
-        sys.exit(1)
-    else:
-        parser.print_help()
-
-if __name__ == "__main__":
-    main()
-
+"""
+Command-Line Interface for termux-tts:
+- termux-tts synth : Option A Deep Learning Neural Synthesis to File
+- termux-tts speak : Option B Android System Native Immediate Voice Output
+- termux-tts doctor: 12-Stage Vulkan GPU Hardware Diagnostics
+"""
+
+import argparse
+from .engine import load, doctor
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="termux-tts",
+        description="Termux Neural & Native Text-to-Speech Engine"
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Sub-commands")
+
+    # 1. Synth (Option A: DSP Formant or ONNX Neural Vocoder to File)
+    synth_parser = subparsers.add_parser("synth", help="Synthesize text to audio WAV file (DSP / ONNX)")
+    synth_parser.add_argument("-t", "--text", required=True, help="Input text to synthesize")
+    synth_parser.add_argument("-o", "--output", default="output.wav", help="Output WAV filepath")
+    synth_parser.add_argument("-l", "--lang", default="ko", help="Language code (ko, en)")
+    synth_parser.add_argument("-e", "--engine", default="auto", choices=["auto", "dsp", "onnx"], help="Synthesis engine (dsp=zero-dependency, onnx=deep learning)")
+    synth_parser.add_argument("-m", "--model", default=None, help="Path to .onnx model file (required for onnx engine)")
+    synth_parser.add_argument("-p", "--preset", default="balanced", choices=["fast", "balanced", "expressive", "ultra"])
+    synth_parser.add_argument("-d", "--device", default="auto", choices=["auto", "gpu", "vulkan", "cpu"])
+    synth_parser.add_argument("-s", "--speed", type=float, default=1.0, help="Speech speed multiplier (0.5 to 2.0)")
+
+    # 2. Speak (Option B: Native Samsung/Google System Voice)
+    speak_parser = subparsers.add_parser("speak", help="Speak text directly through device speaker (Option B: Native)")
+    speak_parser.add_argument("-t", "--text", required=True, help="Input text to speak")
+    speak_parser.add_argument("-l", "--lang", default="ko", help="Language code (ko, en)")
+    speak_parser.add_argument("-s", "--stream", default="MUSIC", help="Audio stream (MUSIC, NOTIFICATION, ALARM)")
+
+    # 3. Doctor (Diagnostics)
+    subparsers.add_parser("doctor", help="Run 12-stage Vulkan GPU hardware diagnostics")
+
+    # ── AMEVA Component Protocol v1 ─────────────────────────────────────────
+    _protocol_available = False
+    try:
+        from ameva_component.cli_support import build_protocol_subcommands
+        build_protocol_subcommands(subparsers)
+        _protocol_available = True
+    except ImportError as _proto_err:
+        _protocol_available = False
+    # ────────────────────────────────────────────────────────────────────────
+
+    args = parser.parse_args()
+
+    if args.command == "synth":
+        with load(model=args.model, language=args.lang, preset=args.preset, device=args.device, engine=args.engine) as engine:
+            res = engine.synthesize(args.text, output=args.output, speed=args.speed)
+            print(f"[SUCCESS] Synthesized via {res.backend} ({res.model_name}) -> {args.output}")
+            print(f"  Duration: {res.duration_sec:.2f}s | Elapsed: {res.elapsed_ms:.1f}ms | RTF: {res.rtf:.4f}x")
+
+    elif args.command == "speak":
+        with load(language=args.lang) as engine:
+            res = engine.speak(args.text, stream=args.stream)
+            print(f"[SUCCESS] Spoken via {res.engine_name} on stream {args.stream} ({res.elapsed_ms:.1f}ms)")
+
+    elif args.command == "doctor":
+        diag = doctor()
+        print("=" * 60)
+        print("   TERMUX-TTS 12-STAGE VULKAN HARDWARE DIAGNOSTICS")
+        print("=" * 60)
+        for k, v in diag.items():
+            print(f"  - {k:30s}: {v}")
+        print("=" * 60)
+
+    elif args.command in ("component", "model", "instance") and _protocol_available:
+        from ameva_component.cli_support import dispatch_protocol
+        from termux_tts.control import TTSControl
+        dispatch_protocol(args, TTSControl())
+    elif args.command in ("component", "model", "instance"):
+        print("[ERROR] ameva-component-sdk not installed.", file=sys.stderr)
+        sys.exit(1)
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()
+