termux-stt

v1.1.1

Published

9 minutes ago

Production-Grade On-Device Speech-to-Text & Speaker Diarization Framework for Android Termux & Samsung Galaxy

Termux-STT

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

Production-Grade On-Device Speech-to-Text & Speaker Diarization Framework for Android Termux
Dual-Engine Architecture (Python & Node.js / TypeScript) with Native Bionic ARM64 Acceleration & 0 PyTorch Dependency

Live Audio Showcase & Demo • Official Documentation Site (13 Languages) • AMEVA Foundation • Quickstart • Architecture • Benchmarks

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.

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                               │
└─────────────────────────────────────────────────────────────────────────────┘

Subprocess Isolation: C++ inference runs in isolated native subprocesses. Memory errors or Segfaults never kill the host Python/Node.js application.
Pure Python Clustering: Cosine distance matrix and K-Means clustering are implemented with 0 external dependencies (numpy / scikit-learn optional, not required).
Automated Android Bionic Fixes: Solves sys.platform = 'linux' spoofing, libvosk CFFI extraction, and ffmpeg audio format normalization (16kHz / 1ch / PCM s16le) under the hood.
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).

| Engine / Pipeline | Model | Peak RAM | RTF (Speed) | KO Accuracy | Diarization Support | Termux Rating | | :--- | :--- | :---: | :---: | :---: | :---: | :---: | | whisper.cpp | ggml-tiny (39M) | ~150 MB | 0.80 | 85% | ❌ External | ⭐⭐⭐⭐⭐ | | whisper.cpp | ggml-base (74M) | ~250 MB | 1.20 | 88% | ❌ External | ⭐⭐⭐⭐ | | whisper.cpp | ggml-medium (769M) | ~1.5 GB | 3.40 | 95%+ | ❌ External | ⭐⭐⭐ (Golden Acc) | | Vosk | small-ko-0.22 (42M) | ~100 MB | 0.25 | 78% | ✅ 128d X-Vector | ⭐⭐⭐ | | Sherpa-ONNX | Zipformer | ~300 MB | 0.42 | 86% | ✅ CAM++ | ⭐⭐⭐⭐ | | Pyannote.audio 3.1 | diarization-3.1 | > 3.5 GB | 2.80~3.50 | N/A | ✅ Gold Standard | ❌ OOM Crashes | | termux-stt (Hybrid) | Vosk + Whisper Base| ~350 MB | 1.45 | 92%+ | ✅ Built-in K-Means | ⭐⭐⭐⭐⭐ (Recommended) |

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:

⚖️ 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