编码与格式 / 系统课时
用 ffprobe 读取媒体文件的流信息
用 ffprobe 读取媒体文件的流信息
拿到一个 MP4、MOV 或 MP3 文件后,先用 ffprobe 检查容器、音视频轨道和编码参数,就能判断它是否符合上传、转码或播放要求。本文会完成命令行检查、字段解读和 JSON 导出,并给出可直接用于程序校验的示例。
学习目标
- 使用 ffprobe 读取视频、音频和容器的关键参数。
- 区分编码格式、分辨率、采样率、码率与时长的字段含义。
- 将探测结果输出为 JSON,并使用 Python 自动判断媒体文件是否符合要求。
准备工具与测试文件
ffprobe 是 FFmpeg 工具集中的媒体探测程序,只读取媒体信息,不会修改原始文件。以下示例适用于包含 ffprobe、ffmpeg 的 FFmpeg 6.x、7.x 和 8.x 常规命令行发行版。
首先在终端检查安装情况:
ffprobe -version预期输出:
ffprobe version <VERSION>实际版本号及后续编译信息因安装环境而异。如果提示找不到命令,需要安装 FFmpeg,并将可执行文件所在目录加入 PATH。
为了让后面的示例能够复现,可以使用 FFmpeg 生成一个 5 秒、1280×720、30 fps 的 H.264 视频文件,包含 48 kHz AAC 音轨:
ffmpeg -f lavfi -i testsrc2=size=1280x720:rate=30 -f lavfi -i sine=frequency=1000:sample_rate=48000 -t 5 -c:v libx264 -pix_fmt yuv420p -c:a aac -b:a 128k -shortest sample.mp4预期结果:当前工作目录生成 sample.mp4,文件包含一条视频轨道和一条音频轨道。此命令要求 FFmpeg 构建包含 libx264 编码器;可通过 ffmpeg -encoders 检查。文件大小和实际视频码率会随编码器版本变化。
如果已经有业务文件,也可以直接替换后续命令中的 sample.mp4,无需重新生成测试数据。
读取容器与音视频轨道
媒体文件通常分为容器和流两个层次。例如,MP4 是封装格式,容器内部可以存放 H.264 视频、AAC 音频以及字幕等不同轨道。文件扩展名不能可靠地证明内部使用了哪种编码。
使用下面的命令同时显示容器信息和全部流信息:
ffprobe -v error -show_format -show_streams sample.mp4预期输出会包含如下关键字段,其他字段根据文件及 FFmpeg 版本有所不同:
[STREAM]
index=0
codec_name=h264
codec_type=video
width=1280
height=720
[/STREAM]
[STREAM]
index=1
codec_name=aac
codec_type=audio
sample_rate=48000
[/STREAM]
[FORMAT]
filename=sample.mp4
format_name=mov,mp4,m4a,3gp,3g2,mj2
[/FORMAT]这是关键字段节选,不代表实际输出只有这些行。-v error 关闭普通日志,仅保留错误消息;-show_streams 输出每条轨道;-show_format 输出整个容器的信息。
读这些字段时,要注意它们属于不同层次:
| 字段 | 所属层次 | 含义 |
|---|---|---|
format_name |
容器 | 封装格式名称,可能包含多个兼容格式名 |
codec_type |
流 | video、audio 或 subtitle 等类型 |
codec_name |
流 | 编码格式,例如 h264、hevc、aac |
index |
流 | 该流在容器中的索引,不一定等于流类型内部序号 |
duration |
容器或流 | 该层次报告的时长,通常以秒表示 |
bit_rate |
容器或流 | 报告的平均码率,单位为 bit/s,可能不存在 |
例如,文件同时含有两个音轨时,不能简单地认为索引为 1 的流一定是唯一音轨。应该按 codec_type 筛选,再决定使用哪条轨道。
精确检查视频与音频参数
业务中通常不需要 ffprobe 输出的全部字段,可以通过 -select_streams 和 -show_entries 缩小范围。
检查第一条视频轨道的编码、画面大小、像素格式、帧率和码率:
ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height,pix_fmt,r_frame_rate,avg_frame_rate,bit_rate -of default=noprint_wrappers=1 sample.mp4预期输出包含:
codec_name=h264
width=1280
height=720
pix_fmt=yuv420p
r_frame_rate=30/1
avg_frame_rate=30/1bit_rate 是否出现以及具体值取决于文件。v:0 表示选择第一条视频流,而不是全局索引为 0 的流。
avg_frame_rate 表示报告的平均帧率,r_frame_rate 是流的基准帧率相关字段,不能无条件当作实际平均帧率。对可变帧率素材尤其不能仅凭 r_frame_rate 判断真实播放帧率。30/1 表示每秒 30 帧,30000/1001 约为 29.97 帧每秒。
再检查第一条音频轨道:
ffprobe -v error -select_streams a:0 -show_entries stream=codec_name,sample_rate,channels,channel_layout,bit_rate -of default=noprint_wrappers=1 sample.mp4预期输出中的关键字段为:
codec_name=aac
sample_rate=48000
channels=1测试音源是单声道正弦波,因此 channels=1。sample_rate=48000 表示每秒采集或表示 48000 个音频采样点,不是音频码率。若出现 bit_rate=128000 附近的值,它表示压缩后的平均数据速率,实际值允许波动。
播放与转码检查还需要区分三个概念:
- 分辨率:
width和height,如 1280×720,反映编码画面像素尺寸。 - 帧率:
avg_frame_rate等字段,描述视频时间上的画面频率。 - 码率:
bit_rate,反映单位时间的数据量,不直接等同于清晰度。
对于 5 秒、平均总码率约 1 Mb/s 的文件,粗略数据量为 1000000 × 5 ÷ 8 = 625000 字节,约 625 KB。实际文件大小还受封装开销和码率波动影响,不能用这一估算精确校验文件大小。
输出机器可读取的 JSON
程序对接时,应使用 -of json,而不是按文本行位置解析输出。下面的命令同时提取容器时长、总码率,以及各轨道的主要参数:
ffprobe -v error -show_entries format=duration,bit_rate:stream=index,codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels,bit_rate -of json sample.mp4预期输出结构如下。数值字符串及缺省字段以实际文件为准:
{
"programs": [],
"streams": [
{
"index": 0,
"codec_name": "h264",
"codec_type": "video",
"width": 1280,
"height": 720,
"avg_frame_rate": "30/1"
},
{
"index": 1,
"codec_name": "aac",
"codec_type": "audio",
"sample_rate": "48000",
"channels": 1
}
],
"format": {
"duration": "5.000000"
}
}这是按示例文件整理的结构示意:实际结果可能不包含 programs,也可能包含额外的 bit_rate 字段或略有不同的时长。不要把缺失的码率理解为零;对部分流、实时输入或尚未完成写入的文件,时长和码率可能未知。
需要保存结果时,可以使用 Shell 重定向:
ffprobe -v error -show_format -show_streams -of json sample.mp4 > metadata.json预期结果:生成 UTF-8 JSON 文件 metadata.json。重定向操作在 PowerShell 等环境中的默认文本编码行为可能因版本而异;需要严格控制编码时,应在应用程序中直接接收 ffprobe 的标准输出并以 UTF-8 写入。
使用 Python 自动校验媒体文件
假设上传平台要求视频采用 H.264,分辨率不超过 1920×1080,时长不超过 60 秒,并且必须包含 AAC 音轨。可以通过 Python 标准库调用 ffprobe,无需安装额外 Python 包。
以下代码保存为 check_media.py,依赖系统 PATH 中能够找到 ffprobe,并要求当前目录存在 sample.mp4:
import json
import subprocess
from pathlib import Path
def inspect_media(path: str) -> dict:
# 不经过 Shell,避免文件名被解释成命令参数之外的脚本内容
command = [
"ffprobe", "-v", "error",
"-show_entries", "format=duration:stream=codec_type,codec_name,width,height",
"-of", "json", path,
]
result = subprocess.run(
command, capture_output=True, text=True,
encoding="utf-8", check=True, timeout=15,
)
return json.loads(result.stdout)
def validate_media(path: str) -> bool:
metadata = inspect_media(path)
streams = metadata.get("streams", [])
videos = [s for s in streams if s.get("codec_type") == "video"]
audios = [s for s in streams if s.get("codec_type") == "audio"]
# 缺少轨道或缺少有效时长时直接拒绝
if not videos or not audios:
return False
duration = float(metadata.get("format", {}).get("duration", "inf"))
video = videos[0]
return (
0 < duration <= 60
and video.get("codec_name") == "h264"
and 0 < video.get("width", 0) <= 1920
and 0 < video.get("height", 0) <= 1080
and any(a.get("codec_name") == "aac" for a in audios)
)
if __name__ == "__main__":
file_path = "sample.mp4"
if not Path(file_path).is_file():
raise SystemExit("找不到测试文件 sample.mp4")
try:
print("校验通过" if validate_media(file_path) else "校验不通过")
except (subprocess.SubprocessError, OSError, ValueError, json.JSONDecodeError) as exc:
print(f"探测失败:{exc}")执行:
python check_media.py预期输出(使用前面生成的测试文件):
校验通过这里使用 streams 列表筛选轨道,而不是假定 streams[0] 永远是视频。duration 做浮点数转换,因为 ffprobe 的 JSON 输出通常将它表示为字符串。timeout=15 是本地小文件检查的示例限制,远程媒体或大型文件需要按实际场景调整。
这个规则只检查首条视频流和是否存在 AAC 音频流,并未证明文件能够完整解码,也未校验全部音视频轨道。正式上传服务还应设置文件体积限制、探测进程资源限制,并根据需要执行解码测试。
处理探测异常和字段缺失
遇到 Invalid data found when processing input,先检查路径是否正确、文件是否下载完整、是否确实属于可识别的媒体格式。不要仅通过修改文件后缀尝试修复编码问题。
可以先运行以下命令,仅检查容器是否可以被识别:
ffprobe -v error -show_entries format=format_name,duration -of json sample.mp4预期结果:正常 MP4 返回包含 format.format_name 的 JSON;损坏或不支持的文件则可能向标准错误输出报错并返回非零退出码。文件能读取容器信息,并不代表每一帧均可正确解码。
常见边界可按下面的方法处理:
| 现象 | 可能原因 | 正确处理 |
|---|---|---|
没有 duration |
某些实时流或不完整文件未提供时长 | 将时长标为未知,不默认填写 0 |
没有流 bit_rate |
编码或封装未提供该信息 | 用容器码率辅助分析,不当作该轨道码率 |
视频 avg_frame_rate 为 0/0 |
帧率信息不可确定 | 避免直接做除法,按帧时间戳进一步分析 |
| 没有音频流 | 文件确实无音轨或探测失败 | 根据业务规则接受无声视频或拒绝 |
| 探测命令失败 | 路径错误、文件损坏或格式不受支持 | 检查退出码及标准错误输出 |
特别注意,ffprobe 提取的是媒体描述信息,而不是完整的质量检测报告。例如,文件标记为 H.264、30 fps,不代表播放中不会黑屏、花屏或发生时间戳异常。需要验证解码时可以运行:
ffmpeg -v error -i sample.mp4 -f null -预期结果:正常完成时通常没有错误文本输出,进程退出码为 0;解码错误会写入标准错误输出。该检查与 ffprobe 元数据校验互补,但仍不能替代主观画质和音质评估。
在实际上传接口中,建议同时保存 ffprobe 原始 JSON 和经过归一化的业务字段。原始结果便于排查格式差异,归一化结果则方便播放器选型、转码任务分发及上传规则判断。