简介面向影音发烧友与家庭媒体服务器用户这份Python命令行工具可抓取多个日本影片数据源的元数据自动完成本地影片命名规范化、分类整理与信息刮削并与Plex、Kodi、Emby、Jellyfin等主流媒体中心衔接。资源包共44个文件压缩后仅272KB以18个Python脚本为核心涵盖多站点爬虫解析、核心逻辑与配置另附Dockerfile、docker-compose.yaml、Linux/Windows/FreeBSD脚本及makefile便于跨环境部署。文档、示例图片与json更新数据一并包含目录结构清晰。目前已有16474人次学习/下载实用性获验证。通过该资源读者可直接部署一套本地影片自动整理系统也可学习多数据源爬虫适配、反封禁策略与媒体元数据规范适合作为Python实战与家庭媒体库搭建参考。1. 本地影片库越来越乱AV_Data_Capture 在解决什么问题存了几百部电影的本地硬盘最后往往变成一堆电影_2022_HD.mkv、movie_01.mp4这样毫无信息量的文件。播放器打开后整个媒体库就是一张没有封面、没有简介、没有演员表的原始文件列表想找一部片子只能靠文件名硬猜。AV_Data_Capture 这类本地电影刮削与整理一体化方案做的就是一件非常具体的事扫描本地视频文件到在线影视数据库里匹配影片信息拉回海报、简介、评分、演员等元数据再按照统一规范重命名文件、归入标准目录结构。它适合本地影片量超过一两百部、已经忍不了手动改名的用户也适合折腾过开源媒体服务却总在文件名识别上翻车的朋友。这篇文章把这套方案从原理到落地配置到避坑讲清楚照着做就能把散乱的文件库变成可检索、可展示的海报墙。2. 刮削原理与选型为什么本地整理必须有一条自动化元数据管道2.1 元数据从哪来刮削器两步匹配背后的机制刮削的完整流程可以拆成两步。第一步是从本地文件名里提取“可搜索的影片标识”通常是片名和年份第二步是把这个标识作为关键词发给在线影视数据库的搜索接口拿到候选列表再从中选一个最匹配的条目按条目 ID 拉取完整元数据和海报图片。第一步看着简单实际是最容易出问题的环节。文件名Some.Movie.2019.2160p.mkv会被解析成片名Some Movie、年份2019然后接口按这两个字段去检索。大多数刮削工具给年份非常高的匹配权重因为同名影片太多年份是区分同系列不同版本最稳定的信号。如果文件名里没有年份匹配置信度会明显下降这时候工具很可能从候选列表里挑一个评分最高但不是你想要的那部。理解了这一步后面所有关于改名规范的建议都有了依据文件名里带上准确年份比什么都管用。第二步的候选排序也值得说。接口返回的候选列表通常带一个匹配分数刮削器按分数从高到低排序默认取第一名。分数由多个维度构成包括片名相似度、年份是否一致、类型是否吻合。有些工具还支持“人工确认阈值”当最高分低于某个数值时不自动入库而是生成一个待人工处理清单。这个机制是本地整理方案里非常实用的兜底策略后面会细说。2.2 同一件事为什么常见做法选 AV_Data_Capture 而不是播放器自带刮削很多媒体服务软件本身就带刮削功能那为什么还要单独跑一遍 AV_Data_Capture核心区别在处理的位置和自动化程度上。播放器自带的刮削是“展示时临时刮”它把元数据存在自己的数据库缓存里一旦媒体库目录被移动、文件名被改、软件缓存被清空就要重新刮一遍。而 AV_Data_Capture 的做法是在文件层完成“刮削 重命名 目录整理”让文件系统本身的信息正确媒体服务接入后一次扫描就能稳定识别不再依赖软件的临时缓存。我一般会对比几个同类型工具后选择这个方案核心原因有三点。第一命令行批处理能力挂上定时任务就能每天扫描增量文件不用每次手工打开界面点刷新。第二改名策略和目录结构是显式配置的整理规则透明可预期想改成“按类型分类”还是“按年份归档”都只是一行配置的事而播放器自带方案往往把文件留在原处只改自己的数据库换平台就推倒重来。第三日志完整匹配失败时能直接看到它拿什么关键词去搜索、为什么没匹配上排查路径短。对于超过五百部的媒体库这三点决定了是“一次整理长期稳定”还是“天天手动修刮削结果”。2.3 环境准备Python、FFmpeg 与媒体库目录规划跑起来之前先把环境准备好。工具基于 Python 实现需要 Python 3 以上版本建议用虚拟环境隔离依赖避免和系统里其他 Python 包冲突。FFmpeg 用来读取视频文件的技术信息比如分辨率、时长、码率这些信息有一部分会随着刮削结果一起写入元数据。操作系统的ffmpeg和ffprobe命令要能在 PATH 里找到否则程序启动会直接报错。目录规划是很多人忽略但非常重要的一步。建议分成两层待整理目录和已整理目录。待整理目录放散乱下载的文件已整理目录作为最终的媒体库根目录。两个目录不要有交叉不要用软链接互相指否则扫描时会反复处理同一个文件。我见过一种翻车现场把待整理目录建在已整理目录内部工具处理完一个文件后它又被下一次扫描当成新文件扫了一遍结果同一个片子出现两份元数据记录。等目录稳定后再初始化扫描路径这是开始前的纪律。3. 跑通 AV_Data_Capture初始化、配置与首次刮削3.1 安装与初始化最小步骤环境准备好后直接进入安装环节。下面是完整的初始化流程# 1. 解压或克隆项目源码后进入项目根目录 cd AV_Data_Capture # 2. 创建并激活 Python 虚拟环境 python -m venv venv source venv/bin/activate # Windows 下改用 venv\Scripts\activate # 3. 安装 Python 依赖 pip install -r requirements.txt # 4. 验证 ffprobe 可用 ffprobe -version前三步是任何 Python 项目启动的标准动作。虚拟环境这一步不要省有一些依赖会把版本冲突扩散到全局 Python 目录如果这台机器上还有其他 Python 应用升级依赖时很容易把对方搞挂。第四步的验证很关键很多用户跳过了它直到程序跑起来报“cannot find ffprobe”才回头查。装完之后先不要急着放大量文件进去先在待整理目录里放三到五部命名规范的文件做测试。这一步的含义是用最小样本验证从“文件名解析 → 在线数据库匹配 → 元数据写入 → 重命名移动”的完整链路是否通畅。链路通了再批量处理节省的时间远比现在多花的两分钟多。3.2 配置文件逐项说明媒体库路径、刮削源、语言优先级初始化完成后打开配置文件逐项确认参数。下面是一个典型配置片段[common] media_path /mnt/media/raw # 待整理目录扫完会被改名的文件所在目录 target_path /mnt/media/library # 整理完成后文件要移动到的媒体库根目录 language zh-CN # 元数据语言优先级 scraper online # 元数据来源online 表示从在线影视数据库获取 overwrite false # 是否覆盖已经存在的元数据信息 rename_enable true # 是否执行重命名与移动操作 artwork true # 是否下载海报与背景图 [request] timeout 15 # 单次请求超时时间单位秒 retry 2 # 请求失败后的重试次数 interval 1.0 # 两次请求之间的间隔时间单位秒media_path和target_path最容易搞反。填反了的典型症状是文件没有被整理到媒体库目录反而在待整理目录里被改了名等下一轮扫描时导致重复匹配。language对中文用户建议直接设成zh-CN不设的话默认返回的是英文简介和英文片名海报墙上的中文原名会丢失。overwrite在首次运行时保持false更安全因为部分旧文件可能已经带上了并不准确的本地 nfo 文件如果配置为覆盖工具会用新刮到的结果覆盖它一旦匹配错误就丢了原有的信息。request分区的三个参数是网络环境适配的关键。timeout设置为 15 秒比较合理太短会误判为失败太长会让批处理卡在某一部冷门片上。interval表示请求间隔在线影视数据库通常有接口频率限制设得太短会被临时限流日志里出现成串的HTTP 429设得太长五百部电影可能要跑到天亮。一般建议从 1.0 秒起步遇到限流再往上加适合大多数个人媒体库场景。3.3 首次运行的三种情形与日志读法配置完成后执行首次运行python AV_Data_Capture.py --config config.ini首次运行基本会遇到三种情形每种在日志里的表现完全不同。第一种是匹配成功日志会给出从旧路径到新路径的完整移动记录以及匹配到的在线数据库条目 ID。这是最顺利的情况文件被重命名并移动到目标目录海报和简介也同步下载。第二种是搜索不到结果日志里出现no result或search returned empty然后该文件被原地跳过。这种情况大概率是文件名里的片名拼写不完整比如只写了缩写S.M.2019数据库的搜索接口对缩写支持不好。解决方法是先手动把文件名改成接近“完整片名 年份”的格式再跑一次。第三种是多个候选结果但置信度不足。日志会打印候选列表和每个条目的匹配分数工具因为分数低于阈值不会自动选中而是把该文件列入待人工确认清单。这个时候的正确操作是去打开那个影视数据库的网站用文件名里的关键词手动搜索一次找到正确条目后把它的 ID 记下来在后续操作里指定它。日志里还有三行需要重点看解析出的关键词、搜索返回的候选数、最终选中条目的 ID。这三行信息完整覆盖了一次刮削的整个链路排查时从下往上读很快就能定位是文件名解析的锅还是网络请求的锅。4. 文件整理策略命名规范、目录结构与分卷处理4.1 目标命名规范让媒体服务软件直接认出的文件名刮削完成后的文件名必须遵循稳定规范这是整个本地整理方案的地基。我采用的规范是每一部电影一个独立目录目录名和文件名都使用“片名 (年份)”格式/mnt/media/library/Some Movie Title (2019)/Some Movie Title (2019).mkv目录带年份、文件名也带年份看似冗余实际上非常必要。媒体服务软件扫描媒体库时会同时读取目录名和文件名两者都包含完整的影片标识匹配成功率会明显高于只靠其中一方的方案。空格和标点也有讲究推荐用空格连接单词不要用下划线或点号。Some_Movie_Title_(2019).mkv虽然人眼能读懂但部分解析器会把下划线直接当作片名的一部分导致搜索时拿到的关键词不完整。音轨和字幕文件也要同步改名。一部电影目录下常见的文件包括主视频、正片字幕、多条音轨规范做法是保持主文件名一致/mnt/media/library/Some Movie Title (2019)/ ├── Some Movie Title (2019).mkv ├── Some Movie Title (2019).zh.ass ├── Some Movie Title (2019).en.srt └── Some Movie Title (2019).jpg字幕文件名里的语言代码和格式后缀是媒体服务器识别字幕语言和格式的关键。很多整理工具会同步处理同目录下与视频文件同名的字幕文件但如果下载时把字幕命名成了Some.Movie.2019.chs.srt与视频文件名不一致媒体服务就不会自动加载它。整理前把字幕统一改名的操作虽然基础但能省掉播放时手动选字幕的大量麻烦。4.2 目录结构设计单部电影、合集与分卷目录结构按文件类型区分处理我按实践结果整理成下面的表文件类型目标目录结构说明单部电影/片名 (年份)/片名 (年份).mkv最常规也最稳定的格式系列电影合集/片名 (年份)/之间保持独立目录不要把所有续集塞进一个总目录媒体服务识别多集会失败同一电影多版本/片名 (年份)/片名 (年份) - 导演剪辑版.mkv用版本描述区分媒体服务会识别为同一作品的不同版本分卷文件/片名 (年份)/片名 (年份) - Part 1.mkv等保持同一目录文件名加 Part 编号合集的处理是最容易翻车的。有些人喜欢用“某系列全集”做一个大目录把几十个视频文件混放进去。媒体服务扫描时只能把它当成一个整体来匹配结果找不到任何对应条目。正确做法是每个独立电影保持一个独立目录系列关系靠目录名和媒体服务器的“合集”功能聚合而不是在文件系统里物理合并。分卷文件的难点在于某些播放器不支持直接播放多文件分卷需要工具先做合并。整理工具本身不会合并视频流它的职责只是保证命名规范让媒体服务能识别出同一影片的分卷关系。如果你的播放器不支持分卷播放建议在整理前先用合并工具处理成单文件再进行刮削不然海报墙上会出现两个“同名同年份”的重复条目。4.3 特殊文件类型与整理前预处理ISO、BDMV 与零散文件夹本地影片库里总会有一些特殊封装最常见的是 DVD/BD 镜像的.iso文件、蓝光原盘目录结构BDMV/BDAV以及带一堆附属文件的散装文件夹。对.iso镜像在线影视数据库的搜索接口本身可以匹配但元数据写入有局限。很多工具只处理它能识别的视频扩展名列表如果你的配置里没有包含.iso直接就被跳过了。常见做法是修改配置中的扩展名白名单把iso加进去。需要注意的是刮削工具做的是信息整理不会把镜像内容转码成通用视频格式这也意味着流媒体播放和手机投屏一般不支持直接播放 ISO需要播放器支持光盘镜像挂载。BDMV 目录结构相较之下更麻烦。它的正片视频藏在STREAM子目录下文件没有扩展名工具默认扫描器不会把它当作可识别视频。我处理这类文件的习惯是先提取出正片流并转封装成.mkv或.mp4再把原来的 BDMV 目录归档到别处只让整理工具处理转出来的成品文件。不要在原始 BDMV 目录里硬试工具找不到合适字段刮削结果也是残缺的。散装文件夹是另一个典型场景。某个电影目录下既有视频文件又有官方花絮、删减片段、多个字幕文件。整理工具默认只处理匹配到的视频主文件附属内容不会被整理。我的习惯是先把花絮和删减片段挪到单独的Extras子目录媒体服务器会把它识别为电影附带的额外内容而不是当作新电影去数据库搜索。不预处理的后果就是整个媒体库里冒出一堆“某电影短片”这种匹配不到任何影片条目的孤立条目海报墙上全是空白极难维护。5. 避坑匹配失败、错乱与重复文件的 4 个典型问题5.1 同一个片名被刮到完全不相干的电影条目现象本地文件是某部 2019 年的喜剧片刮削完成后海报墙显示的是 1980 年代的同名老电影简介、演员表全是另一个片子的内容。原因文件名解析出的片名匹配到了数据库里同名的多个条目年份信息缺失或者年份提取错误导致匹配分数最高的候选不是目标影片。绝大多数数据集里同名影片数量远超预期连续剧和电影同名也很常见。解决第一步先把文件名改成“完整片名 (年份)”格式让年份作为硬信号参与匹配。第二步确认配置里的语言和区域选项是否正确某些影片在不同区域有不同片名中文名搜索不到就用英文名搜索。第三步如果还是匹配错手动打开在线影视数据库网站用文件名关键词搜索找到正确条目并记录条目 ID在后续处理时显式指定该 ID绕过自动匹配。5.2 文件名含“合集”“蓝光原盘”字样导致刮削器完全忽略现象文件明明存在且视频格式正常但日志里根本没有这条文件的处理记录直接跳过了。原因文件名或者目录名里的“合集”“套装”“蓝光原盘”等关键词触发了工具的过滤规则。为了让数据库搜索更精准部分工具默认过滤掉这些命名认为它们无法对应单一电影条目。如果文件名本身就是“某系列全集”过滤逻辑起效是好事但有些单部电影的文件名也带了“蓝光原盘”四个字就被误伤了。解决查看配置文件中的过滤规则列表把这个场景加进例外处理或者简单粗暴地把文件名改成标准“片名 (年份)”格式去掉与影片标题无关的描述性后缀。这个操作可以在批量跑之前先用改名工具过一遍避免两次手工处理。5.3 整理后媒体库里出现同一部电影两个完整副本现象目标媒体库目录里出现同一个片子的两份文件一份在/片名 (年份)/下另一份出现在根目录或者别的归档目录下都带了完整元数据。原因待整理目录被配置成了已整理目录的子目录或者整理完成后旧文件没有按预期删除而只是被软链接指向了新位置。刮削工具执行移动操作时如果用的是“复制后删除”的逻辑复制过程被中断就会留下残缺副本下次扫描又把它当成新文件重新刮一遍。解决严格分开待整理目录和已整理目录二者不能存在父子关系或软链接关系。批量扫描前检查磁盘剩余空间确保移动操作不会因空间不足中断。整理完成后用磁盘查重工具扫描已整理目录清掉残留的残缺副本并确认旧的待整理目录为空。5.4 接口请求超时日志里爬满 timeout 与重试失败现象批量运行时前面十几部正常后面大量报错报错基本都是超时重试也救不回来。单部手动运行同一文件却能成功。原因请求间隔设得太短触发了在线数据库的接口频率限制表现为大批量超时。也可能和本地的 DNS 解析、网络连通状态有关表现为持续性的连接超时而不是偶发。数据库的接口对同一 IP 的请求频率有隐含限制批量场景下尤其容易踩到。解决优先调大request分区里的interval从 1.0 秒调到 2 到 3 秒超时和重试次数可以维持原样。如果仍然超时把timeout适当增加到 30 秒左右排除慢响应的情况但不要超过 60 秒否则单次批处理会耗时过长。调整后先用二十部文件做小批次测试确认稳定再放开全量。批量任务尽量安排在低峰时段跑也能明显减少限流概率。5.5 重命名后字幕文件没有跟随播放器找不到外挂字幕现象视频文件被整理进了新的媒体库目录但原来的.srt、.ass字幕文件还留在旧目录里播放时字幕列表为空。原因不少刮削整理工具默认只处理视频主文件和图片资源外挂字幕不在处理范围内。如果输入文件名和字幕文件名不一致工具就不会把它们关联起来整理后视频移动了位置字幕被遗留在原地。解决整理前做一次文件名规范化让字幕文件和视频文件保持完全一致的主文件名只是扩展名不同。或者在配置里开启“同步处理同名字幕文件”的功能如果工具有这一项的话。对已经整理过的文件可以用批处理脚本重新匹配一遍把字幕文件移动到对应目录下再统一改名。6. 接入媒体服务器并验证刮削结果从目录到海报墙的最后一公里6.1 用字段清单验证刮削质量哪些字段没有就算失败刮削完成后别急着入库先按下面这张表逐项验证。验证不是看“有没有海报”这种笼统感觉而是要逐项对照字段缺一项都说明匹配可能出了问题。验证字段缺失时的处理标题与原始文件名是否一致不一致则手动修正后重新刮削年份是否为该部影片的正确上映年份错误则强制指定正确条目重新刮削简介语言是否为中文英文则调整配置中的language后重跑海报分辨率是否达到高清标准低清海报重新下载或手动替换本地图片文件评分与演员列表是否完整不完整说明选了错误条目需要人工确认片长与本地视频实际时长偏差是否在 5 分钟以内偏差过大可能匹配到另一个版本评分和演员不完整是最常见的“伪成功”信号。工具显示匹配成功也下载了海报和背景图但演员列表为空说明候选条目里选到的是信息维护不完整的条目。这时候回到在线数据库网站的对应页面确认一下如果网站上有完整演员表但本地下不下来多半是请求频率被限制换个时间重刮就能补上。6.2 批量整理批次验证与增量扫描技巧整理大批量文件时不要一把梭全量跑完再检查而是分批处理每批控制在五十部左右。每批次跑完后生成一份整理结果清单随机抽其中百分之十核对目录结构和文件名含有年份、媒体库根目录下没有散文件这两项对了就说明整理规范在正确执行。全部批次跑完后再抽检一次总媒体库确认没有批量性的错位。增量扫描是日常维护的关键习惯。第一次全量整理完成之后每次新增影片只需要扫描待整理目录配置里保持增量模式工具会跳过已经处于已整理目录中的文件。配合计划任务每天自动扫描一次新增文件就能做到“下载完躺平海报墙自动更新”。人工介入点只有一条当文件名本身完全无法解析时工具把它列出后人工补一个规范文件名剩下的流程不用管。做这套整理方案这几年我最大的教训是别在几百部文件全积压时才想起整理也别指望工具能读懂所有乱七八糟的命名。工具负责批量化和自动化人工负责把文件名里的错误信息改对。每批都验证增量及时跑媒体库就不会再变成那堆永远理不清的movie_01.mp4。希望这篇能帮你的本地影片库少走一段弯路。本文还有配套的精品资源点击获取
