VideoGear API Parameters¶

api¶

This parameter selects the underlying capture backend for VideoGear using the Backend enum.

Data-Type: Backend enum

Default Value: Backend.CAMGEAR

Accepted Values:

Usage:

from vidgear.gears import VideoGear
from vidgear.gears.helper import Backend

VideoGear(api=Backend.CAMGEAR)  # default — CamGear backend
VideoGear(api=Backend.PIGEAR)   # PiGear backend
VideoGear(api=Backend.FFGEAR)   # FFGear backend

enablePiCamera (Deprecated)¶

This parameter previously provided direct access to PiGear or CamGear APIs respectively. If True, the PiGear API was accessed; if False, the CamGear API was accessed.

Data-Type: Boolean

Default Value: None

Migration:

# Old (deprecated)
VideoGear(enablePiCamera=True)

# New
from vidgear.gears.helper import Backend
VideoGear(api=Backend.PIGEAR)

Parameters for Stabilizer Backend¶

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

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:

• STABILIZER_MODE (StabilizerMode enum): This attribute selects the underlying stabilization algorithm.

  Accepted values are:

  • StabilizerMode.ASW (Average Sliding-Window — default)
  • StabilizerMode.KALMAN (reserved; raises NotImplementedError until a future release).
  • Invalid values silently fall back to StabilizerMode.ASW.

  You can easily pass this attribute as follows:

  New in v0.3.5

  The STABILIZER_MODE option and the StabilizerMode enum were added in v0.3.5. Omitting STABILIZER_MODE keeps the previous behavior — VideoGear defaults to StabilizerMode.ASW.

  from vidgear.gears.stabilizer import StabilizerMode
  options = {'STABILIZER_MODE': StabilizerMode.ASW}
  

• 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¶

source¶

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 supports 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.

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

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

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:

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:

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¶

camera_num¶

This parameter selects the camera index to be used as the source, allowing you to drive these multiple cameras simultaneously from within a single Python session. Its value can only be zero or greater, otherwise, VideoGear API will throw ValueError for any negative value.

Data-Type: Integer

Default Value: Its default value is 0.

Usage:

from vidgear.gears.helper import Backend
# select Camera Module at index `1`
VideoGear(api=Backend.PIGEAR, camera_num=1)

resolution¶

This parameter controls the resolution - a tuple (i.e. (width,height)) of two values giving the width and height of the output frames.

Data-Type: Tuple

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

Usage:

from vidgear.gears.helper import Backend
VideoGear(api=Backend.PIGEAR, resolution=(1280,720)) # sets 1280x720 resolution

framerate¶

This parameter controls the framerate of the source.

Data-Type: integer/float

Default Value: Its default value is 30.

Usage:

from vidgear.gears.helper import Backend
VideoGear(api=Backend.PIGEAR, framerate=60) # sets 60fps framerate

options¶

This dictionary parameter in the internal PiGear API backend allows you to control various camera settings for both the picamera2 and legacy picamera backends and some internal API tasks. These settings include:

A. Configurational Camera Parameters¶

• These parameters are provided by the underlying backend library (depending upon backend in use), and must be applied to the camera system before the camera can be started.
• These parameter include: Brightness, Contrast, Saturation, Exposure, Colour Temperature, Colour Gains, etc.
• All supported parameters are listed in this Usage example ➶

B. User-defined Parameters¶

• These user-defined parameters control specific internal behaviors of the API and perform certain tasks on the camera objects.
• All supported User-defined Parameters are listed here ➶

Data-Type: Dictionary

Default Value: Its default value is {}

Usage:

You can format these user-defined and configurational parameters as attributes of this options dictionary parameter as follows:

# formulate various Picamera2 API parameters
options = {
    "queue": True,
    "buffer_count": 4,
    "controls": {"Brightness": 0.5, "ExposureValue": 2.0},
    "exposure_compensation": 15,
    "sensor": {"output_size": (480, 320)},  # !!! will override `resolution` !!!
}

# open pi video stream with defined parameters
stream = VideoGear(api=Backend.PIGEAR, resolution=(640, 480), framerate=60, logging=True, **options).start()

from vidgear.gears.helper import Backend
# formulate various Picamera API parameters
options = {
    "hflip": True,
    "exposure_mode": "auto",
    "iso": 800,
    "exposure_compensation": 15,
    "awb_mode": "horizon",
    "sensor_mode": 0,
}

# open pi video stream with defined parameters
stream = VideoGear(api=Backend.PIGEAR, resolution=(640, 480), framerate=60, logging=True, **options).start()

Parameters for FFGear backend¶

source¶

Defines the source for FFGear input. Passed directly to FFdecoder API.

Data-Type: Any

Default Value: 0

Valid inputs: device index, filepath, network URL (http(s), rtsp, rtp, rtmp), image-sequence glob, or streaming URL (with stream_mode=True).

VideoGear(api=Backend.FFGEAR, source="myvideo.mp4")
VideoGear(api=Backend.FFGEAR, source="rtsp://192.168.1.10:554/stream")

stream_mode¶

Enables yt_dlp-backed Stream Mode for streaming service URLs.

Data-Type: Boolean

Default Value: False

VideoGear(api=Backend.FFGEAR, source="https://youtu.be/bvetuLwJIkA", stream_mode=True)

source_demuxer¶

Specifies the FFmpeg demuxer for the source. Required when the source type cannot be auto-detected.

Data-Type: String or None

Default Value: None (auto-detect)

VideoGear(api=Backend.FFGEAR, source="/dev/video0", source_demuxer="v4l2")

frame_format¶

Specifies the pixel layout for decoded frames. Accepts any FFmpeg-supported pixel format string.

Data-Type: String

Default Value: "bgr24"

VideoGear(api=Backend.FFGEAR, source="myvideo.mp4", frame_format="gray")

custom_ffmpeg¶

Path to a custom FFmpeg executable. Useful when FFmpeg is not on PATH.

Data-Type: String

Default Value: "" (uses system FFmpeg)

VideoGear(api=Backend.FFGEAR, source="myvideo.mp4", custom_ffmpeg="/opt/ffmpeg/bin/ffmpeg")

options¶

Passes additional FFdecoder parameters and FFGear queue-tuning parameters. See FFGear options ➶ for full details.

Data-Type: Dictionary

Default Value: {}

options = {"-vf": "scale=1280:720", "QUEUE_SIZE": 128}
VideoGear(api=Backend.FFGEAR, source="myvideo.mp4", **options)

Common Parameters¶

colorspace¶

This parameter selects the colorspace of the source stream.

Data-Type: String

Default Value: None

Usage:

VideoGear(colorspace="COLOR_BGR2HSV")

logging¶

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

Data-Type: Boolean

Default Value: False

Usage:

VideoGear(logging=True)

time_delay¶

This parameter sets the time delay (in seconds) before the VideoGear API starts reading frames. Required only if the source needs a warm-up delay before starting.

Data-Type: Integer

Default Value: 0

Usage:

VideoGear(time_delay=1)  # 1 second warm-up delay