# Android TV

**Repository Path**: licq_workspace/android

## Basic Information

- **Project Name**: Android TV
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Android TV 直播 hongmeng-tv（Android 版）

> 基于 **Kotlin + Jetpack Compose + Media3（ExoPlayer）** 的电视直播与视频播放应用，**单 APK 同时适配电视/盒子与手机**：安装时自动识别目标设备——TV 走遥控器按键交互，手机走手势交互，功能两端对齐。

**搜索关键词**：Android TV ・ Leanback ・ Jetpack Compose ・ ExoPlayer / Media3 ・ Kotlin ・ HLS / m3u8 ・ IPTV ・ 电视直播 ・ 直播源 ・ 切换播放源 ・ OkHttp ・ 机顶盒应用开发

---

## ✨ 功能特性

### 📺 电视直播（重点）

- **300+ 频道开箱即用**：内置经全量测活的预过滤源快照（`assets/live_filtered.m3u`），启动零等待，无需任何配置
- **一个频道一条，备源不占列表**：列表干净无重复；每频道最多 3 路源，多源频道带 `N源` 角标
- **播放页一键切源**：`切源 n/m` 手动循环切换；播放失败 / 起播超时 10 秒自动切换备用源（连续 5 次失败才提示）
- **分类 + 搜索 + 收藏 + 历史**：央视 / 卫视 / 国际 / 港澳台 / 专题 / 地类标签，可与关键词搜索叠加；收藏星标一键切换，播放历史自动记录（上限 50 条）
- **EPG 节目单**：公共 XMLTV 源（双地址兜底）+ 12 小时本地缓存，列表与播放页显示"正在播 / 接下来"；失败自动隐藏不影响使用
- **全部源视图**：过滤前 1700+ 条原始源同样可按分类浏览，带 `已验证 / 未验证` 标注
- **m3u 订阅**：自定义订阅地址自动解析（去重 → 测活 → 每频道保留 3 个可用源），订阅原文本地留存

### 📱 手机 / 🕹 TV 双端交互

| 场景 | 手机（手势） | TV（遥控器） |
| --- | --- | --- |
| 播放页单击 / OK 键 | 全屏时呼出/隐藏控制栏；非全屏播放/暂停 | 呼出控制栏 |
| 双击 | 播放 / 暂停 | — |
| 左右滑 / 左右键 | 直播换台；点播快进退 ±10s | 直播切源；点播快进退 ±10s |
| 上下滑 / 上下键 | 直播切换备用源 | 直播换台 |
| 返回键 | 退出全屏 → 返回列表 | 退出全屏 → 返回列表 |
| 选台 | 点按频道条目 | 焦点导航（放大描边高亮）+ OK 选台 |
| 全屏 | 横屏 + 沉浸式 | 天然全屏横屏 |

- 设备识别：`UiModeManager` UI 模式为电视，或系统声明 `FEATURE_LEANBACK` → TV 模式；否则手机模式
- TV 端功能与手机端对齐：分类侧栏 / 搜索 / 收藏 / 历史 / EPG / 开机自动进入当前频道
- 清单声明 `touchscreen`、`leanback` feature 均为非必需：**无触屏的老旧电视盒子也可安装**

### 🎬 点播播放

- 本地 assets 视频 + 在线 MP4 / HLS 片源，自定义片源可持久化保存
- `Media3 ExoPlayer` + `PlayerView`：播放/暂停、进度拖动、点播循环、按视频真实比例渲染（letterbox 不拉伸）、屏幕常亮、加载/失败提示

## 🛠 技术栈

| 项 | 说明 |
| --- | --- |
| 语言/UI | **Kotlin** + Jetpack Compose（Material3），单 Activity + Navigation |
| 媒体播放 | **Media3 / ExoPlayer** + PlayerView（本地 assets / HTTP-HLS 直播） |
| 网络请求 | **OkHttp**（常规 / 测活 / EPG 三组超时配置） |
| 架构 | ViewModel + StateFlow + Coroutines；SharedPreferences 持久化（收藏/历史/订阅/免责声明） |
| 构建 | Gradle 8.10 + AGP 8.7，**minSdk 21**（覆盖 Android 5.0+ 老盒子）/ targetSdk 35 |
| 测试 | JUnit + MockK + coroutines-test（M3U 解析 / 频道归一化分组 / 测活流水线 / EPG 解析） |

## 🚀 快速开始

