Termux-STT

 ████████╗███████╗██████╗ ███╗   ███╗██╗   ██╗██╗  ██╗      ███████╗████████╗████████╗
 ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██║   ██║╚██╗██╔╝      ██╔════╝╚══██╔══╝╚══██╔══╝
    ██║   █████╗  ██████╔╝██╔████╔██║██║   ██║ ╚███╔╝ █████╗███████╗   ██║      ██║   
    ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██║   ██║ ██╔██╗ ╚════╝╚════██║   ██║      ██║   
    ██║   ███████╗██║  ██║██║ ╚═╝ ██║╚██████╔╝██╔╝ ██╗      ███████║   ██║      ██║   
    ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝      ╚══════╝   ╚═╝      ╚═╝   

AMEVA Foundation — Mobile AI Ecosystem

"$0 Cloud Egress, 0% External Data Leaks. Transforming every smartphone into an independent on-device AI workstation." The AMEVA Open-Source Foundation (AOSF) builds next-generation, client-centric AI runtimes spanning on-device large models, browser automation, neural network training, and speaker diarization.

Project	Platform & Packages	Core Capability & Technology	Documentation & Demo
🎙️ termux-stt		Integrated On-Device STT & Pure Python 128d X-Vector Diarization (Whisper + Vosk + Sherpa)	Showcase • Docs
🎨 termux-diffusion		Mobile On-Device Stable Diffusion Image Generation (bfloat16 ARM NEON acceleration)	Docs
🌐 termux-playwright		Non-Root Native Headless Chromium Browser Automation & Scraping	Docs
🧠 termux-train		Mobile Native Autograd Neural Network Training & LoRA Fine-Tuning	Docs
🖥️ AMEVA Workstation		100% Client-Side WebGPU Multimodal Document Intelligence Workspace	Live Demo
⚡ AMEVA-Forge		Real-Time 3D Neural Studio & WebGPU Visualization Engine	Live Demo

1. Quick Scenario Playbook

Installation

Python SDK:

pkg update -y && pkg install python ffmpeg git -y
pip install termux-stt && termux-stt install

Node.js / TypeScript:

pkg update -y && pkg install nodejs-lts ffmpeg git -y
---

## 1. Quick Scenario Playbook

### 1-Click Installation

