How to Turn Your Home TV into a Web Platform with WebHomeTV

Anyone who has tried to set up a media center on Android TV or a TV box has likely come across the TVBox and FongMi ecosystem. These are popular open-source players that can load content through Python and JavaScript scripts. They have one problem: the home screen interface is tightly coupled to the standard app grid layout. Changing the layout or embedding a custom recommendation feed without rebuilding the entire APK is simply not possible.

Developer fish2018 decided to take a different approach and created the webhtv (WebHomeTV) repository. The project is based on FongMi's codebase but changes the very concept of the home screen. Now the home screen is a full-fledged web page built with HTML, CSS, and JS that communicates with Android through a built-in JS bridge and the app's native APIs.

What's Inside and How It Works

Essentially, this is a hybrid Android app for smartphones and TVs. Inside, two layers work together. On one side, familiar content parsers (Spider/CSP) remain, while on the other, a Chromium context and local web server spin up to render custom layouts.

You can build any frontend, place it on your own server or the box's storage, and from there control search, call the video player, check link availability, and sync viewing history.

What Makes This Project Interesting

The developers designed a native SDK for the browser context. When the frontend loads inside the app's WebView, it gets access to an object with methods for interacting with hardware and the operating system. The web page can independently send cross-domain network requests bypassing CORS rules, request viewing history, use the system proxy, and pass video streams directly to the internal video player. If the standard category grid gets boring, you can build a frontend in the style of a cinematic interactive dashboard or as a text-based terminal.

Special attention should be paid to the built-in link checking system for cloud storage and the smart ranking engine for sources. The app checks the validity of shared folders on popular file-sharing services right out of the box. At the same time, the system tracks the success rate of searches and playback for each connected site. Over time, the fastest and most stable sources automatically rise higher in the results list.

Controlling all this with a remote control isn't always convenient, so an admin panel is built into the app. If you run WebHomeTV on your TV and open address /m in a browser on your computer or smartphone, a web control panel opens. Through it, you can conveniently configure sources, pass authorization tokens, upload custom extension scripts, and view video player logs.

If you have several TV boxes and phones in your home, you won't need to manually adjust the configuration on each device. Local network synchronization is implemented inside: settings, viewing history, authorization cookies, and bookmarks are transferred between clients in a couple of clicks. For remote devices, you can set up an intermediate relay in Go, Rust, Cloudflare Workers, or Vercel.

Architecture and Native Libraries

The technical contents of the repository look serious. This is far from a simple facade over the system Android MediaPlayer.

The app is built with Java 21 and Android SDK 37 (compileSdk 37, minSdk 24). The code supports two flavors: mobile for touchscreens and leanback for remote control operation.

The most interesting part is hidden in the player engine. The authors didn't limit themselves to the standard ExoPlayer and embedded a deeply customized MPV based on C/C++. Inside, it uses fresh builds of FFmpeg (n8.0.3), libplacebo, and curl with HTTP/2 support. For video output on Android 15, they used a combination of Vulkan and MediaCodec via AImageReader and Android Hardware Buffer, which makes it possible to decode the video stream directly in GPU memory without unnecessary frame copies.

In addition to MPV, the project includes a fork of Media3 (version 1.11.0-alpha01-fongmi) with custom patches. For example, one patch adds a high-performance WebSocket handler for online comments and subtitles with queue support and frame rate limits.

Building from Source

If you want to build the project yourself, you'll need a prepared Android SDK with NDK 28.2.13676358 and JDK 21. The repository already contains precompiled .so libraries, so you won't need to rebuild MPV and FFmpeg from scratch on the first build.

The build process from the console looks standard:

git clone https://github.com/fish2018/webhtv.git
cd webhtv
echo "sdk.dir=$ANDROID_HOME" > local.properties
bash gradlew :app:assembleMobileArm64_v8aDebug :app:assembleLeanbackArm64_v8aDebug

Finished APK files are placed in directories in app/build/outputs/apk/. The repository also has scripts in the scripts/ folder that check ELF header integrity and rebuild JNI bridges if necessary.

Developer Kit and AI Tools

In the webhome-devkit folder, the authors shared a full toolkit for creating your own home screens. There are ready-made layout templates, examples of extensions for injecting JS code into web pages, and documentation for working with the SDK.

An interesting detail: the developers added a set of ready-made rules (skills) for AI assistants. You can connect them to Cursor, Claude, or other neural network editors to generate new modules and parsers for WebHomeTV automatically through prompts.

Who Will Find This Project Useful

If you're writing pet projects for Android TV or want to make a custom media hub for home use, WebHomeTV will give you a powerful ready-made foundation. You don't need to write decoders, network request managers, and remote control event handling from scratch. Just build a neat web page and bind it to the native SDK.

The project turned out to be specific but extremely well-thought-out. It solves the long-standing problem of monolithic TV players, giving web developers complete freedom in creating interfaces for large screens.