# 自研媒体刮削监听服务 —— 使用说明

一个 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（+ 海报）」。