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. Installation & Provisioning

Method A: 1-Click Automated Installation (Recommended)

termux-stt install automatically provisions lightweight system dependencies (ffmpeg, libbluray, libxml2) and fetches the pre-compiled Bionic ARM64 whisper-cli binary from GitHub Releases in <1s (with automatic local Clang/NEON compilation fallback if offline).

Python SDK:

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

Node.js / TypeScript:

pkg update -y && pkg install nodejs-lts ffmpeg git -y
npm install -g termux-stt && termux-stt install

Method B: Manual Pre-Compiled Binary Download (Direct GitHub Release)

If you prefer to manually download the pre-compiled ARM64 native binary without building from source:

# 1. Download official ARM64 Bionic binary directly into ~/.local/bin
mkdir -p ~/.local/bin
curl -sL "https://github.com/uno-km/termux-stt/releases/download/v1.1.1/whisper-cli-arm64-android" -o ~/.local/bin/whisper-cli
chmod 755 ~/.local/bin/whisper-cli
ln -sf ~/.local/bin/whisper-cli ~/.local/bin/whisper-cpp

# 2. Ensure PATH includes ~/.local/bin
export PATH=$HOME/.local/bin:$PATH

# 3. Verify installation
whisper-cli --help

Method C: Manual Source Compilation (From Scratch)

If you wish to compile whisper.cpp directly with Snapdragon / Cortex NEON vector optimizations:

pkg install -y clang cmake make git ffmpeg
git clone --depth 1 https://github.com/ggerganov/whisper.cpp.git ~/tmp/whisper.cpp
cmake -B ~/tmp/whisper.cpp/build -S ~/tmp/whisper.cpp -DWHISPER_NEON=ON -DCMAKE_BUILD_TYPE=Release
cmake --build ~/tmp/whisper.cpp/build -j$(nproc)
cp ~/tmp/whisper.cpp/build/bin/whisper-cli ~/.local/bin/whisper-cli
chmod 755 ~/.local/bin/whisper-cli

🎙️ 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): Welcome to today's financial intelligence briefing.
[Speaker_1] (3.8s - 7.2s): Major equity indices closed higher following sustained foreign institutional inflows.
[Speaker_0] (7.5s - 10.1s): What is the latest outlook on the semiconductor sector?

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="Financial briefing", # 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 Engineering 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.

This project is an independent open-source library engineered for Android Termux and is not officially affiliated with or endorsed by the Termux project, OpenAI, or Google LLC.

📄 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