video_parser：自动解析视频文件名与元数据的工程实践

简介video_parser是一个基于TypeScript实现的视频解析库面向需要处理MP4、FLV、MKV等多媒体容器并从中提取元数据、帧率、编码格式等关键信息的Web或Node.js开发者。它将解析能力拆分为services、interfaces、entity、controllers等模块既保证类型安全也便于按业务场景复用适合在视频处理工具、媒资系统或自动化分析流程中直接集成。压缩包共13个文件以TypeScript源码、JSON配置和依赖锁文件为主并内置了编译配置与依赖管理入口整体仅61KB结构紧凑便于快速审阅与工程化落地。目前已有197人学习/下载适合具备一定TypeScript基础、希望避免从底层手写解析逻辑的中级开发者。通过这套源码可以获得可运行的解析库骨架、模块划分思路、构建脚本以及对常见容器格式的解析思路能显著缩短视频格式适配和元数据提取功能的开发周期。 如果你和我一样本地攒了上千个视频文件你一定清楚存储从来不是最头疼的事最头疼的是管理。文件名风格五花八门从标准的Movie.Name.2021.1080p.BluRay.x264到第12集.mp4再到手机导出的VID_20240301_153012.mp4想快速定位一部片子基本靠挨个打开看。我写 video_parser 这个工具就是想解决这个问题读取视频文件和内嵌元数据再结合文件名里的有效信息自动产出一份结构化的视频档案。这个工具适合两类人。一类是本地视频库比较庞大、想做自动化归档和整理的爱好者另一类是做内容分析、需要批量拉取视频技术参数分辨率、编码、时长、音轨字幕轨道情况的开发者。下面我把设计思路、核心实现、踩过的坑都写下来方便你复现或者改成符合自己需求的版本。1. 我为什么写video_parser从手工整理视频库的痛点说起1.1 手里的现成工具为什么不够用不写这个工具之前我试过好几种方案。最笨的方法是用 Python 调 ffprobe 拿媒体信息然后自己写正则从文件名里抠标题、年份、清晰度。听起来可行实际跑一遍就发现问题了ffprobe 输出的 JSON 字段虽然完整但不同格式的视频字段层级和命名不完全一致。有的文件流信息嵌套两层有的嵌套三层写解析代码时全是 if 分支越写越恶心。文件名正则只能覆盖你自己见过的命名习惯。今天遇到一个 xxx.2023.2160p.WEB-DL.DDP5.1.x264 还能处理明天来一个 【4KHDR】电影名2022第3季合集 就彻底歇菜。没有统一的数据出口。脚本输出结果每次都不一样想接进 Emby、Jellyfin 或者自己的数据库还得再写一遍字段映射。这些痛点叠加起来就是一句话我需要一个工具它能稳定地把一个视频文件路径变成一份不依赖具体文件格式的标准化信息结构。1.2 video_parser要解决的三个核心问题在动手之前我把需求收敛成三件事。第一元数据读取要稳。不管输入的是 MP4、MKV、AVI、TS 还是 MOV都要能拿到容器格式、视频流编码、分辨率、帧率、码率、时长、音轨列表、字幕轨列表这些基础信息而且字段结构必须统一。第二文件名解析要聪明但不能莽撞。能识别常见的命名规律提取出标题、年份、清晰度、来源、季集编号等字段。如果识别不出来宁可留空也不能瞎猜避免把标题切得乱七八糟这种更糟的结果。第三对外接口要简单。命令行人人都能用Python API 方便二次开发输出默认 JSON看一眼就能用不用再解释。这个工具在我的设计定位里不是一个下载器也不是一个播放器它就是一个纯粹的视频档案提取器输入路径输出结构化信息仅此而已。2. video_parser的解析流程一条命令如何拆出一部视频的完整档案2.1 解析三步走文件名 → 媒体信息 → 结构化合并整个解析流程不复杂就三步文件名解析、媒体流探测、信息合并。但每一步的细节比想象中多。第一步拿到文件路径后先丢给文件名解析器。它会剥离扩展名把纯文件名切分成若干 token然后尝试匹配不同的模式。比如用分隔符点、空格、下划线、中文方括号等拆分再逐个判断 token 属于哪一类是年份、清晰度标签、编码标签、还是视频标题的组成部分。第二步调用 ffprobe 读取多媒体文件信息。这块我直接用 subprocess 调用系统安装的 ffprobe然后解析返回的 JSON。之所以没有用纯 Python 的纯解析库是因为市面上成熟的开源 ffprobe 封装已经非常稳定没必要重复造轮子。但我在外层又包了一层映射逻辑把所有可能的字段结构统一成自己定义的 schema。第三步把前两步得到的信息合并成一份最终输出。合并规则是技术参数以 ffprobe 为准文件名字段只作为补充。比如文件名里有 1080p但 ffprobe 实际读出来分辨率是 1920x1080那就以 ffprobe 的宽度和高度为准文件名里没写年份而 ffprobe 的元数据标签里有 creation_time就把这个时间补进 year 字段。如果你只是想快速看一部视频的信息命令行直接输video_parser /path/to/your/video.mp4输出的 JSON 大概是这样的{ file: { path: /path/to/your/video.mp4, name: video.mp4, size_mb: 2453.28, container: matroska }, video_stream: { codec: h264, profile: High, width: 1920, height: 1080, frame_rate: 23.976, bit_rate_kbps: 8492, pixel_format: yuv420p }, audio_streams: [ {index: 0, codec: aac, channels: 6, language: eng}, {index: 1, codec: ac3, channels: 2, language: chi} ], subtitle_streams: [], duration_sec: 7420.5, title: video, year: null, resolution_tag: 1080p }2.2 内部数据模型为了不让自己在各处维护零散的字典我定义了几个简单类VideoInfo、VideoStreamInfo、AudioStreamInfo、SubtitleStreamInfo。每个类只负责持有和自身相关的字段并提供to_dict()方法。字段全部用 snake_case方便映射到 Python 代码也方便 JSON 序列化。类设计得比较扁平没有搞多重继承解析逻辑放到了独立模块里类和解析器解耦这样后续想加新格式支持只需要扩展解析器不动数据模型。3. 文件名智能解析正则之外的那些设计取舍3.1 视频文件命名的常见规律文件名解析是整个工具里最容易翻车的地方也是花时间最多的地方。我先把常见视频文件命名规律撸了一遍发现再多样也能归成几类模式电影类标题 年份 清晰度 来源 编码比如 The.Matrix.1999.1080p.BluRay.x264剧集类标题 SxxExx 集名 清晰度来源比如 Breaking.Bad.S01E01.BluRay.1080p 或者中文 《狂飙》第05集综艺/番剧类标题 集数 格式比如 SomeShow.EP12.720p 或 【合集】某某节目第3期设备导出类无规律纯时间戳或序号比如 VID_20240301_153012.mp4这个规律一旦理清解析器的架构思路就变清晰了不能一上来就写一套万能正则而应该定义一套分级规则让不同命名模式的解析器按优先级依次尝试。3.2 解析规则的优先级从具体到模糊我的规则引擎从最具体的模式开始匹配匹配失败再降级尝试下一个剧集模式先找 SxxExx 或 第x集 等特征命中后就按剧集逻辑拆。电影模式找年份四位数通常 1900-2100 之间找到后再往前截标题。清晰度优先模式找 4K、1080p、720p、REMUX 等清晰度标签确定分辨率标签和来源标签BluRay、WEB-DL、HDTV。全标题兜底上述都没命中就把文件名去掉前后缀后整体当作标题。这样设计有一个好处先拿最确定的锚点再把剩余部分按逻辑拆分避免了在模糊段落里到处套正则导致误伤。3.3 几个容易误判的真实案例踩过的坑比预想多。举三个例子第一个是标题里含年份。The.1999.Project.2021.1080p 这种年份前后都有数字。如果无脑找第一个四位数就会把片名里的 1999 当发行年份。我的处理方式是在电影模式下优先选择最后一个四位数作为年份因为按常见命名习惯发行年份更接近文件名尾部。第二个是混合分隔符。有的文件是 电影名.2021.1080p [BDRemux]既有英文点又有中文方括号。简单按点切分就会把 [BDRemux] 带方括号的 token 和其他 token 混在一起。所以切分时我保留原始分隔符信息不是简单拆字符串而是把文件名拆成一个 token 列表每个 token 带上自己前面的分隔符类型再交给规则引擎。第三个是第2021期这种集数。中文里第xxxx期的数字并不一定是年份这类节目集数字段和年份字段要分开对待。我目前的对策是一旦命中第x期/第x集模式优先按剧集处理年份字段只从显式四位数里提取。4. 元数据读取的底层逻辑容器、编码流与比特率计算4.1 容器层和编码层是两个概念很多刚开始解析视频的读者会在一个点上绕晕容器格式和编码格式不是一个东西。MKV、MP4、AVI 是容器格式H.264、H.265、VP9 是编码格式。容器负责把视频流、音轨、字幕轨、章节信息打包到一起编码则是压缩图像和声音的算法本身。这个区分非常重要因为视频解析出的技术参数里容器信息来自文件头部编码信息来自流数据。如果只调 ffprobe 而不关心这两层很可能出现一种情况一个 MKV 文件容器是 MKV但视频流编码是 AV1。如果你在归档脚本里拿扩展名判断编码格式就永远得不到正确结果。4.2 时长、帧率、比特率这些参数是怎么算出来的大部分元数据直接来自 ffprobe 的format和streams字段但有几个参数需要额外处理。时长duration直接取format.duration但某些损坏文件或录制流这个字段可能是空。遇到这种情况我会尝试用视频流中的duration字段替代还不行就标记为null绝不填 0。帧率frame_rateffprobe 返回的是一个分数形式字符串比如 24000/1001这才是准确形式。我拿到后会把它转成浮点数同时保留原始分数供需要精确计算的场景使用。比特率bit_rate需要注意format.bit_rate是整个文件的平均比特率包含视频、音频以及所有附加数据。而streams里每个流有自己的bit_rate。如果只看文件总比特率来判断画质会被多音轨拉高产生误判。所以我默认展示视频流的bit_rate总比特率作为参考字段。4.3 为什么要做多数据源校验解析过程中经常遇到文件名和元数据打架的情况。比如文件名叫 xxx.1080p但 ffprobe 实际读出分辨率是 1280x720显然是文件名写错了或者片源被重新压过。video_parser 的处理逻辑是技术字段优先信元数据文件名标签只作为附加参考两者不一致时在输出的warnings字段里给出提示而不是直接报错。这种宁可多给一条警告也不替用户做决定的设计思路在工具开发中很实用。自动解析系统最怕的就是在不确定的环节硬猜猜对了是运气猜错了用户没法排查。5. 两种使用姿势命令行输出与Python API嵌入5.1 命令行单文件查看与批量输出命令行设计参照了 Unix 工具哲学默认输出人类可读的摘要--json输出完整 JSON方便管道处理。我实际最常用的命令是两个# 查看单文件摘要 video_parser video.mp4 # 批量解析目录下所有视频输出 JSON 到文件 video_parser --batch /path/to/folder --json result.json批量模式下我加了进度条和失败日志两个开关。一个大目录几百个视频跑起来最怕的就是中途某文件损坏导致整个进程退出。所以批量处理时我对每个文件做异常捕获失败的写入独立错误日志最后汇总打印一句成功 N 个失败 M 个不打断整体流程。5.2 Python API作为管道接入自动化脚本命令行做交互够用但真正要自动化还是得靠 Python API。用法很直接from video_parser import parse_file info parse_file(/path/to/video.mkv) print(info.video_stream.codec) # h264 print(info.title) # 从文件名提取的标题 print(info.duration_sec) # 7420.5我在设计 API 时刻意保持极简对外就几个核心函数——parse_file、parse_folder、parse_name。前两个管文件解析第三个单独暴露文件名解析能力方便用户不想碰 ffprobe 时单独使用。内部实现里ffprobe 的调用结果会做一层缓存。同一个文件短时间内重复解析直接从缓存取结果避免反复 IO 拖慢批量任务。这个缓存默认关在传入use_cacheTrue时启用。5.3 输出格式怎么选JSON 是我默认推荐的输出格式结构清晰、前后端通用。但为了照顾快速看一眼的场景我也做了默认的文本摘要输出类似这样File: video.mp4 (2.4 GB) Container: matroska Video: h264 (High) 1920x1080 23.976 fps, ~8492 kbps Audio: aac 6ch (eng), ac3 2ch (chi) Subtitle: (none) Duration: 2h03m40s如果接了--yaml还会输出 YAML 格式专门给喜欢把参数直接写成配置文件的人用。YAML 和 JSON 内容一样只是序列化方式不同内部没有额外维护两套数据。6. 实测表现、踩坑记录和后续扩展想法6.1 1000个文件的批量实测我把工具放到自己一个存了 1137 个视频文件的测试目录里跑了一遍测试环境是 MacBook Pro M1Python 3.11。结果如下指标数值总耗时约 6 分 40 秒平均单文件耗时约 0.35 秒成功解析1105 个文件名解析成功提取到标题986 个元数据读取失败32 个主要是损坏文件大部分耗时花在 ffprobe 对整个文件的头部和索引信息的读取上。视频文件越大耗时越明显尤其是一些 4K 高码率 MKV单文件可能耗时 2 秒以上。如果追求速度可以考虑只读容器头部的参数比如用更轻量的工具但信息完整度会打折。我的取舍是默认完整解析后续再考虑轻量模式。6.2 值得记录的三个坑第一个坑文件路径里的中文字符导致解析失败。在 macOS 和 Windows 上Python 传给 subprocess 参数时如果路径包含特殊字符或全角空格偶发编码问题。解决方式是所有路径操作统一转成绝对路径并显式指定编码参数避免系统默认编码差异。第二个坑可变帧率VFR文件的时长对不上。某些录制文件是可变帧率ffprobe 返回的帧率只是一个平均参考值视频流的 duration 和 format 的 duration 可能差零点几秒。对于这种文件我选择在warnings里提示检测到可变帧率部分时间参数仅供参考而不是强行统一时间轴。第三个坑多音轨和字幕轨的语言标签缺失。很多老片源音轨没有 language 字段ffprobe 返回空字符串。我一开始把它们标成 undundefined后来发现用户体验不好。改成有标签读标签没标签时按轨道序号显示track 1并额外加一个language_guessed布尔字段告诉用户这个语言信息是猜的。6.3 下一步字幕流、章节信息和媒体服务器对接目前的版本已经能稳定处理视频流、音轨和字幕轨信息但我觉得还有三个很实际的扩展方向。第一个是把字幕流和章节信息也纳入详细输出。很多 MKV 自带章节文件名不一定能看到但章节能帮助快速定位片段对做剪辑的人很有用。第二个是直接生成 Emby / Jellyfin 可识别的图片信息文件或者 NFO 文件。这样批量解析后直接丢进媒体服务器能省掉刮削器的时间。这个功能我正在写基本思路是把解析结果映射到 NFO 的 XML 结构上。第三个是提供一个简单的 Web 服务接口POST 一个文件路径就返回 JSON方便其他工具通过 HTTP 调用。技术栈打算用 FastAPI内部还是调用现有的解析核心不做额外改动。工具的核心思路就一句话把读取视频信息这件事从为单个文件写命令升级成批量结构化的自动流程。如果你也遇到过类似的管理痛点直接用这个思路写一个自己的版本应该能省下不少时间。我个人实际使用中的体会是一个工具用得顺手关键不在于功能多而在于它在一个场景里足够可靠。video_parser 的目标就是让视频信息提取这个场景变可靠后面的扩展都只是顺水推舟。本文还有配套的精品资源点击获取