TVBox

TVBox 是一个面向 Android TV / 电视盒子场景的视频聚合播放器项目，核心能力包括点播、直播、搜索、推送/远程控制、备份恢复，以及基于外部 spider 的动态扩展。

这份 README 同时面向两类读者：

• 普通使用者：快速了解应用能做什么、怎么配置、怎么使用、常见问题怎么排查。
• 开发维护者：快速了解整体结构，并快速跳转到单独的开发文档继续深入。

目录

• 功能概览
• 安装与构建产物
• 普通用户使用说明
  • 1. 首次使用
  • 2. 配置源
  • 3. 首页与点播
  • 4. 直播
  • 5. 搜索
  • 6. 设置
  • 7. 推送与远控
  • 8. 备份与恢复
• 常见问题
  • 配置拉取失败
  • jar 加载失败或某些站点突然不可用
  • 直播能进页面但无法播放
  • Python 版本构建失败
  • 备份恢复失败
• 开发者文档
• 配置格式参考

功能概览

项目当前的主要能力包括：

• 点播浏览：分类、筛选、翻页、详情、选集、收藏、历史记录。
• 直播播放：频道组、频道列表、EPG 节目单、回看/时移、直播设置。
• 搜索：普通搜索、快捷搜索、多源聚合搜索。
• 推送与远控：局域网内网页推送、远程输入、部分本地代理与控制能力。
• 设置与个性化：接口地址、首页源、播放器、DNS、缩放方式、预览、聚搜等开关。
• 备份恢复：备份数据库与本地配置，并从备份恢复。
• 动态扩展：支持 jar / js / python 形式的 spider 扩展能力。

安装与构建产物

项目是一个多 flavor 的 Android 工程，主要构建产物如下：

• normal flavor：常规版本。
• python flavor：包含 Python 相关能力，依赖 :pyramid 模块。

APK 文件名由 app/build.gradle 生成，格式为：

• TVBox_<buildType>-<flavor>.apk

例如：

• TVBox_debug-java.apk
• TVBox_debug-python.apk

说明：

• 当前 Gradle 配置仅构建 armeabi-v7a。
• python flavor 的 minSdkVersion 高于普通版本。

普通用户使用说明

1. 首次使用

应用启动后会进入首页。首页启动时会先做两件关键事情：

• 启动本地控制服务，用于推送、远控和部分代理能力。
• 读取并加载当前配置源，必要时继续加载外部 spider jar。

如果首次进入后没有内容，通常先检查：

• 是否已经设置可用的接口地址。
• 配置地址能否正常访问。
• 所依赖的 spider 是否可下载、可加载。

2. 配置源

配置源是应用的核心入口。它定义了：

• spider
• sites
• parses
• lives
• rules
• doh
• hosts
• wallpaper

应用通过配置源加载站点、解析、直播源以及动态扩展能力。

在设置页中，你可以：

• 修改当前接口地址
• 查看历史接口地址并快速切换
• 选择首页默认数据源
• 为直播单独设置接口

如果接口地址修改后首页内容没有刷新，通常需要重新进入首页，或者清理相关缓存后再试。

3. 首页与点播

首页是应用主入口，负责：

• 展示当前首页源
• 展示分类/站点导航
• 进入点播、搜索、直播、设置等功能区

点播浏览的基本流程：

1. 在首页选择分类或站点。
2. 进入列表页后浏览分类、筛选条件和分页内容。
3. 选中条目后进入详情页。
4. 在详情页中切换线路、切换选集、收藏、搜索相关内容，或进入播放。

如果某些项目表现为“文件夹式”进入，不是异常，这是 GridFragment 中支持的一种列表/目录化展示模式。

4. 直播

直播播放页支持：

• 频道组切换
• 频道列表切换
• 节目单（EPG）显示
• 回看/时移
• 直播源切换与部分播放设置

如果直播体验异常，优先检查：

• 当前直播接口是否可用
• EPG 地址是否有效
• 播放器类型是否适配该直播流
• DNS 设置是否需要切换

5. 搜索

项目包含两类搜索：

• 普通搜索：按常规流程搜索内容。
• 快捷/聚合搜索：适合跨源快速搜索。

