AV_Data_Capture：本地视频元数据刮削与媒体库整理实战指南

简介这是一款面向本地影片管理场景的Python命令行工具专门为Emby、Jellyfin、Kodi等媒体服务器提供电影元数据刮削与自动分类能力。它能够自动抓取影片信息、封面与类别并据此完成本地文件分类整理解决影片库信息缺失、命名不规范与目录杂乱的问题既适合普通影音玩家使用也适合想了解爬虫与元数据处理流程的Python学习者深入研究。资源包共44个文件压缩后仅272KB以18个Python模块为核心涵盖javbus、javdb、dlsite、mgstage、fanza等多个抓取源以及番号解析、配置加载、日志输出等功能模块同时附带2个INI配置模板、8张流程图与截图、Linux/Windows/macOS启动脚本、Dockerfile和演示GIF并包含README与LICENSE等文档便于快速上手和跨平台部署。目前已有16366人浏览学习在媒体库管理类开源工具中具备不错的参考价值。通过源码不仅能学习到元数据抓取、番号识别、图片下载与目录归类的完整实现思路还可以直接基于自带配置和Docker方案搭建私有影片管理服务目录划分清晰核心模块与爬虫解耦方便二次开发新的数据源或调整整理策略省去大量手动整理影片的重复劳动。如果你的本地视频文件越来越多、文件名混乱、媒体库总是刮不出正确的海报和简介那你大概率需要的是一个能自动“整理元数据”的工具。这篇博文就围绕 AV_Data_Capture 这个开源项目讲清楚它的原理、配置、实操流程和常见坑帮你把本地片库从“一堆乱码文件名”变成“规整可检索的海报墙”。我用 AV_Data_Capture以下简称 AVDC整理本地视频库已经有一段时间了今天把从部署到日常使用的经验完整梳理一遍。这个项目本质上是一个基于 Python 的命令行刮削器核心逻辑是扫描指定目录里的视频文件从文件名里提取出唯一标识也就是番号然后去多个数据源站点抓取对应的元数据最后把标题、封面、演员、简介、类型等信息写进本地文件同时把视频文件本身重命名为统一格式。适合那些有大量本地视频收藏、想用 Kodi / Emby / Jellyfin 搭建家庭媒体库、又不愿意一个个手动改按键盘的朋友。1. 工具定位与整体设计思路1.1 为什么需要“刮削”——媒体库背后的元数据问题先聊一个很多人容易忽略的点本地视频文件里其实并不包含“海报”“简介”“演员表”这些信息。视频文件本身只有画面和声音你在播放器里看到的海报墙全部来自播放器读取到的元数据。这些元数据要么由文件附带比如内嵌字幕、章节信息要么由播放器去网络数据库匹配。如果你的文件名是“abc123.avi”这种样子播放器连这部片是什么都认不出来自然也就刮不到任何海报。AVDC 要解决的就是“给视频文件补上元数据”这一步。它做的事情可以拆成三块把文件名改成标准格式让媒体库服务器能识别抓取元数据生成对应的 nfo 文件和图片文件把输出结果按媒体库约定好的目录结构放好。这三件事做完把你的媒体目录交给 Emby 或 Kodi它们就能自动读取到完整的海报墙和信息页体验和流媒体平台几乎一样。1.2 AVDC 的技术路线目录监听 番号提取 多源聚合AVDC 的整个流程可以概括为三个阶段。第一阶段是文件扫描它会遍历你设置的目标目录找出所有视频扩展名的文件跳过临时文件、隐藏文件和已经处理过的文件第二阶段是番号提取这是整个项目最核心的部分它通过正则表达式从文件名里匹配出类似“ABC-123”这样的唯一编码这个编码在东京热系、蚊香社系、SOD 系等多个厂商的作品命名体系里是通用的第三阶段是数据抓取拿到番号之后AVDC 会按配置好的优先级去不同的数据源站点查询拿到结果后解析出标题、封面图 URL、演员列表、类型标签、简介等信息。数据抓取之后还有一个“去重 排序”的逻辑。因为不同数据源对同一个番号的收录详细程度不同有的源只有简介没有封面有的源封面图清晰度低AVDC 会在配置里给你一个优先级列表比如 javbus 排在前面javdb 排在后面第一个源抓到了完整数据就直接用抓不到再退到下一个源。这个设计思路很务实——不是所有源都稳定也不存在一个源永远最全多源聚合加优先级回退才能最大化成功率。1.3 选型考量为何不用纯脚本或在线工具有人可能会问我自己写个 Python 脚本重命名文件或者用在线网站一个个查番号、手动下载封面不也能达到类似效果这里我对比过几条路。手写脚本的难点在于数据源的反爬、解析规则维护和异常处理每个站点的 HTML 结构不同接口也可能随时变化自己写要维护的成本远高于直接用社区维护的项目。而在线刮削工具大多不支持批量处理或者需要你把视频逐个上传到某个网页先不说隐私问题几百个文件一个个操作下来手都要断。AVDC 属于“半自动批量处理工具”它跑一次就能把整个目录里的几百个文件全部处理完输出结果也是标准化的 nfo 和图片文件直接可以被 Emby、Kodi 读取。还有一个隐蔽的优点是离线可用——它只依赖网络查询元数据不依赖某个客户端软件处理完之后的所有信息都保存在本地即使数据源网站挂了你本地媒体库照样能正常展示。这一点在搭建家庭影音系统时非常重要。2. 核心细节解析与实操要点2.1 环境准备Python、ffmpeg、依赖项一个不能少AVDC 是一个 Python 项目所以第一步是把 Python 环境搞定。官方要求 Python 3.7 以上我建议直接用 3.8 或 3.9 稳定版3.10 之后有些旧的依赖库可能会报兼容性警告。Windows 下安装的时候记得勾选“Add Python to PATH”这步不勾后面命令行运行会找不到 python 命令是新手最常见的问题之一。依赖安装用项目根目录下的requirements.txt一键完成pip install -r requirements.txt如果你下载的是源码包依赖文件在根目录里如果你用的是打包好的 exe 版这一步可以跳过。但不管是源码还是 exe 版你都需要单独安装 ffmpeg并把它加入环境变量。AVDC 处理某些格式的视频时需要调用 ffmpeg 来提取信息比如时长、分辨率没有它会直接报错退出。验证 ffmpeg 是否安装成功在命令行输入ffmpeg -version能正常打印版本号就说明 PATH 配好了。如果提示找不到命令去官网下载对应系统版本解压后把bin目录地址加进系统的环境变量 Path 里然后重启终端。2.2 config.ini 关键配置逐项拆解AVDC 的所有行为都由根目录下的config.ini控制。我第一次用的时候直接跑默认配置结果什么都刮不到后来才发现是没配置数据源。这个文件里最常见的几个配置项我一个个说。[common] main_mode 1 failed_output_folder failed success_output_folder success multithread Truemain_mode是运行模式1表示完整刮削模式会抓取全部元数据信息2是只刮削不重命名。日常使用建议保持1。failed_output_folder和success_output_folder是处理结果的分类目录成功和失败的文件会分别被移动过去这样你可以方便地复查哪些文件没处理成功。数据源相关的配置如下[javbus] switch on priority 1每个数据源站都有独立的小节switch控制是否启用这个数据源priority控制抓取顺序。数字越小优先级越高。我实际用下来的经验是优先把返回信息最全、封面图最稳定的源排在前面把补充性质的源排在后面。优先级不仅影响抓取顺序还影响结果合并时的取舍逻辑同一番号如果前一个源拿到了数据后一个源就不会再请求了这样能明显提升批量处理的效率。还有一个容易忽略的配置是本地文件的写入选项比如是否下载封面图、是否生成 fanart 背景图、nfo 文件的编码格式等。默认的 UTF-8 编码在 Windows 下有时候会导致 Emby 读取中文乱码如果遇到这种问题可以在 nfo 相关配置里把编码改成UTF-8或者GBK具体看你媒体库服务器的操作系统。2.3 目录规则与文件命名规范AVDC 对输入文件有一个硬性要求文件名里必须包含可识别的番号。比如ABC-123.avi、[ABC-123] 中文字幕.mp4、abc123 - 1080p.mkv这类名字都能被正确识别。反过来如果文件名是movie1.mp4、新建文件夹.avi、2024合集.rar那它永远也刮削不到任何东西因为没有唯一标识可供查询。推荐的命名格式有三种。第一种是纯番号ABC-123.avi最简单第二种是带发布商前缀ABC-123-4K.mp4也能识别第三种是番号后面加自定义描述比如ABC-123 1080P 中字.mp4AVDC 会从文件名头部提取番号并忽略后面的描述。但要注意番号中间不能有空格字母和数字之间不要加分隔符否则正则匹配会失败。还有一个目录规范AVDC 会把它处理的源文件移动到deploy目录下的分类子目录里比如deploy/AV、deploy/AV_C、deploy/4AV等。这些字母前缀代表命名规范的类型比如以ABC-123开头的文件会被分进一类以CWP-123开头的会进另一类。具体分类规则在源码里有映射表一般不用手动干预但你要知道这个机制否则找文件时会有点懵。3. 实操过程与核心环节实现3.1 从零到跑通完整部署流程记录我以 Windows 环境为例把完整流程走一遍。下载项目源码后解压到本地目录结构大概是这样的根目录下有一个main.py、一个config.ini、一个requirements.txt还有AV_Data_Capture.py不同版本可能叫不同名字、deploy目录和lib目录。首先装依赖cd AV_Data_Capture pip install -r requirements.txt接着修改config.ini把数据源开关打开优先级按自己的需求排好。然后把你要处理的视频文件全部放进deploy目录下或者放进一个统一的待处理目录并在配置里指定路径。这一步要注意AVDC 会直接移动源文件所以不要把你原始收藏的目录直接填进去建议复制一份到deploy再跑避免处理失败把原文件移动乱套。最后在命令行启动python main.py运行日志会逐行打印当前正在处理哪个文件、匹配到哪个番号、从哪个数据源抓取、是否成功等信息。如果一切正常你会看到deploy目录下的文件慢慢减少同时出现一堆以番号命名的文件夹每个文件夹里包含视频文件本身、封面图、nfo 文件和背景图。这个过程可以挂机跑几百个文件差不多一两个小时能跑完具体看你文件大小和网络速度。3.2 刮削核心链路识别、匹配、写入的完整闭环前面说了一堆理论这里把核心链路拆开说。AVDC 的文件名识别模块用的是正则表达式加厂商规则表它会先尝试从文件名里提取出类似ABC-123的三段式番号。如果文件名是英文直发那种比如没有番号的它还会尝试把文件名里的英文单词拆成可识别的关键词去搜但成功率低一些核心场景还是面向日系厂商的编码体系。匹配阶段AVDC 把提取到的番号拼接成不同数据源的搜索 URL然后发起 HTTP 请求。这一步要注意有些数据源对 User-Agent 有校验AVDC 默认带了一个伪装过的请求头如果某个源突然开始大量返回 403 错误很可能是网站风控升级了这时候最好的办法是给该源加代理或降低请求频率。AVDC 支持在配置里设置请求延时参数批量跑的时候稍微加一点延时能显著降低被封概率。写入阶段是把解析好的 JSON 数据渲染进模板生成 Kodi/Emby 标准的 nfo 文件。nfo 是 XML 格式的文本文件里面包含title、actor、release、genre、plot等标签。AVDC 还会根据视频分辨率生成对应的poster.jpg和fanart.jpg两种图片一个做封面一个做背景墙。我一直觉得这个“生成文件夹 移动文件”的设计很巧妙。它不是一个视频文件加一个同名 nfo而是每个番号一个独立文件夹文件夹名字就是标准化的“番号 标题 分辨率”格式里面统一放视频和元数据文件。这种结构对 Emby 的电影模式识别非常友好直接指定根目录为媒体库根目录Emby 会自动按二级目录扫描每个文件夹。3.3 与 Emby / Jellyfin / Kodi 的联动方式AVDC 处理完之后的目录可以直接被主流媒体库服务器读取。我用 Emby 举例在 Emby 后台添加媒体库类型选择“电影”路径指定到deploy目录刮削器设置里把“本地 nfo”勾选上然后扫描。Emby 会读取每个子文件夹下的 nfo 文件直接显示海报和信息不会再去请求在线刮削器速度极快。Kodi 的操作类似网络存储里添加视频源选择“刮削器 - 本地信息”然后刷新目录。因为 nfo 和图片都是本地就绪的Kodi 会直接展示不会出现网络请求超时的问题。Jellyfin 作为 Emby 的开源分支行为基本一致只是设置项的位置稍微不同。一个实用技巧AVDC 处理完成后你可以把deploy目录直接挂载给 NAS或者同步到其他设备。因为所有元数据都在本地换设备后只要重新配置媒体库指向这个目录海报墙就不会丢不需要重新刮削。这是本地化整理方案最大的优势。4. 常见问题与排查技巧实录4.1 高频问题速查表现象可能原因解决方案所有文件都处理失败日志无输出未安装 Python 或依赖不完整重新执行 pip install -r requirements.txt部分文件刮削失败其他正常文件名中不含可识别番号手动重命名文件补上标准番号番号识别正确但匹配不到数据该数据源未收录这张作品或该源已被风控调整数据源优先级启用另一个源Emby 读取后中文乱码nfo 编码与系统编码不一致在配置中把 nfo 编码改为 UTF-8重启服务封面图没有下载下来网站图片 CDN 不可达或域名解析失败检查图片 URL 的可访问性必要时配置网络代理程序报内存溢出或卡死批量处理时并发线程数过高在 config 中把multithread改为 False或调低线程数这里有个容易混淆的点AVDC 的“成功”和“失败”是指元数据是否抓取成功而不是文件是否移动成功。有时候视频文件已经被移动到成功目录了但实际上只是重命名了文件、没有抓到完整元数据。所以跑完一批后不要急着收工抽查几个文件夹写没写 nfo尤其是检查有标题和简介的才算真正成功。4.2 三个值得牢记的防坑细节第一个坑是路径不能有中文。AVDC 的依赖库在 Windows 下对中文路径的兼容性存在问题源文件目录、deploy 目录、甚至 Python 所在路径都尽量用纯英文否则运行时可能报编码错误。我一开始把整个工具放在桌面的“电影刮削”文件夹下结果每次跑都报UnicodeDecodeError最后改成D:\avdc就正常了。第二个坑是文件名里的点号和括号。很多老司机喜欢在文件名里写ABC-123 [中字] [高清]中括号本身没问题但如果在番号正中间出现中括号比如AB[C-123正则匹配会直接失败。文件名尽量保持番号部分连续不中断特殊描述放在番号之后。第三个坑是视频文件不要有中文字幕封装的内嵌字幕流。这不是 AVDC 的问题而是媒体库在播放时可能默认选择不到正确的音轨或字幕轨。AVDC 不管音轨字幕这些它只整理元数据播放层面的问题要找播放器或者媒体库服务器的转码设置去解决。4.3 批量处理时的效率优化心得如果文件数量在几百部以上建议分批次跑不要一次性全塞进 deploy。原因很简单AVDC 的日志输出和文件移动机制在极端大批量时可能出现偶发漏处理而且单次跑太久容易撞上数据源的反爬限制。我习惯每批放 200 个左右跑完一批查看日志确认失败率在可接受范围后再放下一批。并发线程数的调节也对效率影响很大。默认的multithread True会同时开多个请求线程批量处理速度快但也更容易被数据源限流。如果你的网络带宽不大或者数据源很敏感可以先把并发关掉单线程跑一两个文件验证稳定后再打开。实际体验下来刮削速度的瓶颈通常在网络请求延迟而不是本地文件读写所以并发太高带来的收益并不大还可能带来封 IP 的风险。5. 基于个人经验的操作建议最后再分享一点我自己长时间使用后的体会。AVDC 这类刮削工具解决的是“批量整理”的问题但它不是一个全程无脑的保姆。文件名越规范刮削成功率越高你的网络环境越稳定能访问的数据源越多最终能拿到的元数据就越完整。我个人的建议是先小批量试运行 10 个文件覆盖不同厂商的番号风格检查 nfo 和封面的质量再决定要不要放开跑全量。跑完之后用 Emby 或 Kodi 打开媒体库目录抽查几部作品的演员信息、简介、类型标签是否完整如果个别缺失可以手动补充 nfoEmby 支持在 Web 界面直接编辑。另外一个实用的扩展思路AVDC 的输出目录可以配合定时任务使用。比如你每隔几天把新下载的视频放进一个“待处理”文件夹然后用计划任务定时运行 AVDC处理完自动移动到媒体库目录这样你只需要维护一个“下载完往里丢”的动作后面整个流程都是自动化的。用 Windows 自带的“任务计划程序”就能实现不用额外装软件。AVDC 本身是一个社区项目它的数据源规则和解析逻辑会随着网站结构变化而失效因此保持关注项目更新、及时拉取新版本是长期使用下来最重要的一条经验。如果你已经部署好了这套流程后面要做的就是定期更新和维持文件命名习惯这两点做到位本地媒体库的体验基本可以一直稳定下去。本文还有配套的精品资源点击获取