Termux-Diffusion

Production On-Device AI Image Generation Framework for Android Termux & Samsung Galaxy
Dual-Engine Architecture (Python & Node.js / TypeScript) with Native Bionic ARM64 Tensor Acceleration

1. System Overview

termux-diffusion is an enterprise-grade, on-device AI text-to-image synthesis pipeline designed specifically for Android Termux environments and Samsung Galaxy hardware.

Unlike desktop-centric WebUI ports that require heavy containerization (e.g., PRoot Linux / Ubuntu) or suffer from memory exhaustion under the Android Low Memory Killer (LMK), termux-diffusion executes directly against native Android Bionic libc with ARM64 NEON SIMD vectorization and GGML quantized tensor weights.

2. Automated Bootstrap & Installation

Option A: One-Line Zero-Touch Bootstrap (Recommended)

Run the platform bootstrap script in Termux to automatically verify toolchains, storage permissions, and native engine binaries:

Python Runtime

curl -sL https://raw.githubusercontent.com/uno-km/termux-diffusion/main/docs/install.sh | bash

Node.js / TypeScript Runtime

curl -sL https://raw.githubusercontent.com/uno-km/termux-diffusion/main/docs/install-node.sh | bash

Option B: Package Manager Installation

Python (PyPI)

pip install termux-diffusion && termux-diffusion-install

Node.js (npm)

npm install -g termux-diffusion && npx termux-diffusion install

3. Core Architectural Capabilities

• Zero-PRoot Native Bionic Execution: Executes natively on ARM64 without container overhead, achieving maximum memory efficiency.
• Integrated Model Hub: Built-in streaming downloader with automatic checksum verification and cache persistence.
• Power & WakeLock Management (TermuxWakeLock): Automatically holds Android CPU WakeLock during inference, preventing kernel suspension when the screen turns off.
• Low-Memory & LMK Guard: Inspects physical memory and Android zRAM (Samsung RAM Plus) before allocating tensor weight buffers.
• Samsung Gallery Integration: Automatically persists generated outputs to ~/storage/pictures/TermuxDiffusion/ and triggers android.intent.action.MEDIA_SCANNER_SCAN_FILE for instant indexing in Samsung Gallery.
• big.LITTLE Core Affinity Tuning: Auto-detects Exynos (e.g., 1380, 1480, 2400) and Snapdragon cluster topologies to maintain high sustained clock rates without thermal throttling.
• Hardware Compute Selection: Explicit compute backend targeting via device="cpu" or device="gpu".

4. Built-in Model Hub Presets

5. Usage & Integration

Python API

from termux_diffusion import generate

result = generate(
    prompt="RAW photo, portrait of a happy smiling young Korean man in his 30s wearing glasses and hoodie, working on laptop, photorealistic, cinematic",
    model="realistic",
    device="cpu",
    steps=10,
    cfg_scale=4.0,
    output="developer.png"
)

print(f"Output Path: {result.path}")
print(f"Android MediaStore: {result.gallery_path}")
print(f"Elapsed Time: {result.elapsed_sec:.2f}s")

Node.js / TypeScript API

const { generate } = require('termux-diffusion');

async function main() {
    const result = await generate({
        prompt: 'cyberpunk cat with neon collar in rainy alley, 8k, photorealistic',
        model: 'speed',
        device: 'cpu',
        steps: 10,
        output: 'cyber_cat.png'
    });

    console.log(`Output Path: ${result.path}`);
    console.log(`Android MediaStore: ${result.galleryPath}`);
}

main().catch(console.error);

6. Custom Models & Hugging Face Resolution

1. Direct Hugging Face Repository Identifier

Pass any repository ID and .gguf filename. The framework resolves, streams, caches, and executes the weights:

generate(
    "1girl, anime masterpiece, vibrant colors",
    model="second-state/DreamShaper-8-GGUF/dreamshaper-8-Q4_k.gguf"
)

2. Local File Reference

generate(
    "fantasy landscape at sunrise",
    model="~/storage/downloads/custom_model.gguf"
)

3. Alias Registration (register_model)

from termux_diffusion import register_model, generate

register_model("waifu", repo_id="second-state/DreamShaper-8-GGUF", filename="dreamshaper-8-Q4_k.gguf")
generate("anime portrait", model="waifu")

7. Pre-flight Diagnostic Tool

Verify system packages, architecture, available memory, and native engine status:

# Python
termux-diffusion-doctor

# Node.js
npx termux-diffusion doctor

8. License

Released under the MIT License. Maintained by uno-km.