港澳台直播开发文档

这个项目是什么

港澳台直播是一个 Android TV 直播播放器（Kotlin + Media3/ExoPlayer），内置香港、澳门、台湾三个分组共 55 个频道，装上就能用遥控器换台。项目完全免费可用（每天 1 小时，可升级会员），无广告、无第三方 SDK，播放源在 App 内实时解析，不依赖任何中转服务——它只是一个播放器外壳，不存储、不转播任何视频内容。

面向二次开发者的定位：一个「遥控器优先」的电视直播壳工程，可以换频道源、改授权对接、调整交互模型。

技术栈与架构

语言与构建：Kotlin，Android Gradle Kotlin DSL（build.gradle.kts），JDK 17（sourceCompatibility / jvmTarget = 17）。
播放：Android Media3 / ExoPlayer 1.3.1（media3-exoplayer、media3-exoplayer-hls、media3-ui、media3-datasource），支持 FLV 直播流与 HLS。
兼容层：androidx.core:core-ktx 1.12.0、androidx.appcompat 1.6.1、androidx.webkit 1.9.0，Leanback 兼容让 TV 桌面出现横幅图标。
SDK 范围：minSdk 21（Android 5.0+）、compileSdk/targetSdk 35，包名 com.iptv807.tv，横屏。
播放链路：App 内实时解析播放页（Referer / 302 跟随 / FLV 直播流）→ 内存 + 磁盘三级缓存 → 断流自动换线路 → token 过期自动刷新源。
接入服务端：https://auth.88531.cn（请求头 X-Api-Key），负责安装统计、版本推送与卡密/订单校验，接口文档见 auth.88531.cn/#/docs。

仓库结构

路径	作用
`app/build.gradle.kts`	应用模块构建脚本：SDK 版本、签名配置、Media3 依赖
`app/src/main/`	Kotlin 源码与资源（唯一源码模块）
`app/proguard-rules.pro`	混淆规则（release 当前 `isMinifyEnabled = false`）
`apk/`	各版本 APK 存档（当前为 `gangao-tv-v9.3.0.apk`）
`assets/`	`banner.png`、`icon.png` 等宣传与图标素材
`build.gradle.kts` / `settings.gradle.kts` / `gradle.properties`	根工程与 Gradle 配置（仓库未附带 `gradlew` wrapper）
`CHANGELOG.md`	逐版本更新日志（v1.x 起，当前记录到 v9.3.0）
`LICENSE` / `README.md`	MIT 许可与项目说明

本地开发环境

仓库没有 gradlew wrapper，需要本机已装 Android SDK 与 Gradle：

git clone http://127.0.0.1:3200/jinghui/gangao-tv.git
cd gangao-tv
gradle assembleDebug        # 调试包，无需签名配置
gradle assembleRelease      # 正式包，读取 keystore.properties

app/build.gradle.kts 从仓库根目录的 keystore.properties 读取 storeFile、storePassword、keyAlias、keyPassword（该文件已 .gitignore，缺失时不影响 debug 构建，只是 release 拿不到签名）。versionCode / versionName 同样在这个文件的 defaultConfig 里（当前 versionCode 961、versionName 9.6.1）。

配置项说明

配置键	当前值	含义
`applicationId` / `namespace`	`com.iptv807.tv`	包名
`minSdk`	`21`	Android 5.0 及以上
`compileSdk` / `targetSdk`	`35`	编译与目标 SDK
`versionCode` / `versionName`	`961` / `9.6.1`	应用版本（发版时必须与 CHANGELOG、`apk/` 同步）
`keystore.properties`	仓库根目录、不入库	release 签名四项
`media3-*`	`1.3.1`	ExoPlayer 全家桶版本
接入服务端	`https://auth.88531.cn`	安装登记 / 心跳 / 版本检查 / 卡密校验，`X-Api-Key` 请求头

权限方面，v9.3.0 起新增 REQUEST_INSTALL_PACKAGES、POST_NOTIFICATIONS（应用内下载 APK 并拉起安装所需）。

构建与发布

gradle assembleRelease    # 产物在 app/build/outputs/apk/release/

发布一个新版本前依次完成三件事：versionCode +1 并更新 versionName；在 CHANGELOG.md 追加该版本条目；把新 APK 放入 apk/ 目录并同步更新 Releases 页。

签名链路：keystore.properties（存在时）→ signingConfigs.release → buildTypes.release；release 未开混淆（isMinifyEnabled = false），proguard-rules.pro 保留但未实际生效。

二次开发要点

遥控器交互是自绘的，不走系统焦点：选台面板的高亮（选中行蓝底）、上下左右移动、OK 确认全部由按键逻辑直接处理——历史上把按键交给系统焦点后，在部分盒子上焦点进不了列表导致「换不了台」。同理，设置页/商店页的可操作项用 StateListDrawable（获得焦点即变蓝），不要用 setBackgroundColor 固定底色覆盖系统焦点高亮。
每频道独立锁：解析原用全局锁，后台预取占锁时用户切台要排队；改为每频道独立锁后切台不再阻塞。源站 m.iptv807.com 抓播放页 1～7 秒且失败率不低，token 与频道绑定（换频道复用会 404），所以切到没打开过的频道必须现抓一次。
缓存策略：频道源缓存 30 分钟（改回秒开的关键），预取只抓当前高亮的那一行（1.2 秒去抖动），全部线路失败时自动强制刷新源再试一轮。
加载遮罩要加 awaitingStart 标记：只有新频道真正起播才收起遮罩，否则旧频道的缓冲回调会把提示一闪而过（v9.1.0 修的 bug，改动播放回调时别退回去）。
退出弹窗必须 App 内自绘：电视全屏主题下 AlertDialog 会创建失败且异常被兜底吞掉，直接无提示退出。
返回画面定格：从设置页/桌面返回直接重连当前流，不依赖 play()；「▶ 继续播放」按钮走同一重连逻辑。
版本号一致性：README 的下载链接曾指向 v9.2.0、apk/ 目录实为 v9.3.0、build.gradle.kts 已是 9.6.1 而 CHANGELOG 只记录到 v9.3.0——发版时三处要一起更新，文档以 apk/ 目录实际文件与 Releases 为准。
测试卡密：v8.5.0 起内置测试卡密 88531（本地判定、不走服务器，显示「测试卡：永久有效」），用于验证购买/时长逻辑，正式卡密走 /api/public/verify。
早期版本（v1.x～v6.x、v7.0.1）的 APK 因当时无 git 历史已删除且无法恢复，自 v8.3.0 起不再删除任何版本。

港澳台直播 开发文档