如果你在某些分类下按下搜索后行为不同，这是正常的：不同 source、不同 flag 配置会决定是否允许快速搜索、是否走聚合搜索。

6. 设置

设置页目前集中在“设置其他”页签中，常见可调项包括：

• 调试开关
• 解析 WebView 类型（系统 WebView / XWalkView）
• 默认播放器
• 默认缩放方式
• 渲染方式
• 首页数据源
• 安全 DNS
• 首页推荐样式
• 历史记录数量
• 聚搜开关
• 预览开关
• m3u8 广告净化开关
• 默认首页显示为“点播”或“直播”
• 备份恢复

其中几项特别需要注意：

• XWalkView 更偏兼容低版本 Android，较新的系统通常优先使用系统 WebView。
• DNS、播放器、缩放方式会直接影响播放体验。
• 首页源切换后通常会回到首页重新加载。

7. 推送与远控

应用启动后会启动一个本地 HTTP 服务，用于：

• 推送播放 URL
• 浏览器远程控制页面
• 本地代理
• DNS over HTTPS 转发
• 某些文件访问/上传操作

这意味着：

• 局域网功能正常依赖本地网络环境。
• 推送、代理、远控问题通常不是单一页面问题，而是本地服务链路问题。

8. 备份与恢复

应用支持把本地数据备份到外部存储目录：

• /tvbox_backup/

备份内容主要包括：

• Room 数据库
• Hawk 配置数据

恢复成功后，应用会自动重启。

如果备份或恢复失败，优先检查：

• 是否授予存储权限
• 外部存储是否可写
• 备份目录结构是否完整

常见问题

配置拉取失败

优先检查：

• 接口地址是否正确
• 当前网络是否可访问该地址
• 配置内容是否符合应用预期格式

jar 加载失败或某些站点突然不可用

优先检查：

• 配置中的 spider 地址是否有效
• jar 是否已更新但本地缓存未刷新
• 首页顶部相关操作是否已经清掉 jar 缓存

直播能进页面但无法播放

优先检查：

• 直播源地址本身是否有效
• 当前播放器设置是否适合该流
• DNS / 代理链路是否影响请求

Python 版本构建失败

优先检查：

• pyramid/build.gradle 中的 Python 路径是否适合当前机器
• 本机是否具备 Chaquopy 依赖的 Python 环境

备份恢复失败

优先检查：

• 存储权限
• /tvbox_backup/ 目录内容
• 备份中是否同时包含 sqlite 与 hawk

开发者文档

如果你要维护或二次开发这个项目，继续阅读：

• 开发者文档

开发文档包含：

• 模块结构与 flavor 差异
• 构建、安装、Lint、测试命令
• 启动链路与配置加载链路
• 动态扩展架构（jar / js / python）
• UI、播放、本地服务、持久化与缓存
• 维护这个仓库时最容易联动出问题的区域

配置格式参考

下面保留当前仓库原有的 JSON 接口示例，作为配置字段参考。相关字段由 ApiConfig 负责解析；如果修改配置解析逻辑，应同步保持与该 schema 的兼容关系。

{
"spider": "./your.jar",
"wallpaper": "./api/img",
"sites": [],
"parses": [],
"hosts": [
"cache.ott.ystenlive.itv.cmvideo.cn=base-v4-free-mghy.e.cdn.chinamobile.com",
"cache.ott.bestlive.itv.cmvideo.cn=ip"
],
"lives": [],
"rules": [],
"doh": [
{
"name": "騰訊",
"url": "https://doh.pub/dns-query"
},
{
"name": "阿里",
"url": "https://dns.alidns.com/dns-query"
},
{
"name": "360",
"url": "https://doh.360.cn/dns-query"
}
]
}

补充字段说明：

• searchable：搜索开关，0 关闭，1 启用
• filterable：首页是否可选，0 否，1 是
• playerType：播放器类型，0 系统，1 IJK，2 EXO
• type：采集接口类型，0 xml，1 json，3 jar，4 remote
• parses 里的解析类型：0 嗅探 / 自带播放器，1 解析 / 返回直链
• 直播参数中常见扩展：ua 用户自定义 UA、epg 节目网址、logo 台标网址