如何使用 WebHomeTV 将家庭电视变成 Web 平台

任何尝试在 Android TV 或电视盒子上搭建媒体中心的人都可能遇到过 TVBox 和 FongMi 生态系统。这些是流行的开源播放器，可以通过 Python 和 JavaScript 脚本加载内容。它们有一个问题：主屏幕界面与标准应用网格布局紧密耦合。在不重新构建整个 APK 的情况下更改布局或嵌入自定义推荐信息流是不可能的。

开发者 fish2018 决定采用不同的方法，创建了 webhtv（WebHomeTV）仓库。该项目基于 FongMi 的代码库，但改变了主屏幕的根本概念。现在主屏幕是一个使用 HTML、CSS 和 JS 构建的完整网页，通过内置的 JS bridge 和应用的原生 API 与 Android 进行通信。

内部结构与工作原理

本质上，这是一个适用于智能手机和电视的混合 Android 应用。内部有两个协同工作的层。一方面是熟悉的内容解析器（Spider/CSP），另一方面是启动的 Chromium 上下文和本地 Web 服务器，用于渲染自定义布局。

您可以构建任何前端，将其放在自己的服务器或盒子的存储上，然后从那里控制搜索、调用视频播放器、检查链接可用性以及同步观看历史。

这个项目的亮点

开发者为浏览器上下文设计了一个原生 SDK。当前端加载到应用的 WebView 中时，它可以访问一个对象，该对象包含与硬件和操作系统交互的方法。网页可以独立发送跨域网络请求，绕过 CORS 规则，请求观看历史记录，使用系统代理，并将视频流直接传递给内部视频播放器。如果标准的分类网格变得乏味，您可以构建一个电影风格交互仪表盘或基于文本的终端式前端。

特别值得注意的内置功能包括云存储链接检查系统和智能源排序引擎。该应用开箱即用地检查流行文件共享服务上共享文件夹的有效性。同时，系统跟踪每个已连接网站的搜索成功率和播放成功率。随着时间的推移，最快和最稳定的源会自动上升到结果列表的顶部。

用遥控器控制所有这些功能并不总是很方便，因此应用内置了管理面板。如果您在电视上运行 WebHomeTV，并在电脑或智能手机的浏览器中打开地址 /m，则会打开一个 Web 控制面板。通过它，您可以方便地配置源、传递授权令牌、上传自定义扩展脚本以及查看视频播放器日志。

如果您家中有多台电视盒子和手机，则无需在每个设备上手动调整配置。应用内置了本地网络同步功能：设置、观看历史、授权 cookie 和书签可以在几次点击内在客户端之间传输。对于远程设备，您可以使用 Go、Rust、Cloudflare Workers 或 Vercel 设置中间 relay。

架构与原生库

仓库的技术内容看起来相当专业。这远非简单的系统 Android MediaPlayer 封装层。

应用使用 Java 21 和 Android SDK 37（compileSdk 37，minSdk 24）构建。代码支持两种风格：mobile 用于触摸屏，leanback 用于遥控器操作。

最有趣的部分隐藏在播放器引擎中。作者没有局限于标准的 ExoPlayer，而是嵌入了一个基于 C/C++ 深度定制的 MPV。内部使用 FFmpeg（n8.0.3）、libplacebo 和带 HTTP/2 支持的 curl 的最新构建版本。对于 Android 15 上的视频输出，他们使用了 Vulkan 和 MediaCodec 的组合，通过 AImageReader 和 Android Hardware Buffer，可以直接在 GPU 内存中解码视频流，无需不必要的帧复制。

除了 MPV，该项目还包含一个带有自定义补丁的 Media3（版本 1.11.0-alpha01-fongmi）分支。例如，一个补丁添加了高性能 WebSocket 处理器，用于在线评论和字幕，支持队列和帧率限制。

从源码构建

如果您想自己构建项目，需要准备好的 Android SDK，包含 NDK 28.2.13676358 和 JDK 21。仓库已经包含预编译的 .so 库，因此首次构建时无需从头重新构建 MPV 和 FFmpeg。

从控制台构建的过程看起来是标准的：

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

完成的 APK 文件放置在 app/build/outputs/apk/ 目录中。仓库还有 scripts/ 文件夹中的脚本，用于检查 ELF 头完整性并在必要时重新构建 JNI bridge。

开发者工具包与 AI 工具

在 webhome-devkit 文件夹中，作者分享了用于创建自己的主屏幕的完整工具包。有现成的布局模板、将 JS 代码注入网页的扩展示例，以及用于 SDK 的文档。

一个有趣的细节：开发者添加了一套现成的 AI 助手规则（skills）。您可以将它们连接到 Cursor、Claude 或其他神经网络编辑器，通过 prompts 自动为 WebHomeTV 生成新模块和解析器。

谁会发现这个项目有用

如果您正在为 Android TV 编写个人项目，或者想要为家庭使用制作一个自定义媒体中心，WebHomeTV 将为您提供强大的现成基础。您无需从头开始编写解码器、网络请求管理器和遥控器事件处理。只需构建一个整洁的网页并将其绑定到原生 SDK。

这个项目非常专业但又经过深思熟虑。它解决了 monolithic TV 播放器长期存在的问题，为 Web 开发者在创建大屏幕界面方面提供了完全的自由。