计算机视觉 / 系统课时
排查视频无法保存
排查视频无法保存
视频处理能正常显示,却没有生成文件、文件大小为 0,或生成后无法播放,通常不是 write() 单点故障,而是编码器、扩展名、帧率、帧尺寸或写入权限之间不匹配。本篇按“先隔离环境,再回到业务代码”的顺序定位问题。
学习目标
- 判断
VideoWriter是初始化失败、写帧失败,还是文件落盘后不可读 - 核对 FourCC、扩展名、FPS、帧尺寸与实际帧数据是否一致
- 用最小脚本验证编码器和输出路径,再把结论迁回业务程序
先把故障切成几个阶段
排查时不要先盯着最终播放器。VideoWriter 的链路至少包含“创建输出文件 → 打开编码器 → 接收符合约定的帧 → 释放并封装 → 再次解码验证”几个阶段。最关键的第一问是 writer.isOpened() 是否为真;如果这里已经失败,后续调用 write() 再多次也不会得到有效视频。

一个常见误区是“文件已经出现,所以写入一定成功”。容器文件可能在创建 VideoWriter 时就被建立,即使后续编码没有真正写出可解码帧,路径上仍可能看到一个很小的空壳文件。
用最小脚本隔离编码与路径问题
先脱离摄像头、业务滤镜和复杂线程,只写一段固定尺寸的测试画面。下面示例使用 MJPG 与 .avi 做环境自检,并在写完后立即用 OpenCV 回读第一帧。
from pathlib import Path
import cv2
import numpy as np
output = Path("writer-check.avi").resolve()
fps = 25.0
size = (640, 360) # VideoWriter 使用 (width, height)
fourcc = cv2.VideoWriter_fourcc(*"MJPG")
writer = cv2.VideoWriter(str(output), fourcc, fps, size)
print(f"writer_opened={writer.isOpened()}")
if not writer.isOpened():
raise RuntimeError("VideoWriter 打开失败")
for index in range(30):
frame = np.zeros((size[1], size[0], 3), dtype=np.uint8)
cv2.putText(
frame,
f"frame {index}",
(40, 180),
cv2.FONT_HERSHEY_SIMPLEX,
1.2,
(255, 255, 255),
2,
cv2.LINE_AA,
)
writer.write(frame)
writer.release()
cap = cv2.VideoCapture(str(output))
print(f"file_exists={output.exists()}")
print(f"file_size={output.stat().st_size if output.exists() else 0}")
print(f"readback_opened={cap.isOpened()}")
ok, frame = cap.read()
print(f"first_frame_read={ok}")
if ok:
print(f"first_frame_size={frame.shape[1]}x{frame.shape[0]}")
cap.release()预期输出
writer_opened=True
file_exists=True
file_size=<VALUE>
readback_opened=True
first_frame_read=True
first_frame_size=640x360<VALUE> 是随平台和编码器变化的非零文件大小。若 writer_opened=False,优先检查当前 OpenCV 构建是否支持该编码方式,以及输出目录是否存在并可写;不要继续排查业务帧内容。
核对实际项目中的五个约束
FourCC 与文件扩展名要组成后端能够封装的组合。不要只改扩展名,例如把原本按 AVI 方式写出的文件直接命名为 .mp4;如果目标容器和编码器不兼容,VideoWriter 可能无法打开,或生成播放器无法识别的文件。
FPS 必须是正数,并且最好来自可靠来源。读取文件时可以用 cap.get(cv2.CAP_PROP_FPS) 获取;若返回 0、NaN 或明显异常值,应给出业务允许的回退值,而不是把异常值原样传给 VideoWriter。
尺寸最容易写反。初始化参数是 (width, height),而 NumPy 图像的 shape 通常是 (height, width, channels)。如果初始化为 (1280, 720),每次传入的彩色帧就必须对应 frame.shape[:2] == (720, 1280);裁剪、旋转或缩放后尺寸发生变化时,要先统一到固定输出尺寸再写入。
彩色视频通常应写入 8 位三通道 BGR 帧。若流程中转成了灰度图,要么在创建 writer 时明确使用灰度模式并确认后端支持,要么在写入前转换回三通道。还应确认 frame 不是空值,且数据类型没有意外变成浮点张量。
路径问题则包括父目录不存在、当前用户无写权限、目标文件被其他进程占用,以及相对路径落到了意料之外的工作目录。排查时先打印绝对输出路径,再确认目录可创建普通文件。
写完之后必须做回读验证
正常结束前必须执行 writer.release()。编码器往往会在释放阶段写入容器尾部信息,因此程序被强制终止、异常路径漏掉 release(),都可能留下“有文件但打不开”的结果。稳妥做法是在 finally 中统一释放 VideoWriter、VideoCapture 和窗口资源。
修复后不要只看文件是否存在,还要同时验证文件大小大于 0、VideoCapture 能重新打开、至少能读取第一帧,并检查回读帧尺寸是否与写入约定一致。这样才能确认问题已经从“文件创建”一路排除到“可实际解码”。