📚 课程目录第3章基于ffmpeg的实时帧率采集

3. 基于 ffmpeg 的实时帧率采集：命令行参数、输出解析、日志记录

3.1 原理概述

ffmpeg 在处理视频时默认向标准错误（stderr）输出进度信息，包括当前帧号、时间戳、速度等。通过特定的命令行参数可以控制输出的格式与位置，从而实现帧率的实时采集。核心思路是：

启动 ffmpeg 并指定输出为 null 或 pipe，仅用于帧率测量而不写入实际文件。
捕获文本输出：从 stderr 或指定的进度管道中读取每一行。
解析帧号与时间戳，计算瞬时帧率与平均帧率。
记录日志：将采集到的帧率数据写入文件或发送给监控系统。

推荐方式：使用 -progress pipe:1 将进度信息输出到 stdout 而非 stderr，便于与主进程的日志分离，避免管道阻塞。

3.2 实现流程

构建 ffmpeg 命令行（输入源、输出选项、进度输出方式）。
通过子进程启动 ffmpeg，同时重定向 stdout/stderr 到管道。
循环读取输出流，按行解析键值对（例如 frame=123、fps=25.0）。
从 frame= 行提取当前帧序号，从 out_time_us= 提取微秒时间戳。
计算每秒帧数：(当前帧 - 上一帧) / (当前时间 - 上一时间)，并记录瞬时帧率。
将结果追加到日志文件，同时可输出为 JSON 或 Prometheus 格式。
处理 ffmpeg 退出（正常结束或因异常中断）。

3.3 关键命令行参数

参数	作用	示例
`-progress pipe:1`	将进度信息输出到 stdout（文件描述符1）	`-progress pipe:1`
`-f null`	丢弃视频输出，不写文件，仅解码	`-f null -`
`-an`	禁用音频处理，减少干扰	`-an`
`-vn`	禁用视频处理？❌ 此处应保留视频解码	不指定
`-vstats_file`	将编码统计写入文件（较少用于实时采集）	`-vstats_file /tmp/vstats.log`
`-loglevel level`	控制日志详细度，建议 `error` 减少输出	`-loglevel error`
`-re`	限制读取速度为原始帧率（用于模拟实时输入）	`-re -i input.ts`

3.4 输出解析方法

以 -progress pipe:1 为例，ffmpeg 会输出如下格式的行：

frame=   47
fps=25.0
stream_0_0_q=24.0
bitrate=  1234.5kbits/s
total_size=    67890
out_time_us=   1880000
out_time_ms=   1880000
out_time=00:00:01.880000
dup_frames=0
drop_frames=0
speed=2.34x
progress=continue

解析脚本（Python 示例）可通过逐行匹配键值对提取帧号与时间：

import subprocess, re, sys

def parse_progress_line(line):
    m = re.match(r'^(\w+)=(.+)', line.strip())
    if m:
        key, val = m.group(1), m.group(2).strip()
        return key, val
    return None, None

proc = subprocess.Popen(
    ['ffmpeg', '-progress', 'pipe:1', '-i', 'input.mp4', '-f', 'null', '-'],
    stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
    universal_newlines=True)

frame = None
time_us = None
for line in proc.stdout:
    key, val = parse_progress_line(line)
    if key == 'frame':
        frame = int(val)
    elif key == 'out_time_us':
        time_us = int(val)
    # 计算帧率逻辑略
proc.wait()

注意：stderr 中仍然会输出 frame= N 等行，但格式不稳定（可能包含其他日志）。优先使用 -progress pipe:1 以获得干净的键值对。

3.5 日志记录策略

推荐将帧率数据记录为 CSV 或 Prometheus 友好的格式，便于后续分析：

timestamp,frame,time_us,fps
2025-04-01T10:00:00.123,47,1880000,25.0
2025-04-01T10:00:00.173,48,1920000,24.8
...

可在采集进程中周期性地（例如每 1 秒）将累积数据写入日志文件，避免每帧 I/O 开销。同时记录平均帧率与瞬时帧率两个指标。

3.6 调试与常见错误

问题	原因	解决方案
读取管道阻塞	ffmpeg 输出缓冲区满，未及时读取	使用非阻塞 I/O 或异步读取（如 select/poll）
帧编号不连续	B 帧导致显示顺序与解码顺序不一致	改用 `pts_time=` 字段计算帧率
日志文件过大	每帧都记录	降低采样频率（每秒或每 10 帧记录一次）
ffmpeg 意外退出	输入流结束或编码错误	监控子进程状态，自动重启并保存断点
解析数值格式错误	某些 locale 下小数点用逗号	强制 `C` locale：`env={'LC_ALL':'C'}`

3.7 性能与稳定性优化

减少解码负载：若仅需帧率，可使用 -f null -an -vn 跳过输出编码，但仍保留解码（当然不能同时用 -vn 关闭视频，否则无帧率）。可用 -c copy 仅 demux 不解码，但此时帧率信息从容器读取，不适合实时流。
使用 -progress 取代 stderr 解析：避免混合日志干扰，且输出频率可调（默认每帧一次，可通过 -stats_period 控制，但该选项仅部分版本支持）。
批量处理：对于多个视频流，每个 ffmpeg 进程独立运行，使用线程池管理输出解析。
内存回收：若采集长时间运行，需注意子进程的内存泄漏（ffmpeg 本身内存管理良好，但解析程序应避免累积未处理的行）。

3.8 帧率采集流程示意

3.9 部署建议

将采集脚本封装为 systemd 服务或 Docker 容器，设置 Restart=always。
使用 --log-rotate 或外部工具（logrotate）管理日志文件大小。
在采集过程中通过健康检查端点暴露当前帧率状态（如 HTTP /metrics）。
对于高帧率（>60fps）视频，建议将解析代码用 C/Go 实现，或用 Python 的 multiprocessing 分离 I/O 与计算。

3.10 完整命令行示例（生产级）

ffmpeg \
  -re -i rtmp://live.example.com/stream \
  -progress pipe:1 \
  -f null -an - \
  -loglevel error \
  -stats_period 0.1

上述命令以0.1秒的统计周期输出进度行（若ffmpeg版本支持），解析端每行可得到较平滑的帧率数据。若版本较旧，可通过 awk 或自定义间隔抽样。