TVBox 是一个面向 Android TV / 电视盒子的影视播放应用,使用 Kotlin、Jetpack Compose 和 Media3 ExoPlayer 构建。应用重点适配遥控器操作,支持影视分类、搜索、详情、m3u8 播放、观看历史、电视直播和 OTA 更新。
当前源码版本为 1.3.14(versionCode=10314)。本版本新增自动跳过片头、手机扫码输入搜索及菜单键快捷入口,优化频道风格播放设置和倍速循环操作。保留此前设备模式、搜索光标修复与 OTA 安装包保存能力;服务端部署方式见 多平台直播服务部署说明。
请确保使用的影视与直播接口具备合法授权。本项目仅提供客户端能力,不内置或托管影视内容。
- Android TV 适配:支持
LEANBACK_LAUNCHER,可在电视桌面启动,同时保留普通 Android 启动入口。 - 遥控器友好:方向键、确认键、返回键、菜单键和数字键均有对应交互。
- 首页影视列表:默认展示豆瓣热播剧集,支持海报、评分、分页加载、焦点高亮;点击热播卡片后才按片名从当前影视数据源查找详情与播放资源。
- 主题切换:设置页支持“默认主题”和“影院主题”;默认主题保留原有顶部快捷入口,影院主题提供左侧图标导航和 Hero 推荐布局。
- 视频接口管理:内置《影视线路地址整理.md》收录的 32 个资源站,并保留原有扩展线路;设置页可选择首页数据源,也可手机扫码添加 MacCms 自定义接口。
- 搜索与详情:关键词搜索最多三条来源并行,结果增量去重显示;重新进入搜索页时光标位于旧关键词末尾,可用遥控器退格删除。详情页优先显示主来源,后台补齐播放源和选集。
- AI 找片:支持文字、应用内语音识别、快捷推荐词和“换一批”,可在设置页用手机扫码配置大模型、模型名和 API Key。
- 播放器:基于 Media3 ExoPlayer,仅使用其视频解码与画面窗口;TVBox 自行处理遥控器快退/快进、切集、倍速、播放暂停、自动跳下一集和手机播放手势。
- 底栏操作:显示“上一集(1)”“下一集(3)”;点击当前倍速或按播放页菜单键,均直接循环
1x → 1.25x → 1.5x → 2.0x → 0.75x → 1x,不弹出倍速面板。 - 画面比例:点播操作栏“画面”支持自适应、裁剪铺满和拉伸铺满,本机记忆并实时生效;播放页隐藏系统栏,退出后恢复。
- 跳过片头:设置页可设默认秒数,播放页“片头”通过预设和 ±5 秒调整本片/整部剧的秒数;没有自定义输入框或“跟随全局”按钮,未单独设置的影片仍使用默认值。仅从头播放和切集时生效,不覆盖历史续播或换线进度。
- 手机扫码输入:搜索页点击“手机扫码输入 · 菜单键”或短按遥控器菜单键打开二维码,手机在可互通的同一局域网扫码输入片名并提交,电视直接搜索;一次性会话 5 分钟有效,退出搜索页或切后台即失效,无需配套手机应用。
- 该功能的需求建议来自 LINUX DO 社区用户 patrickpa,感谢提出让电视遥控器输入更方便的想法。
- 播放设置:底栏保留播放/暂停、上一集、下一集、倍速和设置;右侧面板参照“电视(4)”频道的 260dp 宽度、半透明深色背景和扁平焦点列表,画面、片头、选集与线路的名称和当前值分层显示。仍右上贴边、全高,无关闭按钮,使用返回键逐级退出并恢复焦点。
- 设备模式:设置提供“电视模式”和“手机模式”,默认电视模式,本机保存并优先于系统识别;电视短剧保持横屏,手机模式保留点播转屏和普通直播手机布局。
- 观看历史:记录影片、封面、播放线路、集数、播放进度和更新时间;首页显示最近六部未看完的“继续观看”,原来源优先续播,备用线路后台补齐。
- 返回定位:首页、搜索和历史页面恢复滚动位置与影片焦点;“继续观看”卡片可用方向上返回顶部导航。
- 电视直播:支持 TVBox 文本与 M3U 直播源,主源不可用时自动尝试备用源;支持分组、左右切台、上下切换线路、数字选台,以及线路异常时自动换线。
- 平台直播:支持斗鱼、虎牙、哔哩哔哩、抖音和快手,统一提供平台、一级分类、二级分类、直播间和播放器流程,并按平台返回结果优先选择最高画质;直播间可在本机收藏,在直播入口的“收藏”卡片中直接打开。
- 播放亮屏:所有播放页在前台保持亮屏,暂停时同样生效;退出播放页或切到后台后恢复原设置。
- 播放中断:切到后台或发生音频焦点中断后暂停,返回后由用户手动恢复播放。
- OTA 更新:系统后台下载 APK,缺少系统下载组件时使用应用备用下载;小窗显示进度与授权状态,前台完成且获得授权后打开安装器,也可保存 APK 后通过文件管理器手动安装。
- 内容过滤:过滤伦理、电影解说、演员、新闻资讯等不需要的分类或资源。
首页:
| 按键 | 功能 |
|---|---|
| 数字 1 | 历史 |
| 数字 2 | 搜索 |
| 数字 3 | AI 推荐 |
| 数字 4 | 电视直播 |
| 数字 5 | 平台直播 |
| 数字 6 | 设置 |
| 方向键 | 移动焦点 |
| 确认键 | 打开当前焦点内容 |
| 下滑到加载更多 | 自动加载下一页 |
搜索页:
| 按键 | 功能 |
|---|---|
| 菜单键 | 打开手机扫码输入;长按不重复触发,二维码已打开时不重新生成 |
播放器:
| 按键 | 功能 |
|---|---|
| 确认键 | 展开控制栏,或操作当前聚焦控件 |
| 媒体播放暂停键 | 直接播放或暂停 |
| 方向左 / 右 | 控制栏关闭时每次快退 / 快进 10 秒并支持长按;控制栏打开时导航按钮,聚焦进度条时调整进度 |
| 菜单键 | 与底部倍速按钮相同,直接循环 1x → 1.25x → 1.5x → 2.0x → 0.75x → 1x |
| 数字 1 | 上一集 |
| 数字 3 | 下一集 |
| 返回键 | 设置子项 → 播放设置 → 操作栏 → 详情页 |
直播:
| 按键 | 功能 |
|---|---|
| 方向左 / 右 | 上一个 / 下一个频道,支持首尾循环 |
| 方向上 / 下 | 切换当前频道的上一条 / 下一条线路 |
| 确认 / 播放暂停 | 显示左侧频道列表 |
| 数字键 | 输入频道号,例如 1、12 |
| 返回键 | 先关闭频道列表,再返回首页 |
从 Release 下载最新 APK:
- Latest Release
- OTA 更新清单:
https://raw.githubusercontent.com/ZxxXinI/tvbox/main/update.json
通过 ADB 安装:
adb install -r app\build\outputs\apk\release\app-release.apk如果是从 Release 下载的 APK:
adb install -r TVBox-v1.3.14.apk应用启动后会请求:
https://raw.githubusercontent.com/ZxxXinI/tvbox/main/update.json
update.json 示例:
{
"versionCode": 10314,
"versionName": "1.3.14",
"apkUrl": "https://gh-proxy.org/https://github.com/ZxxXinI/tvbox/releases/download/v1.3.14/TVBox-v1.3.14.apk",
"apkSha256": "bb080515d598a3dcd168f9112a20f8a61a732535f36e931110fb703594e159a1",
"apkSize": 5083585,
"force": false,
"changelog": [
"新增自动跳过片头,默认关闭;预设和 ±5 秒调整,本片设置在本机保存。",
"搜索页支持手机扫码输入,菜单键可直达,提交片名后电视直接搜索。",
"扫码会话 5 分钟有效且一次性,退出搜索页或切后台立即关闭。",
"播放设置改为频道风格 260dp 侧栏,选集、线路、画面和片头集中收纳。",
"倍速按钮与菜单键直接循环切换,不再弹窗;上/下一集标注数字 1/3。"
]
}说明:
versionCode必须大于当前应用版本,才会提示更新。- v1.3.14 可通过旧版应用的 OTA 提示更新,也可手动下载 APK 覆盖安装,保留本机数据。
- 手机用户请到“设置 → 设备模式”选择手机模式;默认电视模式用于避免盒子播放短剧时切成竖屏。
- 已下载的 APK 可从小窗选择“保存安装包”。系统没有文件选择器时保存到下载目录的
TVBox文件夹;Android 9 需存储授权,手动安装仍受系统权限限制。 - 旧版若无法在线更新,可从 Release 页面下载 APK 手动覆盖安装。
- 下载开始后关闭弹窗或按返回不取消任务;后台下载完成时,回到应用后打开安装界面。系统安装仍需用户确认,取消后可从小型进度卡片手动安装;无需悬浮窗权限。
apkUrl是 APK 下载地址,目前通过gh-proxy.org转发 GitHub Release 附件。apkSha256用于下载完成后的完整性校验。force预留强制更新能力,当前普通更新可选择稍后再说。update.json放在 GitHub 仓库根目录,随main分支更新后,应用会通过 raw 地址读取。- APK 附件上传到 GitHub Release,
update.json中的apkUrl指向对应 GitHub Release 附件。 git push只会上传代码和 tag,不会自动上传 Release 附件。
环境要求:
- JDK 17
- Android SDK
- 使用项目内 Gradle Wrapper
AI 找片配置:
- APK 默认使用打包时配置的
TVBOX_AI_API_KEY和内置 Agnes 参数。 - 用户可在设置页选择 Agnes、DeepSeek、SiliconFlow 或 Qwen。
- 模型名称和 API Key 不需要用遥控器输入;点击“模型”或“API Key”按钮后,电视会弹出二维码,手机扫码填写后自动同步到电视。
- 设置页只有手机提交了 API Key 后才会覆盖 APK 内置 AI 配置;未填写时继续使用默认配置。
打包时的默认 API Key 可放在本地配置中:
TVBOX_AI_API_KEY=你的测试密钥TVBOX_AI_API_KEY 可以放在 local.properties、Gradle 属性或环境变量中。local.properties 已被 .gitignore 忽略,不会上传到仓库。
视频接口配置:
- 内置视频接口保留在 APK 中,不会被用户配置覆盖。
- 设置页“视频接口”可选择当前首页、搜索和 AI 找片使用的数据源。
- 点击“添加接口”后,电视弹出二维码;手机扫码填写接口名称和 MacCms 地址,确认后自动同步到电视。
- MacCms 地址示例:
https://example.com/api.php/provide/vod
平台直播服务配置:
- 服务端运行在电脑或服务器上,TVBox 通过
TVBOX_PLATFORM_LIVE_SERVICE_URL访问统一接口。 - 本次 v1.3.3 Debug 构建使用的服务地址为
http://20.205.10.127:8868。 - Windows PowerShell 临时构建配置:
$env:TVBOX_PLATFORM_LIVE_SERVICE_URL="http://20.205.10.127:8868"
.\gradlew.bat testDebugUnitTest assembleDebug --console=plain- 该变量只在构建时注入 APK,不需要写入服务器代码;服务器 Cookie 只配置在服务器环境变量中。
- 如果服务器地址变化,必须使用新地址重新构建 APK;不要填写
localhost或127.0.0.1。
运行测试:
.\gradlew.bat testDebugUnitTest --console=plain构建 debug APK:
.\gradlew.bat assembleDebug --console=plain构建 release APK:
.\gradlew.bat assembleRelease --console=plainrelease APK 输出位置:
app\build\outputs\apk\release\app-release.apk
release 签名信息从 local.properties、Gradle 属性或环境变量读取,密钥文件不会提交到仓库。
需要配置:
TVBOX_RELEASE_STORE_FILE=signing/xxx.jks
TVBOX_RELEASE_STORE_PASSWORD=***
TVBOX_RELEASE_KEY_ALIAS=***
TVBOX_RELEASE_KEY_PASSWORD=***签名校验:
apksigner verify --print-certs app\build\outputs\apk\release\app-release.apk- 更新版本号、CHANGELOG 和 README;构建签名 APK 后,根据实际 SHA-256 和大小填写根目录
update.json。 - 仅暂存本次发布涉及的主工程代码及文档;如开发日志含无关修改,使用分段暂存。
git add CHANGELOG.md README.md update.json app\build.gradle.kts app\src\main app\src\test app\src\debug devLog\home-player-ui.md devLog\playback-experience.md devLog\release.md
git add -p devLog\README.md
git commit -m "Release v1.3.14"
git tag -a v1.3.14 -m "TVBox v1.3.14"
git push origin v1.3.14- 创建草稿 Release 并上传 APK 与相同版本的 OTA 清单,检查附件完整性。
gh release create v1.3.14 app\build\outputs\apk\release\TVBox-v1.3.14.apk app\build\outputs\apk\release\update.json --repo ZxxXinI/tvbox --verify-tag --draft --title "TVBox v1.3.14" --notes-file app\build\outputs\apk\release\release-notes.md- 公开 Release 后推送主分支,使 OTA 清单指向已经可下载的附件。
gh release edit v1.3.14 --repo ZxxXinI/tvbox --draft=false --latest
git push origin mainGitHub Release 包含对应版本的 APK 和
update.json;应用启动时从 GitHubmain分支读取更新清单。
app/src/main/java/com/tvbox/app
├── data # API、仓库、历史记录、OTA、直播数据
├── domain # 领域模型与解析规则
├── ui # Compose 页面、播放器、直播页
└── MainActivity.kt
- Kotlin
- Jetpack Compose
- Compose for TV 基础能力
- Media3 ExoPlayer
- Retrofit / OkHttp
- kotlinx.serialization
- Coil
详细变更见 CHANGELOG.md。
- LINUX DO — 新的理想型社区 / A new ideal community