官方 API 域名连接超时或失败，每次扫描都要重新请求网络，速度慢且不可靠。
NAS 存视频、本机存元数据的需求难以满足，NFO 文件散落各处，备份和迁移都很麻烦。
目录结构不规范时单集无法识别，episodeguide 未更新导致界面空白，配置门槛高。
均基于 TMDB 原始 JSON 本地缓存与本地优先策略，元数据目录可与视频库完全分离（本地磁盘、SMB、NFS 等）。
metadata.yyba.movie
电影库刮削，缓存格式为 .movie/{文件名}.json。
安装包：metadata.yyba.movie-install.zip
metadata.yyba.tv
电视剧库刮削，缓存格式为 .tv/{剧集名}.json + .tv/{剧集名}/SxxExx.json。
安装包：metadata.yyba.tv-install.zip
Settings → TmdbApi → MetaFiles → Scraper → ListItem
| 模块 | 职责 |
|---|---|
| Settings | 插件设置、Kodi 请求参数、本地存储路径 |
| TmdbApi | TMDB HTTP 请求（搜索 / 详情 / 季 / 单集） |
| MetaFiles | 读写 .movie/ 或 .tv/ 下 JSON 缓存 |
| Scraper | Kodi 入口（find / getdetails / …） |
| ListItem | TMDB JSON → Kodi ListItem |
刮削时先读本地 JSON（电影 .movie/，电视剧 .tv/），命中则不走 TMDB 网络。多台设备或多次扫描共享同一份本地缓存即可复用元数据。
本地存储路径独立配置，电影缓存 {路径}/.movie/，电视剧缓存 {路径}/.tv/，可与视频库不在同一磁盘。
磁盘上保存 TMDB API 原始响应 JSON，便于备份、调试与二次开发，不生成 tvshow.nfo / movie.nfo。
支持 api.tmdb.org、api.themoviedb.org 或手动 IP + Host 头，适配 hosts 指向、反向代理、内网镜像等场景。
海报、背景、演员头像可切换 TMDB 官方 CDN 或 tmdb.img.yyba.cn YYBA 代理，解决 Sony 电视等设备无法访问 TMDB 图片 CDN 导致有字无图的问题。
E:\多媒体\多媒体影院\电影\ ← Kodi 电影源
蜘蛛侠.mp4
阿凡达 (2009).mkv
E:\多媒体\多媒体影院\mata\ ← 插件「本地存储路径」
.movie\
蜘蛛侠.json ← TMDB /movie/{id} 原始 JSON
阿凡达 (2009).json缓存键与本地文件名一致（无扩展名），与 TMDB 显示名无关。
Kodi 电视剧源应设为「每个文件夹一个剧集」，源路径指向包含多个剧集子文件夹的目录。
E:\多媒体\多媒体影院\电视剧\美剧\ ← Kodi 电视剧源（此层级）
黑镜\ ← 一部剧 = 一个文件夹
Season 1\
S01E01.mp4
S01E02.mp4
Season 2\
S02E01.mp4
怪奇物语\
Season 1\
S01E01.mp4
E:\多媒体\多媒体影院\tvmeta\ ← 插件「本地存储路径」
.tv\
黑镜.json ← 整剧 TMDB JSON
黑镜\
S01E01.json ← 单集 TMDB JSON
S01E02.json
怪奇物语.json
怪奇物语\
S01E01.json| 层级 | 推荐命名 | 说明 |
|---|---|---|
| 剧集文件夹 | 黑镜 | 与 .tv/ 缓存键一致 |
| 季文件夹 | Season 1 | 也支持 Season 01 |
| 单集文件 | S01E01.mp4 | 季号+集号需与 TMDB 一致 |
① find → 选择剧集（本地缓存或 TMDB 搜索）
② getdetails → 读/写 .tv/黑镜.json，返回整剧信息
③ getepisodelist → 拉取各季单集，写入 .tv/黑镜/S01E01.json …
④ getepisodedetails → 匹配本地 S01E01.mp4，返回单集 ListItem额外支持 getartwork 刷新剧集海报与背景。
| 项目 | 电影 | 电视剧 |
|---|---|---|
| 视频源 | E:\多媒体\电影\ | E:\多媒体\电视剧\美剧\ |
| 本地存储路径 | E:\多媒体\mata\ | E:\多媒体\tvmeta\ |
Kodi → 设置 → 插件 → 对应 YYBA 刮削器 → 配置
| 设置项 | 说明 |
|---|---|
| 本地存储路径 | 元数据根目录；电影缓存 {路径}/.movie/，电视剧缓存 {路径}/.tv/ |
| TMDB API 密钥 | 在 TMDB 设置 申请 |
| TMDB 语言 | 中文（zh-CN，默认）/ 英文（en-US） |
| API 域名 | 默认 / themoviedb.org / 手动 IP（可配置协议、端口、Host 头） |
| 图片 CDN 域名 | media.themoviedb.org（默认）/ image.tmdb.org / tmdb.img.yyba.cn（YYBA 代理转发） |
| 验证 SSL 证书 | 手动 IP 或特殊代理时可关闭 |
在项目目录中运行 build_zip.py 生成 zip 安装包。
# 电影刮削器
cd metadata.yyba.movie
python build_zip.py
# 生成 metadata.yyba.movie-install.zip
# 电视剧刮削器
cd metadata.yyba.tv
python build_zip.py
# 生成 metadata.yyba.tv-install.zipKodi：**设置 → 插件 → 从 zip 安装** → 选择对应 zip 文件。
在插件设置中填写本地存储路径和 TMDB API Key，然后在媒体库源中选择对应刮削器。
...\美剧\），不要只指向单个剧集文件夹若刮削行为异常，建议：删除资料库中对应条目（不删视频与本地缓存）→ 重新扫描或「刷新信息」→ 必要时清除刮削器缓存 %APPDATA%\Kodi\cache\scrapers\metadata.yyba.*
适用 Kodi 20+（Python 3）。需要 xbmc.metadata ≥ 2.1.0、xbmc.python ≥ 3.0.0。
检查源是否为「每文件夹一剧」结构，episodeguide 是否已更新。确认源路径指向含多部剧集的父目录（如 美剧\），而非单个剧集文件夹。必要时删除库中条目后重新扫描。
源路径指向了分类目录而非剧集目录。将源改为 美剧\ 层级，并删除误生成的 .tv/美剧.json。
对对应条目执行「刷新信息」以更新 artwork。海报通过 TMDB CDN URL 提供，不写本地图片文件。
部分设备（如 Sony 电视）无法访问 TMDB 官方图片 CDN。在插件设置 → 图片 CDN 域名 中选择 tmdb.img.yyba.cn（YYBA 代理转发），然后对条目执行「刷新信息」即可正常显示海报与背景。
在插件设置中切换 API 域名（api.tmdb.org / api.themoviedb.org），或使用手动 IP 模式配置 hosts 指向、反向代理或内网镜像。
完全免费、完全开源，遵循 Apache-2.0 协议。你可以自由使用、修改和分发。如果觉得好用，欢迎在 Gitee 点个 Star ⭐。