# TVBoxOSC

**Repository Path**: ycgpp/TVBoxOSC

## Basic Information

- **Project Name**: TVBoxOSC
- **Description**: No description available
- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2024-05-01
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TVBoxOSC

Android 电视 / 机顶盒影音播放器。本身不含片源，运行时通过可配置的远程“源”（API）拉取内容，并用可插拔的 Spider 爬虫（支持加载外部 JAR）解析。适配遥控器 D-pad 操作的横屏 TV 界面。

> 当前界面为 **极简扁平 + 现代卡片网格**的深色 TV 设计，主色为橙红 `#FF6A00`，完整规范见 [`design-system/MASTER.md`](design-system/MASTER.md)。

## 功能特性

- 远程“源”管理：通过 `ApiConfig` 加载 / 切换不同的内容源与解析器。
- 可插拔爬虫：基于 `com.github.catvod.crawler` 的 Spider / JarLoader，支持加载外部爬虫 JAR。
- 本地控制服务：内置基于 NanoHTTPD 的 HTTP 服务（`server/`），可通过浏览器 / 推送远程控制。
- 点播与直播：含详情、播放、搜索、收藏、历史、设置等页面，以及直播频道分组与换台。
- 播放能力：`:player` 模块封装 ExoPlayer 2.14.2 + DKPlayer 3.3.5。
- 本地持久化：使用 Room（数据库 schema 位于 `app/schemas`）与 Hawk 配置。

## 技术栈

| 类别 | 说明 |
|------|------|
| 语言 | Java 8（无 Kotlin） |
| 构建 | Gradle 6.7.1 + Android Gradle Plugin 4.2.1 |
| 工程 | 根工程 `TVBox`，含 `:app`（应用）与 `:player`（库）两个模块 |
| 平台 | compileSdk 30 / minSdk 16 / targetSdk 26 |
| 架构 | `:app` 依赖 `:player`；主入口 `base/App`，Launcher 为 `HomeActivity` |
| 关键库 | OKGo（HTTP）、Hawk（配置）、LoadSir（状态页）、AutoSize（1280×720 设计基准）、xWalk（Web 容器）、NanoHTTPD（控制服务）、Room |
| ABI | NDK `abiFilters` 仅 `armeabi-v7a`，产物仅支持 32 位 ARM |

## 项目结构（核心）

```
app/src/main/java/com/github/tvbox/osc/
├── api/        ApiConfig：远程源与解析器管理
├── base/       App：Application 入口
├── bean/       数据模型
├── cache/      Room 数据库
├── server/     本地 NanoHTTPD 控制服务
├── ui/         activity / fragment / adapter / dialog / tv 控件
├── util/       工具（HawkConfig、OkGoHelper、PlayerHelper…）
└── player/     播放相关封装
app/src/main/java/com/github/catvod/crawler/   插件式 Spider 爬虫框架
player/          ExoPlayer + DKPlayer 播放库模块
```

## UI 设计系统

统一的极简扁平 / 卡片网格视觉语言，规范集中在 [`design-system/MASTER.md`](design-system/MASTER.md)（全局事实来源）：

- **颜色令牌**：`colors.xml` 语义令牌（`bg_*` / `surface_*` / `on_surface_*` / `accent*`），旧颜色名已重映射到新调色板。
- **复用 Drawable**：`bg_card`、`bg_panel`、`bg_chip`、`bg_card_focus`、`bg_sort_focus`、`bg_topbar` 等扁平圆角表面。
- **复用 Style**：`Widget.TV.Card` / `Widget.TV.Panel` / `Widget.TV.Button.Surface` 等（注意带点号样式已显式 `parent=""` 关闭隐式继承）。
- 焦点态：遥控器选中项使用橙红描边（`bg_card_focus`、`shape_*_focus` 等选择器），不改变布局尺寸以避免抖动。
- 单位沿用仓库既有 `mm`（物理尺寸缩放，保证不同尺寸电视视觉一致），**不改为 dp**。
- 注释与文档使用中文。

## 构建

### 环境要求

- **JDK**：项目 `sourceCompatibility/targetCompatibility = 1.8`（仅字节码级别）。构建工具 Gradle 6.7.1 + AGP 4.2.1，可用 **JDK 8 或 JDK 11** 运行 Gradle（JDK 11 可正常向下编译）。
- **Android SDK**：需本机已安装（compileSdk 30 / minSdk 16 / targetSdk 26）。并在仓库根目录自建 `local.properties`（已被 `.gitignore` 忽略，不会提交）：
  ```properties
  sdk.dir=/path/to/Android/Sdk
  ```
- **Crosswalk**：`xwalk_shared_library` 首次构建需联网从 `download.01.org` maven 拉取。
- 必须导出 `JAVA_HOME`，否则 `./gradlew` 报 `JAVA_HOME is not set`。本机已装 JDK 11 于 `/home/molong/opt/jdk11`：
  ```bash
  export JAVA_HOME=/home/molong/opt/jdk11
  export PATH=$JAVA_HOME/bin:$PATH
  # 永久生效：写入 ~/.bashrc 后 source ~/.bashrc
  ```

### 本地签名（.env）

敏感信息（keystore 路径 / 别名 / 密码）统一放在项目根目录 **`.env`**（已被 `.gitignore` 忽略，不入库）。复制 [`env.example`](env.example) 为 `.env` 并填入真实值：

```properties
TVBOX_STORE_FILE=/home/molong/tvbox-release.jks
TVBOX_KEY_ALIAS=tvbox
TVBOX_STORE_PASSWORD=你的store密码
TVBOX_KEY_PASSWORD=你的key密码
```

> 也可用同名环境变量覆盖 `.env` 中的值，避免写入文件。
> 仅当 `TVBOX_STORE_FILE` 存在时 `release` 包才会被签名；否则保持未签名（与 CI 行为一致，若启用 CI）。

### 命令

```bash
# 首次需赋予 gradlew 执行权限
chmod +x gradlew

# 清理并打包 Release APK（已签名，若已配置 .env）
./gradlew clean assembleRelease
```

产物位于 `app/build/outputs/apk/release/app-release.apk`。

> 标准 Gradle 任务名为 `assembleRelease`（R 大写）；若小写 `assemblerelease` 报错，请改用大写。

### 常见报错速查

| 现象 | 原因 / 解决 |
|------|------|
| `JAVA_HOME is not set` | 未导出 `JAVA_HOME`，按上文设置 |
| `SDK location not found` | 缺少 `local.properties` 或未写 `sdk.dir` |
| `Could not resolve xwalk_...` | Crosswalk 拉取失败，检查网络 / 镜像 |
| `resource style/Widget.TV not found` | 样式名点号隐式继承导致，已通过 `parent=""` 修复（见设计系统） |
| `keystore password was incorrect` | `.env` 中密码与生成 keystore 时不一致，请核对 |
| `assemblerelease` 失败 | 改用大写 `assembleRelease` |

## 许可证

参见仓库 `LICENSE`。