Skip to content

VideoGear API Parameters⚓

VideoGear acts as a Common Video-Capture API that provides internal access for both CamGear and PiGear APIs and their parameters.

enablePiCamera⚓

This parameter provide direct access to PiGear or CamGear APIs respectively in VideoGear. This means the if enablePiCamera flag is True, the PiGear API will be accessed, and if False, the CamGear API will be accessed.

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

VideoGear(enablePiCamera=True) # enable access to PiGear API

Its complete usage example is given here ➶.

 

 

Parameters for Stabilizer Backend⚓

Enable this backend with stabilize=True in VideoGear.

stabilize⚓

This parameter enable access to Stabilizer Class for stabilizing frames, i.e. can be set to True(to enable) or unset to False(to disable).

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

VideoGear(stabilize=True) # enable stablization

Its complete usage example is given here ➶.

 

options⚓

This parameter can be used in addition, to pass user-defined parameters supported by Stabilizer Class. These parameters can be formatted as this parameter's attribute.

Supported dictionary attributes for Stabilizer Class are:

  • SMOOTHING_RADIUS (integer) : This attribute can be used to alter averaging window size. It basically handles the quality of stabilization at the expense of latency and sudden panning. Larger its value, less will be panning, more will be latency and vice-versa. Its default value is 25. You can easily pass this attribute as follows:

    options = {'SMOOTHING_RADIUS': 30}
    
  • BORDER_SIZE (integer) : This attribute enables the feature to extend border size that compensates for stabilized output video frames motions. Its default value is 0(no borders). You can easily pass this attribute as follows:

    options = {'BORDER_SIZE': 10}
    
  • CROP_N_ZOOM(boolean): This attribute enables the feature where it crops and zooms frames(to original size) to reduce the black borders from stabilization being too noticeable (similar to the Stabilized, cropped and Auto-Scaled feature available in Adobe AfterEffects). It simply works in conjunction with the BORDER_SIZE attribute, i.e. when this attribute is enabled, BORDER_SIZE will be used for cropping border instead of extending them. Its default value is False. You can easily pass this attribute as follows:

    options = {'BORDER_SIZE': 10, 'CROP_N_ZOOM' : True}
    
  • BORDER_TYPE (string) : This attribute can be used to change the extended border style. Valid border types are 'black', 'reflect', 'reflect_101', 'replicate' and 'wrap', learn more about it here. Its default value is 'black'. You can easily pass this attribute as follows:

    Altering BORDER_TYPE attribute is Disabled while CROP_N_ZOOM is enabled.

    options = {'BORDER_TYPE': 'black'}
    

 

 

Parameters for CamGear backend⚓

Enable this backend with enablePiCamera=False in VideoGear. Default is also False.

source⚓

VideoGear API will throw RuntimeError if source provided is invalid.

This parameter defines the source for the input stream.

Data-Type: Based on input.

Default Value: Its default value is 0.

Its valid input can be one of the following:

  • Index (integer): Valid index of the connected video device, for e.g 0, or 1, or 2 etc. as follows:

    VideoGear(source=0)
    
  • Filepath (string): Valid path of the video file, for e.g "/home/foo.mp4" as follows:

    VideoGear(source='/home/foo.mp4')
    
  • Streaming Services URL Address (string): Valid Video URL as input when Stream Mode is enabled(i.e. stream_mode=True)

    CamGear internally implements yt_dlp backend class for pipelining live video-frames and metadata from various streaming services. For example Twitch URL can be used as follows:

    Supported Streaming Websites

    The list of all supported Streaming Websites URLs can be found here ➶

    CamGear(source='https://www.twitch.tv/shroud', stream_mode=True)
    
  • Network Address (string): Valid (http(s), rtp, rtsp, rtmp, mms, etc.) incoming network stream address such as 'rtsp://192.168.31.163:554/' as input:

    VideoGear(source='rtsp://192.168.31.163:554/')
    
  • GStreamer Pipeline:

    CamGear API also supports GStreamer Pipeline.

    Requirements for GStreamer Pipelining

    Successful GStreamer Pipelining needs your OpenCV to be built with GStreamer support. Checkout this FAQ for compiling OpenCV with GStreamer support.

    Thereby, You can easily check GStreamer support by running print(cv2.getBuildInformation()) python command and see if output contains something similar as follows:

    Video I/O:
    ...
         GStreamer:                   YES (ver 1.8.3)
    ...
    

    Be sure convert video output into BGR colorspace before pipelining as follows:

    VideoGear(source='udpsrc port=5000 ! application/x-rtp,media=video,payload=96,clock-rate=90000,encoding-name=H264, ! rtph264depay ! decodebin ! videoconvert ! video/x-raw, format=BGR ! appsink')
    

 

stream_mode⚓

This parameter controls the Stream Mode, .i.e if enabled(stream_mode=True), the VideoGear API will interpret the given source input as YouTube URL address.

