yujian0815 / fnmedia-ext

# 飞牛影视 · 在线资源扩展 (fnmedia-ext)
给飞牛影视增加在线能力：媒体库首页注入 **4 个豆瓣榜单库 + 4 个资源站海量分类库**（无限滚动、点开即播），并在**原生搜索**里聚合苹果 CMS 资源站的在线影视，用飞牛自带播放器**直接播放**。搜索结果默认**在线前排**。零侵入、完全可逆：不改官方二进制 / nginx / 数据库，靠 Unix Socket 原子接管。
> 点播源会随时间失效，因此本扩展**不做转存/STRM 落库**——即刷即播、即搜即播；源不可用时可在管理页删除或替换。
>
> 📌 各版本更新内容见 CHANGELOG.md。
> ⚠️ **免责声明**：本项目是开源免费的技术研究 / 个人媒体库工具，**本身不提供、不存储、不分发任何影视、图片或播放地址，也不内置资源数据库**；所有在线内容均来自互联网公开的第三方接口与公开榜单，版权归原权利人所有。本项目**不提供、不推荐、不解答任何资源站点的名称、地址或获取方法**，接口由使用者自行配置并自行核实合法性。仅供学习交流与个人合法观看自有 / 已授权内容，请勿商用或传播侵权内容；由此产生的法律责任由使用者自行承担。
## 适配版本
| 项目 | 已验证 / 要求 |
|---|---|
| fnOS | **1.2.0 及以上**（FPK manifest 最低要求） |
| 官方影视应用 | **trim.media `0.9.8-1`**（已实测） |
| CPU 架构 | `all`（纯 Python，安装时创建独立 venv） |
| 安装方式 | fnOS 应用中心手动安装 FPK，可安装在 `/vol1`、`/vol2` 等数据卷 |
| 依赖 | 官方「影视 (trim.media)」必须保持安装并启用 |
| 网络 | 资源站访问使用直连（`trust_env=False`），不读取代理环境变量 |
> 本扩展通过 Unix Socket 可逆接管官方影视接口，不改官方二进制、nginx 或数据库。未来若 fnOS / trim.media 升级后签名常量或接口结构变化，停用扩展会立即恢复官方服务，等待新版本适配。
## 下载安装
1. 打开 Releases，下载最新的 `fnmedia-ext- .fpk`。
2. 在 fnOS **应用中心 → 手动安装 FPK** 中选择该文件。
3. 选择应用安装所在存储卷，保持依赖应用 **影视 (trim.media)** 为运行状态。
4. 安装完成后启用「飞牛影视在线扩展」，桌面/应用内会出现 **影视在线扩展管理**。
5. 打开官方「影视」，直接搜索中文片名即可看到带 `【在线】` 标记的结果。
管理入口为应用内 iframe：`/app/fnmedia-ext/`；旧的直连路径 `/v/online-admin` 仍保留。卸载或停用扩展会自动把 `/var/run/trim_media.sock` 还原给官方影视服务。
## 工作原理
 [code] 
### 热门榜单媒体库（展示 / 播放解耦，对齐 LibreTV）
“热门”不再用资源站的「最近更新」冒充（那是“刚录入了什么”，不是“大家在看什么”，且电影稀少、
海报差、无评分）。改为与 LibreTV 相同的两层设计：
- **展示层（真实榜单）**：后台定时（默认每 6 小时）拉取豆瓣周榜 + 豆瓣官方 tag 推荐（经 60s 公开 API
 免 key 转发，实例失败自动回退），合成 4 个虚拟库 **🎬热门电影 / 📺热门剧集 / 🌸动漫新番 / 🎤热门综艺**，
 每库最多 160 部（豆瓣 tag 多标签多页聚合去重，综艺去重后约 130+），含豆瓣海报、评分、年份、简介；原子缓存到 `state/charts.json`，媒体库只读、秒开。
- **播放层（按需解析）**：榜单条目的 guid 是稳定的 chart guid，**点进详情时才用片名实时聚合搜索内置
 资源站**（复用搜索的跨源合并与相关性过滤），命中后把可播放 brief 挂到该 guid，复用既有
 详情/选集/多线路/续播/代理播放链；首次解析约几秒，之后命中内存/持久缓存秒开。源站没有的
 （部分新综艺）返回 can_play=0 与「暂无在线片源」，不误导用户。
- 容错：榜单全部失败/为空时保留旧缓存；豆瓣图床经 `/online/` 海报代理并带豆瓣 Referer，
 失败回退内联 SVG（HTTP 200）。兼容官方 `page/page_size` 分页、`tags.type`、`sort_column`
 （榜单次序即热度，也可按评分/年份/片名排序）。
- 管理页可开关、设置榜单刷新间隔(1-24h)、立即刷新。旧的“最近更新”库 guid 仍可打开（映射到热门剧集）。
### 海量分类片库（方案 C · 资源站全量深翻，无限滚动）
除精选榜单外，额外注入 4 个海量库 **🎞海量电影 / 📺海量剧集 / 🌸海量动漫 / 🎤海量综艺**，用于“一直往下刷”：
- 启动/每 6 小时拉取各资源站苹果 CMS 分类表 `ac=list`，把全部子分类按名称归并到四大类，
 自动剔除伦理/福利/解说/预告/体育/短剧等脏类；每类探测各源子类第一页，选页数最多的作“规范源”
 （实测电影/剧/动漫可达 250 页≈**5000 部**、综艺 147 页≈2940），其余源作回退。
- 浏览时按页直连 `ac=detail&t= &pg=N`（每页 20、详情自带播放地址，**点开即可播、无需再搜索**）；
 页级 10 分钟内存缓存 + 单 flight，规范源某页失败自动换源。
- 适配官方前端**虚拟列表无限滚动**：前端按 22 条/页块请求，服务端用“全局偏移跨 CMS 页取窗 +
 会话级 guid 去重 + 不足一窗自动补页”，保证滚动连续、每部片全局只出现一次、到底自然停止。
- 条目 guid 绑定 `(源, vod_id)` 并入库，复用既有详情/选集/多线路/续播/代理播放链。
- `supervise.py` 先校验官方 socket 的监听者 exe，再在私有暂存 socket 启动本服务；
 健康检查通过后用 `renameat2(NOREPLACE)` 原子换名接管；退出/崩溃时原子换回官方 socket（fail-closed）。
- 播放：HLS 源返回自研 `play_link=/v/media/online/ /preset.m3u8`，
 服务端实时抓取源站 m3u8，把分片/密钥 URI 重写为同源代理地址（透传 Referer/UA/Range）；
 mp4 等非 HLS 直链返回 `/direct`，流式反向代理并透传 `Range`（支持拖动进度，206 直通）。
- 在线条目 guid = `md5("on_ _ ")`，media/video/season/episode guid 确定性派生、可反查。
- 标题与线路持久化在 `state/titles.json`，重启后历史卡片仍可播放。
## 目录
 [code]