termux-tts 1.5.3 → 1.5.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +71 -284
  2. package/README.pypi.md +31 -92
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,351 +1,138 @@
1
- # Termux-TTS (v1.5.0)
1
+ # Termux-TTS
2
2
 
3
3
  [![PyPI](https://img.shields.io/pypi/v/termux-tts.svg?style=flat-square&color=0369a1)](https://pypi.org/project/termux-tts/)
4
4
  [![Python](https://img.shields.io/pypi/pyversions/termux-tts.svg?style=flat-square)](https://pypi.org/project/termux-tts/)
5
5
  [![npm](https://img.shields.io/npm/v/termux-tts.svg?style=flat-square&color=b91c1c)](https://www.npmjs.com/package/termux-tts)
6
6
  [![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/termux-tts)
7
- [![Platform](https://img.shields.io/badge/Platform-Android_ARM64_|_Qualcomm_Adreno_|_ARM_Mali-0284c7.svg?style=flat-square)](https://github.com/uno-km/termux-tts)
8
7
 
9
- > Production-Grade 4-Tier On-Device Speech Synthesis Framework: 100% Native Vulkan GPU Pipeline, Zero-Silent-Fallback Standard, Multilingual Neural Orchestrator, Zero-Dependency DSP Formant & Resident C-API Acceleration.
8
+ > Production-Grade 4-Tier On-Device Speech Synthesis Framework (Multilingual Neural Orchestrator, Zero-Dependency DSP Formant & C++ Acceleration)
10
9
 
11
10
  ---
12
11
 
13
- ## 1. Executive Summary & Core Mission
12
+ ## Architecture & Overview
14
13
 
15
- Constrained mobile edge environments frequently suffer from execution instability, excessive thermal throttling, and unpredictable runtime memory spikes when running conventional deep learning text-to-speech stacks. Heavyweight dependencies like full PyTorch exhaust mobile DRAM, while cross-language code-switching historically required multiple disconnected runtimes or heavy cloud APIs.
14
+ 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:
16
15
 
17
- **Termux-TTS** delivers a deterministic, resilient 4-Tier on-device speech synthesis framework built specifically for Android Termux and mobile ARM64 hardware. It operates entirely offline without telemetry, cloud dependencies, or hidden telemetry.
18
-
19
- ```
20
- ┌─────────────────────────────────────────────────────────────────────────────┐
21
- │ Termux-TTS 4-Tier Architecture │
22
- ├─────────────────────────────────────────────────────────────────────────────┤
23
- │ Tier 1: Zero-Dependency Parametric DSP Formant Vocoder (0MB, <50ms) │
24
- │ Rosenberg glottal pulse formulation + 5-band biquad filters. │
25
- ├─────────────────────────────────────────────────────────────────────────────┤
26
- │ Tier 2: Android System Native Voice Service Bridge (Immediate, IPC) │
27
- │ Direct routing to Samsung TTS and Google Speech Services. │
28
- ├─────────────────────────────────────────────────────────────────────────────┤
29
- │ Tier 3: Subprocess-Isolated Sherpa C++ CPU Engine (ARM64 NEON SIMD) │
30
- │ Resident C-API in-memory acceleration (sub-0.18x RTF, 9 languages). │
31
- ├─────────────────────────────────────────────────────────────────────────────┤
32
- │ Tier 4: Pure Vulkan GPU Hardware Neural Engine (100% Native Silicon) │
33
- │ SPIR-V compute shaders bound directly to /system/lib64/libvulkan.so │
34
- └─────────────────────────────────────────────────────────────────────────────┘
35
- ```
36
-
37
- ---
38
-
39
- ## 2. Engineering Standard: The Anti-Deception Trifecta Purged
40
-
41
- In strict adherence to the **AOSF-ENG-STD-2026** engineering protocol, Termux-TTS v1.5.0 permanently eradicates deceptive offloading, silent fallbacks, and brittle filesystem assumptions:
42
-
43
- 1. **Zero Deceptive CPU Offloading**:
44
- - If Vulkan GPU acceleration is requested (`--device vulkan` / `engine="vulkan"`), execution is bound 100% to physical GPU compute queues. Unlogged fallback to CPU execution or synthetic dummy audio spoofing is strictly prohibited.
45
- 2. **Zero Silent Fallbacks (Fail-Fast Semantics)**:
46
- - Replaced multi-layered exception swallowers with deterministic, standardized error codes:
47
- - `[AMEVA-TTS-E001]`: Missing Native Executable or Neural Weights.
48
- - `[AMEVA-TTS-E002]`: Vulkan Compute Runtime Execution Failure with command and stderr dump.
49
- - `[AMEVA-TTS-E003]`: Truncated or Empty Audio Buffer output.
50
- 3. **Zero Hardcoded Paths**:
51
- - Completely eliminated absolute filesystem assumptions (`/data/data/com.termux/files/home/...`).
52
- - Dynamic asset discovery queries prioritized candidate sets across `$PREFIX`, `sys.prefix`, `$HOME`, and `$PATH`.
53
- 4. **Deletion-First Hygiene**:
54
- - Legacy tightly coupled files (`engine_dsp.py`) have been cleanly deleted under the Deletion-First engineering doctrine.
55
-
56
- ---
57
-
58
- ## 3. Ground Truth: Resolving the Mobile GPU Slowdown Anomaly
59
-
60
- ### 3.1 The Root Cause: Mesa `llvmpipe` CPU Software Emulation
61
- In standard Android Termux installations, default user-space Vulkan loaders (`$PREFIX/lib/libvulkan.so`) frequently bind to Mesa's **`llvmpipe` (CPU Software Rasterizer)** instead of the underlying hardware silicon. This caused SPIR-V compute shaders to be emulated on CPU cores with massive memory-copy overhead, resulting in GPU inference being 5x~10x slower than direct CPU SIMD.
62
-
63
- ### 3.2 The Solution: Direct System ABI Binding (`/system/lib64/libvulkan.so`)
64
- Termux-TTS v1.5.0 enforces direct binding to the vendor Android Bionic Vulkan loader (`/system/lib64/libvulkan.so`), unlocking true hardware compute queues across **Qualcomm Adreno** and **ARM Mali** silicon.
65
-
66
- ```cpp
67
- // Native C++ Silicon Verification (probe_system_vk.cpp)
68
- // Confirms physical hardware device 0 binding via Bionic loader:
69
- // Galaxy S25: Adreno (TM) 830 (Vendor: 0x5143, Driver: 0x80320040, API: 1.3.298)
70
- // Galaxy S22: Adreno (TM) 730 (Vendor: 0x5143, Driver: 0x80267062, API: 1.1.205)
71
- // Galaxy S21: Mali-G78 (Vendor: 0x13B5, Driver: 0x9800000, API: 1.1.0)
72
- // Galaxy A35: Mali-G68 (Vendor: 0x13B5, Driver: 0x9801000, API: 1.1.0)
73
- ```
74
-
75
- ---
76
-
77
- ## 4. Empirical Hardware Benchmarks (Physical Android 16 Fleet)
78
-
79
- The following metrics represent empirical end-to-end speech synthesis on physical hardware running Termux ARM64 with 100% Native Vulkan GPU compute queues:
80
-
81
- | Target Device | SoC / Hardware GPU Silicon | Vulkan Driver ABI | Audio Length | Synthesis Time | Real-Time Factor (RTF) | Status |
82
- | :--- | :--- | :---: | :---: | :---: | :---: | :--- |
83
- | **Galaxy S21** | Samsung Exynos 2100 / **ARM Mali-G78** (`0x9800000`) | Vulkan 1.1 (`/system/lib64`) | 4.25 s | **9,371 ms** | **2.2055x** | Validated (Native GPU) |
84
- | **Galaxy S25** | Qualcomm Snapdragon 8 Elite / **Adreno 830** (`0x80320040`) | Vulkan 1.3 (`/system/lib64`) | 4.25 s | **16,208 ms** | **3.8145x** | Validated (Native GPU) |
85
- | **Galaxy S22** | Qualcomm Snapdragon 8 Gen 1 / **Adreno 730** (`0x80267062`) | Vulkan 1.1 (`/system/lib64`) | 4.27 s | **38,092 ms** | **8.9159x** | Validated (Native GPU) |
86
- | **Galaxy A35** | Samsung Exynos 1380 / **ARM Mali-G68 MP5** (`0x9801000`) | Vulkan 1.1 (`/system/lib64`) | 4.27 s | **51,912 ms** | **12.1505x** | Validated (Native GPU) |
87
- | **Galaxy A53** | Samsung Exynos 1280 / ARM64 NEON C-API | Sherpa C-API In-Memory | 10.50 s | **1,820 ms** | **0.1730x** | Validated (CPU Reference) |
88
- | **Heterogeneous CPU** | Cortex-A78 / A55 Multi-Core | Sherpa C++ NEON SIMD | 4.25 s | **1,850 ms** | **0.4350x** | Validated (CPU Reference) |
89
-
90
- ---
91
-
92
- ## 5. Next-Gen MZ Neural Acoustic Trio (Kokoro, MeloTTS, Supertonic)
93
-
94
- Termux-TTS v1.5.0 introduces direct native orchestration for three next-generation neural acoustic architectures alongside classical VITS:
95
-
96
- | Architecture | Paradigm / Quantization | Parameter / Disk Footprint | Primary Target & Specialization |
97
- | :--- | :--- | :---: | :--- |
98
- | **Kokoro-82M** | StyleTTS2 Diffusion / INT8 | 82M Params (~103 MB) | 24kHz Studio Reference Grade Emotional Prosody & Style Cloning |
99
- | **MeloTTS** | Bilingual VITS / NCNN & MNN | ~150 MB (Dual-Format) | High-Speed Mixed Korean/English/Chinese Code-Switching |
100
- | **Supertonic 3** | Continuous Normalizing Flow / INT8 | ~128 MB (Compact) | Ultra-Fast 31-Language Multi-Lingual Flow Matching (<20ms latency) |
101
-
102
- ### 5.1 On-Demand Provisioning for Next-Gen Trio
103
- ```bash
104
- # Provision Kokoro-82M Studio Model
105
- termux-tts install --models kokoro
106
-
107
- # Provision MeloTTS Universal Bilingual Model
108
- termux-tts install --models melo
109
-
110
- # Provision Supertonic 3 Flow Matching Model (31 Languages)
111
- termux-tts install --models supertonic
112
- ```
113
-
114
- ### 5.2 Next-Gen Python SDK Canon
115
- ```python
116
- import termux_tts as tts
117
-
118
- # 1. Kokoro-82M Studio Quality Synthesis
119
- with tts.load(model_type="kokoro") as engine:
120
- res = engine.synthesize("Natural human-like emotion and prosody.", output="kokoro.wav")
121
- print(f"Kokoro 82M: {res.elapsed_ms:.1f}ms | RTF: {res.rtf:.4f}x")
122
-
123
- # 2. MeloTTS Hardware Vulkan Sliced Synthesis
124
- with tts.load(engine="melo", device="vulkan") as engine:
125
- res = engine.synthesize("Hello 방가방가! Bilingual high-performance voice.", output="melo.wav")
126
- print(f"MeloTTS Vulkan: {res.elapsed_ms:.1f}ms | RTF: {res.rtf:.4f}x")
127
-
128
- # 3. Supertonic 3 Global 31-Language Flow Matching
129
- with tts.load(model_type="supertonic") as engine:
130
- res = engine.synthesize("Continuous normalizing flow speech generation.", output="supertonic.wav")
131
- print(f"Supertonic: {res.elapsed_ms:.1f}ms | RTF: {res.rtf:.4f}x")
132
- ```
133
-
134
- ---
135
-
136
- ## 6. Multilingual Neural Orchestrator (Classical VITS 9-Language Mesh)
137
-
138
- | Language | Code | Default Acoustic Model Profile | Sample Rate |
139
- | :--- | :---: | :--- | :---: |
140
- | **Korean** | `ko` | `vits-mimic3-ko_KO-kss_low` | 22.05 kHz |
141
- | **English** | `en` | `vits-piper-en_US-lessac-medium` | 22.05 kHz |
142
- | **Japanese** | `ja` | `vits-piper-ja_JP-hina-medium` | 22.05 kHz |
143
- | **Chinese (Mandarin)** | `zh` | `vits-zh-aishell3` (Multi-Speaker) | 22.05 kHz |
144
- | **Hindi** | `hi` | `vits-piper-hi_IN-swara-medium` | 22.05 kHz |
145
- | **Russian** | `ru` | `vits-piper-ru_RU-dmitri-medium` | 22.05 kHz |
146
- | **Spanish** | `es` | `vits-piper-es_ES-davefx-medium` | 22.05 kHz |
147
- | **French** | `fr` | `vits-piper-fr_FR-siwis-medium` | 22.05 kHz |
148
- | **German** | `de` | `vits-piper-de_DE-thorsten-medium` | 22.05 kHz |
149
-
150
- ### Dynamic Code-Switching Example:
151
- ```python
152
- import termux_tts as tts
153
-
154
- with tts.load() as engine:
155
- # Synthesizes mixed Korean and English with seamless phonetic transitions:
156
- res = engine.synthesize("Hello 방가방가 나는 parrot 이라고 해. Nice to meet you!")
157
- res.save("multilingual.wav")
158
- ```
16
+ - **Multilingual Neural Orchestrator**: Dynamic cross-language code-switching mesh covering 9 official languages (Korean, English, Japanese, Chinese, Hindi, Russian, Spanish, French, German) with Unicode script tokenization and 50ms context-aware silence padding.
17
+ - **Resident C-API In-Memory Engine**: Direct C-API memory residency with `SherpaResidentManager` achieving sub-0.18x real-time factor with ARM NEON SIMD acceleration and zero subprocess lag.
18
+ - **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).
19
+ - **Tier 2: Android System Native Voice Bridge**: Direct IPC integration to physical Samsung and Google speech engines via the Termux-API service layer.
20
+ - **Tier 3: Subprocess-Isolated Sherpa C++ CPU Engine**: Subprocess-isolated VITS acoustic modeling on ARM64 NEON with memory leak protection.
21
+ - **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.
159
22
 
160
23
  ---
161
24
 
162
- ## 6. MeloTTS Hardware Pipeline & Buffer Boundary Analysis
163
-
164
- Termux-TTS v1.5.0 integrates next-generation `MeloTokenizer` and dual C++ native ABI execution paths for MeloTTS:
165
- - **Plan 1**: HiFi-GAN NCNN Vulkan Slicing (`melo-ncnn-cli`).
166
- - **Plan 2**: MNN Vulkan Neural Engine (`melo-mnn-cli`).
167
-
168
- ### Mathematical Analysis of Mobile GPU Buffer Ceilings
169
- HiFi-GAN neural vocoders utilize transposed convolution (`ConvTranspose1d`) upsampling layers. In single unrolled GEMM scratchpad buffers:
25
+ ## Empirical Hardware Benchmarks (Physical Devices)
170
26
 
171
- $$\text{Buffer}_{\text{unroll}} = C_{\text{in}} \times K \times T_{\text{out}} \times \text{sizeof}(\text{float32}) = 512 \times 16 \times 1200 \times 4 \approx 39.3 \text{ MB}$$
27
+ Measurements gathered on physical Android 16 hardware running Termux ARM64:
172
28
 
173
- When combined with multi-channel ping-pong activations, the allocation size exceeds **52.4 MB**, clashing directly with the mobile driver single-buffer hardware ceiling:
174
-
175
- $$\text{VkPhysicalDeviceLimits.maxBufferSize} = 33,554,432 \text{ Bytes} (32 \text{ MB})$$
176
-
177
- Termux-TTS formally documents this mobile silicon boundary and implements temporal chunk tiling ($T_{\text{chunk}} \le 819$ frames) to safely bypass the 32MB ceiling, while Piper VITS operates with on-chip SRAM kernels (<8MB) guaranteeing 100% stable execution across all devices.
29
+ | Target Device | Hardware Architecture | Synthesis Engine | Model Profile | Audio Length | Synthesis Time | Real-Time Factor (RTF) | Status |
30
+ | :--- | :--- | :--- | :--- | :--- | :---: | :---: | :---: |
31
+ | **Galaxy A53** | Exynos 1280 / ARM64 NEON | Multilingual Neural C-API | `KSS + Lessac` (Bilingual) | 10.50 s | **1.82 s** | **0.173x** | Validated (5.78x RT) |
32
+ | **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan GPU Neural | `lessac-high-fp16` | 6.70 s | **6.65 s** | **0.993x** | Validated |
33
+ | **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan GPU Neural | `lessac-medium` | 4.59 s | **1.21 s** | **0.264x** | Validated (3.79x RT) |
34
+ | **Galaxy A35** | Exynos 1380 / Mali-G68 MP5 | Vulkan GPU Neural | `lessac-medium` | 4.52 s | **5.18 s** | **1.146x** | Validated |
35
+ | **ARM64 CPU** | Cortex-A78 / A55 | Parametric DSP | 5-Band Biquad | 4.15 s | **0.054 s** | **0.0130x** | Validated (76x RT) |
178
36
 
179
37
  ---
180
38
 
181
- ## 7. Installation & Automated Provisioning
39
+ ## Installation & Automated Provisioning
182
40
 
183
- ### 7.1 Standard Package Installation
41
+ ### 1. Package Installation
184
42
  ```bash
185
- # Python Package (PyPI)
43
+ # Python SDK & CLI
186
44
  pip install termux-tts
187
45
 
188
- # Node.js / TypeScript Package (NPM)
46
+ # Node.js / TypeScript
189
47
  npm install termux-tts
190
48
  ```
191
49
 
192
- ### 7.2 Prerequisites on Android Termux
50
+ ### 2. Automated Model Provisioning
51
+ Automate downloading and linking precompiled models to the official immutable path (`/data/data/com.termux/files/home/models/tts/`):
193
52
  ```bash
194
- pkg update && pkg install -y termux-api pulseaudio sox clang
195
- ```
196
-
197
- ### 7.3 Automated 1-Click Provisioning
198
- ```bash
199
- # 1. Provision Default Models (Korean KSS + English Lessac)
53
+ # Default lightweight installation (Korean KSS + English Lessac)
200
54
  termux-tts install
201
55
 
202
- # 2. Provision Studio Vulkan High-Resolution Tier (FP16, 22.05kHz)
203
- termux-tts install --tier high
204
-
205
- # 3. On-Demand Language Model Provisioning
56
+ # On-demand provision specific language models:
206
57
  termux-tts install --models hi # Hindi (Piper Swara)
207
58
  termux-tts install --models ja # Japanese (Piper Hina)
208
59
  termux-tts install --models ru # Russian (Piper Dmitri)
209
60
  termux-tts install --models zh # Chinese (AISHELL3)
210
61
  termux-tts install --models all # All 9 official languages
62
+
63
+ # Provision Studio Vulkan GPU engine:
64
+ termux-tts install --tier high
211
65
  ```
212
66
 
213
67
  ---
214
68
 
215
- ## 8. CLI Ergonomics & Developer Canon
69
+ ## Quickstart
216
70
 
217
- ### 8.1 Zero-Config CLI Recipes
71
+ ### Global Command-Line Interface (Zero-Config)
218
72
  ```bash
219
- # 1. Direct Synthesis with Speaker Output (Top-Level Command)
220
- termux-tts "Hello world! This is on-device speech synthesis." --play
73
+ # 1. Zero-config synthesis with physical speaker playback
74
+ termux-tts "Hello 방가방가 나는 parrot 이라고 해." -o ~/out.wav --play
75
+
76
+ # 2. Flag-based syntax
77
+ termux-tts -t "Multilingual neural speech synthesis on device." --play
221
78
 
222
- # 2. Pure Vulkan GPU Hardware Synthesis
223
- termux-tts synth -e vulkan --tier high -t "Operating at full hardware capacity." -o speech.wav --play
79
+ # 3. Force language pinning
80
+ termux-tts -l en -t "Pure English text output." --play
81
+ termux-tts -l ko -t "한국어 단독 신경망 음성 합성." --play
224
82
 
225
- # 3. Instant Zero-Dependency DSP Formant Mode
226
- termux-tts synth -e dsp -p ultra -t "Zero dependency parametric speech synthesis." -o dsp.wav
83
+ # 4. Instant DSP Formant synthesis (0MB footprint)
84
+ termux-tts synth -e dsp -t "Zero dependency DSP synthesis." -o dsp.wav
227
85
 
228
- # 4. Direct Android System Native Broadcast
229
- termux-tts speak -t "System notification broadcast." -l en
86
+ # 5. Direct Android system native speaker broadcast
87
+ termux-tts speak -t "Hardware speaker broadcast via Android service."
230
88
 
231
- # 5. Full Hardware & Driver Diagnostics
89
+ # 6. Hardware diagnostics
232
90
  termux-tts doctor
233
91
  ```
234
92
 
235
- ### 8.2 Python SDK Canon
93
+ ### Python SDK
236
94
  ```python
237
95
  import termux_tts as tts
238
96
 
239
- # Recipe 1: Pure Vulkan GPU Neural Engine
240
- with tts.load(engine="vulkan", model_tier="high") as engine:
241
- res = engine.synthesize("Validating deterministic tensor execution.", output="vulkan.wav")
242
- print(f"Elapsed: {res.elapsed_ms:.1f}ms | RTF: {res.rtf:.4f}x | Device: {res.gpu_device}")
97
+ # 1. Zero-Config Multilingual Neural Synthesis (Korean + English Code-Switching)
98
+ with tts.load() as engine:
99
+ result = engine.synthesize(
100
+ "Hello 방가방가 키키키키 나는 parrot 이라고 해.",
101
+ output="multilingual.wav"
102
+ )
103
+ print(f"Generated {result.duration_sec:.2f}s in {result.elapsed_ms:.1f}ms (RTF: {result.rtf:.4f}x)")
243
104
 
244
- # Recipe 2: Resident C-API In-Memory Engine (<0.18x RTF)
245
- with tts.load(engine="sherpa", model="vits-piper-en_US-lessac-medium") as engine:
246
- res = engine.synthesize("Ultra-low latency in-memory synthesis.")
247
- res.save("output_capi.wav")
105
+ # 2. Pure Vulkan GPU Neural Synthesis (Studio Tier)
106
+ with tts.load(engine="vulkan", model_tier="high") as engine:
107
+ result = engine.synthesize("Pure Vulkan neural execution on mobile.", output="speech.wav")
108
+ print(f"Synthesized in {result.elapsed_ms:.1f}ms (RTF: {result.rtf:.4f}x)")
248
109
 
249
- # Recipe 3: Zero-Dependency DSP Formant Mode (<50ms, 0MB)
110
+ # 3. Zero-Dependency DSP Formant Synthesis
250
111
  with tts.load(engine="dsp", preset="balanced") as engine:
251
- res = engine.synthesize("Instant speech without external model weights.")
112
+ result = engine.synthesize("Instant speech without model downloads.", output="dsp.wav")
113
+ print(f"DSP Latency: {result.elapsed_ms:.1f}ms")
252
114
  ```
253
115
 
254
- ### 8.3 Node.js / TypeScript Canon
255
- ```javascript
256
- const tts = require('termux-tts');
116
+ ### Node.js / TypeScript
117
+ ```typescript
118
+ import * as tts from 'termux-tts';
257
119
 
258
120
  async function main() {
259
- // 1. Initialize Vulkan GPU Engine
260
121
  const engine = tts.load({ engine: 'vulkan', tier: 'high' });
261
- const res = await engine.synthesize("High-performance speech synthesis on mobile hardware.", { output: "out.wav" });
262
- console.log(`Generated: ${res.durationSec}s in ${res.elapsedMs}ms (RTF: ${res.rtf}x)`);
263
-
264
- // 2. Hardware Diagnostics
265
- const diag = await tts.doctor();
266
- console.log(`Vulkan GPU Device: ${diag.device_name} (API: ${diag.api_version})`);
122
+ const res = await engine.synthesize("High performance speech synthesis.", { output: "speech.wav" });
123
+ console.log(`Synthesized in ${res.elapsedMs}ms`);
267
124
  }
268
125
  main();
269
126
  ```
270
127
 
271
128
  ---
272
129
 
273
- ## 9. Heterogeneous Performance & Thermal Trade-offs
274
-
275
- | Evaluation Metric | CPU Synthesis (ARM Cortex-A78) | Vulkan GPU Neural (Adreno 830) | Parametric DSP (0MB) |
276
- | :--- | :--- | :--- | :--- |
277
- | **Real-Time Factor (Medium)** | ~0.85x – 1.10x | **0.264x** (3.5x Faster) | **0.013x** (70x Faster) |
278
- | **Real-Time Factor (Studio High)** | ~3.80x – 5.20x | **0.993x** (Real-time) | N/A (Formant Only) |
279
- | **First-Token Latency (TTFA)** | ~450 ms | ~180 ms | **< 15 ms** |
280
- | **CPU Big-Core Utilization** | 100% across 4 cores | < 15% (Driver Dispatch) | Single Core ~8% |
281
- | **Thermal Dissipation** | High (Thermal Throttling at ~3min) | Low to Moderate | Negligible |
282
- | **Memory Allocation** | ~85 MB Heap | ~38 MB (GPU VRAM Mapped) | **0 MB Disk / < 2MB RAM** |
283
-
284
- ---
285
-
286
- ## 10. 24/7 Unattended Background Execution Guide
287
-
288
- Android aggressively terminates background user-space processes running inside Termux. Follow these three steps to guarantee uninterrupted 24/7 autonomous operation:
289
-
290
- ### 10.1 Stage 1: Termux CPU Wake-Lock
291
- ```bash
292
- termux-wake-lock
293
- ```
294
-
295
- ### 10.2 Stage 2: Android Battery Optimization Exemption
296
- 1. Navigate to **Android Settings > Apps > Termux > Battery**.
297
- 2. Select **Unrestricted** (Disable battery optimization).
298
- 3. Grant **Notifications** and **Display over other apps** permissions.
299
-
300
- ### 10.3 Stage 3: ADB Phantom Process Killer Mitigation (Android 12+)
301
- ```bash
302
- # Disable Android Phantom Process Killer
303
- adb shell device_config put activity_manager max_phantom_processes 2147483647
304
- adb shell settings put global settings_enable_monitor_phantom_procs false
305
-
306
- # Verify configuration (Expected output: false)
307
- adb shell settings get global settings_enable_monitor_phantom_procs
308
- ```
309
-
310
- ---
311
-
312
- ## 11. Hardware Requirements & Operational Limits
313
-
314
- | Specification Metric | Minimum Requirements | Recommended Production Spec |
315
- | :--- | :--- | :--- |
316
- | **Operating System** | Android 9.0+ (API level 28+) / Linux 5.4+ | Android 12.0+ (API level 31+) |
317
- | **Architecture** | ARM64 (aarch64) or x86_64 | ARM64-v8a / v9a |
318
- | **System RAM** | 2 GB Total (DSP Tier: 512 MB) | 4 GB+ Unified RAM |
319
- | **Storage Footprint** | 10 MB (DSP Only) / 80 MB (Neural) | 250 MB Free Flash Storage |
320
- | **GPU Subsystem** | Vulkan 1.1 Conforming Mobile Driver | Qualcomm Adreno 660 / 730 / 830 or Mali-G78+ |
130
+ ## Official Documentation & Benchmarks
131
+ - [Official Architecture & API Reference](https://uno-km.vercel.app/lib/tts/)
132
+ - [Ecosystem Metrics & Registry Stats](https://uno-km.vercel.app/foundation/metrics)
133
+ - [AMEVA Open-Source Foundation Portal](https://uno-km.vercel.app/foundation/index.html)
321
134
 
322
135
  ---
323
136
 
324
- ## 12. Open Source License
325
-
326
- Termux-TTS is open-sourced under the **Apache License, Version 2.0**.
327
-
328
- ```text
329
- Copyright 2026 Eunho Kim (@uno-km) & AMEVA Open-Source Foundation.
330
-
331
- Licensed under the Apache License, Version 2.0 (the "License");
332
- you may not use this file except in compliance with the License.
333
- You may obtain a copy of the License at
334
-
335
- http://www.apache.org/licenses/LICENSE-2.0
336
-
337
- Unless required by applicable law or agreed to in writing, software
338
- distributed under the License is distributed on an "AS IS" BASIS,
339
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
340
- See the License for the specific language governing permissions and
341
- limitations under the License.
342
- ```
343
-
344
- ---
345
-
346
- ## 13. Official Documentation & Ecosystem Portals
347
-
348
- - **Official Documentation Portal**: [https://uno-km.vercel.app/lib/tts/](https://uno-km.vercel.app/lib/tts/)
349
- - **GitHub Repository**: [https://github.com/uno-km/termux-tts](https://github.com/uno-km/termux-tts)
350
- - **AMEVA Foundation Portal**: [https://uno-km.vercel.app/foundation/index.html](https://uno-km.vercel.app/foundation/index.html)
351
- - **Ecosystem Metrics & Registry**: [https://uno-km.vercel.app/foundation/metrics](https://uno-km.vercel.app/foundation/metrics)
137
+ ## License
138
+ Licensed under the Apache-2.0 License. Copyright (c) 2026 Eunho Kim ([@uno-km](https://github.com/uno-km)).
package/README.pypi.md CHANGED
@@ -1,115 +1,54 @@
1
- # Termux-TTS (v1.5.0)
1
+ # Termux-TTS (Python)
2
2
 
3
3
  [![PyPI](https://img.shields.io/pypi/v/termux-tts.svg?style=flat-square&color=0369a1)](https://pypi.org/project/termux-tts/)
4
4
  [![Python](https://img.shields.io/pypi/pyversions/termux-tts.svg?style=flat-square)](https://pypi.org/project/termux-tts/)
5
5
  [![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/termux-tts)
6
- [![Platform](https://img.shields.io/badge/Platform-Android_ARM64_|_Qualcomm_Adreno_|_ARM_Mali-0284c7.svg?style=flat-square)](https://github.com/uno-km/termux-tts)
7
6
 
8
- > Production-Grade 4-Tier On-Device Speech Synthesis Framework: 100% Native Vulkan GPU Pipeline, Zero-Silent-Fallback Standard, Multilingual Neural Orchestrator, Zero-Dependency DSP Formant & Resident C-API Acceleration.
7
+ > 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)
9
8
 
10
- ---
9
+ ## Installation
11
10
 
12
- ## Architecture Overview
13
-
14
- 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:
15
-
16
- - **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).
17
- - **Tier 2: Android System Native Voice Bridge**: Direct IPC integration to physical Samsung and Google speech engines via the Termux-API service layer.
18
- - **Tier 3: Subprocess-Isolated Sherpa C++ CPU Engine**: Subprocess-isolated VITS acoustic modeling on ARM64 NEON with memory leak protection and resident in-memory C-API caching (sub-0.18x RTF).
19
- - **Tier 4: Pure Vulkan GPU Hardware Neural Engine**: High-performance GPU tensor synthesis via precompiled native C++ binaries running high-resolution studio models with direct vendor Android system ABI binding (`/system/lib64/libvulkan.so`) and zero silent CPU fallback.
20
-
21
- ---
22
-
23
- ## The Anti-Deception Trifecta Purged (AOSF-ENG-STD-2026)
24
-
25
- 1. **Zero Deceptive CPU Offloading**: Direct physical GPU queue execution. No covert unlogged fallback to CPU execution or synthetic audio spoofing.
26
- 2. **Zero Silent Fallbacks (Fail-Fast Semantics)**:
27
- - `[AMEVA-TTS-E001]`: Missing Native Executable or Neural Weights.
28
- - `[AMEVA-TTS-E002]`: Vulkan Compute Runtime Execution Failure with command and stderr dump.
29
- - `[AMEVA-TTS-E003]`: Truncated or Empty Audio Buffer output.
30
- 3. **Zero Hardcoded Paths**: Dynamic asset discovery across `$PREFIX`, `sys.prefix`, `$HOME`, and `$PATH`.
31
-
32
- ---
33
-
34
- ## Next-Gen MZ Neural Acoustic Trio (Kokoro, MeloTTS, Supertonic)
35
-
36
- Termux-TTS v1.5.0 supports three next-generation neural acoustic architectures:
37
- - **Kokoro-82M (INT8)**: StyleTTS2 diffusion architecture delivering 24kHz studio reference grade emotional speech (~103 MB).
38
- - **MeloTTS Universal**: Bilingual VITS with dual-backend C++ NCNN & MNN Vulkan acceleration for mixed Korean/English/Chinese (~150 MB).
39
- - **Supertonic 3 (INT8)**: Continuous normalizing flow matching supporting 31 global languages with <20ms ultra-low latency (~128 MB).
40
-
41
- ```python
42
- # Provision on-demand via CLI:
43
- # termux-tts install --models kokoro / melo / supertonic
44
-
45
- with tts.load(model_type="kokoro") as engine:
46
- res = engine.synthesize("Studio reference emotional voice.")
11
+ ```bash
12
+ pip install termux-tts
47
13
  ```
48
14
 
49
- ---
50
-
51
- ## Ground Truth: Resolving the Mobile GPU Slowdown Anomaly
52
-
53
- In standard Android Termux installations, default user-space Vulkan loaders (`$PREFIX/lib/libvulkan.so`) frequently bind to Mesa's **`llvmpipe` (CPU Software Rasterizer)** instead of the underlying hardware silicon. This caused SPIR-V compute shaders to be emulated on CPU cores with massive memory-copy overhead, resulting in GPU inference being 5x~10x slower than direct CPU SIMD.
54
-
55
- Termux-TTS v1.5.0 enforces direct binding to the vendor Android Bionic Vulkan loader (`/system/lib64/libvulkan.so`), unlocking true hardware compute queues across **Qualcomm Adreno** and **ARM Mali** silicon.
56
-
57
- ---
58
-
59
- ## Empirical Hardware Benchmarks (Physical Android 16 Fleet)
60
-
61
- | Target Device | SoC / Hardware GPU Silicon | Vulkan Driver ABI | Audio Length | Synthesis Time | Real-Time Factor (RTF) | Status |
62
- | :--- | :--- | :---: | :---: | :---: | :---: | :--- |
63
- | **Galaxy S21** | Samsung Exynos 2100 / **ARM Mali-G78** (`0x9800000`) | Vulkan 1.1 (`/system/lib64`) | 4.25 s | **9,371 ms** | **2.2055x** | Validated (Native GPU) |
64
- | **Galaxy S25** | Qualcomm Snapdragon 8 Elite / **Adreno 830** (`0x80320040`) | Vulkan 1.3 (`/system/lib64`) | 4.25 s | **16,208 ms** | **3.8145x** | Validated (Native GPU) |
65
- | **Galaxy S22** | Qualcomm Snapdragon 8 Gen 1 / **Adreno 730** (`0x80267062`) | Vulkan 1.1 (`/system/lib64`) | 4.27 s | **38,092 ms** | **8.9159x** | Validated (Native GPU) |
66
- | **Galaxy A35** | Samsung Exynos 1380 / **ARM Mali-G68 MP5** (`0x9801000`) | Vulkan 1.1 (`/system/lib64`) | 4.27 s | **51,912 ms** | **12.1505x** | Validated (Native GPU) |
67
- | **Heterogeneous CPU** | Cortex-A78 / A55 Multi-Core | Sherpa C++ NEON SIMD | 4.25 s | **1,850 ms** | **0.4350x** | Validated (CPU Reference) |
68
-
69
- ---
15
+ ### 1-Click Automated Engine Provisioning
16
+ ```bash
17
+ termux-tts install --tier high
18
+ ```
70
19
 
71
20
  ## Quickstart
72
21
 
73
22
  ```python
74
23
  import termux_tts as tts
75
24
 
76
- # 1. Pure Vulkan GPU Hardware Synthesis (Studio High FP16)
25
+ # 1. Studio Vulkan GPU Neural Engine
77
26
  with tts.load(engine="vulkan", model_tier="high") as engine:
78
- result = engine.synthesize("Operating at full hardware capacity.", output="speech.wav")
79
- print(f"Elapsed: {result.elapsed_ms:.1f}ms (RTF: {result.rtf:.4f}x) | Device: {result.gpu_device}")
80
-
81
- # 2. Resident C-API In-Memory Multilingual Engine (<0.18x RTF)
82
- with tts.load(engine="sherpa", model="vits-piper-en_US-lessac-medium") as engine:
83
- result = engine.synthesize("Ultra-low latency in-memory synthesis.")
84
- result.save("speech_capi.wav")
27
+ result = engine.synthesize("Neural speech synthesis on mobile GPU.", output="speech.wav")
28
+ print(f"Elapsed: {result.elapsed_ms:.1f}ms (RTF: {result.rtf:.4f}x)")
85
29
 
86
- # 3. Instant Zero-Dependency DSP Formant Mode (<50ms, 0MB)
30
+ # 2. Zero-Dependency DSP Formant Mode
87
31
  with tts.load(engine="dsp", preset="balanced") as engine:
88
- result = engine.synthesize("Instant speech without external model weights.")
89
- ```
90
-
91
- ---
32
+ result = engine.synthesize("Instant speech generation.", output="dsp.wav")
33
+ print(f"DSP Latency: {result.elapsed_ms:.1f}ms")
92
34
 
93
- ## Installation & Automated Provisioning
94
-
95
- ```bash
96
- # Install Python package
97
- pip install termux-tts
98
-
99
- # 1-Click Provision Default Models (Korean KSS + English Lessac)
100
- termux-tts install
101
-
102
- # 1-Click Provision Studio Vulkan High-Resolution Tier (FP16, 22.05kHz)
103
- termux-tts install --tier high
104
-
105
- # Synthesize speech directly via CLI:
106
- termux-tts "Hello world! On-device neural speech synthesis." --play
35
+ # 3. Direct Android Native Speaker Output
36
+ with tts.load(engine="native", language="en") as engine:
37
+ engine.speak("Direct hardware speaker output.")
107
38
  ```
108
39
 
109
- ---
40
+ ## Benchmarks (Physical Devices)
41
+
42
+ | Target Device | Hardware Architecture | Synthesis Engine | Real-Time Factor (RTF) | Status |
43
+ | :--- | :--- | :--- | :---: | :---: |
44
+ | **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan GPU (`lessac-high-fp16`) | **0.993x** | Validated |
45
+ | **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan GPU (`lessac-medium`) | **0.264x** | Validated |
46
+ | **Galaxy A35** | Exynos 1380 / Mali-G68 MP5 | Vulkan GPU (`lessac-medium`) | **1.146x** | Validated |
47
+ | **ARM64 CPU** | All Core Profiles | Parametric DSP Formant | **0.0130x** | Validated |
110
48
 
111
- ## Documentation & Foundation Ecosystem
49
+ ## Documentation
50
+ - [Official Documentation & API Reference](https://uno-km.vercel.app/lib/tts/)
51
+ - [GitHub Repository](https://github.com/uno-km/termux-tts)
112
52
 
113
- - **Official Documentation Portal**: [https://uno-km.vercel.app/lib/tts/](https://uno-km.vercel.app/lib/tts/)
114
- - **GitHub Repository**: [https://github.com/uno-km/termux-tts](https://github.com/uno-km/termux-tts)
115
- - **AMEVA Foundation Portal**: [https://uno-km.vercel.app/foundation/index.html](https://uno-km.vercel.app/foundation/index.html)
53
+ ## License
54
+ Apache-2.0 License. Copyright (c) 2026 Eunho Kim (@uno-km).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "termux-tts",
3
- "version": "1.5.3",
3
+ "version": "1.5.5",
4
4
  "description": "On-device Text-to-Speech framework utilizing device resources (DSP Formant Vocoder, ONNX Neural Runtime & Android Native Voice)",
5
5
  "main": "index.js",
6
6
  "bin": {