#### Python SDK:
```bash
pip install termux-stt && termux-stt install

Node.js / TypeScript:

npm install -g termux-stt && termux-stt install

🎙️ Try with the Included Sample Audio! (JFK 1-Minute Speech)

termux-stt includes John F. Kennedy's 1961 Inaugural Address (60.00s 16kHz Mono PCM) in samples/jfk_1min.wav for instant out-of-the-box testing.

Option A: CLI One-Liner (Python / npm)

# 1. Transcribe the 60s sample speech with Whisper (auto-generates SRT subtitles)
termux-stt transcribe samples/jfk_1min.wav --engine whisper --model tiny --format srt

# 2. Transcribe and separate speakers (128d X-Vector Diarization)
termux-stt diarize samples/jfk_1min.wav --speakers 2 --format text

# 3. Benchmark on-device latency & RTF
termux-stt benchmark --audio samples/jfk_1min.wav --model tiny

Option B: Python SDK

from termux_stt import create_engine

# 1. Initialize Whisper Engine (auto-loads native ARM NEON binary)
engine = create_engine("whisper", model="tiny", lang="en", threads=4)

# 2. Transcribe JFK 60s speech
result = engine.transcribe("samples/jfk_1min.wav")

print("Transcript:\n", result.text)
print("SRT Subtitles:\n", result.to_srt())

Option C: Node.js / TypeScript

const { createEngine } = require("termux-stt");

async function main() {
  const engine = createEngine("whisper", { model: "tiny", lang: "en", threads: 4 });
  const result = await engine.transcribe("samples/jfk_1min.wav");
  
  console.log("Transcript:", result.text);
  console.log("SRT Subtitles:\n", result.toSrt());
}
main();

2. Advanced Scenarios

[Streaming] Scenario 3: Real-Time Microphone Streaming

Speak into your smartphone microphone and receive real-time transcribed text with sub-second latency:

from termux_stt import create_engine

# Use ultra-lightweight Tiny model (RTF 0.80 on Exynos 1380)
engine = create_engine("whisper", model="tiny", lang="ko")

print("🎙️ Listening... Speak into your phone microphone (Ctrl+C to stop)")
for segment in engine.stream_mic():
    print(f"[{segment.start:.1f}s -> {segment.end:.1f}s] {segment.text}")

[Diarize] Scenario 4: Hybrid Speaker Diarization ("Who Spoke When?")

Run high-precision speaker diarization without PyTorch or CUDA:

from termux_stt import create_engine

# Hybrid Pipeline: Vosk 128d X-Vector + Whisper STT + Pure Python K-Means
engine = create_engine("hybrid", lang="ko", num_speakers=2)
result = engine.diarize("interview.wav")

for seg in result.segments:
    print(f"[{seg.speaker}] ({seg.start:.1f}s - {seg.end:.1f}s): {seg.text}")

Output Example:

[Speaker_0] (0.0s - 3.5s): 오늘 경제 브리핑을 시작하겠습니다.
[Speaker_1] (3.8s - 7.2s): 네, 오늘 코스피 지수가 외국인 순매수로 상승 마감했습니다.
[Speaker_0] (7.5s - 10.1s): 반도체 섹터 동향은 어떤가요?

2. 🏛️ Why termux-stt? Architectural Pillars

┌─────────────────────────────────────────────────────────────────────────────┐
│                           termux-stt Architecture                          │
├────────────────────────┬────────────────────────┬───────────────────────────┤
│   User Interface Layer │   Engine Abstraction   │   Output / Export Layer   │
│  • Python API          │  • EngineRegistry      │  • JSON / SRT / VTT       │
│  • Node.js API         │  • create_engine()     │  • RTTM (Diarization)     │
│  • CLI (termux-stt)    │  • ModelHub & Cache    │  • Streaming Callback     │
├────────────────────────┼────────────────────────┼───────────────────────────┤
│                   Core Pipeline Layer                                       │
│  Audio Loader (7 Formats) ➔ Preprocessor (16kHz Mono) ➔ Silero-VAD Filter  │
│  ➔ Multi-Engine STT (whisper.cpp / Vosk / Sherpa-ONNX)                     │
│  ➔ Hybrid Diarizer (128d X-Vector ➔ Pure Python Cosine/K-Means ➔ Time Align)│
├─────────────────────────────────────────────────────────────────────────────┤
│                   Platform & Process Isolation                              │
│  • Subprocess Isolation (Host Python never crashes on C++ Segfault)         │
│  • MobileGuard (WakeLock, Doze Mode Bypass, Phantom Process Killer Shield)  │
│  • Bionic ARM64 NEON & FP16 SIMD Acceleration                               │
└─────────────────────────────────────────────────────────────────────────────┘

1. Subprocess Isolation: C++ inference runs in isolated native subprocesses. Memory errors or Segfaults never kill the host Python/Node.js application.
2. Pure Python Clustering: Cosine distance matrix and K-Means clustering are implemented with 0 external dependencies (numpy / scikit-learn optional, not required).
3. Automated Android Bionic Fixes: Solves sys.platform = 'linux' spoofing, libvosk CFFI extraction, and ffmpeg audio format normalization (16kHz / 1ch / PCM s16le) under the hood.
4. Mobile Battery & CPU Guard: Manages Android WakeLocks and background task states to prevent process termination when the screen locks.

3. 📊 Empirical Benchmarks (Galaxy A35 / Exynos 1380)

Measured on Samsung Galaxy A35 5G (Exynos 1380 4x A78 + 4x A55, 6GB RAM, Android 14 Termux).

4. ⚙️ Engine Comparison Matrix

5. 📚 Complete API Reference Summary

Python API

import termux_stt

# Create Engine with fine-grained control parameters
engine = termux_stt.create_engine(
    engine="whisper",         # "whisper" | "vosk" | "sherpa" | "hybrid"
    model="base",             # "tiny" | "base" | "small" | "medium" | "custom"
    lang="ko",                # ISO 639-1 language code
    num_speakers=0,           # 0 = disabled, 2+ = enable diarization
    threads=4,                # CPU threads (defaults to big cores count)
    vad=True,                 # Enable Silero-VAD silence stripping
    quantization="q5_1",      # "f16" | "q8_0" | "q5_1" | "q4_0"
    prompt="경제 브리핑",     # Initial decoding context / vocabulary
    beam_size=5,              # Beam search beam size
    temperature=0.0           # Sampling temperature
)

# Transcribe File
result = engine.transcribe("audio.wav")
# Returns: TranscriptResult(text=str, segments=List[Segment], language=str, duration=float)

# Export Methods
result.to_json()              # Structured JSON string
result.to_srt()               # Standard SRT subtitle format
result.to_vtt()               # WebVTT subtitle format
result.to_rttm()              # NIST RTTM diarization format

# Stream Microphone
for seg in engine.stream_mic(duration=30.0):
    print(f"[{seg.speaker}] {seg.text}")

# Speaker Diarization
diar_result = engine.diarize("meeting.wav", num_speakers=2)

CLI Reference

# General Syntax
termux-stt [COMMAND] [OPTIONS] [FILE]

# Commands
termux-stt transcribe [FILE]   # Transcribe audio file (--prompt, --beam-size, --translate)
termux-stt listen              # Real-time microphone transcription
termux-stt diarize [FILE]      # Perform speaker diarization
termux-stt models list         # List installed and available models
termux-stt models download [M] # Download specific model
termux-stt doctor              # Run hardware and environment diagnostics
termux-stt benchmark           # Run performance benchmark suite

6. 🛠️ Troubleshooting & Android FAQs

Q1: pip install vosk fails with CMake or wheel error on Android

• Cause: Vosk does not publish official prebuilt aarch64-android wheels on PyPI.
• Solution: termux-stt-install automatically extracts libvosk.so from the official Android AAR and generates the CFFI bindings.

Q2: Whisper crashes on 44.1kHz stereo MP3/M4A files

• Cause: Whisper models strictly require single-channel 16,000Hz 16-bit PCM WAV.
• Solution: termux-stt automatically runs ffmpeg normalization on any audio format (mp3, m4a, flac, ogg, opus, webm).

Q3: Process killed after 10 minutes in background

• Cause: Android Phantom Process Killer terminates background tasks.
• Solution: Enable Termux WakeLock (termux-wake-lock) and disable battery optimization for Termux in Android Settings.

7. 🔍 15-Part Empirical Research Blog Series

This framework is built upon the exhaustive 15-part research series published on Eunho Kim's Technical Blog (우노킴 티스토리):

1. [Whisper.cpp] #1. Edge Agent AI: Whisper.cpp Speech Processing (Base vs Tiny)
2. [Audio Extraction] #2. Extracting Specific Audio Segments on Android
3. [Whisper.cpp] #3. Korean STT Conversion Comparison (4 Models)
4. [Comparison-1] #4. STT + Speaker Diarization: 3 Lightweight Engines + Pyannote
5. [Comparison-2] #5. Sherpa-ONNX Execution, Diarization, and Troubleshooting
6. [Comparison-3] #6. Speaker Diarization using Pyannote Model
7. [Pyannote] Troubleshooting Diarization in Mobile/Termux/ARM Environments
8. [Comparison-4] #7. Vosk Execution, Speaker Diarization, and Troubleshooting
9. [Vosk] Troubleshooting Vosk in Mobile/Termux/ARM Environments
10. [Comparison-5] #8. Vosk / Pyannote / Sherpa-ONNX / Whisper.cpp Comprehensive Comparison
11. [Comparison-6] #9. Vosk + Whisper.cpp Hybrid Pipeline & X-Vector Diarization
12. [Development-1] #10. Large-Scale Batch Automation & Task Management Architecture
13. [Comparison-7] #11. STT + Diarization Final: Small vs Turbo & Optimization Magic (4-Model Benchmark)
14. [Development-2] #12. Domain-Specific STT Training: Whisper Tiny Fine-Tuning on CPU
15. [Comparison-8] #13. Vanilla Model vs Custom Fine-Tuned Model (Economics/News Domain)

⚖️ Disclaimer (면책 조항)

Disclaimer:
termux-stt is an independent open-source project developed for the Android Termux environment and is not officially affiliated with, endorsed by, or sponsored by the Termux project, OpenAI, or any other third party.

(본 프로젝트는 안드로이드 Termux 환경을 위해 개발된 독립적인 오픈소스 라이브러리이며, Termux 공식 프로젝트, OpenAI 및 기타 제3자와 직접적인 제휴 관계가 아닙니다.)

📄 License

Released under the MIT License. Maintained by AMEVA Foundation & uno-km (쌩초보코딩단) / Eunho Kim.

💖 Sponsorship & Community Backing

AMEVA is an independent open-source public good governed under the AMEVA Open-Source Foundation (AOSF). All sponsorship funds are 100% publicly audited and dedicated to physical ARM64 testbeds and CI/CD GPU runners.

• Open Collective (Non-Profit 501(c)(6)): https://opencollective.com/ameva-fund
• GitHub Sponsors: https://github.com/sponsors/uno-km
• Official Foundation Portal: https://uno-km.vercel.app/docs/foundation/sponsorship.html ======= Apache License 2.0. Copyright (c) 2026 uno-km (AMEVA Foundation).

Stashed changes