KV-TrimUI

The complete open-source native software ecosystem and application suite for TrimUI handheld consoles.
Stream YouTube ad-free, listen to lossless Hi-Fi music, watch on-demand cinema, tune into live TV & radio, read news & manga, clean your system, and install apps over-the-air.
Engineered with Rust 60 FPS Direct Framebuffer rendering, Next.js 15, static Musl daemons, and hardware-accelerated MPV/ALSA.

Why KV-TrimUI? • Applications Suite • Hardware Support • Comparison • Architecture • AI & Developer Hub • Controls • Cooking Workflow • SD Card Install • Structure

---

⚡ Why KV-TrimUI?

The TrimUI Smart Pro (1280×720 IPS) and TrimUI Brick Pro (1024×768 IPS) are standout budget retro handhelds featuring stereo speakers, Wi-Fi, and tactile controls. However, out-of-the-box software is almost exclusively focused on retro emulators, leaving modern media and utility applications broken or non-existent:

• ❌ Bloated Browsers & Memory Leaks: Stock Chromium or web wrappers on embedded Linux consume 500+ MB of RAM, suffer constant OOM crashes, and rely on clumsy joystick-as-mouse navigation.
• ❌ DRM & Commercial Overload: Traditional streaming apps demand Widevine DRM, proprietary Google Play Services, and force unskippable advertising.
• ❌ Zero Gamepad First Design: Desktop media players lack D-Pad focus rings, hardware hotkeys, or on-screen virtual keyboards.
• ❌ No Over-The-Air Software Ecosystem: Installing new tools usually requires removing the MicroSD card, inserting it into a PC, and manually copying zip files.

KV-TrimUI transforms TrimUI handhelds into modern, connected smart media consoles:

• 🛡️ Zero Tracking, Zero Ads & No Accounts: Direct stream extraction via InnerTube, direct HLS pipelines, and open APIs with no commercial interruptions.
• 🚀 Dual-Engine Architecture (Hybrid & Pure Native):
  • Pure Native 60 FPS Engine: Written in 100% Rust, rendering directly to /dev/fb0 via mmap with sub-millisecond D-Pad response and < 2 MB – 5 MB RAM consumption.
  • Lightweight Web Hybrid: Next.js 15 static UI paired with static Musl Rust daemons, consuming less than 15 MB RAM.
• 🎮 100% Gamepad & On-Screen Virtual Keyboard: Unified @kv-trimui/shared-gamepad input layer with repeat acceleration, instant OSK search (X button), and smooth bumper tab switching.
• 📺 Hardware 720p 60fps MPV Acceleration: Video streams render directly via native mpv with hardware-assisted decoding (--hwdec=auto, --vo=gpu), guaranteeing zero stutter.
• 🎧 Bit-Perfect Lossless Audio: Stream Tidal Hi-Fi, Apple Music Top 50, and Synology NAS Vault tracks directly through ALSA (hw:0,0) without lossy system resampling.
• 📶 Over-The-Air (OTA) Updates & App Store: One-click updates and downloads over Wi-Fi powered by the Official KV-TrimUI App Store and kv-store / kv-file.

---

🎮 Applications Suite

The suite comprises 12 production-ready applications, an official App Store web portal, and developer boilerplates:

