Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 54 ยท Video and Cameras

Reading and Writing Video

Read video files and webcams with cv2.VideoCapture, loop over frames, query fps and size, and save results with VideoWriter. Includes a NumPy frame-loop stand-in.

A video is just a long list of images, called frames, shown at a fixed rate. Because every frame is an ordinary array (see Images Are NumPy Arrays), everything you learned about single images applies to video: you read a frame, process it, and move on to the next one. OpenCV's VideoCapture class reads frames from files, image sequences, network streams and cameras, and VideoWriter saves them again.

Video decoding and cameras are not available in the browser, so every cv2 snippet here is read-only. The live examples are honest stand-ins: a small FakeCapture class that mimics the read() loop on synthetic NumPy frames, and a FakeWriter that collects frames. They teach the loop and the arithmetic (fps, duration, frame counts), not real decoding.

Reading frames with VideoCapture

The basic pattern is a loop that reads until the source runs out:

Python
import cv2

cap = cv2.VideoCapture("clip.mp4")      # file path, URL, or camera index
if not cap.isOpened():
    raise RuntimeError("Could not open the video source")

while True:
    ok, frame = cap.read()              # ok is False at the end or on error
    if not ok:
        break
    # frame is a BGR uint8 array of shape (height, width, 3)
    cv2.imshow("video", frame)
    if cv2.waitKey(25) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

Four details matter:

  1. cap.read() returns a tuple (ok, frame). When ok is False, frame is None, so using it without checking crashes later with a confusing error.
  2. VideoCapture does not raise when a path is wrong. It simply stays closed, so always check isOpened().
  3. waitKey(25) waits 25 ms for a key and also gives the GUI time to redraw. Without a waitKey, imshow shows nothing. About 25 ms matches a 40 fps playback; the real delay should come from the video's frame rate.
  4. release() frees the file or device. Forgetting it can leave a camera locked until the process exits.

The read loop

Open VideoCapture(source), then isOpened().
Read ok, frame = cap.read()
Check Stop when ok is False.
Release cap.release() when done.
1 / 2

Properties: size, fps and frame count

cap.get(property) returns numbers describing the stream, always as floats:

Python
width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
fps = cap.get(cv2.CAP_PROP_FPS)                    # for example 29.97
count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))     # total frames in a file
position = cap.get(cv2.CAP_PROP_POS_FRAMES)        # index of the NEXT frame

duration_seconds = count / fps

For files these are usually right. For cameras and streams, FRAME_COUNT is meaningless and FPS may be 0.0, so do not divide by it blindly. You can also jump around a file with cap.set(cv2.CAP_PROP_POS_FRAMES, 120) before the next read(), though seeking is only exact with some codecs and can be slow or approximate.

The first stand-in is a FakeCapture that behaves like the loop above on synthetic frames: a bright square moves across a dark background. It reports the same properties and follows the same read() protocol, so you can practice the loop and the arithmetic.

Python A fake VideoCapture and the read loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The loop ends when read() returns (False, None), which is why the last frame is None and the shape line has to guard for it. After release(), further reads fail, just like on a real capture.

Cameras, streams and indexes

Passing an integer opens a camera by index: 0 is usually the default webcam, 1 the next one.

Python
cap = cv2.VideoCapture(0)                        # default webcam
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280)          # request, not a guarantee
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720)

A set call is a request: the driver picks the closest mode it supports, so read the properties back afterwards. On Windows, a specific backend can fix slow startup or missing frames, for example cv2.VideoCapture(0, cv2.CAP_DSHOW), and on Linux cv2.CAP_V4L2. A URL (an RTSP or HTTP stream) also works as the source, subject to how OpenCV was built.

Writing video with VideoWriter

VideoWriter needs the output path, a fourcc codec code, the fps and the frame size:

Python
fourcc = cv2.VideoWriter_fourcc(*"mp4v")         # codec for .mp4 files
out = cv2.VideoWriter("result.mp4", fourcc, 30.0, (width, height))

while True:
    ok, frame = cap.read()
    if not ok:
        break
    out.write(frame)                             # frame must match (width, height)

out.release()

Habits that avoid the common failures:

  • The size is (width, height), the opposite order of frame.shape[:2], which is (height, width). A mismatch makes write silently produce an empty or broken file.
  • The frames must be 8-bit BGR with 3 channels (unless you pass isColor=False for gray frames).
  • Always call release(); the file is not finalized without it.
  • Codecs depend on your OpenCV build and the operating system. mp4v into .mp4 and MJPG or XVID into .avi are the safest choices. avc1 (H.264) is only available when your build includes it. If isOpened() on the writer is False, the codec or the extension is the first suspect.
  • out.write does not change the frame rate of the source. If you skip frames or process slower than real time, the saved video's timing is still whatever fps you declared.

The second stand-in builds a FakeWriter that collects frames and applies the same size checks you would make by hand, then summarizes the result the way you would inspect an output file.

Python A fake VideoWriter and the size trap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Only the six well-formed frames were saved, and the swapped one was reported. A real VideoWriter.write would not print anything, which is exactly why this bug is annoying.

Headless servers and other pitfalls

  • No window on servers. cv2.imshow and waitKey need a GUI. The opencv-python-headless build (see Installing OpenCV) removes them, so a server script should write files or frames instead of displaying them.
  • Wrong path, no error. VideoCapture("typo.mp4") returns a closed capture. Check isOpened().
  • Color order. Frames arrive as BGR, like every OpenCV image.
  • Frame rate drift. read() is as fast as decoding allows, not real time. To play at the original speed, sleep or waitKey(int(1000 / fps)).
  • Camera buffers. A webcam keeps a small buffer. If your processing is slower than the camera, you see old frames. Reading continuously and processing every Nth frame helps.
  • Memory. Do not append every frame to a list: a one-minute 1080p video is about 11 GB as raw uint8 arrays (1920 x 1080 x 3 bytes x 30 fps x 60 s). Process each frame and drop it.
  • Image sequences. A file pattern like "frames/img_%04d.png" works as a source and reads numbered images as a video.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does cap.read() return?

    read() returns a success flag and the frame. At the end of a file or on an error, ok is False and frame is None, so check ok before using the frame.
  2. 2. What happens when you pass a wrong file path to cv2.VideoCapture?

    OpenCV reports the failure silently. Always test cap.isOpened() right after creating the capture.
  3. 3. Which size order does VideoWriter expect?

    VideoWriter takes (width, height). Passing the shape order swaps them and gives a broken or empty file.
  4. 4. Why is it a bad idea to store every frame of a long video in a Python list?

    A single 1080p BGR frame is about 6 MB, so even a short clip needs gigabytes if all frames are kept.
  5. 5. Which build of OpenCV should a server without a display normally install?

    The headless wheel leaves out the GUI so it works without a display and with fewer system libraries.

Summary

  • VideoCapture(source) opens a file, a stream or a camera index; always check isOpened().
  • ok, frame = cap.read() in a loop reads frames; stop when ok is False and call release().
  • cap.get returns width, height, fps and frame count as floats; camera streams often have no frame count.
  • VideoWriter(path, fourcc, fps, (width, height)) saves frames; the size order is the reverse of frame.shape[:2].
  • Codec support depends on your build; mp4v and MJPG are the safest.
  • On servers use the headless build and write files instead of calling imshow.

Next: Processing Video Frame by Frame