Class for video capturing from video files or cameras

The class provides an API for capturing video from cameras or for reading video files and image sequences.

Example

Here is how the class can be used:

cap = cv.VideoCapture(0);        % open the default camera
pause(3);                        % see note below
if ~cap.isOpened()               % check if we succeeded
    error('camera failed to initialized');
end
for t=1:30
    frame = cap.read();           % get a new frame from camera
    imshow(frame);
    pause(0.1);
end
% the camera will be deinitialized automatically in destructor
% when "cap" goes out of scope
% you can also explicitly call cap.release() to close the camera

Note: In some environments, there is a concurrency issue during camera initialization. To avoid unexpected crash, pause for a few seconds after the initialization of cv.VideoCapture object.

Video I/O with OpenCV Overview

The OpenCV "videoio" module is a set of classes and functions to read and write video or images sequence.

Basically, the module provides the cv.VideoCapture and cv.VideoWriter classes as 2-layer interface to many video I/O APIs used as backend.

Some backends such as (DirectShow) Direct Show, Video For Windows (VfW), Microsoft Media Foundation (MediaFoundation), Video 4 Linux (V4L), etc... are interfaces to the video I/O library provided by the operating system.

Some others backends like OpenNI2 for Kinect, Intel Perceptual Computing SDK, GStreamer, XIMEA Camera API, etc... are interfaces to proprietary drivers or to external library.

See the list of supported backends here: cv.VideoCapture.open

Warning: Some backends are experimental use them at your own risk. Note: Each backend supports devices properties (cv.VideoCapture.set) in a different way or might not support any property at all.

Select the backend at runtime

OpenCV automatically selects and uses first available backend (API='Any').

As advanced usage you can select the backend to use at runtime. Currently this option is available only with cv.VideoCapture.

For example to grab from default camera using Direct Show as backend

% declare a capture object
cap = cv.VideoCapture(0, 'API','DirectShow')

% or specify the API preference with open
cap.open(0, 'API','DirectShow');

If you want to grab from a file using the Direct Show as backend:

% declare a capture object
cap = cv.VideoCapture(filename, 'API','DirectShow')

% or specify the API preference with open
cap.open(filename, 'API','DirectShow');

Enable backends

Backends are available only if they have been built with your OpenCV binaries.

Check in opencv2/cvconfig.h to know which APIs are currently available (e.g. HAVE_MSMF, HAVE_VFW, HAVE_LIBV4L, etc...).

To enable/disable APIs, you have to:

1. re-configure OpenCV using appropriates CMake switches (e.g. -DWITH_MSMF=ON -DWITH_VFW=ON ...) or checking related switch in cmake-gui
2. rebuild OpenCV itself

Use 3rd party drivers or cameras

Many industrial cameras or some video I/O devices don't provide standard driver interfaces for the operating system. Thus you can't use cv.VideoCapture or cv.VideoWriter with these devices.

The FFmpeg library

OpenCV can use the FFmpeg library as backend to record, convert and stream audio and video. FFMpeg is a complete, cross-reference solution. If you enable FFmpeg while configuring OpenCV than CMake will download and install the binaries in OPENCV_SOURCE_CODE/3rdparty/ffmpeg/. To use FFMpeg at runtime, you must deploy the FFMepg binaries with your application.

Note: FFmpeg is licensed under the GNU Lesser General Public License (LGPL) version 2.1 or later. See OPENCV_SOURCE_CODE/3rdparty/ffmpeg/readme.txt and http://ffmpeg.org/legal.html for details and licensing information.