Due to a FFmpeg bug that causes video to freeze frequently in OpenCV, It is advised to always use GStreamer backend (backend=cv2.CAP_GSTREAMER) for any livestreams (such as Twitch).

VideoGear automatically enforce GStreamer backend (backend=cv2.CAP_GSTREAMER) for YouTube-livestreams!

VideoGear will exit with RuntimeError for YouTube livestreams, if OpenCV is not compiled with GStreamer(>=v1.0.0) support. Checkout this FAQ for compiling OpenCV with GStreamer support.

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

VideoGear(source='https://youtu.be/bvetuLwJIkA', stream_mode=True)

Its complete usage example is given here ➶.

 

backend⚓

This parameter manually selects the backend for OpenCV's VideoCapture class (only if specified).

Data-Type: Integer

Default Value: Its default value is 0

Usage:

All supported backends are listed here ➶

Its value can be for e.g. backend = cv2.CAP_DSHOW for selecting Direct Show as backend:

VideoGear(source=0, backend = cv2.CAP_DSHOW)

 

options⚓

This parameter provides the ability to alter various Source Tweak Parameters available within OpenCV's VideoCapture API properties.

Data-Type: Dictionary

Default Value: Its default value is {}

Usage:

All supported parameters are listed here ➶

The desired parameters can be passed to VideoGear API by formatting them as this parameter's attributes, as follows:

# formatting parameters as dictionary attributes
options = {"CAP_PROP_FRAME_WIDTH":320, "CAP_PROP_FRAME_HEIGHT":240, "CAP_PROP_FPS":60}
# assigning it
VideoGear(source=0, **options)

 

 

Parameters for PiGear backend⚓

Enable this backend with enablePiCamera=True in VideoGear.

camera_num⚓

This parameter selects the camera module index which will be used as source, if you're having multiple camera modules connected. Its value can only be greater than zero, otherwise, it will throw ValueError for any negative value.

This parameter shouldn't be altered, until unless you using Raspberry Pi 3/3+ Compute Module IO Board."

Data-Type: Integer

Default Value: Its default value is 0.

Usage:

VideoGear(enablePiCamera=True, camera_num=0)

 

resolution⚓

This parameter sets the resolution (i.e. (width,height)) of the source.

For more information read here ➶

Data-Type: Tuple

Default Value: Its default value is (640,480).

Usage:

VideoGear(enablePiCamera=True, resolution=(1280,720)) # sets 1280x720 resolution

 

framerate⚓

This parameter sets the framerate of the source.

For more information read here ➶

Data-Type: integer/float

Default Value: Its default value is 30.

Usage:

VideoGear(enablePiCamera=True, framerate=60) # sets 60fps framerate

 

options⚓

This parameter provides the ability to alter various Tweak Parameters like brightness, saturation, senor_mode, resolution, etc. available within Picamera library.

Data-Type: Dictionary

Default Value: Its default value is {}

Usage:

All supported parameters are listed in PiCamera Docs

The desired parameters can be passed to VideoGear API by formatting them as this parameter's attributes, as follows:

# formatting parameters as dictionary attributes
options = {
    "hflip": True,
    "exposure_mode": "auto",
    "iso": 800,
    "exposure_compensation": 15,
    "awb_mode": "horizon",
    "sensor_mode": 0,
}
# assigning it
VideoGear(enablePiCamera=True, logging=True, **options)

User-specific attributes:

Additionally, options parameter also support some User-specific attributes, which are as follows:

  • HWFAILURE_TIMEOUT (float): PiGear contains Threaded Internal Timer - that silently keeps active track of any frozen-threads/hardware-failures and exit safely, if any does occur at a timeout value. This parameter can be used to control that timeout value i.e. the maximum waiting time (in seconds) after which PiGear exits with a SystemError to save resources. Its value can only be between 1.0 (min) and 10.0 (max) and its default value is 2.0. Its usage is as follows:

    options = {"HWFAILURE_TIMEOUT": 2.5}  # sets timeout to 2.5 seconds
    

 

 

Common Parameters⚓

These are common parameters that works with every backend in VideoGear.

colorspace⚓

This parameter selects the colorspace of the source stream.

Data-Type: String

Default Value: Its default value is None.

Usage:

All supported colorspace values are given here ➶

VideoGear(colorspace="COLOR_BGR2HSV")

Its complete usage example is given here ➶

 

logging⚓

This parameter enables logging (if True), essential for debugging.

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

VideoGear(logging=True)

 

time_delay⚓

This parameter set the time delay (in seconds) before the VideoGear API start reading the frames. This delay is only required if the source required some warm-up delay before starting up.

Data-Type: Integer

Default Value: Its default value is 0.

Usage:

VideoGear(time_delay=1)  # set 1 seconds time delay

 


Last update: July 31, 2022