计算机视觉 / 系统课时
实现键盘交互控制
实现键盘交互控制
实时视频窗口需要在播放循环里同时处理帧和键盘事件。本课用 cv2.waitKey() 实现空格暂停/继续、S 截图、Q 或 Esc 退出,并处理暂停状态下仍要持续接收按键这一关键细节。
学习目标
- 能用
cv2.waitKey()读取窗口键盘事件,并把按键映射为控制动作。 - 能用状态变量实现播放与暂停切换,而不是暂停后阻塞整个程序。
- 能在当前帧上完成截图,并正确释放视频与窗口资源。
先定义按键与状态
最小交互只需要一个布尔状态 paused 和一份当前帧缓存 frame。播放状态继续 cap.read();暂停状态停止取新帧,但循环本身仍运行,因此 waitKey() 还能收到继续、截图和退出按键。
| 按键 | 动作 | 状态变化 |
|---|---|---|
Space |
暂停或继续 | paused = not paused |
S |
保存当前帧 | 播放状态不变 |
Q |
退出 | 结束循环 |
Esc |
退出 | 结束循环 |

完整实现暂停、截图与退出
下面示例读取 input.mp4。正常播放时按源视频 FPS 估算等待时间;暂停时改为约 30 ms 轮询一次键盘,从而让窗口保持响应。截图保存为 shot_001.png、shot_002.png 这样的连续文件名。
import cv2
# 打开视频并用源 FPS 估算播放等待时间。
cap = cv2.VideoCapture("input.mp4")
if not cap.isOpened():
raise RuntimeError("无法打开 input.mp4")
fps = cap.get(cv2.CAP_PROP_FPS)
play_delay = max(1, round(1000 / fps)) if fps > 0 else 33
# paused 只控制是否读取新帧,不停止 GUI 事件循环。
paused = False
frame = None
shot_index = 1
while True:
if not paused:
ok, next_frame = cap.read()
if not ok:
print("video ended")
break
frame = next_frame
# 显示副本上写提示,不污染保存的原始当前帧。
display = frame.copy()
cv2.putText(
display,
"SPACE pause/resume | S screenshot | Q/ESC quit",
(20, 35),
cv2.FONT_HERSHEY_SIMPLEX,
0.7,
(0, 255, 0),
2,
cv2.LINE_AA,
)
cv2.imshow("Video", display)
# 暂停时仍持续轮询键盘,避免窗口失去响应。
key = cv2.waitKey(30 if paused else play_delay) & 0xFF
if key in (ord("q"), ord("Q"), 27):
print("quit")
break
if key == ord(" "):
paused = not paused
print("paused" if paused else "playing")
continue
if key in (ord("s"), ord("S")):
filename = f"shot_{shot_index:03d}.png"
if cv2.imwrite(filename, frame):
print(f"saved screenshot: {filename}")
shot_index += 1
else:
print("screenshot failed")
# 所有退出路径汇合到同一处释放资源。
cap.release()
cv2.destroyAllWindows()例如先按空格、再按 S、再按空格、最后按 Q,控制台预期会出现:
paused
saved screenshot: shot_001.png
playing
quit若什么键都不按并让视频自然播放到结尾,最后一行会是 video ended,不会出现 quit。
waitKey 的延迟决定交互手感
对 30 FPS 视频,单帧理论间隔约为 33.3 ms,因此 round(1000 / fps) 会得到约 33 ms;25 FPS 对应约 40 ms。这个值只是 GUI 事件等待时间,不是高精度定时器,解码和处理本身也会消耗时间,所以实时处理较重时实际播放可能慢于原速。
暂停时不能写成一个不再调用 waitKey() 的死循环,否则窗口会失去继续键。示例在暂停时固定使用 30 ms 轮询,约每秒检查 33 次按键,CPU 占用和响应速度都比较合适。若只做单步调试,也可以在特定场景使用 cv2.waitKey(0) 等待一次按键,但它不适合这里的持续状态控制。
按键无效时先检查窗口环境
按键事件由 OpenCV 的 HighGUI 窗口接收,通常要求 Video 窗口处于焦点状态。若安装的是 opencv-python-headless,则不包含常规 GUI 能力,imshow() 和键盘窗口交互不适用;桌面环境应安装带 GUI 支持的 OpenCV Python 包。
如果字母键能用而方向键、功能键行为不一致,不要把 waitKey() 返回值硬编码成不同平台的扩展键码。基础控制优先使用 Space、字母和 Esc;确实需要方向键时再考虑 cv2.waitKeyEx() 并在目标系统上实测键码。退出路径最终都应执行 cap.release() 与 cv2.destroyAllWindows(),避免摄像头或窗口资源残留。