102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
# 自研媒体刮削监听服务 —— 使用说明
|
||
|
||
一个 Python 服务：监听「清理后媒体目录」，新媒体出现自动刮削（TMDB），结果**复制**落库到成品目录。
|
||
已在本机 macOS 用 mock 模式跑通整条链路（监听 → 识别 → 刮削 → 复制落库）。
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 职责 |
|
||
|---|---|
|
||
| `media_scraper.py` | 核心刮削器：文件名解析 → TMDB 查询 → 生成 nfo(Kodi规范) → 下载海报 → 复制落库 |
|
||
| `watcher.py` | 监听服务：watchdog 监听清理目录，写入稳定后自动触发刮削 |
|
||
| `config.json` | 配置：源目录、成品目录、TMDB Key、mock 开关 |
|
||
| `.venv/` | 本地 Python 环境（已装 watchdog、requests） |
|
||
|
||
## 快速上手（本地 macOS）
|
||
|
||
```bash
|
||
# 1) 已准备好 .venv（watchdog、requests 已装）。若新环境：
|
||
python3 -m venv .venv
|
||
./.venv/bin/pip install watchdog requests
|
||
|
||
# 2) 先 mock 跑通管线（无需 Key，验证 nfo 生成 + 复制落库）
|
||
./.venv/bin/python watcher.py --config config.json --once
|
||
|
||
# 3) 配好 TMDB Key 后真刮削
|
||
# 在 config.json 填 tmdb_api_key，并把 "mock": true 改成 false
|
||
```
|
||
|
||
## 配置（config.json）
|
||
|
||
```json
|
||
{
|
||
"source": "/vol1/media/cleaned", // 你的清理后媒体目录（media_final.py 的输出）
|
||
"dest": "/vol1/media/library", // 成品落库目录（刮削+复制后）
|
||
"tmdb_api_key": "", // TMDB API Key（themoviedb.org/settings/api 免费申请）
|
||
"mock": true, // true=模拟元数据；配好 Key 后改 false
|
||
"settle": 6, // 写入稳定等待秒数（大文件拷贝完再处理）
|
||
"language": "zh-CN" // 刮削文案语言
|
||
}
|
||
```
|
||
|
||
> `mock: true` 时不需要 Key，用于无网络/无 Key 环境下验证整条管线；正式使用务必 `mock: false` + 填 Key。
|
||
|
||
## 部署到飞牛 fnOS
|
||
|
||
飞牛基于 Linux(Debian)。推荐用 Python3 + systemd（或直接用容器把本目录挂进去跑）。
|
||
|
||
```bash
|
||
cd /你的项目目录
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install watchdog requests
|
||
# 编辑 config.json，把 source/dest 改成飞牛上的真实路径，填 TMDB Key，mock 改 false
|
||
|
||
# 常驻运行（前台，Ctrl+C 停止）
|
||
.venv/bin/python watcher.py --config config.json
|
||
|
||
# 后台常驻（nohup）
|
||
nohup .venv/bin/python watcher.py --config config.json > scraper.out 2>&1 &
|
||
|
||
# 或用 systemd 自启（推荐）
|
||
# 项目里已附 media-scraper.service：先把它里面 3 处「/你的项目绝对路径」改成飞牛真实路径
|
||
sudo cp media-scraper.service /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now media-scraper # 开机自启 + 立即启动
|
||
journalctl -u media-scraper -f # 看日志
|
||
```
|
||
|
||
## 命令行用法（media_scraper.py 单条/批量）
|
||
|
||
```bash
|
||
# 处理单个媒体文件或目录
|
||
./.venv/bin/python media_scraper.py --source "阿凡达(2009).mkv" --dest /成品目录
|
||
|
||
# 递归处理某目录下所有新媒体
|
||
./.venv/bin/python media_scraper.py --source /清理目录 --dest /成品目录 --recurse
|
||
|
||
# 预览不落盘
|
||
./.venv/bin/python media_scraper.py --source xx --dest yy --dry-run
|
||
|
||
# mock 模式（无 Key 验证）
|
||
./.venv/bin/python media_scraper.py --source xx --dest yy --mock
|
||
```
|
||
|
||
## 行为与命名约定
|
||
|
||
- **电影**：单文件 `阿凡达(2009).mkv` 或电影目录 → 复制后生成 `阿凡达(2009).nfo` + 海报。
|
||
- **剧集**：目录内文件带 `S01E01` / `第01集` / `E01` → 识别为剧集 → 生成 `tvshow.nfo` + 每集 `xxx.nfo` + 海报。
|
||
- **落库方式**：始终「复制」，源目录保持原样、不写入任何文件。
|
||
- **安全保护**：目标路径若与源相同会直接报错终止，绝不误删源目录。
|
||
|
||
## 已知限制（诚实说明）
|
||
|
||
- 数据源仅 TMDB 单一来源；冷门片/非主流命名可能匹配不准。
|
||
- 海报下载依赖能访问 TMDB 图片服务器；国内网络可能需代理或换 TMDB 备用源。
|
||
- 单集文件若无季信息默认按第 1 季处理；建议目录按「剧名(年份)/剧名.SxxExx.mkv」组织识别最准。
|
||
- nfo 字段已覆盖 title/year/rating/plot/uniqueid/genre/**director/studio/actor** 等核心项；如需更多字段可再扩展。演员、导演、制片厂来自 TMDB credits 接口，连不上时为空白但不影响 nfo 生成。
|
||
|
||
## 验证方式
|
||
|
||
- 本机已用 mock 跑通：电影、剧集目录、单集均正确复制 + 生成 nfo，且实时监听投放新文件能自动触发刮削落库。
|
||
- 部署后自查：往 `source` 丢一个清理后的影片，几秒后检查 `dest` 是否出现「媒体副本 + .nfo（+ 海报）」。
|