Application	Category	Description	Core Stack	Port / Display
kv-store	Store	On-device App Store & ROM manager with 1-click Wi-Fi installation, update checks, and dual-mirror fallback.	100% Native Rust Framebuffer	/dev/fb0
kv-tube	Media	Ad-free YouTube client with InnerTube extraction, watch history resume, red progress bars, and 720p 60fps MPV playback.	Next.js 15 / Rust Musl / MPV	4545 & /dev/fb0
kv-tidal	Media	Handheld lossless audiophile streamer supporting Tidal, Apple Music Top 50, and Synology NAS Vault via bit-perfect ALSA.	Next.js 15 / Rust Musl / ALSA	4546
kv-netflix	Media	Handheld cinema client with remote catalog scraping, 6-digit TV/phone pairing, Vietnamese & English subtitles, and HLS streaming.	Next.js 15 Static / Rust Musl / MPV	4547
kv-radio	Media	Pure Native 60 FPS internet radio player streaming VOV, VOH, traffic, and worldwide stations directly via ALSA (< 900 KB RAM).	100% Native Rust Framebuffer / ALSA	/dev/fb0
kv-file	Utility	Dual-pane file manager, high-speed Wi-Fi companion portal (:8866), instant QR code file sharing, and ZIP package installer.	Pure Native Rust / Axum Daemon	/dev/fb0 & 8866
kv-tv	Media	Live IPTV player streaming national channels (VTV, HTV, VTC) and international 24/7 feeds (NHK World, DW, Bloomberg, Red Bull TV).	Native Rust Framebuffer / MPV	/dev/fb0
kv-news	Tools	Kindle-style distraction-free news reader for VnExpress, Tuổi Trẻ, Dân Trí with zero ads, font scaling, and high-contrast themes.	100% Native Rust Framebuffer	/dev/fb0
kv-anime	Media	Manga and comic reader fetching NetTruyen series with fast page caching, aspect-ratio scaling, and smooth D-Pad pagination.	100% Native Rust Framebuffer	/dev/fb0
kv-stremio	Media	Handheld cinema & anime streaming client with hardware-accelerated MPV playback, episode selectors, and bilingual subtitles.	100% Native Rust Framebuffer / MPV	/dev/fb0
kv-cleanup	Utility	1-Click system booster, memory flush (drop_caches), zombie task killer, dotfile cleaner (._*), and MainUI app deduplicator.	100% Native Rust Framebuffer	/dev/fb0
kv-retroarch	Gaming	Pre-tuned Libretro emulation center with low-latency ALSA audio, pre-mapped gamepad hotkeys, Ozone UI, and Wi-Fi core updates.	Libretro / Ozone / ALSA	Direct Display
website	Cloud	Official web portal, OTA distribution server, developer handbook, and REST API hosted at trimui.vndns.net.	Next.js 15 App Router / Tailwind v4	3000

---

🕹️ Device Compatibility

Device	Display Specs	Recommended Application Focus
TrimUI Smart Pro	16:9 (1280×720 IPS)	All Applications Supported: Full web-hybrid viewport applications (kv-file, kv-netflix, kv-tube, kv-tidal) and all pure native 60 FPS apps.
TrimUI Brick Pro	4:3 (1024×768 IPS)	Pure Native 60 FPS Suite: Seamless execution of all native Framebuffer apps (kv-store, kv-radio, kv-tv, kv-news, kv-anime, kv-stremio, kv-cleanup, kv-retroarch, and native kv-file).

---

📊 Competitive Matrix

Feature / Capability	🎮 KV-TrimUI Suite	🕹️ Stock TrimUI Player	🌐 Chromium Handheld Browser	📱 Android Handhelds
Ad-Free YouTube Streaming	✅ Yes (InnerTube, zero ads)	❌ None	⚠️ Heavy adblock extensions	⚠️ ReVanced / NewPipe
Lossless Hi-Fi Audio (Tidal/Vault)	✅ Yes (Direct FLAC/ALSA)	⚠️ Local MP3 only	❌ Cloud web player (lossy)	⚠️ Android audio resampler
On-Demand Movie Catalog	✅ Yes (Instant CDN stream)	❌ Manual SD transfers	⚠️ Popups & broken players	⚠️ Third-party APKs
Live IPTV & Internet Radio	✅ Yes (VTV, HTV, VOV, Global)	❌ None	❌ Heavy buffering	⚠️ Ad-filled IPTV apps
Kindle-Style News & Manga	✅ Yes (Ad-free, 60 FPS)	❌ None	❌ Cluttered web pages	⚠️ Heavy reading apps
Direct Framebuffer 60 FPS	✅ Yes (/dev/fb0 mmap)	⚠️ SDL wrapper	❌ Slow X11/software render	❌ Android SurfaceFlinger
Handheld D-Pad / Gamepad UI	✅ 100% Native Navigation	⚠️ Clunky UI	❌ Joystick mouse cursor	⚠️ Touchscreen-first
On-Screen Virtual Keyboard	✅ Built-in D-Pad Keyboard	❌ None	❌ Awkward OSK	⚠️ Android soft keyboard
Hardware 720p H.264 Playback	✅ Native MPV GPU Direct	⚠️ Limited formats	❌ Software lag / drop frames	✅ Android MediaCodec
RAM Footprint (Daemons)	⚡ < 1 MB – 15 MB (Rust)	N/A	❌ 400 MB – 800 MB RAM	❌ High OS overhead
OTA Wi-Fi App Updates	✅ 1-Click Wi-Fi Updates	❌ None	❌ Manual download	⚠️ Google Play Store
Account & Login Requirement	✅ Zero accounts required	N/A	❌ Google login requested	❌ Google Play Services

