ConfigData/rename-media/自研刮削服务说明.md

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

一个 Python 服务：监听「清理后媒体目录」，新媒体出现自动刮削（TMDB），结果复制落库到成品目录。 已在本机 macOS 用 mock 模式跑通整条链路（监听 → 识别 → 刮削 → 复制落库）。

文件清单

文件	职责
media_scraper.py	核心刮削器：文件名解析 → TMDB 查询 → 生成 nfo(Kodi规范) → 下载海报 → 复制落库
watcher.py	监听服务：watchdog 监听清理目录，写入稳定后自动触发刮削
config.json	配置：源目录、成品目录、TMDB Key、mock 开关
.venv/	本地 Python 环境（已装 watchdog、requests）

快速上手（本地 macOS）

# 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）

{
  "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（或直接用容器把本目录挂进去跑）。

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 单条/批量）

# 处理单个媒体文件或目录
./.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（+ 海报）」。