项目名称 ：cocoTV 项目类型 ：网络电视直播聚合播放平台 开发语言 ：Python / JavaScript 技术栈 ：FastAPI + React + SQLite
cocoTV 是一款面向家庭用户的网络电视直播聚合平台，旨在为用户提供便捷、高效的电视直播观看体验。系统采用前后端分离架构，支持本地化部署，开箱即用。
本项目的开发初衷源于一个真实的家庭需求场景：当家中的电视机或机顶盒出现故障时，家庭成员往往面临无法及时观看电视直播节目的困境。传统的解决方案（如等待维修、购买新设备）存在时间成本高等问题。
cocoTV 的设计理念是： 让任何一台联网设备都能快速变身为电视终端 。用户只需在电脑上启动应用程序，即可通过浏览器访问直播服务，实现电视节目的即时观看，有效解决了设备故障期间的应急观看需求。
功能 说明 M3U/M3U8 导入 支持本地文件上传及远程 URL 导入直播源 自定义直播源 手动添加、编辑和管理个性化直播频道 多清晰度支持 同一频道可配置多个不同清晰度的播放源 批量导入 支持批量添加直播源，最多单次 500 个
- 分类浏览 ：按频道类别（央视、卫视、地方台等）分类展示
- 收藏夹 ：收藏常观看频道，快速访问
- 观看历史 ：自动记录观看历史，便于追溯
- 频道搜索 ：快速定位目标频道
- HLS 流播放 ：基于 hls.js 实现流畅的 HLS 直播流播放
- 多源切换 ：同一频道多源自动切换，保障播放稳定性
- 跨域代理 ：内置 M3U8/TS 代理服务，解决跨域播放问题
- 直播源有效性检测 ：自动验证直播源可用性，过滤失效频道
- 响应时间测试 ：评估直播源服务器响应速度
- 配置备份与恢复 ：支持用户配置数据的导出与导入
- M3U 文件导出 ：整理后的直播源可导出为标准 M3U 格式
┌─────────────────────────────────────────────────────────┐
│ cocoTV 系统架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ HTTP/WS ┌─────────────────────┐ │
│ │ Browser │ ◄──────────► │ Frontend │ │
│ │ (用户界面) │ │ React + Ant Design │ │
│ └─────────────┘ └──────────┬──────────┘ │
│ │ API Calls │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ Backend │ │
│ │ FastAPI + Uvicorn │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌─────────────────────┼─────────────┤
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ SQLite │ │ 直播源服务 │ │
│ │ (数据存储) │ │ (外部接口) │ │
│ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
后端技术栈：
-
FastAPI：高性能异步 Web 框架
-
Uvicorn：ASGI 服务器
-
SQLAlchemy：ORM 数据库操作
-
SQLite：轻量级嵌入式数据库
-
Requests：HTTP 请求处理 前端技术栈：
-
React 19：现代化 UI 框架
-
Ant Design 6：企业级 UI 组件库
-
React Router 7：路由管理
-
hls.js：HLS 流播放器
-
Tailwind CSS：原子化 CSS 框架
-
Vite 8：构建工具
Channel (频道)
├── id: 主键
├── name: 频道名称
├── category: 分类
├── logo: 图标
└── streams: Stream[] (播放源列表)
Stream (播放源)
├── id: 主键
├── channel_id: 所属频道
├── url: 播放地址
├── quality: 清晰度
├── is_default: 是否默认
└── is_active: 是否可用
CustomSource (自定义源)
FavoriteChannel (收藏频道)
WatchHistory (观看历史)
UserSettings (用户设置)
cocoTV_integrated/
├── cocoTV.exe # 编译后的可执行文件
├── main.py # 应用入口
├── requirements.txt # Python 依赖
├── app/ # 后端模块
│ ├── api.py # API 路由
│ ├── database.py # 数据模型
│ ├── config.py # 配置管理
│ ├── live_source.py # 直播源管理
│ ├── m3u_parser.py # M3U 解析器
│ ├── cache.py # 缓存模块
│ ├── proxy_cache.py # 代理缓存
│ ├── middleware.py # 中间件
│ └── logging_config.py # 日志配置
├── frontend/ # 前端项目
│ ├── src/
│ │ ├── pages/ # 页面组件
│ │ ├── components/ # 公共组件
│ │ ├── contexts/ # React Context
│ │ └── utils/ # 工具函数
│ └── package.json
├── static/ # 前端构建产物
├── data/ # 数据目录（运行时生成）
└── tests/ # 测试用例
- 操作系统：Windows 10/11
- 网络：需要互联网连接以获取直播流
本项目已编译为独立可执行文件，无需安装 Python 环境即可运行。
使用步骤：
- 双击运行 cocoTV.exe
- 程序启动后将自动打开浏览器访问应用界面
- 如浏览器未自动打开，手动访问 http://localhost:8000 首次运行说明：
- 程序启动时会自动创建 data 目录存储数据库
- 首次启动可能需要几秒钟初始化直播源数据
- 默认端口为 8000，如被占用将自动切换到可用端口
如需基于源码运行或进行二次开发：
环境要求：
- Python 3.10+
- Node.js 18+（前端开发需要） 运行步骤：
# 安装后端依赖
pip install -r requirements.txt
# 启动应用
python main.py
前端开发：
cd frontend
npm install
npm run dev
构建前端：
cd frontend
npm run build
构建产物将输出到 static 目录。
如需自行编译可执行文件：
# 安装 PyInstaller
pip install pyinstaller
# 编译
pyinstaller cocoTV.spec
编译产物位于 dist 目录。
- 应急替代方案 ：电视设备故障时的即时观看解决方案
- 零安装成本 ：无需复杂的有线电视线路铺设
- 操作简便 ：直观的 Web 界面，适合大多年龄段用户
- 数据本地化 ：所有数据存储于本地，保护用户隐私
- 轻量级架构 ：基于 SQLite 嵌入式数据库，无需额外数据库服务
- 跨域代理 ：内置流媒体代理服务，解决浏览器跨域限制
- 智能检测 ：直播源有效性自动检测与过滤
- 端口自适应 ：自动检测可用端口，避免端口冲突
- 可执行打包 ：支持打包为独立可执行程序，开箱即用
- ✅ 直播源导入与管理
- ✅ 频道分类浏览
- ✅ HLS 流播放
- ✅ 收藏与历史记录
- ✅ 配置备份恢复
- ✅ 多源自动切换
- ✅ 直播源有效性检测
- 支持 RTMP、FLV 等更多流媒体协议
- 添加电子节目单（EPG）功能
- 支持多用户账户管理
- 移动端适配优化
- Docker 容器化部署支持
开发动机 ：解决家庭电视设备故障时的应急观看需求，让家人能够快速恢复电视节目的正常观看。因为我的家人喜欢观看电视台直播，会使用电脑，并且我发现现在可以观看电视台直播的app和网页数量少,且频道不多，所以我使用solo在1天内做好了cocoTV电视台直播播放器，方便了家人继续观看直播