---

🏗️ System Architecture

┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                             TrimUI Handheld (Allwinner A133, aarch64 Linux)                      │
│                                                                                                  │
│   ┌──────────────────────────────────────────────┐    ┌──────────────────────────────────────┐   │
│   │        Engine A: Hybrid Web Viewport         │    │       Engine B: Pure Native Rust     │   │
│   │  - Next.js 15 Static UI / React 19           │    │  - 100% Statically-linked Rust Musl  │   │
│   │  - @kv-trimui/shared-gamepad navigation      │    │  - Linux Evdev Input (/dev/input)    │   │
│   │  - On-Screen Virtual Keyboard (OSK)          │    │  - Memory-mapped FB (/dev/fb0)       │   │
│   │  - Apps: kv-tube, kv-tidal, kv-netflix       │    │  - Apps: kv-store, kv-radio, kv-tv,  │   │
│   │                                              │    │          kv-news, kv-anime, stremio  │   │
│   └──────────────────────┬───────────────────────┘    └──────────────────┬───────────────────┘   │
│                          │ Localhost IPC / HTTP                          │ Direct Render         │
│                          ▼                                               │                       │
│   ┌──────────────────────────────────────────────┐                       │                       │
│   │           Embedded Rust Musl Daemons         │                       │                       │
│   │  - InnerTube, HLS stream resolver, REST APIs │                       │                       │
│   │  - TinyHTTP static server & Wi-Fi telemetry  │                       │                       │
│   │  - Process Manager & MainUI signal control   │                       │                       │
│   └──────────────────────┬───────────────────────┘                       │                       │
│                          │                                               │                       │
│                          ▼                                               ▼                       │
│   ┌──────────────────────────────────────────────────────────────────────────────────────────┐   │
│   │                                Hardware Abstraction Layer                                │   │
│   │  - Display: Direct Linux Framebuffer (/dev/fb0, 1280×720 @ 60Hz 32bpp BGRA/RGBA)          │   │
│   │  - Video: Native MPV Engine (--hwdec=auto, --vo=gpu, cedar hardware decoding)            │   │
│   │  - Audio: Native ALSA Engine (Direct PCM hw:0,0, bit-perfect lossless stream)            │   │
│   │  - Gamepad: Linux Evdev Subsystem (/dev/input/event0, event1)                            │   │
│   └──────────────────────────────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────┬─────────────────────────────────────────────────┘
                                                 │ Wi-Fi Sync / Dual-Mirror OTA
                                                 ▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                             KV-TrimUI Dual-Mirror Distribution                                   │
│  - Primary: GitHub 'latest' Release (github.com/vndangkhoa/kv-trimui/releases/latest)            │
│  - Backup Mirror: MyDS Forgejo 'latest' Release (git.khoavo.myds.me/vndangkhoa/kv-trimui)       │
│  - Web Portal & REST API: https://trimui.vndns.net                                               │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘

---

🤖 Developer & AI Agent Knowledge Hub

KV-TrimUI provides a comprehensive set of machine-readable specifications and starter boilerplates designed for AI coding agents (Antigravity, Claude Code, Cursor, Copilot) and systems engineers:

Essential Endpoints

• 📖 Technical Handbook (llms-full.txt): Deep dive into Framebuffer double-buffering, Evdev polling, TrueType glyph rendering, and packaging.
• 🤖 LLM Canonical Index (llms.txt): High-level architectural overview and critical invariants.
• ⚙️ Agent Knowledge API: Machine-readable JSON specifications for hardware registers, evdev keycode maps, and build targets.
• 🚀 Rust 60 FPS Starter Template: Fully working starter boilerplate with Framebuffer, Evdev input polling, launch script, and package config.
• 🌐 Interactive Guide Webpage: Architectural diagrams, code walkthroughs, and 1-click prompt copy tools.

