termux-stt 1.2.3 → 1.2.4

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 (4) hide show
  1. package/README.md +448 -447
  2. package/README.pypi.md +448 -447
  3. package/index.d.ts +1 -1
  4. package/package.json +87 -87
package/README.pypi.md CHANGED
@@ -1,447 +1,448 @@
1
- # Termux-STT: Enterprise On-Device Speech-to-Text & Speaker Diarization
2
-
3
- [![PyPI](https://img.shields.io/pypi/v/termux-stt.svg?style=flat-square&color=0369a1)](https://pypi.org/project/termux-stt/)
4
- [![Python](https://img.shields.io/pypi/pyversions/termux-stt.svg?style=flat-square)](https://pypi.org/project/termux-stt/)
5
- [![npm](https://img.shields.io/npm/v/termux-stt.svg?style=flat-square&color=b91c1c)](https://www.npmjs.com/package/termux-stt)
6
- [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/uno-km/termux-stt)
7
- [![Hardware Acceleration](https://img.shields.io/badge/Vulkan-1.1%2B%20Compute-orange?style=flat-square&logo=vulkan)](https://www.vulkan.org/)
8
-
9
- > **Termux-STT** is an industrial-grade, zero-compilation on-device Speech-to-Text (STT) and multi-speaker diarization framework engineered specifically for Android Termux, ARM64 mobile hardware, and edge environments. By orchestrating a Tri-Engine acoustic pipeline (**Whisper.cpp**, **Vosk/Kaldi**, and **Sherpa-ONNX Zipformer**) with pure-Python x-vector speaker clustering and direct Vulkan GPU acceleration, Termux-STT achieves sub-realtime transcription speeds (up to **10x faster than real-time**, RTF **0.102x**) and continuous offline listening with zero cloud telemetry.
10
-
11
- ---
12
-
13
- ## 1. Installation Guide
14
-
15
- Termux-STT is distributed across both Python (PyPI) and Node.js (npm) ecosystems. It runs in unprivileged user-space on Android Termux (ARM64) and Linux aarch64/x86_64.
16
-
17
- ### 1.1 Prerequisites on Android Termux
18
- Update package repositories and install the foundational audio and build utilities:
19
- ```bash
20
- pkg update -y
21
- pkg install -y clang python python-numpy nodejs termux-api ffmpeg pulseaudio
22
- ```
23
-
24
- ### 1.2 Pure Package Installation (Zero-Compilation Bundled Binary)
25
- Install the core package from PyPI via `pip`:
26
- ```bash
27
- pip install --upgrade pip
28
- pip install termux-stt
29
- ```
30
-
31
- > [!NOTE]
32
- > **Bundled ARM64 Binary Architecture**: The official Python universal wheel (`termux_stt-*.whl`) directly bundles a pre-compiled Android ARM64 (Bionic libc) `whisper-cli` ELF executable inside `termux_stt/bin/whisper-cli`. When installed via `pip`, this binary is automatically unpacked into Python `site-packages`. Pure 16kHz WAV transcription is functional immediately without requiring any local C/C++ compiler toolchain.
33
-
34
- To install with development extras:
35
- ```bash
36
- pip install "termux-stt[dev]"
37
- ```
38
-
39
- ### 1.3 Node.js / TypeScript SDK & CLI Installation
40
- Install globally or locally via `npm`:
41
- ```bash
42
- # Global CLI installation (bridges to underlying Python runtime)
43
- npm install -g termux-stt
44
-
45
- # Project dependency installation
46
- npm install termux-stt
47
- ```
48
-
49
- ### 1.4 Post-Installation Automated Environment Provisioner (`termux-stt install`)
50
- While pure package installation provides instant offline WAV inference, production deployments involving compressed media (MP3/M4A/FLAC), live microphone streaming, or mobile GPU acceleration require full environment provisioning. Run the automated 1-click provisioner:
51
-
52
- ```bash
53
- termux-stt-install
54
- # Or equivalently:
55
- termux-stt install
56
- ```
57
-
58
- The automated engine installer (`EngineInstaller`) executes a 3-stage provisioning pipeline:
59
- 1. **Native System Dependencies (`install_system_dependencies`)**:
60
- Automatically invokes Termux `pkg` to install `ffmpeg`, `libbluray`, `libxml2`, `git`, `termux-api`, and `curl`, enabling universal audio decoding and microphone capture via Android APIs.
61
- 2. **Adaptive Engine Binary Provisioning (`install_whisper_cpp`)**:
62
- - **Vulkan GPU Silicon Detected**: Inspects `/system/lib64/libvulkan.so` and `Doctor().quick_probe()`. If mobile GPU compute is available, provisions `cmake`, `make`, `clang`, clones `whisper.cpp`, and compiles a device-tailored native binary with `-DGGML_VULKAN=ON` and `-DVulkan_LIBRARY=/system/lib64/libvulkan.so`, installing it to `$PREFIX/bin/whisper-cli` and `$HOME/.local/bin/whisper-cli` with top execution priority.
63
- - **CPU-Only Fallback**: If Vulkan is absent, downloads the pre-built optimized ARM64 NEON static binary directly from GitHub Releases to `$HOME/.local/bin/whisper-cli`.
64
- 3. **Sub-Engine Ecosystem Provisioning (`install_vosk`, `install_sherpa_onnx`)**:
65
- Provisions `vosk` for sub-30ms real-time streaming and `sherpa-onnx` for next-generation ONNX Zipformer models, while pre-initializing model cache structures in `~/.cache/termux-stt/models/`.
66
-
67
- ### 1.5 Pure Install vs. Post-Install Comparison Matrix
68
-
69
- | Feature / Capability | Pure Install (`pip install termux-stt`) | Post-Install (`termux-stt install`) |
70
- | :--- | :--- | :--- |
71
- | **Native Binary State** | Bundled CPU-NEON static binary (`site-packages/termux_stt/bin/`) | Dynamic: Local Vulkan GPU compilation or updated ARM64 release |
72
- | **GPU Acceleration** | Hardware binding attempted via ameva-runtime | Fully compiled with native SPIR-V Vulkan shaders (`-DGGML_VULKAN=ON`) |
73
- | **Supported Audio Formats** | Uncompressed WAV (16kHz PCM) | Universal: MP3, M4A, AAC, FLAC, OGG, WAV (via system `ffmpeg`) |
74
- | **Live Microphone Stream** | Requires manual `termux-api` installation | Automated `termux-api` package provisioning |
75
- | **Streaming Engine (Vosk)** | Skipped (Whisper-only mode) | Automated `vosk` pip package & model cache configuration |
76
- | **Zipformer (Sherpa-ONNX)** | Skipped | Automated `sherpa-onnx` pip package & model cache configuration |
77
- | **Setup Time** | Instantaneous (~3–5 seconds) | ~1–3 minutes (depending on whether local compilation occurs) |
78
- | **Recommended Use Case** | Quick smoke testing, batch WAV inference | Production services, 24/7 background daemons, mobile GPU offloading |
79
-
80
- ---
81
-
82
- ## 2. GPU Hardware Acceleration Provisioning (`ameva-runtime`)
83
-
84
- To unlock mobile GPU tensor compute via Vulkan SPIR-V compute pipelines on Qualcomm Adreno or ARM Mali silicon, pair `termux-stt` with the unified `@ameva/runtime` hardware acceleration layer.
85
-
86
- ### 2.1 Unified Installation Command
87
- Install both the STT engine and the hardware acceleration runtime simultaneously:
88
-
89
- ```bash
90
- # Python Environment
91
- pip install termux-stt ameva-runtime
92
-
93
- # Node.js / JavaScript Environment
94
- npm install -g termux-stt @ameva/runtime
95
- ```
96
-
97
- ### 2.2 Hardware Diagnostics & Zero-Silent-Fallback Guarantee
98
- Verify Vulkan driver detection and SIMD feature availability:
99
- ```bash
100
- termux-stt doctor
101
- ```
102
-
103
- Termux-STT strictly enforces a **Zero-Silent-Fallback Protocol**:
104
- - When `--device vulkan` or `--device gpu` is requested and `ameva-runtime` is not installed, the engine immediately halts with `[ERROR: AMEVA-STT-E001]` rather than silently degrading to CPU execution.
105
- - If no compatible Vulkan driver (`/system/lib64/libvulkan.so`) is found, the engine halts with `[ERROR: AMEVA-STT-E002]`, preventing unexpected battery drain and thermal throttling.
106
-
107
- ---
108
-
109
- ## 3. Basic Usage Guide
110
-
111
- Termux-STT provides intuitive interfaces across CLI, Python, and Node.js.
112
-
113
- ### 3.1 Command-Line Interface (CLI)
114
-
115
- ```bash
116
- # 1. Transcribe Audio File with Whisper (WAV, MP3, M4A, FLAC)
117
- termux-stt transcribe meeting.wav -e whisper -m base -l en
118
-
119
- # 2. Transcribe and Export to Timestamped Subtitles (SRT / VTT / JSON)
120
- termux-stt transcribe interview.mp3 --format srt -o output.srt
121
-
122
- # 3. Multi-Speaker Diarization (Who Spoke When)
123
- termux-stt diarize discussion.wav --speakers 2 --format rttm -o speakers.rttm
124
-
125
- # 4. Live Microphone Real-Time Listening (Termux-API)
126
- termux-stt listen -e vosk -m small-ko
127
-
128
- # 5. Run Built-in Benchmark with Verification Sample
129
- termux-stt demo
130
- ```
131
-
132
- ### 3.2 Python SDK
133
- ```python
134
- import termux_stt
135
-
136
- # 1. Initialize High-Accuracy Whisper Engine with Auto Hardware Routing
137
- engine = termux_stt.create_engine("whisper", model="base", device="auto")
138
-
139
- # 2. Transcribe Audio File
140
- result = engine.transcribe("meeting.wav")
141
- print(f"Full Text: {result.text}")
142
- for segment in result.segments:
143
- print(f"[{segment.start_sec:.2f}s -> {segment.end_sec:.2f}s] {segment.text}")
144
-
145
- # 3. Instant Streaming with Vosk Engine (<30ms Latency)
146
- vosk_engine = termux_stt.create_engine("vosk", model="small-ko")
147
- vosk_result = vosk_engine.transcribe("quick_voice.wav")
148
- print(f"Vosk Output: {vosk_result.text}")
149
- ```
150
-
151
- ### 3.3 Node.js / TypeScript SDK
152
- ```typescript
153
- import { createEngine } from 'termux-stt';
154
-
155
- async function main() {
156
- const engine = createEngine('whisper', {
157
- model: 'base',
158
- device: 'auto'
159
- });
160
-
161
- const result = await engine.transcribe('sample.wav');
162
- console.log('Transcription:', result.text);
163
- console.log(`Elapsed Time: ${result.elapsedMs}ms | RTF: ${result.rtf}x`);
164
- }
165
-
166
- main().catch(console.error);
167
- ```
168
-
169
- ---
170
-
171
- ## 4. Advanced Usage & Architecture
172
-
173
- Termux-STT features a versatile Tri-Engine architecture designed to adapt dynamically between studio precision and low-latency continuous listening.
174
-
175
- ```mermaid
176
- flowchart TD
177
- AudioInput["Audio Input (Microphone / WAV / MP3)"] --> Preproc["Audio Preprocessor (16kHz Mono PCM)"]
178
- Preproc --> VAD["EnergyVAD / Voice Activity Detector"]
179
-
180
- VAD --> Router{"Engine Dispatcher"}
181
- Router -->|"High Accuracy (GGML Quantized)"| Whisper["WhisperEngine (whisper.cpp Subprocess)"]
182
- Router -->|"Continuous Streaming (<30ms)"| Vosk["VoskEngine (Kaldi CFFI)"]
183
- Router -->|"Zipformer Next-Gen ONNX"| Sherpa["SherpaEngine (sherpa-onnx)"]
184
-
185
- Whisper & Vosk --> Hybrid["HybridEngine (Speaker Diarization)"]
186
- Hybrid --> XVec["Vosk 128-d X-Vector Extraction"]
187
- XVec --> KMeans["Pure-Python K-Means Clustering"]
188
-
189
- KMeans --> Export["Export Layer (JSON, SRT, VTT, RTTM)"]
190
- ```
191
-
192
- ### 4.1 Subprocess Process Isolation & Mobile Crash Protection
193
- Android Termux environments are prone to out-of-memory kernel kills (OOM) and SIGSEGV segmentation faults during heavy native C++ tensor inference. Termux-STT wraps `whisper.cpp` and `sherpa-onnx` in isolated process pools (`ProcessPool`), intercepting crashes gracefully without aborting the host Python application.
194
-
195
- ### 4.2 Multi-Speaker Diarization Pipeline (No Scikit-Learn Needed)
196
- Traditional speaker diarization requires heavy machine learning frameworks (`scikit-learn`, `torchaudio`). Termux-STT integrates an ultra-lightweight **HybridEngine**:
197
- 1. Extracts 128-dimensional acoustic x-vector embeddings using Vosk.
198
- 2. Evaluates spatial clustering via an in-house pure-Python K-Means implementation with zero external dependencies.
199
- 3. Time-aligns speaker identities with Whisper transcript segments.
200
-
201
- ```python
202
- import termux_stt
203
-
204
- engine = termux_stt.create_engine("hybrid", whisper_model="base", num_speakers=2)
205
- result = engine.transcribe("board_meeting.wav", diarize=True)
206
-
207
- for seg in result.segments:
208
- print(f"[{seg.speaker_id}] {seg.start_sec:.1f}s - {seg.end_sec:.1f}s: {seg.text}")
209
- ```
210
-
211
- ### 4.3 Real-Time Live Microphone Streaming with VAD
212
- Capture live audio directly from Android hardware microphones via Termux-API:
213
- ```python
214
- import termux_stt
215
-
216
- def on_partial_speech(text):
217
- print(f"Live Stream: {text}", end="\r", flush=True)
218
-
219
- engine = termux_stt.create_engine("vosk", model="small-ko")
220
- # Listen continuously with Voice Activity Detection
221
- engine.listen(callback=on_partial_speech, sample_rate=16000)
222
- ```
223
-
224
- ---
225
-
226
- ## 5. Feature & Parameter Matrix
227
-
228
- ### 5.1 CLI Subcommands Overview
229
-
230
- | Subcommand | Description | Example |
231
- | :--- | :--- | :--- |
232
- | `transcribe` | Transcribes audio file with chosen engine and model. | `termux-stt transcribe speech.wav -e whisper -m base` |
233
- | `listen` | Captures live microphone audio and streams transcriptions. | `termux-stt listen -e vosk -m small-ko` |
234
- | `diarize` | Identifies distinct speakers and outputs timestamped RTTM. | `termux-stt diarize meeting.wav --speakers 3` |
235
- | `demo` | Runs end-to-end self-test on bundled JFK sample audio. | `termux-stt demo` |
236
- | `doctor` | Diagnoses hardware SIMD, Vulkan GPU, and audio drivers. | `termux-stt doctor` |
237
- | `benchmark` | Profiles Real-Time Factor (RTF) and memory allocation. | `termux-stt benchmark speech.wav` |
238
- | `models` | Lists, downloads, and inspects cached offline weights. | `termux-stt models list` |
239
-
240
- ### 5.2 Transcription Parameters Matrix
241
-
242
- | Parameter Flag | Type | Default | Description |
243
- | :--- | :--- | :--- | :--- |
244
- | `-e`, `--engine` | `enum` | `whisper` | Acoustic engine: `whisper`, `vosk`, `sherpa`, `hybrid`. |
245
- | `-m`, `--model` | `string` | `base` | Model profile: `tiny`, `base`, `small`, `medium`, `small-ko`. |
246
- | `-l`, `--lang` | `string` | `auto` | Target language locale code (`en`, `ko`, `ja`, `zh`, `auto`). |
247
- | `-d`, `--device` | `enum` | `auto` | Execution backend: `auto`, `vulkan`, `gpu`, `cpu`. |
248
- | `-t`, `--threads` | `int` | *(Optimal)* | Big-core worker thread allocation. |
249
- | `--format` | `enum` | `text` | Export formatting: `text`, `json`, `srt`, `vtt`, `rttm`. |
250
- | `--diarize` | `flag` | `False` | Enables speaker identity recognition and segment alignment. |
251
- | `--speakers` | `int` | `2` | Expected speaker cluster count for diarization. |
252
- | `-o`, `--output` | `path` | `stdout` | Destination file path for generated transcript. |
253
-
254
- ---
255
-
256
- ## 6. Production Code Examples & Diagnostics
257
-
258
- ### 6.1 Multi-Agent Voice Pipeline (`termux-stt` + `termux-llamacpp` + `termux-tts`)
259
- Construct a 100% on-device autonomous voice conversational loop:
260
-
261
- ```python
262
- import termux_stt
263
- import termux_llamacpp as llama
264
- import termux_tts as tts
265
-
266
- def run_conversational_cycle(user_audio="input.wav"):
267
- # 1. Listen & Transcribe User Voice via Termux-STT
268
- stt = termux_stt.create_engine("whisper", model="base")
269
- user_text = stt.transcribe(user_audio).text
270
- print(f"Heard: {user_text}")
271
-
272
- # 2. Reason & Answer via Termux-LlamaCpp
273
- llm = llama.LlamaRuntime(llama.RuntimeConfig(model_path="qwen2.5-1.5b-instruct"))
274
- ai_response = llm.generate(prompt=user_text, max_tokens=100)
275
- print(f"Thought: {ai_response}")
276
-
277
- # 3. Speak Out Loud via Termux-TTS
278
- with tts.load(engine="vulkan", tier="medium") as voice:
279
- voice.synthesize(ai_response, output="response.wav")
280
- print("[SUCCESS] Full on-device voice loop completed.")
281
-
282
- if __name__ == "__main__":
283
- run_conversational_cycle()
284
- ```
285
-
286
- ### 6.2 Hardware Diagnostics & Environment Audit
287
- ```python
288
- from termux_stt.cli.doctor import run_diagnostics
289
-
290
- report = run_diagnostics()
291
- print(f"Vulkan GPU Available: {report.get('vulkan_available')}")
292
- print(f"Optimal Threads: {report.get('optimal_threads')}")
293
- print(f"Installed Engines: {report.get('available_engines')}")
294
- ```
295
-
296
- ---
297
-
298
- ## 7. Real-World Outputs & Empirical Hardware Benchmarks
299
-
300
- ### 7.1 Empirical Mobile Hardware Benchmarks
301
- Benchmarks conducted on physical mobile hardware using JFK's 60.00s 16kHz Mono Inaugural Address (`samples/jfk_1min.wav`):
302
-
303
- | Target Device | Processor Architecture | Engine & Model | Audio Duration | Transcribe Latency | Real-Time Factor (RTF) | Peak RAM | Status |
304
- | :--- | :--- | :--- | :---: | :---: | :---: | :---: | :---: |
305
- | **Galaxy S25** | Snapdragon 8 Elite (Adreno 830) | Whisper Tiny (39M) | 60.0 s | **3.82 s** | **0.0636x (15.7x Faster)** | 24 MB | Validated |
306
- | **Galaxy S25** | Snapdragon 8 Elite (Adreno 830) | Whisper Base (74M) | 60.0 s | **7.14 s** | **0.1190x (8.4x Faster)** | 26 MB | Validated |
307
- | **Galaxy S21** | Snapdragon 865 (Adreno 650) | Whisper Tiny (39M) | 60.0 s | **6.13 s** | **0.1021x (10x Faster)** | 25 MB | Validated |
308
- | **Galaxy S21** | Snapdragon 865 (Adreno 650) | Whisper Base (74M) | 60.0 s | **12.46 s** | **0.2077x (5x Faster)** | 25 MB | Validated |
309
- | **Galaxy S21** | Snapdragon 865 (Adreno 650) | Whisper Small (244M)| 60.0 s | **26.63 s** | **0.4439x (2.3x Faster)** | 28 MB | Validated |
310
- | **Galaxy A35** | Exynos 1380 (Mali-G68 MP5) | Whisper Tiny (39M) | 60.0 s | **22.36 s** | **0.3726x (2.7x Faster)** | 6 MB | Validated |
311
- | **Galaxy A35** | Exynos 1380 (Mali-G68 MP5) | Vosk Small Korean | 60.0 s | **2.71 s** | **0.0452x (22x Faster)** | 45 MB | Validated |
312
-
313
- > **Real-Time Factor (RTF) Definition**: $\text{RTF} = \frac{\text{Processing Latency (Seconds)}}{\text{Audio Duration (Seconds)}}$.
314
- > An RTF of `0.10x` means 60 seconds of recorded voice is transcribed into text in only 6 seconds.
315
-
316
- ### 7.2 Verified Transcription Output Sample
317
- ```text
318
- $ termux-stt transcribe samples/jfk_1min.wav -e whisper -m base --format srt
319
- 1
320
- 00:00:00,000 --> 00:00:09,000
321
- And so my fellow Americans, ask not what your country can do for you.
322
-
323
- 2
324
- 00:00:09,000 --> 00:00:15,000
325
- Ask what you can do for your country.
326
-
327
- [SUCCESS] Transcribed 60.00s audio in 12.46s (RTF: 0.2077x) -> stdout
328
- ```
329
-
330
- ---
331
-
332
- ## 8. GPU Interconnect Architecture & Compatibility
333
-
334
- ### 8.1 Vulkan Compute Acceleration Pipeline
335
- Termux-STT interfaces directly with Android's Bionic Vulkan loader (`/system/lib64/libvulkan.so`). Tensor mel-spectrogram transformations and encoder attention blocks are offloaded to mobile GPU SPIR-V compute shaders via `whisper.cpp` Vulkan backend bindings.
336
-
337
- ### 8.2 Silicon Compatibility Matrix
338
- - **Qualcomm Snapdragon (Adreno 6xx, 7xx, 8xx)**:
339
- - **Tier-1 Full Support**. Native FP16 compute instructions and high dispatch concurrency deliver RTF performance as fast as **0.063x** on Snapdragon 8 Elite.
340
- - **Samsung Exynos / MediaTek Dimensity (ARM Mali / Immortalis)**:
341
- - **Supported**. Mali tile-based architectures benefit from `-ngl` layer tuning. Whisper Tiny and Base models operate smoothly without shader compilation stalls.
342
- - **Strict Zero-Silent-Fallback**:
343
- - Requesting `--device vulkan` without valid Vulkan drivers immediately triggers `PlatformNotSupportedError`, preventing silent fallback to unoptimized CPU execution.
344
-
345
- ---
346
-
347
- ## 8-1. CPU vs. GPU Performance & Thermal Trade-offs
348
-
349
- | Evaluation Metric | CPU Inference (ARM Cortex-A78) | Vulkan GPU Inference (Adreno 830) | Benefit of GPU Offloading |
350
- | :--- | :--- | :--- | :--- |
351
- | **Real-Time Factor (Tiny)** | ~0.28x | **0.063x** | **4.4x Speedup** |
352
- | **Real-Time Factor (Base)** | ~0.55x | **0.119x** | **4.6x Speedup** |
353
- | **CPU Core Temperature** | High (Thermal Throttling at ~5min) | Low to Moderate | Prevents thermal CPU clock reduction |
354
- | **Battery Power Draw** | ~3.8 W Peak | ~1.9 W Peak | **~50% Lower Energy Footprint** |
355
- | **Interactive Latency** | Noticeable system stutter | Smooth background execution | Audio UI responsiveness preserved |
356
-
357
- Offloading audio encoder matrix multiplications to the Vulkan GPU keeps ARM CPU cores available for real-time audio capture, VAD buffering, and downstream LLM inference.
358
-
359
- ---
360
-
361
- ## 9. Hardware Requirements & Operational Limits
362
-
363
- ### 9.1 Hardware Specifications
364
-
365
- | Specification Metric | Minimum Requirements | Recommended Production Spec |
366
- | :--- | :--- | :--- |
367
- | **Operating System** | Android 9.0+ (API level 28+) / Linux 5.4+ | Android 12.0+ (API level 31+) |
368
- | **Architecture** | ARM64 (aarch64) or x86_64 | ARM64-v8a / v9a |
369
- | **System RAM** | 2 GB Total Unified RAM | 4 GB+ Unified RAM |
370
- | **Storage Footprint** | 150 MB (Vosk) / 300 MB (Whisper Base) | 1 GB Free Flash Storage |
371
- | **Audio Subsystem** | Termux-API Microphone Permissions | 16kHz PCM Audio Capture Support |
372
-
373
- ### 9.2 Operational Limits & Best Practices
374
- - **32-Bit ARM (armeabi-v7a)**: Not supported for Whisper GPU neural inference. Use Vosk CFFI for legacy 32-bit hardware.
375
- - **Microphone Permissions**: Real-time microphone listening (`termux-stt listen`) requires Android microphone permission granted to Termux: `termux-microphone-record`.
376
-
377
- ---
378
-
379
- ## 10. 24/7 Unattended Background Execution Guide
380
-
381
- Android aggressively kills background user-space processes inside Termux unless battery and process monitor policies are explicitly configured. Follow these three stages to ensure uninterrupted continuous speech recognition:
382
-
383
- ### 10.1 Stage 1: Termux Kernel Wake-Lock
384
- Prevent the mobile CPU from entering low-power sleep states:
385
- ```bash
386
- # Acquire persistent CPU wake-lock
387
- termux-wake-lock
388
- ```
389
-
390
- ### 10.2 Stage 2: Android GUI Battery Optimization Exemption
391
- 1. Open **Android Settings > Apps > Termux > Battery**.
392
- 2. Set battery policy to **Unrestricted** (Disable power-saving restrictions).
393
- 3. Under **Permissions**, grant **Microphone** and **Display over other apps**.
394
-
395
- ### 10.3 Stage 3: ADB Phantom Process Killer Exemption (Android 12+)
396
- Android 12+ terminates background processes exceeding child process thresholds. Execute these commands via ADB:
397
-
398
- ```bash
399
- # Disable Android Phantom Process Killer
400
- adb shell device_config put activity_manager max_phantom_processes 2147483647
401
- adb shell settings put global settings_enable_monitor_phantom_procs false
402
-
403
- # Verify configuration
404
- adb shell settings get global settings_enable_monitor_phantom_procs
405
- # Expected output: false
406
- ```
407
-
408
- ---
409
-
410
- ## 11. Open Source License
411
-
412
- Termux-STT is open-sourced under the **MIT License**.
413
-
414
- ```text
415
- Copyright (c) 2026 Eunho Kim (@uno-km) & AMEVA Open-Source Foundation.
416
-
417
- Permission is hereby granted, free of charge, to any person obtaining a copy
418
- of this software and associated documentation files (the "Software"), to deal
419
- in the Software without restriction, including without limitation the rights
420
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
421
- copies of the Software, and to permit persons to whom the Software is
422
- furnished to do so, subject to the following conditions:
423
-
424
- The above copyright notice and this permission notice shall be included in all
425
- copies or substantial portions of the Software.
426
-
427
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
428
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
429
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
430
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
431
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
432
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
433
- SOFTWARE.
434
- ```
435
-
436
- ---
437
-
438
- ## 12. SEO Technical Keywords & Ecosystem Metadata
439
-
440
- `termux`, `stt`, `speech-to-text`, `whisper`, `whisper-cpp`, `vosk`, `sherpa-onnx`, `diarization`, `speaker-diarization`, `voice-recognition`, `audio-transcription`, `on-device-ai`, `edge-ai`, `mobile-ai`, `vulkan`, `vulkan-compute`, `gpu-acceleration`, `real-time-factor`, `low-latency`, `arm64`, `android`, `snapdragon`, `adreno`, `exynos`, `arm-mali`, `zero-compilation`, `vad`, `voice-activity-detection`, `silero-vad`, `x-vector`, `k-means`, `clustering`, `srt-export`, `vtt-export`, `rttm`, `microphone-streaming`, `headless-audio`, `pulseaudio`, `offline-speech`, `privacy-first`, `termux-aichain`, `termux-tts`, `termux-llamacpp`, `termux-diffusion`, `ameva-runtime`, `ggml`, `quantization`, `bionic-libc`, `autonomous-agents`, `voice-assistant`
441
-
442
- ---
443
-
444
- ## Official Documentation & Foundation Ecosystem
445
- - **Official Documentation Portal**: [https://uno-km.github.io/termux-stt/](https://uno-km.github.io/termux-stt/)
446
- - **GitHub Repository**: [https://github.com/uno-km/termux-stt](https://github.com/uno-km/termux-stt)
447
- - **AMEVA Foundation Portal**: [https://uno-km.vercel.app/foundation/index.html](https://uno-km.vercel.app/foundation/index.html)
1
+ # Termux-STT: Enterprise On-Device Speech-to-Text & Speaker Diarization
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/termux-stt.svg?style=flat-square&color=0369a1)](https://pypi.org/project/termux-stt/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/termux-stt.svg?style=flat-square)](https://pypi.org/project/termux-stt/)
5
+ [![npm](https://img.shields.io/npm/v/termux-stt.svg?style=flat-square&color=b91c1c)](https://www.npmjs.com/package/termux-stt)
6
+ [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/uno-km/termux-stt)
7
+ [![Hardware Acceleration](https://img.shields.io/badge/Vulkan-1.1%2B%20Compute-orange?style=flat-square&logo=vulkan)](https://www.vulkan.org/)
8
+
9
+ > **Termux-STT** is an industrial-grade, zero-compilation on-device Speech-to-Text (STT) and multi-speaker diarization framework engineered specifically for Android Termux, ARM64 mobile hardware, and edge environments. By orchestrating a Tri-Engine acoustic pipeline (**Whisper.cpp**, **Vosk/Kaldi**, and **Sherpa-ONNX Zipformer**) with pure-Python x-vector speaker clustering and direct Vulkan GPU acceleration, Termux-STT achieves sub-realtime transcription speeds (up to **10x faster than real-time**, RTF **0.102x**) and continuous offline listening with zero cloud telemetry.
10
+
11
+ ---
12
+
13
+ ## 1. Installation Guide
14
+
15
+ Termux-STT is distributed across both Python (PyPI) and Node.js (npm) ecosystems. It runs in unprivileged user-space on Android Termux (ARM64) and Linux aarch64/x86_64.
16
+
17
+ ### 1.1 Prerequisites on Android Termux
18
+ Update package repositories and install the foundational audio and build utilities:
19
+ ```bash
20
+ pkg update -y
21
+ pkg install -y clang python python-numpy nodejs termux-api ffmpeg pulseaudio
22
+ ```
23
+
24
+ ### 1.2 Pure Package Installation (Zero-Compilation Bundled Binary)
25
+ Install the core package from PyPI via `pip`:
26
+ ```bash
27
+ pip install --upgrade pip
28
+ pip install termux-stt
29
+ ```
30
+
31
+ > [!NOTE]
32
+ > **Bundled ARM64 Binary Architecture**: The official Python universal wheel (`termux_stt-*.whl`) directly bundles a pre-compiled Android ARM64 (Bionic libc) `whisper-cli` ELF executable inside `termux_stt/bin/whisper-cli`. When installed via `pip`, this binary is automatically unpacked into Python `site-packages`. Pure 16kHz WAV transcription is functional immediately without requiring any local C/C++ compiler toolchain.
33
+
34
+ To install with development extras:
35
+ ```bash
36
+ pip install "termux-stt[dev]"
37
+ ```
38
+
39
+ ### 1.3 Node.js / TypeScript SDK & CLI Installation
40
+ Install globally or locally via `npm`:
41
+ ```bash
42
+ # Global CLI installation (bridges to underlying Python runtime)
43
+ npm install -g termux-stt
44
+
45
+ # Project dependency installation
46
+ npm install termux-stt
47
+ ```
48
+
49
+ ### 1.4 Post-Installation Automated Environment Provisioner (`termux-stt install`)
50
+ While pure package installation provides instant offline WAV inference, production deployments involving compressed media (MP3/M4A/FLAC), live microphone streaming, or mobile GPU acceleration require full environment provisioning. Run the automated 1-click provisioner:
51
+
52
+ ```bash
53
+ termux-stt-install
54
+ # Or equivalently:
55
+ termux-stt install
56
+ ```
57
+
58
+ The automated engine installer (`EngineInstaller`) executes a 3-stage provisioning pipeline:
59
+ 1. **Native System Dependencies (`install_system_dependencies`)**:
60
+ Automatically invokes Termux `pkg` to install `ffmpeg`, `libbluray`, `libxml2`, `git`, `termux-api`, and `curl`, enabling universal audio decoding and microphone capture via Android APIs.
61
+ 2. **Adaptive Engine Binary Provisioning (`install_whisper_cpp`)**:
62
+ - **⚡ Fast-Track Stream Extractor (~3s)**: On Android ARM64 Termux, precompiled Vulkan+NEON Bionic binaries (`whisper-cli-android-arm64.tar.gz`) are automatically extracted from GitHub Releases in ~3 seconds, completely eliminating 20-minute on-device compilation and mobile OOM aborts.
63
+ - **🛡️ Zero-Hardcoding SSOT Endpoints**: Binary downloads dynamically route through unified SSOT candidate endpoints (`TERMUX_STT_RELEASE_TAG` -> `v{__version__}` -> `releases/latest/download` -> `uno-km/ameva-runtime` releases fallback) with automated fallback to on-device C++ compilation (`cmake` + `clang`) in offline or air-gapped environments.
64
+ - **📦 Bundled Package Binary Fallback**: Automatically discovers and links bundled `termux_stt/bin/whisper-cli` if present.
65
+ 3. **Sub-Engine Ecosystem Provisioning (`install_vosk`, `install_sherpa_onnx`)**:
66
+ Provisions `vosk` for sub-30ms real-time streaming and `sherpa-onnx` for next-generation ONNX Zipformer models, while pre-initializing model cache structures in `~/.cache/termux-stt/models/`.
67
+
68
+ ### 1.5 Pure Install vs. Post-Install Comparison Matrix
69
+
70
+ | Feature / Capability | Pure Install (`pip install termux-stt`) | Post-Install (`termux-stt install`) |
71
+ | :--- | :--- | :--- |
72
+ | **Native Binary State** | Bundled CPU-NEON static binary (`site-packages/termux_stt/bin/`) | Dynamic: Local Vulkan GPU compilation or updated ARM64 release |
73
+ | **GPU Acceleration** | Hardware binding attempted via ameva-runtime | Fully compiled with native SPIR-V Vulkan shaders (`-DGGML_VULKAN=ON`) |
74
+ | **Supported Audio Formats** | Uncompressed WAV (16kHz PCM) | Universal: MP3, M4A, AAC, FLAC, OGG, WAV (via system `ffmpeg`) |
75
+ | **Live Microphone Stream** | Requires manual `termux-api` installation | Automated `termux-api` package provisioning |
76
+ | **Streaming Engine (Vosk)** | Skipped (Whisper-only mode) | Automated `vosk` pip package & model cache configuration |
77
+ | **Zipformer (Sherpa-ONNX)** | Skipped | Automated `sherpa-onnx` pip package & model cache configuration |
78
+ | **Setup Time** | Instantaneous (~3–5 seconds) | ~1–3 minutes (depending on whether local compilation occurs) |
79
+ | **Recommended Use Case** | Quick smoke testing, batch WAV inference | Production services, 24/7 background daemons, mobile GPU offloading |
80
+
81
+ ---
82
+
83
+ ## 2. GPU Hardware Acceleration Provisioning (`ameva-runtime`)
84
+
85
+ To unlock mobile GPU tensor compute via Vulkan SPIR-V compute pipelines on Qualcomm Adreno or ARM Mali silicon, pair `termux-stt` with the unified `@ameva/runtime` hardware acceleration layer.
86
+
87
+ ### 2.1 Unified Installation Command
88
+ Install both the STT engine and the hardware acceleration runtime simultaneously:
89
+
90
+ ```bash
91
+ # Python Environment
92
+ pip install termux-stt ameva-runtime
93
+
94
+ # Node.js / JavaScript Environment
95
+ npm install -g termux-stt @ameva/runtime
96
+ ```
97
+
98
+ ### 2.2 Hardware Diagnostics & Zero-Silent-Fallback Guarantee
99
+ Verify Vulkan driver detection and SIMD feature availability:
100
+ ```bash
101
+ termux-stt doctor
102
+ ```
103
+
104
+ Termux-STT strictly enforces a **Zero-Silent-Fallback Protocol**:
105
+ - When `--device vulkan` or `--device gpu` is requested and `ameva-runtime` is not installed, the engine immediately halts with `[ERROR: AMEVA-STT-E001]` rather than silently degrading to CPU execution.
106
+ - If no compatible Vulkan driver (`/system/lib64/libvulkan.so`) is found, the engine halts with `[ERROR: AMEVA-STT-E002]`, preventing unexpected battery drain and thermal throttling.
107
+
108
+ ---
109
+
110
+ ## 3. Basic Usage Guide
111
+
112
+ Termux-STT provides intuitive interfaces across CLI, Python, and Node.js.
113
+
114
+ ### 3.1 Command-Line Interface (CLI)
115
+
116
+ ```bash
117
+ # 1. Transcribe Audio File with Whisper (WAV, MP3, M4A, FLAC)
118
+ termux-stt transcribe meeting.wav -e whisper -m base -l en
119
+
120
+ # 2. Transcribe and Export to Timestamped Subtitles (SRT / VTT / JSON)
121
+ termux-stt transcribe interview.mp3 --format srt -o output.srt
122
+
123
+ # 3. Multi-Speaker Diarization (Who Spoke When)
124
+ termux-stt diarize discussion.wav --speakers 2 --format rttm -o speakers.rttm
125
+
126
+ # 4. Live Microphone Real-Time Listening (Termux-API)
127
+ termux-stt listen -e vosk -m small-ko
128
+
129
+ # 5. Run Built-in Benchmark with Verification Sample
130
+ termux-stt demo
131
+ ```
132
+
133
+ ### 3.2 Python SDK
134
+ ```python
135
+ import termux_stt
136
+
137
+ # 1. Initialize High-Accuracy Whisper Engine with Auto Hardware Routing
138
+ engine = termux_stt.create_engine("whisper", model="base", device="auto")
139
+
140
+ # 2. Transcribe Audio File
141
+ result = engine.transcribe("meeting.wav")
142
+ print(f"Full Text: {result.text}")
143
+ for segment in result.segments:
144
+ print(f"[{segment.start_sec:.2f}s -> {segment.end_sec:.2f}s] {segment.text}")
145
+
146
+ # 3. Instant Streaming with Vosk Engine (<30ms Latency)
147
+ vosk_engine = termux_stt.create_engine("vosk", model="small-ko")
148
+ vosk_result = vosk_engine.transcribe("quick_voice.wav")
149
+ print(f"Vosk Output: {vosk_result.text}")
150
+ ```
151
+
152
+ ### 3.3 Node.js / TypeScript SDK
153
+ ```typescript
154
+ import { createEngine } from 'termux-stt';
155
+
156
+ async function main() {
157
+ const engine = createEngine('whisper', {
158
+ model: 'base',
159
+ device: 'auto'
160
+ });
161
+
162
+ const result = await engine.transcribe('sample.wav');
163
+ console.log('Transcription:', result.text);
164
+ console.log(`Elapsed Time: ${result.elapsedMs}ms | RTF: ${result.rtf}x`);
165
+ }
166
+
167
+ main().catch(console.error);
168
+ ```
169
+
170
+ ---
171
+
172
+ ## 4. Advanced Usage & Architecture
173
+
174
+ Termux-STT features a versatile Tri-Engine architecture designed to adapt dynamically between studio precision and low-latency continuous listening.
175
+
176
+ ```mermaid
177
+ flowchart TD
178
+ AudioInput["Audio Input (Microphone / WAV / MP3)"] --> Preproc["Audio Preprocessor (16kHz Mono PCM)"]
179
+ Preproc --> VAD["EnergyVAD / Voice Activity Detector"]
180
+
181
+ VAD --> Router{"Engine Dispatcher"}
182
+ Router -->|"High Accuracy (GGML Quantized)"| Whisper["WhisperEngine (whisper.cpp Subprocess)"]
183
+ Router -->|"Continuous Streaming (<30ms)"| Vosk["VoskEngine (Kaldi CFFI)"]
184
+ Router -->|"Zipformer Next-Gen ONNX"| Sherpa["SherpaEngine (sherpa-onnx)"]
185
+
186
+ Whisper & Vosk --> Hybrid["HybridEngine (Speaker Diarization)"]
187
+ Hybrid --> XVec["Vosk 128-d X-Vector Extraction"]
188
+ XVec --> KMeans["Pure-Python K-Means Clustering"]
189
+
190
+ KMeans --> Export["Export Layer (JSON, SRT, VTT, RTTM)"]
191
+ ```
192
+
193
+ ### 4.1 Subprocess Process Isolation & Mobile Crash Protection
194
+ Android Termux environments are prone to out-of-memory kernel kills (OOM) and SIGSEGV segmentation faults during heavy native C++ tensor inference. Termux-STT wraps `whisper.cpp` and `sherpa-onnx` in isolated process pools (`ProcessPool`), intercepting crashes gracefully without aborting the host Python application.
195
+
196
+ ### 4.2 Multi-Speaker Diarization Pipeline (No Scikit-Learn Needed)
197
+ Traditional speaker diarization requires heavy machine learning frameworks (`scikit-learn`, `torchaudio`). Termux-STT integrates an ultra-lightweight **HybridEngine**:
198
+ 1. Extracts 128-dimensional acoustic x-vector embeddings using Vosk.
199
+ 2. Evaluates spatial clustering via an in-house pure-Python K-Means implementation with zero external dependencies.
200
+ 3. Time-aligns speaker identities with Whisper transcript segments.
201
+
202
+ ```python
203
+ import termux_stt
204
+
205
+ engine = termux_stt.create_engine("hybrid", whisper_model="base", num_speakers=2)
206
+ result = engine.transcribe("board_meeting.wav", diarize=True)
207
+
208
+ for seg in result.segments:
209
+ print(f"[{seg.speaker_id}] {seg.start_sec:.1f}s - {seg.end_sec:.1f}s: {seg.text}")
210
+ ```
211
+
212
+ ### 4.3 Real-Time Live Microphone Streaming with VAD
213
+ Capture live audio directly from Android hardware microphones via Termux-API:
214
+ ```python
215
+ import termux_stt
216
+
217
+ def on_partial_speech(text):
218
+ print(f"Live Stream: {text}", end="\r", flush=True)
219
+
220
+ engine = termux_stt.create_engine("vosk", model="small-ko")
221
+ # Listen continuously with Voice Activity Detection
222
+ engine.listen(callback=on_partial_speech, sample_rate=16000)
223
+ ```
224
+
225
+ ---
226
+
227
+ ## 5. Feature & Parameter Matrix
228
+
229
+ ### 5.1 CLI Subcommands Overview
230
+
231
+ | Subcommand | Description | Example |
232
+ | :--- | :--- | :--- |
233
+ | `transcribe` | Transcribes audio file with chosen engine and model. | `termux-stt transcribe speech.wav -e whisper -m base` |
234
+ | `listen` | Captures live microphone audio and streams transcriptions. | `termux-stt listen -e vosk -m small-ko` |
235
+ | `diarize` | Identifies distinct speakers and outputs timestamped RTTM. | `termux-stt diarize meeting.wav --speakers 3` |
236
+ | `demo` | Runs end-to-end self-test on bundled JFK sample audio. | `termux-stt demo` |
237
+ | `doctor` | Diagnoses hardware SIMD, Vulkan GPU, and audio drivers. | `termux-stt doctor` |
238
+ | `benchmark` | Profiles Real-Time Factor (RTF) and memory allocation. | `termux-stt benchmark speech.wav` |
239
+ | `models` | Lists, downloads, and inspects cached offline weights. | `termux-stt models list` |
240
+
241
+ ### 5.2 Transcription Parameters Matrix
242
+
243
+ | Parameter Flag | Type | Default | Description |
244
+ | :--- | :--- | :--- | :--- |
245
+ | `-e`, `--engine` | `enum` | `whisper` | Acoustic engine: `whisper`, `vosk`, `sherpa`, `hybrid`. |
246
+ | `-m`, `--model` | `string` | `base` | Model profile: `tiny`, `base`, `small`, `medium`, `small-ko`. |
247
+ | `-l`, `--lang` | `string` | `auto` | Target language locale code (`en`, `ko`, `ja`, `zh`, `auto`). |
248
+ | `-d`, `--device` | `enum` | `auto` | Execution backend: `auto`, `vulkan`, `gpu`, `cpu`. |
249
+ | `-t`, `--threads` | `int` | *(Optimal)* | Big-core worker thread allocation. |
250
+ | `--format` | `enum` | `text` | Export formatting: `text`, `json`, `srt`, `vtt`, `rttm`. |
251
+ | `--diarize` | `flag` | `False` | Enables speaker identity recognition and segment alignment. |
252
+ | `--speakers` | `int` | `2` | Expected speaker cluster count for diarization. |
253
+ | `-o`, `--output` | `path` | `stdout` | Destination file path for generated transcript. |
254
+
255
+ ---
256
+
257
+ ## 6. Production Code Examples & Diagnostics
258
+
259
+ ### 6.1 Multi-Agent Voice Pipeline (`termux-stt` + `termux-llamacpp` + `termux-tts`)
260
+ Construct a 100% on-device autonomous voice conversational loop:
261
+
262
+ ```python
263
+ import termux_stt
264
+ import termux_llamacpp as llama
265
+ import termux_tts as tts
266
+
267
+ def run_conversational_cycle(user_audio="input.wav"):
268
+ # 1. Listen & Transcribe User Voice via Termux-STT
269
+ stt = termux_stt.create_engine("whisper", model="base")
270
+ user_text = stt.transcribe(user_audio).text
271
+ print(f"Heard: {user_text}")
272
+
273
+ # 2. Reason & Answer via Termux-LlamaCpp
274
+ llm = llama.LlamaRuntime(llama.RuntimeConfig(model_path="qwen2.5-1.5b-instruct"))
275
+ ai_response = llm.generate(prompt=user_text, max_tokens=100)
276
+ print(f"Thought: {ai_response}")
277
+
278
+ # 3. Speak Out Loud via Termux-TTS
279
+ with tts.load(engine="vulkan", tier="medium") as voice:
280
+ voice.synthesize(ai_response, output="response.wav")
281
+ print("[SUCCESS] Full on-device voice loop completed.")
282
+
283
+ if __name__ == "__main__":
284
+ run_conversational_cycle()
285
+ ```
286
+
287
+ ### 6.2 Hardware Diagnostics & Environment Audit
288
+ ```python
289
+ from termux_stt.cli.doctor import run_diagnostics
290
+
291
+ report = run_diagnostics()
292
+ print(f"Vulkan GPU Available: {report.get('vulkan_available')}")
293
+ print(f"Optimal Threads: {report.get('optimal_threads')}")
294
+ print(f"Installed Engines: {report.get('available_engines')}")
295
+ ```
296
+
297
+ ---
298
+
299
+ ## 7. Real-World Outputs & Empirical Hardware Benchmarks
300
+
301
+ ### 7.1 Empirical Mobile Hardware Benchmarks
302
+ Benchmarks conducted on physical mobile hardware using JFK's 60.00s 16kHz Mono Inaugural Address (`samples/jfk_1min.wav`):
303
+
304
+ | Target Device | Processor Architecture | Engine & Model | Audio Duration | Transcribe Latency | Real-Time Factor (RTF) | Peak RAM | Status |
305
+ | :--- | :--- | :--- | :---: | :---: | :---: | :---: | :---: |
306
+ | **Galaxy S25** | Snapdragon 8 Elite (Adreno 830) | Whisper Tiny (39M) | 60.0 s | **3.82 s** | **0.0636x (15.7x Faster)** | 24 MB | Validated |
307
+ | **Galaxy S25** | Snapdragon 8 Elite (Adreno 830) | Whisper Base (74M) | 60.0 s | **7.14 s** | **0.1190x (8.4x Faster)** | 26 MB | Validated |
308
+ | **Galaxy S21** | Snapdragon 865 (Adreno 650) | Whisper Tiny (39M) | 60.0 s | **6.13 s** | **0.1021x (10x Faster)** | 25 MB | Validated |
309
+ | **Galaxy S21** | Snapdragon 865 (Adreno 650) | Whisper Base (74M) | 60.0 s | **12.46 s** | **0.2077x (5x Faster)** | 25 MB | Validated |
310
+ | **Galaxy S21** | Snapdragon 865 (Adreno 650) | Whisper Small (244M)| 60.0 s | **26.63 s** | **0.4439x (2.3x Faster)** | 28 MB | Validated |
311
+ | **Galaxy A35** | Exynos 1380 (Mali-G68 MP5) | Whisper Tiny (39M) | 60.0 s | **22.36 s** | **0.3726x (2.7x Faster)** | 6 MB | Validated |
312
+ | **Galaxy A35** | Exynos 1380 (Mali-G68 MP5) | Vosk Small Korean | 60.0 s | **2.71 s** | **0.0452x (22x Faster)** | 45 MB | Validated |
313
+
314
+ > **Real-Time Factor (RTF) Definition**: $\text{RTF} = \frac{\text{Processing Latency (Seconds)}}{\text{Audio Duration (Seconds)}}$.
315
+ > An RTF of `0.10x` means 60 seconds of recorded voice is transcribed into text in only 6 seconds.
316
+
317
+ ### 7.2 Verified Transcription Output Sample
318
+ ```text
319
+ $ termux-stt transcribe samples/jfk_1min.wav -e whisper -m base --format srt
320
+ 1
321
+ 00:00:00,000 --> 00:00:09,000
322
+ And so my fellow Americans, ask not what your country can do for you.
323
+
324
+ 2
325
+ 00:00:09,000 --> 00:00:15,000
326
+ Ask what you can do for your country.
327
+
328
+ [SUCCESS] Transcribed 60.00s audio in 12.46s (RTF: 0.2077x) -> stdout
329
+ ```
330
+
331
+ ---
332
+
333
+ ## 8. GPU Interconnect Architecture & Compatibility
334
+
335
+ ### 8.1 Vulkan Compute Acceleration Pipeline
336
+ Termux-STT interfaces directly with Android's Bionic Vulkan loader (`/system/lib64/libvulkan.so`). Tensor mel-spectrogram transformations and encoder attention blocks are offloaded to mobile GPU SPIR-V compute shaders via `whisper.cpp` Vulkan backend bindings.
337
+
338
+ ### 8.2 Silicon Compatibility Matrix
339
+ - **Qualcomm Snapdragon (Adreno 6xx, 7xx, 8xx)**:
340
+ - **Tier-1 Full Support**. Native FP16 compute instructions and high dispatch concurrency deliver RTF performance as fast as **0.063x** on Snapdragon 8 Elite.
341
+ - **Samsung Exynos / MediaTek Dimensity (ARM Mali / Immortalis)**:
342
+ - **Supported**. Mali tile-based architectures benefit from `-ngl` layer tuning. Whisper Tiny and Base models operate smoothly without shader compilation stalls.
343
+ - **Strict Zero-Silent-Fallback**:
344
+ - Requesting `--device vulkan` without valid Vulkan drivers immediately triggers `PlatformNotSupportedError`, preventing silent fallback to unoptimized CPU execution.
345
+
346
+ ---
347
+
348
+ ## 8-1. CPU vs. GPU Performance & Thermal Trade-offs
349
+
350
+ | Evaluation Metric | CPU Inference (ARM Cortex-A78) | Vulkan GPU Inference (Adreno 830) | Benefit of GPU Offloading |
351
+ | :--- | :--- | :--- | :--- |
352
+ | **Real-Time Factor (Tiny)** | ~0.28x | **0.063x** | **4.4x Speedup** |
353
+ | **Real-Time Factor (Base)** | ~0.55x | **0.119x** | **4.6x Speedup** |
354
+ | **CPU Core Temperature** | High (Thermal Throttling at ~5min) | Low to Moderate | Prevents thermal CPU clock reduction |
355
+ | **Battery Power Draw** | ~3.8 W Peak | ~1.9 W Peak | **~50% Lower Energy Footprint** |
356
+ | **Interactive Latency** | Noticeable system stutter | Smooth background execution | Audio UI responsiveness preserved |
357
+
358
+ Offloading audio encoder matrix multiplications to the Vulkan GPU keeps ARM CPU cores available for real-time audio capture, VAD buffering, and downstream LLM inference.
359
+
360
+ ---
361
+
362
+ ## 9. Hardware Requirements & Operational Limits
363
+
364
+ ### 9.1 Hardware Specifications
365
+
366
+ | Specification Metric | Minimum Requirements | Recommended Production Spec |
367
+ | :--- | :--- | :--- |
368
+ | **Operating System** | Android 9.0+ (API level 28+) / Linux 5.4+ | Android 12.0+ (API level 31+) |
369
+ | **Architecture** | ARM64 (aarch64) or x86_64 | ARM64-v8a / v9a |
370
+ | **System RAM** | 2 GB Total Unified RAM | 4 GB+ Unified RAM |
371
+ | **Storage Footprint** | 150 MB (Vosk) / 300 MB (Whisper Base) | 1 GB Free Flash Storage |
372
+ | **Audio Subsystem** | Termux-API Microphone Permissions | 16kHz PCM Audio Capture Support |
373
+
374
+ ### 9.2 Operational Limits & Best Practices
375
+ - **32-Bit ARM (armeabi-v7a)**: Not supported for Whisper GPU neural inference. Use Vosk CFFI for legacy 32-bit hardware.
376
+ - **Microphone Permissions**: Real-time microphone listening (`termux-stt listen`) requires Android microphone permission granted to Termux: `termux-microphone-record`.
377
+
378
+ ---
379
+
380
+ ## 10. 24/7 Unattended Background Execution Guide
381
+
382
+ Android aggressively kills background user-space processes inside Termux unless battery and process monitor policies are explicitly configured. Follow these three stages to ensure uninterrupted continuous speech recognition:
383
+
384
+ ### 10.1 Stage 1: Termux Kernel Wake-Lock
385
+ Prevent the mobile CPU from entering low-power sleep states:
386
+ ```bash
387
+ # Acquire persistent CPU wake-lock
388
+ termux-wake-lock
389
+ ```
390
+
391
+ ### 10.2 Stage 2: Android GUI Battery Optimization Exemption
392
+ 1. Open **Android Settings > Apps > Termux > Battery**.
393
+ 2. Set battery policy to **Unrestricted** (Disable power-saving restrictions).
394
+ 3. Under **Permissions**, grant **Microphone** and **Display over other apps**.
395
+
396
+ ### 10.3 Stage 3: ADB Phantom Process Killer Exemption (Android 12+)
397
+ Android 12+ terminates background processes exceeding child process thresholds. Execute these commands via ADB:
398
+
399
+ ```bash
400
+ # Disable Android Phantom Process Killer
401
+ adb shell device_config put activity_manager max_phantom_processes 2147483647
402
+ adb shell settings put global settings_enable_monitor_phantom_procs false
403
+
404
+ # Verify configuration
405
+ adb shell settings get global settings_enable_monitor_phantom_procs
406
+ # Expected output: false
407
+ ```
408
+
409
+ ---
410
+
411
+ ## 11. Open Source License
412
+
413
+ Termux-STT is open-sourced under the **MIT License**.
414
+
415
+ ```text
416
+ Copyright (c) 2026 Eunho Kim (@uno-km) & AMEVA Open-Source Foundation.
417
+
418
+ Permission is hereby granted, free of charge, to any person obtaining a copy
419
+ of this software and associated documentation files (the "Software"), to deal
420
+ in the Software without restriction, including without limitation the rights
421
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
422
+ copies of the Software, and to permit persons to whom the Software is
423
+ furnished to do so, subject to the following conditions:
424
+
425
+ The above copyright notice and this permission notice shall be included in all
426
+ copies or substantial portions of the Software.
427
+
428
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
429
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
430
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
431
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
432
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
433
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
434
+ SOFTWARE.
435
+ ```
436
+
437
+ ---
438
+
439
+ ## 12. SEO Technical Keywords & Ecosystem Metadata
440
+
441
+ `termux`, `stt`, `speech-to-text`, `whisper`, `whisper-cpp`, `vosk`, `sherpa-onnx`, `diarization`, `speaker-diarization`, `voice-recognition`, `audio-transcription`, `on-device-ai`, `edge-ai`, `mobile-ai`, `vulkan`, `vulkan-compute`, `gpu-acceleration`, `real-time-factor`, `low-latency`, `arm64`, `android`, `snapdragon`, `adreno`, `exynos`, `arm-mali`, `zero-compilation`, `vad`, `voice-activity-detection`, `silero-vad`, `x-vector`, `k-means`, `clustering`, `srt-export`, `vtt-export`, `rttm`, `microphone-streaming`, `headless-audio`, `pulseaudio`, `offline-speech`, `privacy-first`, `termux-aichain`, `termux-tts`, `termux-llamacpp`, `termux-diffusion`, `ameva-runtime`, `ggml`, `quantization`, `bionic-libc`, `autonomous-agents`, `voice-assistant`
442
+
443
+ ---
444
+
445
+ ## Official Documentation & Foundation Ecosystem
446
+ - **Official Documentation Portal**: [https://uno-km.github.io/termux-stt/](https://uno-km.github.io/termux-stt/)
447
+ - **GitHub Repository**: [https://github.com/uno-km/termux-stt](https://github.com/uno-km/termux-stt)
448
+ - **AMEVA Foundation Portal**: [https://uno-km.vercel.app/foundation/index.html](https://uno-km.vercel.app/foundation/index.html)