计算机视觉 / 系统课时
读取视频文件
读取视频文件
读取本地视频时,最小闭环是用 cv2.VideoCapture 打开文件,循环调用 read() 取得帧,按原视频帧率显示,并在结束或退出时释放句柄与窗口。下面示例适用于 OpenCV 4.x 的 Python 接口。
学习目标
- 能用
cv2.VideoCapture打开本地视频并检查是否成功。 - 能按帧循环读取、显示视频,并正确判断文件结束。
- 能查询分辨率、帧率和总帧数,并在退出时释放资源。
打开文件并先检查状态
cv2.VideoCapture(path) 会让 OpenCV 选择可用的视频后端尝试打开文件。创建对象不等于一定打开成功,所以第一步必须检查 cap.isOpened();相对路径还要特别注意当前工作目录,排错时优先改成绝对路径。
可直接检查的四项属性是 CAP_PROP_FRAME_WIDTH、CAP_PROP_FRAME_HEIGHT、CAP_PROP_FPS 和 CAP_PROP_FRAME_COUNT。例如一个 1920×1080、25 FPS、250 帧的视频,理论时长约为 10 秒;部分编码或后端可能返回 0,此时不要把元数据当成唯一真值。
循环读取并按帧率显示
cap.read() 每次同时完成抓取与解码,返回 (ok, frame)。ok=True 时 frame 通常是 BGR 顺序的 NumPy 数组;视频到达末尾、解码失败或输入中断时会返回 ok=False,循环应立即停止。

下面脚本保存为 read_video.py,运行时传入一个真实存在的视频文件路径。delay_ms 用 1000 / fps 估算单帧显示时间;若后端没有给出 FPS,则回退到 33 ms,约等于 30 FPS 的显示节奏。
from pathlib import Path
import sys
import cv2
if len(sys.argv) != 2:
raise SystemExit("用法: python read_video.py <video-path>")
video_path = Path(sys.argv[1]).expanduser().resolve()
cap = cv2.VideoCapture(str(video_path))
if not cap.isOpened():
raise SystemExit(f"无法打开视频: {video_path}")
fps = cap.get(cv2.CAP_PROP_FPS)
frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
delay_ms = max(1, round(1000 / fps)) if fps > 0 else 33
print(f"video={video_path}")
print(f"resolution={width}x{height}")
print(f"fps={fps:.2f}")
print(f"frames={frame_count}")
try:
while True:
ok, frame = cap.read()
if not ok:
print("end of video")
break
cv2.imshow("Video", frame)
# Esc 的键值是 27;按下后主动结束播放。
if cv2.waitKey(delay_ms) & 0xFF == 27:
print("stopped by user")
break
finally:
cap.release()
cv2.destroyAllWindows()预期输出
video=<PATH>
resolution=<WIDTH>x<HEIGHT>
fps=<FPS>
frames=<FRAMES>
end of video<PATH>、<WIDTH>、<HEIGHT>、<FPS> 和 <FRAMES> 会随文件变化;如果播放过程中按 Esc,最后一行会变成 stopped by user。窗口应连续显示视频画面,而不是只停在第一帧。
区分正常结束和读取异常
对普通本地文件来说,循环末尾出现一次 ok=False 通常就是正常 EOF;如果第一帧就失败,则优先检查文件路径、文件是否损坏以及当前 OpenCV 构建是否具备对应解码后端。能被系统播放器打开,并不保证当前 OpenCV 构建一定能解码。
可按这个顺序定位:先确认 isOpened();再测试一个常见 MP4 或 AVI 文件;然后用 cv2.getBuildInformation() 查看 Video I/O 段是否包含预期后端。若使用 opencv-python-headless,视频解码仍可能可用,但 cv2.imshow() 不提供桌面 GUI,需改用普通 opencv-python 或取消窗口显示。
释放资源并检查退出行为
cap.release() 负责关闭视频文件或捕获后端,cv2.destroyAllWindows() 负责关闭 HighGUI 窗口。把两者放进 finally,可以覆盖正常播完、按 Esc 退出以及循环中抛出异常三种路径,避免句柄长期占用。
验收时观察三点:视频能连续播放;到末尾后程序自行结束;提前按 Esc 后窗口立即关闭。如果窗口卡住不响应,先确认循环中确实调用了 cv2.waitKey(),因为 HighGUI 依赖它处理窗口事件。