OpenCV调用VideoWriter保存MP4视频无法播放的问题咨询

核心原因 #

OpenCV默认的VideoWriter在编码不支持、初始化失败时不会主动抛出异常，只会静默创建无效的写入实例，后续写入帧的操作不会实际生效，最终生成损坏的空文件。MJPG编码生成AVI的兼容性最好、依赖最少，所以能正常运行，而MP4相关编码受专利授权、依赖组件、参数配置影响，很容易触发静默失败。

第一步：先做有效性校验 #

所有VideoWriter初始化完成后，第一时间加校验代码，避免静默失败：

fourcc = cv2.VideoWriter_fourcc(*"mp4v")
writer = cv2.VideoWriter("video.mp4", fourcc, 5, (W, H), True)
# 加这行判断初始化状态
if not writer.isOpened():
    raise RuntimeError("视频写入器初始化失败，当前编码/参数不合法")

如果校验抛出错误，说明是编码支持问题；如果校验通过但最终文件还是损坏，基本是参数不匹配或者资源没释放的问题。

常见问题对应解决方法 #

• 编码参数写错：不要用*"x264"作为fourcc参数，这是第三方独立编码器的标识，OpenCV默认不识别。要生成H.264编码的MP4，fourcc优先用*"avc1"，MPEG-4编码用*"mp4v"即可，这两个是OpenCV默认支持度最高的MP4编码标识。
• 分辨率不匹配：VideoWriter初始化时传入的(W, H)参数，必须和后续每一次调用writer.write()传入的帧尺寸完全一致，差1个像素都会导致写入失败。注意不要把帧的宽高顺序搞反：OpenCV读取的帧数组维度是（高度、宽度、通道数），初始化VideoWriter的时候传的参数顺序是（宽度、高度），顺序写反是最常见的无报错生成坏文件的原因。
• 缺少编码依赖：pip默认安装的opencv-python不带H.264编码的商用授权组件，Windows平台下首次调用H.264编码时会自动下载openh264动态库，网络异常导致下载失败就会触发静默初始化失败。可以换用*"mp4v"编码规避，不需要额外安装依赖，绝大多数播放器都支持该编码的MP4文件。
• 资源未正常释放：MP4格式的文件头索引需要在写入结束时更新，写完所有帧之后必须调用writer.release()，否则文件结构不完整，任何播放器都无法打开。AVI格式对资源释放的敏感度较低，就算没正常释放有时也能播放，这也是很多人写AVI正常、写MP4损坏的高频原因。
• 零依赖兜底方案：如果不想折腾编码兼容问题，可以先用已经跑通的MJPG逻辑生成AVI临时文件，再调用本地ffmpeg转码为H.264编码的MP4，转码命令为：

  ffmpeg -i input.avi -c:v libx264 -crf 23 output.mp4
  

  转出来的文件兼容性最好，全平台所有播放器都能正常播放。

内容的提问来源于stack exchange，提问作者Gautam Anew