OpenCV视频保存实战：VideoWriter与fourcc编码格式详解-北京尧图网络

做OpenCV视频处理的时候不少人会遇到这样一个情况cv2.VideoCapture()能正常读帧画面也能一帧一帧地显示出来但一旦想把它存成视频文件要么直接报错要么生成一个0字节的mp4折腾半天还不知道问题出在哪。我当年第一次用OpenCV做摄像头录像时也这样后来才发现关键就在cv2.VideoWriter_fourcc()和cv2.VideoWriter()这两个函数的配合上。其实这两个函数就是OpenCV里负责“把图像帧序列写成视频文件”的核心组合。cv2.VideoWriter_fourcc()用来指定视频的编码格式cv2.VideoWriter()则负责真正创建视频文件、接收图像帧、按帧率写入。很多教程把它们分开讲但实际用的时候少了哪个都不行而且一旦对编码格式和容器格式的匹配关系理解不到位后面各种问题都会冒出来。这篇文章就打算把我自己踩过的坑和总结出的经验完整写一遍内容包括为什么视频保存必须先确定编码格式、两个函数各自的参数怎么填、从摄像头和从视频文件两种场景下的完整写法、以及我最常被问到的“mp4打不开”“视频播放速度不对”“分辨率对不上”这类问题的排查思路。不管你是刚接触OpenCV的初学者还是写了一些图像处理代码想加一个视频保存功能的开发者这篇文章应该能帮你省下很多试错时间。1. 整体设计思路为什么视频保存这么容易翻车1.1 视频文件不是“一堆图片拼起来”那么简单很多人初学时会有一种直觉视频嘛就是把一帧一帧的图像连续存起来像连环画一样。但实际工程里视频文件远比这复杂。一个标准的视频文件其实由两部分组成容器格式和编码格式。容器是外壳决定文件的封装结构比如我们常见的.mp4、.avi、.mov它们是“盒子”编码是内核决定每一帧图像怎么被压缩存储比如H.264、MPEG-4、Motion JPEG它们是“压缩算法”。我用一个生活里比较好懂的类比来解释容器像是快递箱编码像是你把行李打包的方式。快递箱决定了外观尺寸和运输规则打包方式决定了里面塞了多少东西、塞得紧不紧。OpenCV写视频时cv2.VideoWriter()负责拿快递箱也就是创建文件、管理帧数据cv2.VideoWriter_fourcc()则负责告诉它行李该按什么方式打包。两者必须配合使用缺一个快递员底层代码就不知道该按什么规格处理你的包裹。所以在动手写代码之前第一件要想清楚的事就是我要输出什么格式的文件用什么编码器来压缩。一旦这个组合不匹配——比如你用mp4v编码器却写了.avi扩展名或者某个平台不支持你指定的编码器——结果就是保存失败或者文件看起来有大小但任何播放器都打不开。1.2 cv2.VideoWriter_fourcc()到底是什么东西cv2.VideoWriter_fourcc()这个函数名字看起来长实际作用非常单纯把四个字符转换成一个整数编码值。这个值是OpenCV内部用来标识编码器的ID底层根据这个ID去查找对应的编码器插件。举个例子fourcc cv2.VideoWriter_fourcc(*mp4v)这行代码的含义是把字符m、p、4、v组合成一个四字符编码告诉OpenCV“我要用MPEG-4编码器”。星号*的作用是把字符串拆成四个独立的字符传参写成cv2.VideoWriter_fourcc(m, p, 4, v)也完全等价只是前者更简洁。这里有个特别容易忽略的重点cv2.VideoWriter_fourcc()本身不携带任何“编码器实现”它只是做了一次查表映射真正干活的编码器是OpenCV在运行时从系统底层的编解码库比如FFmpeg里加载的。所以同样一段代码在Windows上可能正常到了Linux服务器上可能因为缺少编码器库而报错。这也是为什么我后面会专门讨论不同平台的差异。1.3 cv2.VideoWriter()初始化时其实一次性定死了参数cv2.VideoWriter()的构造函数签名是这样的cv2.VideoWriter(filename, fourcc, fps, frameSize[, isColor])参数依次是输出文件名、编码ID、帧率、帧尺寸、是否彩色。表面上看有五个参数但真正的决策在初始化那一刻就全部锁死了文件格式、压缩方式、播放速度、画面大小、色彩模式之后你再想改任何一项都需要重新构造一个VideoWriter对象。这个“初始化即锁定”的特性很多初学者不知道导致代码里出现类似“写完几帧之后突然改变图片尺寸”的操作然后莫名其妙报错。实际上VideoWriter一旦创建内部缓冲区、编码器状态、文件头信息全都按初始参数分配好了后续每一帧write()进去的数据都必须严格符合初始化时的宽度、高度、色彩通道数要求。我见过一个常见的翻车写法初始化时用的分辨率是(1280, 720)处理过程中因为用了cv2.resize()输出帧尺寸变成了(640, 480)结果writer.write(frame)直接抛出异常。这种情况不是函数随机抽风而是你违背了“初始化即锁定”这个规则。2. 核心细节解析编码格式、容器和参数选型2.1 常用FourCC编码格式对比先放一张我实际测试过且常用的编码格式对比表。如果你只打算保存一种格式建议直接在这几个里面选.mp4配mp4v或avc1.avi配XVID或MJPG追求兼容性就选.avi配MJPG。FourCC编码全称常见容器压缩方式特点与适用场景mp4vMPEG-4 Part 2.mp4有损压缩兼容性好OpenCV内置支持度高Windows/macOS通用avc1H.264.mp4有损压缩压缩率高、画质好但OpenCV默认不带编码器经常初始化失败XVIDXvid MPEG-4.avi有损压缩老牌编码Linux/Windows上常见适合普通视频保存MJPGMotion JPEG.aviMJPEG逐帧压缩每帧独立压缩写入速度尚可兼容性极好调试首选DIVXDivX MPEG-4.avi有损压缩早期DVD播放器常用现在用的人少了I420Uncompressed YUV.avi无压缩文件巨大一般不用于日常保存从实际项目经验来看如果你开发的程序要拿到不同电脑上运行又不想装额外的编解码器MJPG.avi是最稳妥的组合。它的缺点是压缩率低同样分辨率文件体积比H.264大不少优点是几乎所有平台和播放器都认得它OpenCV自带的编码支持也够不需要额外安装库。如果你追求的是“文件小、清晰度好”在Windows下用mp4v.mp4就很好多数系统自带MPEG-4解码器生成的视频能被QQ影音、Windows Media Player等直接打开。avc1虽然压缩率最好但我必须提醒你OpenCV在默认安装情况下并不总是包含H.264编码器支持尤其是Linux下一旦系统里没有FFmpeg的H.264库VideoWriter初始化就会失败哪怕编码ID填得再正确也没用。2.2 扩展名和编码格式不是随便组装的这里有个隐藏规则很多人没弄明白扩展名决定“文件外壳”FourCC决定“压缩内核”两者可以不匹配但能不能播放就不好说。我用一个现实中的例子来说明。OpenCV的VideoWriter在写文件时其实并不强制校验扩展名与编码是否配套某些组合能跑通但生成的文件可能打不开。比如用XVID编码写.mp4文件OpenCV底层能用FFmpeg封装但很多播放器对“开放容器里塞了非标准编码”这件事兼容性极差。反过来用mp4v编码写.avi情况也差不多。我自己总结了一套选择逻辑思路很直接先定容器再选编码。你要输出.mp4就在H.264/MPEG-4里选你要输出.avi就老老实实用XVID或MJPG。不要用“这个方法我试过能写文件”作为标准——写出来是一码事别人能不能打开是另一码事。还有一点容易忽略视频文件后缀的大小写。video.mp4和video.MP4在Windows上没区别但在Linux服务器上区分大小写是系统级的规则OpenCV底层通过文件系统创建文件时会严格按你传入的字符串处理。我吃过这个亏在Windows上开发完美运行部署到Linux后代码直接不生成文件排查半天发现是文件名后缀写成了.MP4系统里压根没创建出来文件。2.3 帧率、分辨率和彩色通道参数的细节fps参数设置多少直接决定你保存的视频看起来是正常速度还是快进/慢放。它的本质是告诉编码器“每秒播放多少帧画面”但这个值不一定等于你采集时的真实帧率。最常见的错误是摄像头采集是30帧/秒你在初始化VideoWriter时fps填了15结果保存出来的视频播放时整体加速了一倍动作看起来像开了倍速一样。原因很简单源采集向writer里写入的帧数是每秒30帧但writer认为它只需要15帧/秒来播放于是播放器按照15帧/秒的节奏去放30帧的量自然只够放2秒相当于2秒内放完了原本1秒的内容。所以设置fps时要有一个基本原则尽量让写入帧率和采集帧率保持一致。如果你处理的是视频文件读帧可以直接用cap.get(cv2.CAP_PROP_FPS)把源视频的帧率读出来再传给VideoWriter。frameSize参数是另一个高频翻车点格式必须是(width, height)注意是先宽后高。很多人用frame.shape拿到的是(height, width, channels)如果直接传frame.shape[:2]就把(高, 宽)传成了(宽, 高)——顺序反了。虽然有些情况下VideoWriter不会立刻报错但写出来的视频是歪的或者会直接提示frame size does not match。isColor参数默认是True意思是输入帧是BGR彩色。如果你在写灰度图必须显式传False否则OpenCV会试图把单通道帧当作三通道处理结果要么报错要么生成一个颜色通道错乱的文件。要判断输入帧是单通道还是三通道可以在写入前打印frame.shape检查一下。3. 实操过程与核心环节实现3.1 从摄像头采集并实时保存成视频文件这是最典型的入门场景打开摄像头画面在窗口里显示同时把画面保存成视频文件。完整代码如下注释里我会标注每个参数为什么这么填。import cv2 # 打开摄像头0代表默认摄像头 cap cv2.VideoCapture(0) if not cap.isOpened(): print(摄像头打开失败请检查设备) exit() # 读取一帧用于获取真实分辨率 ret, frame cap.read() if not ret: print(无法读取画面) exit() height, width frame.shape[:2] fps 30 # 采集帧率根据你的摄像头实际能力调整 # 关键点先定义编码再传给VideoWriter fourcc cv2.VideoWriter_fourcc(*mp4v) out cv2.VideoWriter(output.mp4, fourcc, fps, (width, height)) print(f开始录制分辨率 {width}x{height}帧率 {fps}) while True: ret, frame cap.read() if not ret: break # 写入当前帧 out.write(frame) cv2.imshow(Recording, frame) # 按q键退出 if cv2.waitKey(1) 0xFF ord(q): break cap.release() out.release() cv2.destroyAllWindows() print(录制完成文件已保存)这段代码里有几个细节值得单独说。第一我在初始化out之前先读了一帧用这帧的实际尺寸来初始化VideoWriter这样能避免“手动填一个分辨率但摄像头实际输出的尺寸不一致”的问题。很多摄像头在初始化后第一帧才真正调整好分辨率直接调用cap.get(cv2.CAP_PROP_FRAME_WIDTH)拿到的值有时候并不可靠。第二fps设置成30这是我假设大多数USB摄像头支持30帧/秒采集。但如果你不想硬编码可以用cap.get(cv2.CAP_PROP_FPS)来获取摄像头当前设置的帧率。这里有一个坑部分摄像头的这个接口返回0或一个不准确的值保险起见先读一帧再根据自己需要的节奏来设置也行。第三我在循环里用cv2.waitKey(1)每次等待1毫秒既能让窗口正常显示画面又不会因为等待太久拖慢录制帧率。3.2 从视频文件读取并处理后再写出另一个常见需求是读一个已有的视频文件对每一帧做处理比如转为灰度图、加Rect框然后输出成一个新视频。这个场景里读取帧率的来源变得很关键因为你要尽量保持输出视频和输入视频的节奏一致。import cv2 cap cv2.VideoCapture(input.avi) if not cap.isOpened(): print(无法打开输入视频) exit() # 从输入视频获取真实帧率和尺寸 fps cap.get(cv2.CAP_PROP_FPS) width int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) # 这里用XVID配合.avi容器 fourcc cv2.VideoWriter_fourcc(*XVID) out cv2.VideoWriter(output.avi, fourcc, fps, (width, height), isColorFalse) while True: ret, frame cap.read() if not ret: break # 转为灰度图模拟图像处理 gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) out.write(gray) cv2.imshow(Processing, gray) if cv2.waitKey(1) 0xFF ord(q): break cap.release() out.release() cv2.destroyAllWindows()这个例子里fps是从源视频里动态读取的所以输出的视频播放节奏会和输入一致。isColorFalse是因为我写了灰度帧如果这里不改成FalseOpenCV会尝试把单通道图像当成三通道写大概率会报frame size does not match。这里还要提醒一个点cap.get(cv2.CAP_PROP_FPS)返回的是浮点数比如29.97用于VideoWriter是没问题的。但如果你对帧率精度要求极高转码后可能有微小的时长偏差一般的预览和日常使用完全感知不到差距。3.3 设置固定时长和停止条件的补充方案有的项目不需要人工按q键停止而是要求录够指定的秒数后自动保存。这种情况不必用复杂定时器直接按帧数计数就可以duration 10 # 录制时长单位秒 frame_count int(fps * duration) current_frame 0 while current_frame frame_count: ret, frame cap.read() if not ret: break out.write(frame) current_frame 1这个方法逻辑简单但有一个默认前提你写入out的速度要跟得上采集速度。如果处理每帧的时间过长比如一帧处理花了200毫秒那么实际录10秒的结果可能只有一半的帧数播放起来会变成慢动作。要在这种“处理慢”的场景下保证输出时长准确更稳妥的办法是引入一个时间戳判断但日常大多数场景直接用帧计数就够了。3.4 多线程提示连续录制不要一直占着主循环如果你的程序里还有其他逻辑比如目标检测、界面刷新不要让视频写入占用主线程。把摄像头读取和视频写入放到独立线程里是工程化时必须考虑的事。基本的思路是主线程负责界面交互采集线程读帧并写入队列写入线程从队列取帧再调用writer.write()。这是一个典型的生产者-消费者模型。OpenCV本身的write()是同步阻塞的在帧率高或编码压力大时如果主线程里做耗时操作帧就会堆积录制出来的视频会越来越卡。我用过一个简单的单生产者单消费者方案队列长度限到10帧满了就丢最旧的一帧保证录制实时性。这个方案对大多数项目来说够用了。4. 常见问题与排查技巧实录4.1 保存的mp4文件打不开或者显示0字节这个问题几乎每个用OpenCV保存视频的人都会遇到核心原因有两种而且往往同时出现。第一种fourcc格式和文件扩展名不匹配。比如用XVID编码器写.mp4文件名虽然代码可能不报错但出来的文件在很多播放器里就是打不开或者只能播放声音没有画面。我的建议是严格对照我前面那套“先定容器再选编码”的逻辑来选组合。第二种系统缺少对应的编码器。OpenCV在Windows上能直接用的编码器通常很多因为系统自带的Media Foundation和DirectShow带了大量解码/编码支持但在Linux上很多发行版默认只装了最小化的FFmpeg库H.264、MPEG-4这些常用编码器不一定安装完整。判断方法很简单在初始化VideoWriter之后立刻检查out.isOpened()如果返回False说明编码器没加载成功这时候再怎么改帧尺寸、帧率都没用。写代码时加上这个检查out cv2.VideoWriter(output.mp4, fourcc, fps, (width, height)) if not out.isOpened(): print(VideoWriter初始化失败请检查编码器支持或更换fourcc) exit()这条检查语句能帮你省掉至少一半的排查时间我建议所有视频写入相关代码都加上。4.2 视频播放速度不对像快进或慢放前面说过核心原因是写入帧率和VideoWriter的fps参数设置不一致。但这里我要补充一个容易被忽视的场景如果你从视频源读帧后做了耗时较长的图像处理实际写入速度低于源视频的fps那你传给VideoWriter的fps应该用“实际处理速度”而不是“源视频帧率”否则生成的视频在播放时会出现“抽帧感”——画面一顿一顿。一个比较实际的调整方法是根据处理耗时的估算降低输出fps值。比如源视频25帧/秒但每帧处理耗时80毫秒约12.5帧/秒那输出fps设为12或13短视频看起来会比较自然。如果你是非实时离线处理更严谨的做法是记录每帧时间戳按时间戳写入但多数场景用固定帧率就足够。4.3 报错 frame size does not match这个错误的字面意思是你传入write()的帧尺寸和初始化时frameSize不一致。触发原因主要有两个第一个直接把frame.shape当成frameSize传入。frame.shape返回(height, width, channels)而VideoWriter的frameSize要求(width, height)。对于非正方形图像顺序一颠倒尺寸就对不上。正确写法是height, width frame.shape[:2] out cv2.VideoWriter(output.avi, fourcc, fps, (width, height))第二个处理过程中改变了图像尺寸。比如你用cv2.resize()把画面缩放成另一尺寸或者拼接了多路图像尺寸变了却没同步给VideoWriter。解决办法有两个一是所有帧写入前统一resize到初始化尺寸二是干脆多创建几个VideoWriter分别对应不同分辨率各自写各自的帧。4.4 不同操作系统的编码支持差异这是最容易被项目文档忽略、但对实际落地影响巨大的问题。我列一张表把我在三个主要平台上实测过的组合整理出来你可以直接当参考。平台推荐组合不建议的组合备注Windowsmp4v .mp4, XVID .aviavc1 .mp4Windows自带编码较多mp4v最省事LinuxMJPG .avi, XVID .aviavc1 .mp4需要检查FFmpeg库是否完整macOSmp4v .mp4, MJPG .aviavc1 .mp4与FFmpeg版本相关部分编码缺失在Linux上如果out.isOpened()返回False可以试试下面这条命令检查系统编码支持情况ffmpeg -encoders | grep 264能看到类似libx264的输出说明H.264编码器可用。如果没有可以用包管理器安装比如Debian/Ubuntu系的sudo apt install libavcodec-extra。装好之后OpenCV通常就能找到对应编码器了。4.5 分辨率、编码识别的调试小技巧除了上面这些直接报错的问题还有一个很隐蔽的情况代码运行起来没毛病文件也写了但视频分辨率不对、画面是花的。这通常是相机分辨率一栏与VideoWriter初始化参数不一致但恰好两者的宽度和高度互换比如360x640和640x360VideoWriter校验通过了画面却旋转了90度。排查时可以加一行打印print(VideoWriter frame size:, out.get(cv2.CAP_PROP_FRAME_WIDTH), out.get(cv2.CAP_PROP_FRAME_HEIGHT))如果输出的值和你的输入帧尺寸不一致说明初始化参数没对齐。另外VideoWriter写完后可以用cv2.VideoCapture()重新打开生成的文件读取它的CAP_PROP_FRAME_WIDTH、CAP_PROP_FRAME_HEIGHT、CAP_PROP_FPS来验证三个关键参数这也是一种事后校验的好习惯。4.6 waitKey没加参数导致画面卡死的现象虽然这篇文章主角是视频写入但很多人在录制视频时也会被cv2.waitKey()坑到。如果你在循环里写了cv2.waitKey()而不传参数它默认是无限等待按键程序就一直卡住不往下走看起来就像视频录制卡死了。正确的方式是给waitKey传一个毫秒数比如cv2.waitKey(1)让OpenCV每1毫秒检查一次键盘输入并刷新窗口。在录制视频时这个值不要设太大否则窗口刷新频率太低画面看起来很卡同时也会拖慢循环整体速度影响实际写帧的节奏。5. 一些进阶建议与项目经验5.1 视频直写还是先缓存再写如果项目追求的是“不能丢帧”比如工业检测现场要把每一帧都留存选用带缓存队列的写入策略会更稳。我先用collections.deque(maxlen30)作为帧缓存采集线程只管把帧丢进队列写入线程单独消费队列这样即使写入偶尔慢一拍也不会影响采集线程。如果项目只要求“尽量实时”不在意偶尔丢几帧那直接在采集循环里写入就行最简单直接代码量和心智负担都低。5.2 用cap.get和VideoWriter.get做参数校验运行完录制程序后我习惯用读取端把输出文件重新读回来做一个快速的自检check_cap cv2.VideoCapture(output.mp4) print(实际写入分辨率:, check_cap.get(cv2.CAP_PROP_FRAME_WIDTH), check_cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) print(实际写入帧率:, check_cap.get(cv2.CAP_PROP_FPS)) check_cap.release()这步相当于对生成文件做冒烟测试。很多编码问题在写入时不会报错生产环境放两天才发现文件打不开那就晚了。5.3 与新版OpenCV相关的原生特性如果你用的是OpenCV 4.5.2以上版本会发现一部分编码格式在安装时被原生支持得更好了。比如有文章提到OpenCV 4.5.2原生支持code128的条码识读这类图像识别特性其实也会侧面影响视频处理项目的选型因为新版本库把更多编解码器编译进主库视频写入所需的依赖就更不容易缺。这也是为什么我一直建议用较新稳定版OpenCV的原因之一。不过要注意这并不代表avc1这类编码在所有平台上都可用平台差异依然是硬伤代码里尽量用通用组合比较省心。写到最后从我这些年的项目经验来看OpenCV视频写入这块最难的不是API本身难学而是大家习惯性跳过编码格式、容器匹配这些底层逻辑直接把一段能跑的代码复制走换到另一台机器上就翻车。cv2.VideoWriter_fourcc()和cv2.VideoWriter()的组合掌握核心一点都不复杂先定容器和编码再定帧率和尺寸保持写入内容与初始参数一致。记住“初始化即锁定”这个特点大多数报错就都能解释了。最后分享一个小习惯在视频保存相关代码里我永远会在初始化之后加isOpened()检查在写完整个文件后加读取端的参数打印。这两行代码不花多少时间但能救回大把半夜排查问题的头发。你如果也在视频写入上踩过什么奇怪的坑或者发现了更好的编码组合欢迎多多交流。

OpenCV视频保存实战：VideoWriter与fourcc编码格式详解

相关推荐

Volcano Agent Scheduler 调度队列深度解析：Kubernetes 调度队列的移植、定制与升级实践

Slate v2 Exact Ledgers：为编辑器框架迁移建立逐文件精确映射台账的实战方案

3D高斯泼溅实战：自采数据+COLMAP位姿重建全流程

更多资讯

基于土壤湿度控制继电器的 Wio Terminal 实战指南（IoT-For-Beginners 自动化植物浇水项目）

VisionMaster授权更新报错“本地LM通讯出错”排查与解决

Sanity React 性能规则详解:订阅派生布尔状态,降低组件重渲染频率

FPGA加法器实验全解析：从Verilog代码到上板调试

国产低噪声LDO LTP7792实测：从参数到ADC供电设计避坑指南

cvtColor内存泄漏排查：从Mat生命周期到输出缓冲区复用

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？