⚠️ Critical Architectural Rules

1. NO X11 OR WAYLAND: Stock OS and CrossMix-OS do not provide any display server. Native apps MUST render directly to /dev/fb0 (1280×720 or 1024×768, 32bpp) via mmap.
2. MUSL STATIC LINKING MANDATORY: Stock OS uses an older GLIBC (~2.28). Dynamically linked binaries compiled with aarch64-unknown-linux-gnu will crash with GLIBC_2.34 not found. Always cross-compile with aarch64-unknown-linux-musl.
3. MAINUI PROCESS CONTROL: In launch.sh, always suspend Stock OS launcher before claiming the display (killall -STOP MainUI or killall MainUI) and resume it on exit (killall -CONT MainUI).
4. EVDEV GAMEPAD INPUT: Buttons and analog sticks must be read directly from /dev/input/event* nodes using non-blocking polling.

---

🕹️ Gamepad & Controls

All applications share the unified @kv-trimui/shared-gamepad layer and native evdev keycode mappings:

TrimUI Button	Keyboard Equiv.	Evdev Event / Code	Functionality across the Suite
D-Pad / Left Stick	W / A / S / D or Arrows	BTN_DPAD_UP/DOWN/LEFT/RIGHT	Move focus, navigate catalog grids, type on virtual keyboard
Button A	Enter or J	BTN_EAST (305)	Confirm / Play video / Toggle audio playback / Press active key
Button B	Escape or K	BTN_SOUTH (304)	Back / Close modal / Dismiss virtual keyboard / Return to grid
Button X	/ or U	BTN_NORTH (307)	Instantly open On-Screen Virtual Keyboard (OSK) for search
Button Y / Menu	M	BTN_WEST (308)	Contextual action (Bookmark to My List, Vinyl drawer, options)
L1 / R1 Bumpers	Shift+Tab / Tab	BTN_TL (310) / BTN_TR (311)	Switch main tabs (Trending, Search, Library, Vault)
Start / Select	Space / Backquote	BTN_START (315) / BTN_SELECT	Open settings / Toggle player controls / Check OTA updates

---

🍳 Local Cooking & Single-Source Release Workflow

KV-TrimUI uses a local cooking workflow (cook.sh) that builds and releases packages directly from your workstation without relying on complex, error-prone CI/CD pipelines. Every release updates a single rolling latest release tag on both GitHub and MyDS Forgejo:

# Cook all apps, synchronize catalog.json, commit to Git, and push releases:
./cook.sh

# Cook only a specific application:
./cook.sh kv-store
./cook.sh kv-tube

# Cook and verify locally without pushing to remote releases:
./cook.sh --no-push

What ./cook.sh does automatically:

1. Packages Apps: Iterates over active app directories in apps/ and generates clean ZIP bundles in apps/website/public/downloads/<app-id>.zip.
2. Exclusion Safeguard: Automatically skips and cleans excluded apps (EXCLUDED_APPS = {"website", "kv-ai", "kv-xxx", "kv-airplay", "kv-kodi"}).
3. Synchronizes Catalog: Updates catalog.json with exact byte sizes, Primary GitHub URLs, and MyDS Backup Mirror URLs, and copies it to all website and store mirrors.
4. Git Sync: Automatically untracks any excluded zips, stages updated catalog & zips, and pushes to both github and forgejo-myds remotes.
5. Dual-Mirror Release Publishing:
   • Primary: Uploads all .zip bundles and catalog.json to GitHub Release latest.
   • Backup Mirror: Uploads all .zip bundles and catalog.json to MyDS Forgejo Release latest.
   • Auto-Purge: Deletes any excluded or deprecated assets from the releases via REST API.

---

💾 Deploying to TrimUI Smart Pro & Brick

MicroSD Card Directory Structure

Place application folders inside /mnt/SDCARD/Apps/:

