# freetv

**Repository Path**: jasonmayun/freetv

## Basic Information

- **Project Name**: freetv
- **Description**: freetv是个免费电视播放器，播放资源来自本地或者网络电视
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 3
- **Created**: 2023-11-10
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FreeTV

#### 项目介绍

FreeTV 是一个专为 Android TV 平台设计的免费电视播放器应用。支持播放本地和网络视频资源，适用于数字标牌、广告屏、企业信息展示等场景。应用采用 Android Leanback 库构建，提供流畅的 TV 界面体验。

**主要特性：**
- 📺 支持视频、图片、文本、幻灯片等多种媒体类型混合播放
- 🔄 自动循环播放节目列表
- 📅 支持节目时间控制（生效时间、过期时间、播放时长）
- 💾 U盘资源自动更新
- 🔄 应用自动更新功能
- 🚀 开机自启动
- 💪 崩溃自动重启
- 📱 完整的 TV 界面体验

#### 软件架构

```
FreeTV
├── 主界面模块
│   ├── MainActivity - 主入口Activity
│   ├── MainFragment - 浏览界面Fragment
│   ├── DetailsActivity - 详情页面
│   └── PlaybackActivity - 视频播放页面
│
├── 广告/节目播放模块
│   ├── AdActivity - 广告播放主Activity
│   ├── Program - 节目管理类
│   ├── Video - 视频播放组件
│   ├── Image - 图片展示组件
│   ├── Text - 文本显示组件
│   └── Slide - 幻灯片组件
│
├── 资源管理模块
│   ├── AssetsListManager - 资源列表管理
│   ├── PlayListManger - 播放列表管理
│   └── FileUtils - 文件工具类
│
├── 系统服务模块
│   ├── BootReceiver - 开机启动接收器
│   ├── UpdateService - 更新服务
│   ├── AutoUpdater - 自动更新器
│   └── UsbReceiver - USB设备监听
│
└── 工具模块
    ├── Http - HTTP请求工具
    ├── CrashExceptionHandler - 崩溃处理
    ├── SystemUtils - 系统工具
    └── XmlUtils - XML解析工具
```

**技术栈：**
- **UI框架**: Android Leanback、Material Design
- **视频播放**: ExoPlayer (Media3)
- **图片加载**: Glide
- **JSON解析**: Gson
- **最低支持**: Android 5.0 (API 21)
- **目标版本**: Android 14 (API 34)

#### 开发环境要求

- Android Studio Hedgehog | 2023.1.1 或更高版本
- JDK 8 或更高版本
- Android SDK API 34
- Gradle 7.4.2 或更高版本

#### 安装教程

**方式一：通过 Android Studio 编译安装**

1. 克隆项目到本地
   ```bash
   git clone [项目地址]
   cd freetv
   ```

2. 使用 Android Studio 打开项目

3. 等待 Gradle 同步完成

4. 连接 Android TV 设备或启动 TV 模拟器

5. 点击运行按钮或使用快捷键 `Shift+F10` 编译并安装

**方式二：直接安装 APK**

1. 在 `app/build/outputs/apk/release/` 目录找到编译好的 APK 文件
   - Debug版本: `freetv_YYYYMMDD_debug.apk`
   - Release版本: `freetv_1.1.8_release.apk`

2. 将 APK 文件传输到 Android TV 设备

3. 在 TV 设备上使用文件管理器打开 APK 文件进行安装

**方式三：通过 U盘安装**

1. 将 APK 文件复制到 U盘根目录

2. 将 U盘插入 Android TV 设备

3. 应用会自动检测并提示安装更新

#### 使用说明

**首次启动：**

1. 应用启动后会自动请求必要的权限（存储权限、安装权限等）
2. 首次运行会初始化资源，请耐心等待
3. 如果设备已插入 U盘，应用会自动检测并更新资源

**资源更新（通过 U盘）：**

1. 准备资源包：
   - 在 U盘根目录创建 `freetv.zip` 压缩包
   - 压缩包内需包含：
     - `playlist_[SHA1哈希值].json` - 播放列表配置文件
     - 视频、图片等媒体资源文件

2. 插入 U盘到 Android TV 设备

3. 应用会自动检测并更新资源：
   - 扫描 U盘中的 `freetv.zip` 文件
   - 验证播放列表文件
   - 解压并复制资源文件到应用缓存目录
   - 更新播放列表配置
   - 自动重新初始化并开始播放

**播放列表配置格式：**

播放列表使用 JSON 格式，包含以下信息：
- 节目列表（programs）
- 每个节目包含：
  - 名称（name）
  - 生效时间（effect_time）
  - 过期时间（expiration_time）
  - 播放时长（total_time）
  - 视图配置（view）- 包含视频、图片、文本等元素

**应用更新：**

1. 将新版本 APK 文件放入 U盘根目录
2. 插入 U盘后，应用会自动检测并提示安装
3. 确认安装后，应用会自动更新

**主要功能：**

- **浏览模式**：在 MainActivity 中浏览视频列表，支持分类查看
- **详情查看**：点击视频卡片查看详细信息
- **视频播放**：支持播放本地和网络视频
- **自动播放**：AdActivity 模式下自动循环播放节目列表
- **时间控制**：自动跳过过期或未生效的节目

#### 权限说明

应用需要以下权限：

- **存储权限**：读取和写入外部存储，用于资源文件管理
- **网络权限**：访问网络资源
- **安装权限**：自动更新应用（需要系统签名）
- **开机启动权限**：开机自动启动应用
- **电池优化白名单**：确保应用在后台正常运行
- **USB 权限**：检测和管理 USB 存储设备

#### 构建说明

**Debug 版本：**
```bash
./gradlew assembleDebug
```
输出文件：`app/build/outputs/apk/debug/freetv_YYYYMMDD_debug.apk`

**Release 版本：**
```bash
./gradlew assembleRelease
```
输出文件：`app/build/outputs/apk/release/freetv_1.1.8_release.apk`

**注意事项：**
- Release 版本需要配置签名文件（`adtv.jks`）
- 在 `gradle.properties` 中配置签名信息

#### 常见问题

**Q: 应用无法启动？**
A: 检查是否授予了所有必要权限，特别是存储权限和安装权限。

**Q: U盘资源更新失败？**
A: 确保：
- U盘根目录存在 `freetv.zip` 文件
- 压缩包内包含有效的播放列表文件（格式：`playlist_[SHA1].json`）
- 设备有足够的存储空间

**Q: 视频无法播放？**
A: 检查：
- 视频文件是否存在且完整
- 视频格式是否支持（MP4、AVI、MOV、MKV等）
- 网络连接是否正常（网络视频）

**Q: 节目不播放？**
A: 检查节目的时间设置：
- 生效时间是否已到
- 过期时间是否已过
- 播放时长是否大于0

#### 参与贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 新建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 新建 Pull Request

#### 版本历史

- **v1.1 (versionCode 8)**: 当前版本
  - 支持多种媒体类型混合播放
  - U盘资源自动更新
  - 应用自动更新功能
  - 崩溃自动重启

#### 相关链接

- [Android Leanback 文档](https://developer.android.com/training/tv/start/start)
- [ExoPlayer 文档](https://exoplayer.dev/)
- [Gradle 镜像](https://mirrors.cloud.tencent.com/gradle/)

#### 许可证

请查看 LICENSE 文件了解详情。