termux-tts 1.1.5 → 1.3.0

package/README.md

@@ -1,31 +1,114 @@
-# termux-tts
+# Termux-TTS
 
-[![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/uno-km)
+[![PyPI](https://img.shields.io/pypi/v/termux-tts.svg?style=flat-square&color=0369a1)](https://pypi.org/project/termux-tts/)
+[![Python](https://img.shields.io/pypi/pyversions/termux-tts.svg?style=flat-square)](https://pypi.org/project/termux-tts/)
+[![npm](https://img.shields.io/npm/v/termux-tts.svg?style=flat-square&color=b91c1c)](https://www.npmjs.com/package/termux-tts)
+[![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/termux-tts)
 
-> ****  
-> **
+> Production-Grade 4-Tier On-Device Speech Synthesis Framework (Zero-Dependency DSP Formant, C++ Vulkan GPU Neural Engine & Android Native Voice Bridge)
 
 ---
 
-## 📌 Architecture & Overview
+## Architecture & Overview
 
+Termux-TTS is an enterprise-grade, on-device text-to-speech framework optimized for mobile edge hardware and Android Termux environments. Built to eliminate heavy dependency stacks and fragile driver behaviors, it features a resilient 4-Tier architecture:
 
+- **Tier 1: Zero-Dependency Parametric DSP Formant Vocoder**: 0MB disk footprint, Rosenberg glottal pulse formulation, and 5-band biquad formant filters providing deterministic speech synthesis in under 50 milliseconds (RTF 0.013x).
+- **Tier 2: Android System Native Voice Bridge**: Direct IPC integration to physical Samsung and Google speech engines via the Termux-API service layer.
+- **Tier 3: Subprocess-Isolated Sherpa C++ CPU Engine**: Subprocess-isolated VITS acoustic modeling on ARM64 NEON with memory leak protection.
+- **Tier 4: Pure Vulkan GPU Hardware Neural Engine**: High-performance GPU tensor synthesis via precompiled native C++ binaries (`sherpa-ncnn-offline-tts-vulkan`) running high-resolution studio models (`vits-piper-en_US-lessac-high-fp16`) with zero silent CPU fallback.
 
+---
+
+## Empirical Hardware Benchmarks (Physical Devices)
+
+Measurements gathered on physical Android 16 hardware running Termux ARM64:
+
+| Target Device | Hardware Architecture | Synthesis Engine | Model Profile | Audio Length | Synthesis Time | Real-Time Factor (RTF) | Status |
+| :--- | :--- | :--- | :--- | :---: | :---: | :---: | :---: |
+| **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan GPU Neural | `lessac-high-fp16` | 6.70 s | **6.65 s** | **0.993x** | Validated |
+| **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan GPU Neural | `lessac-medium` | 4.59 s | **1.21 s** | **0.264x** | Validated |
+| **Galaxy A35** | Exynos 1380 / Mali-G68 MP5 | Vulkan GPU Neural | `lessac-medium` | 4.52 s | **5.18 s** | **1.146x** | Validated |
+| **Galaxy A35** | Exynos 1380 / Mali-G68 MP5 | Vulkan GPU Neural | `lessac-high-fp16` | 6.73 s | **34.33 s** | **5.098x** | Validated |
+| **ARM64 CPU** | Cortex-A78 / A55 | Parametric DSP | 5-Band Biquad | 4.15 s | **0.054 s** | **0.0130x** | Validated |
+
+---
+
+## Installation & 1-Click Provisioning
+
+### 1. Package Installation
+```bash
+# Python SDK & CLI
+pip install termux-tts
+
+# Node.js / TypeScript
+npm install termux-tts
+```
 
+### 2. Automated Engine & Weights Provisioning
+Automate the installation of precompiled ARM64 Vulkan C++ binaries and HuggingFace weights with self-test verification:
+```bash
+# Install Studio Tier (22.05kHz High-Fidelity)
+termux-tts install --tier high
+
+# Or install Medium Tier (Balanced Performance)
+termux-tts install --tier medium
+```
 
 ---
 
-## 🚀 Installation & Quickstart
+## Quickstart
+
+### Global Command-Line Interface (CLI)
+```bash
+# Synthesize using Vulkan GPU with speaker playback
+termux-tts synth -e vulkan --tier high -t "Speech synthesis via Vulkan GPU." -o out.wav --play
+
+# Instant DSP Formant synthesis
+termux-tts synth -e dsp -t "Zero dependency DSP synthesis." -o dsp.wav
+
+# Direct hardware speaker broadcast
+termux-tts speak -t "Hardware speaker broadcast." -l en
+
+# Hardware diagnostics
+termux-tts doctor
+```
+
+### Python SDK
+```python
+import termux_tts as tts
+
+# High-Resolution Vulkan GPU Neural Synthesis
+with tts.load(engine="vulkan", model_tier="high") as engine:
+    result = engine.synthesize("Pure Vulkan neural execution on mobile.", output="speech.wav")
+    print(f"Synthesized in {result.elapsed_ms:.1f}ms (RTF: {result.rtf:.4f}x)")
+
+# Zero-Dependency DSP Formant Synthesis
+with tts.load(engine="dsp", preset="balanced") as engine:
+    result = engine.synthesize("Instant speech without model downloads.", output="dsp.wav")
+    print(f"DSP Latency: {result.elapsed_ms:.1f}ms")
+```
+
+### Node.js / TypeScript
+```typescript
+import * as tts from 'termux-tts';
 
+async function main() {
+  const engine = tts.load({ engine: 'vulkan', tier: 'high' });
+  const res = await engine.synthesize("High performance speech synthesis.", { output: "speech.wav" });
+  console.log(`Synthesized in ${res.elapsedMs}ms`);
+}
+main();
+```
 
 ---
 
-## 📖 Official Documentation & Benchmarks
+## Official Documentation & Benchmarks
 - [Official Architecture & API Reference](https://uno-km.vercel.app/lib/tts/)
 - [Ecosystem Metrics & Registry Stats](https://uno-km.vercel.app/foundation/metrics)
 - [AMEVA Open-Source Foundation Portal](https://uno-km.vercel.app/foundation/index.html)
 
 ---
 
-## 📄 License
+## License
 Licensed under the Apache-2.0 License. Copyright (c) 2026 Eunho Kim ([@uno-km](https://github.com/uno-km)).

package/README.pypi.md

@@ -4,8 +4,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/termux-tts.svg?style=flat-square)](https://pypi.org/project/termux-tts/)
 [![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/termux-tts)
 
-> **High-Performance Multi-Backend Speech Synthesis Framework for Android Termux & Edge Linux**  
-> Supports Zero-Dependency Parametric DSP Formant Vocoder, Deep Learning ONNX Neural Runtime, and Android Native System Voice Bridge.
+> Production-Grade 4-Tier On-Device Speech Synthesis Framework for Mobile & Edge (Zero-Dependency DSP Formant, C++ Vulkan GPU Neural Engine & Android Native Voice Bridge)
 
 ## Installation
 
@@ -13,30 +12,39 @@
 pip install termux-tts
 ```
 
+### 1-Click Automated Engine Provisioning
+```bash
+termux-tts install --tier high
+```
+
 ## Quickstart
 
 ```python
 import termux_tts as tts
 
-# 1. Zero-Dependency DSP Formant Mode (Default)
-with tts.load(engine="dsp", language="ko") as engine:
-    res = engine.synthesize("안녕하세요, 텀묵스 음성 합성입니다.", output="dsp.wav")
-    print(f"Synthesized in {res.elapsed_ms:.1f}ms (RTF: {res.rtf:.4f}x)")
+# 1. Studio Vulkan GPU Neural Engine
+with tts.load(engine="vulkan", model_tier="high") as engine:
+    result = engine.synthesize("Neural speech synthesis on mobile GPU.", output="speech.wav")
+    print(f"Elapsed: {result.elapsed_ms:.1f}ms (RTF: {result.rtf:.4f}x)")
 
-# 2. Deep Learning ONNX Mode
-with tts.load(engine="onnx", model="vits_ko.onnx", language="ko") as engine:
-    res = engine.synthesize("신경망 고품질 음성 합성입니다.", output="onnx.wav")
+# 2. Zero-Dependency DSP Formant Mode
+with tts.load(engine="dsp", preset="balanced") as engine:
+    result = engine.synthesize("Instant speech generation.", output="dsp.wav")
+    print(f"DSP Latency: {result.elapsed_ms:.1f}ms")
 
-# 3. Android System Native Speak Mode
-with tts.load(engine="native", language="ko") as engine:
-    engine.speak("스피커로 즉시 발화합니다.")
+# 3. Direct Android Native Speaker Output
+with tts.load(engine="native", language="en") as engine:
+    engine.speak("Direct hardware speaker output.")
 ```
 
-## Features
-- **Zero-Dependency DSP Engine**: Instant CPU execution with 0MB download overhead (Rosenberg Glottal Pulse + 5-Band Biquad Filters).
-- **Authentic ONNX Neural Runtime**: Deep learning acoustic model execution for VITS, Piper, and FastSpeech ONNX models.
-- **Android Native Bridge**: Direct speaker speech playback via Termux IPC.
-- **Cross-Platform CLI & Node.js Binding**: First-class support for Python, npm, and shell scripts.
+## Benchmarks (Physical Devices)
+
+| Target Device | Hardware Architecture | Synthesis Engine | Real-Time Factor (RTF) | Status |
+| :--- | :--- | :--- | :---: | :---: |
+| **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan GPU (`lessac-high-fp16`) | **0.993x** | Validated |
+| **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan GPU (`lessac-medium`) | **0.264x** | Validated |
+| **Galaxy A35** | Exynos 1380 / Mali-G68 MP5 | Vulkan GPU (`lessac-medium`) | **1.146x** | Validated |
+| **ARM64 CPU** | All Core Profiles | Parametric DSP Formant | **0.0130x** | Validated |
 
 ## Documentation
 - [Official Documentation & API Reference](https://uno-km.vercel.app/lib/tts/)
@@ -44,4 +52,3 @@ with tts.load(engine="native", language="ko") as engine:
 
 ## License
 Apache-2.0 License. Copyright (c) 2026 Eunho Kim (@uno-km).
-