/mnt/SDCARD/
└── Apps/
    ├── kv-store/               # Handheld App & ROM Store (Pure Native 60 FPS)
    │   ├── bin/kv-store-native64
    │   ├── catalog.json
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-tube/                # YouTube Handheld Client (Hybrid + MPV)
    │   ├── bin/kv-tube-native64
    │   ├── bin/kv-tube-runner
    │   ├── package/
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-tidal/               # Lossless Audiophile Streamer (ALSA Direct)
    │   ├── bin/kv-tidal-runner
    │   ├── dist/
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-netflix/             # Handheld Cinema (Adaptive HLS + MPV)
    │   ├── bin/kv-netflix-runner64
    │   ├── www/
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-radio/               # Pure Native 60 FPS Radio Player (ALSA Direct)
    │   ├── bin/kv-radio
    │   ├── channels.json
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-file/                # File Manager & Wi-Fi Web Companion (:8866)
    │   ├── bin/kv-file-native64
    │   ├── bin/kv-file-runner
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-tv/                  # Live IPTV Player (Dual-Tier OTA + MPV)
    │   ├── bin/kv-tv-native64
    │   ├── channels.json
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-news/                # Kindle-Style News Reader (60 FPS Native)
    │   ├── bin/kv-news-native64
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-anime/               # Manga & Comic Reader (NetTruyen, 60 FPS)
    │   ├── bin/kv-anime-native64
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-stremio/             # Stremio Cinema & Anime Player (60 FPS + MPV)
    │   ├── bin/kv-stremio-native64
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    ├── kv-cleanup/             # Handheld System Booster & Optimizer
    │   ├── bin/kv-cleanup-native64
    │   ├── bin/cleanup_engine.sh
    │   ├── launch.sh
    │   ├── config.json
    │   └── icon.png
    │
    └── kv-retroarch/           # Pre-tuned Emulation Suite
        ├── bin/retroarch
        ├── cores/
        ├── retroarch.cfg
        ├── launch.sh
        ├── config.json
        └── icon.png

---

📁 Project Structure

kv-trimui/
├── apps/
│   ├── kv-store/                # Handheld App Store & ROM Manager
│   ├── kv-tube/                 # YouTube handheld client
│   ├── kv-tidal/                # Lossless audiophile streamer
│   ├── kv-netflix/              # Handheld cinema streaming client
│   ├── kv-radio/                # Pure Native 60 FPS internet radio
│   ├── kv-file/                 # Dual-pane file manager & Wi-Fi sharing suite
│   ├── kv-tv/                   # Live IPTV player (Vietnam & International)
│   ├── kv-news/                 # Kindle-style distraction-free news reader
│   ├── kv-anime/                # Manga & comic reader (NetTruyen)
│   ├── kv-stremio/              # Stremio cinema & anime streaming client
│   ├── kv-cleanup/              # System optimizer & memory booster
│   ├── kv-retroarch/            # Tuned Libretro emulation suite
│   └── website/                 # Official App Store portal & OTA server
│
├── packages/
│   └── shared-gamepad/          # Reusable React 19 D-Pad navigation hook
│
├── templates/
│   └── trimui-rust-starter/     # Native 60 FPS Rust Framebuffer starter template
│
├── tools/
│   ├── release_to_github.py     # Local cooking engine & dual-mirror release publisher
│   ├── build_all_native.sh      # Cross-compiles all native Rust binaries (Musl aarch64)
│   ├── deploy_all_to_device.sh  # Push apps directly to console over ADB
│   └── sync_to_smb.py           # Network storage & MicroSD synchronizer
│
├── cook.sh                      # 1-Command local cook & release script
├── catalog.json                 # Canonical repository app catalog
├── pnpm-workspace.yaml          # Monorepo workspace configuration
├── package.json
└── README.md

---

🌟 Support & Community

If KV-TrimUI elevates your handheld entertainment experience:

• Star ⭐ the project on GitHub!
• Visit the official online store at trimui.vndns.net.
• Follow repository mirrors (GitHub & Forgejo MyDS).
• Submit bug reports or feature requests on GitHub Issues.

---

📄 License

Distributed under the GPL-3.0-or-later license. See LICENSE for details.

Developed with ❤️ by Khoa Vo (@vndangkhoa).