1. 安装 [Android Studio](https://developer.android.com/studio)（Ladybug 及以上）
2. `File > Open` 打开本工程，等待 Gradle Sync 完成
3. 连接设备（电视 / 盒子 / 手机，或新建 **Android TV 模拟器**）点击 Run

命令行构建：

```bash
./gradlew assembleDebug            # Debug APK → app/build/outputs/apk/debug/
./gradlew assembleRelease          # Release（未配置签名，仅出未签名包）
./gradlew testDebugUnitTest        # 单元测试
```

安装到电视/盒子：`adb install -r app/build/outputs/apk/debug/app-debug.apk`

## 📡 直播源说明与来源

- 内置播放列表为**预过滤快照**：由 `scripts/refresh_sources.py` 对多份公开源仓库全量去重、测活后生成（2026-09-16：1762+145 个源 → 约 320 个可用频道），生成脚本流程：多仓库拉取 → URL 去重 → 名称归一化分组 → 并发测活 → 每频道保留 ≤3 个可用源。
- **刷新快照**（Python 3.8+，仅标准库）：

  ```bash
  python3 scripts/refresh_sources.py             # 使用仓库内原始快照（离线）
  python3 scripts/refresh_sources.py --remote    # 额外拉取 6 个公共源仓库的最新清单
  ```

- **定时自动刷新**：`scripts/cron_refresh.sh` 会拉取最新代码、执行过滤脚本并在快照有变化时自动提交推送。配置 crontab 每日执行即可（也可接入 Gitee Go / GitHub Actions schedule）：

  ```bash
  10 6 * * * /path/to/android-tv/scripts/cron_refresh.sh >> /tmp/android_tv_refresh.log 2>&1
  ```

- 来源均为 **GitHub 公开开源索引项目**：`iptv-org/iptv`、`Guovin/iptv-api`、`vbskycn/iptv`、`YanG-1989/m3u`、`fanmingming/live` 等。本项目不抓取、不破解任何私有/付费内容。
- 直播源时效性强（公共源随时失效属正常现象）。刷新方式：执行上述脚本重新生成快照，或在 App 内配置 m3u 订阅地址在线过滤。
- 过滤前的完整原始快照同样保留在 `assets/`（`live_guovin.m3u`、`live_vbskycn.m3u`），可在 App「全部源」视图中查看。

## ⚠️ 免责声明（重要）

1. **本项目仅供学习研究**，目的是演示 Android TV / Compose / Media3 / OkHttp 等开发技术。项目**不提供任何影视内容**，不存储、不制作、不传播任何受版权保护的音视频文件。
2. 仓库及内置快照中的频道地址全部来自**公共互联网的开源聚合索引**，本项目未对其合法性、授权状态做任何验证；地址的可用性与合法性不代表本项目立场。
3. **严禁**将本项目或其构建产物用于任何商业用途，或向公众分发、诱导用户观看未经授权的内容。请在下载后 24 小时内自行评估并删除，使用行为须符合所在国家/地区的法律法规。
4. 若你是相关内容的权利人，认为本仓库引用的地址侵犯了你的合法权益，请通过 Issue 或仓库主页联系方式告知，**核实后将立即移除**相关内容。
5. 因使用本项目而产生的任何直接或间接后果，由使用者自行承担；本项目开发者不承担任何法律责任。

## 📂 工程结构

```
android-tv/
├── app/src/main/
│   ├── AndroidManifest.xml          # INTERNET + 明文流量 + leanback/touchscreen feature
│   ├── assets/                      # video.mp4 + 直播源快照（filtered + intl + 原始留存）
│   └── kotlin/com/licq/tv/
│       ├── TvApp / MainActivity     # 单 Activity 入口 + 轻量手动依赖容器
│       ├── core/                    # DeviceFormFactor 设备识别 / SettingsStore / LiveSession
│       ├── data/
│       │   ├── model/               # LiveChannel / VideoItem / M3uParser / ChannelFilter
│       │   ├── LiveCatalog          # 预过滤快照加载 + 同名归并（主源 + alts 备源）
│       │   ├── BuiltinChannels      # 人工验证兜底频道
│       │   ├── StreamProbe          # 直播源测活（2xx + #EXTM3U + 5s 超时）
│       │   ├── EpgService           # XMLTV 节目单（双源 + 12h 缓存）
│       │   └── FavoriteStore / VideoStore
│       ├── net/                     # OkHttp 网络层（fetchText + 三组超时）
│       ├── player/                  # PlayerViewModel：换台/切源状态机 + 10s 看门狗自动换源
│       └── ui/                      # Compose 界面（home / live / tv / player / disclaimer）
└── scripts/                         # PC 端快照生成与定时刷新（与 App 无耦合）
```

## 📦 从鸿蒙版（HarmonyOS ArkTS）迁移对照

| 鸿蒙版 | Android 版 |
| --- | --- |
| EntryAbility 设备分流（tv → TvLive） | `DeviceFormFactor`（UiModeManager + leanback feature）→ 导航起始页分流 |
| ArkUI @State + LiveStore 静态类 | ViewModel + StateFlow + AppContainer 内 LiveSession |
| AVPlayer + XComponent(surface) | Media3 ExoPlayer + PlayerView（RESIZE_MODE_FIT） |
| RCP（RemoteCommunicationKit）三组会话 | OkHttp 三组超时配置（default / probe / epg） |
| preferences 行式存储 | SharedPreferences（键名与格式完全沿用） |
| rawfile 快照 + video.mp4 | assets 原样迁入 |
| 遥控器 onKeyEvent（DPAD 上/下换台） | onPreviewKeyEvent 分发（上/下/左/右/OK/BACK） |
| TvLive 宫格焦点 | Compose 焦点系统（focusable + onFocusChanged + 放大描边），并补齐分类/搜索/收藏/历史/EPG |

## 🤝 参与贡献 & 许可证

1. Fork 本仓库 → 新建 `Feat_xxx` 分支 → 提交 PR
2. 欢迎补充：直播源测活脚本参数化、EPG 完整节目单时间轴、频道 Logo 缓存、画中画
3. 本项目基于 [木兰宽松许可证第 2 版（Mulan PSL-2.0）](./LICENSE) 开源