Skip to content

VideoGear API Usage Examples:

After going through following Usage Examples, Checkout more of its advanced configurations here ➶

 

Bare-Minimum Usage with CamGear backend

VideoGear by default provides direct internal access to CamGear API. Explicitly select it with api=Backend.CAMGEAR.

Following is the bare-minimum code you need to access CamGear API with VideoGear:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# import required libraries
from vidgear.gears import VideoGear
from vidgear.gears.helper import Backend
import cv2


# open any valid video stream(for e.g `myvideo.mp4` file)
stream = VideoGear(api=Backend.CAMGEAR, source="myvideo.mp4").start()

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

Bare-Minimum Usage with FFGear backend

Select FFGear backend with api=Backend.FFGEAR to access FFGear API for hardware-accelerated FFmpeg-powered decoding.

Following is the bare-minimum code you need to access FFGear API with VideoGear:

FFGear Backend requires the deffcode library

FFGear API MUST have the deffcode library installed, along with a valid FFmpeg executable. Any failure in detection will raise ImportError/RuntimeError immediately.

Install via pip:

pip install deffcode

For FFmpeg installation, see FFmpeg Installation ➶

FFGear API Backend does not support colorspace or time_delay parameters. Use its options dict for advanced FFmpeg configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# import required libraries
from vidgear.gears import VideoGear
from vidgear.gears.helper import Backend
import cv2

# select FFGear backend via api parameter
# and open any valid video stream(for e.g `myvideo.mp4` file)
stream = VideoGear(api=Backend.FFGEAR, source="myvideo.mp4").start()

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

Bare-Minimum Usage with PiGear backend

Select PiGear backend with api=Backend.PIGEAR to access PiGear API.

Following is the bare-minimum code you need to access PiGear API with VideoGear:

Under the hood, PiGear API (version 0.3.3 onwards) prioritizes the new picamera2 API backend.

However, PiGear API seamlessly switches to the legacy picamera backend, if the picamera2 library is unavailable or not installed.

It is advised to enable logging(logging=True) to see which backend is being used.

The picamera library is built on the legacy camera stack that is NOT (and never has been) supported on 64-bit OS builds.

You could also enforce the legacy picamera API backend in PiGear by using the enforce_legacy_picamera user-defined optional parameter boolean attribute.

Make sure to complete Raspberry Pi Camera Hardware-specific settings prior using this API, otherwise nothing will work.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# import required libraries
from vidgear.gears import VideoGear
from vidgear.gears.helper import Backend
import cv2

# select PiGear backend via api parameter
stream = VideoGear(api=Backend.PIGEAR).start()

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

Using VideoGear with Video Stabilizer backend

VideoGear API provides a special internal wrapper around VidGear's Exclusive Video Stabilizer class and provides easy way of activating stabilization for various video-streams (real-time or not) with its stabilize boolean parameter during initialization.

The usage example is as follows:

For a more detailed information on Video-Stabilizer Class, Read here ➶

The stabilizer might be slower for High-Quality/Resolution videos-frames.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# import required libraries
from vidgear.gears import VideoGear
import numpy as np
import cv2

# open any valid video stream with stabilization enabled(`stabilize = True`)
stream_stab = VideoGear(source="test.mp4", stabilize=True).start()

# loop over
while True:

    # read stabilized frames
    frame_stab = stream_stab.read()

    # check for stabilized frame if None-type
    if frame_stab is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Stabilized Output", frame_stab)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close streams
stream_stab.stop()
New in v0.3.6

The Kalman backend (StabilizerMode.KALMAN) was added in v0.3.6.

Kalman backend stabilizes every frame immediately, with no SMOOTHING_RADIUS frames of startup delay or lag. Ideal for live streams.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# import required libraries
from vidgear.gears.stabilizer import StabilizerMode
from vidgear.gears import VideoGear
import cv2

# select zero-latency Kalman stabilizer backend
options = {"STABILIZER_MODE": StabilizerMode.KALMAN}

# open any valid video stream with stabilization enabled(`stabilize = True`)
stream_stab = VideoGear(source="test.mp4", stabilize=True, **options).start()

# loop over
while True:

    # read stabilized frames
    frame_stab = stream_stab.read()

    # check for stabilized frame if None-type
    if frame_stab is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Stabilized Output", frame_stab)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close streams
stream_stab.stop()

 

Advanced VideoGear usage with CamGear Backend

VideoGear provides internal access to CamGear, PiGear, and FFGear APIs, and thereby all additional parameters of each backend are also easily accessible within VideoGear API.

The usage example of VideoGear API with Variable Camera Properties is as follows:

This example demonstrates how to use the VideoGear API in a similar manner to the CamGear's example for controlling variable source properties. Any CamGear usage example can be implemented using the VideoGear API in a similar way.

All the supported Source Tweak Parameters can be found here ➶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# import required libraries
from vidgear.gears import VideoGear
from vidgear.gears.helper import Backend
import cv2


# define suitable tweak parameters for your stream.
options = {
    "CAP_PROP_FRAME_WIDTH": 320, # resolution 320x240
    "CAP_PROP_FRAME_HEIGHT": 240,
    "CAP_PROP_FPS": 60, # framerate 60fps
}

# To open live video stream on webcam at first index(i.e. 0) 
# device and apply source tweak parameters
stream = VideoGear(api=Backend.CAMGEAR, source=0, logging=True, **options).start()

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

Advanced VideoGear usage with PiGear Backend

VideoGear provides internal access to both CamGear and PiGear APIs, and thereby all additional parameters of PiGear API or CamGear API are also easily accessible within VideoGear API.

The usage example of VideoGear API with Variable Camera Properties is as follows:

This example demonstrates how to use the VideoGear API in a similar manner to the PiGear's example for using variable camera properties. Any PiGear usage example can be implemented using the VideoGear API in a similar way.

Backend PiGear API now fully supports the newer picamera2 python library under the hood for Raspberry Pi camera modules. Follow this guide ➶ for its installation.

Make sure to complete Raspberry Pi Camera Hardware-specific settings prior using this backend, otherwise nothing will work.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# import required libraries
from vidgear.gears import VideoGear
from vidgear.gears.helper import Backend
from libcamera import Transform
import cv2

# formulate various Picamera2 API 
# configurational parameters
options = {
    "queue": True,
    "buffer_count": 4,
    "controls": {"Brightness": 0.5, "ExposureValue": 2.0},
    "transform": Transform(hflip=1),
    "auto_align_output_config": True,  # auto-align camera configuration
}

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

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()
Under the hood, Backend PiGear API (version 0.3.3 onwards) prioritizes the new picamera2 API backend.

However, the API seamlessly switches to the legacy picamera backend, if the picamera2 library is unavailable or not installed.

It is advised to enable logging(logging=True) to see which backend is being used.

The picamera library is built on the legacy camera stack that is NOT (and never has been) supported on 64-bit OS builds.

You could also enforce the legacy picamera API backend in PiGear by using the enforce_legacy_picamera user-defined optional parameter boolean attribute.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# import required libraries
from vidgear.gears import VideoGear
from vidgear.gears.helper import Backend
import cv2

# formulate various Picamera API 
# configurational 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()

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

Advanced VideoGear usage with FFGear Backend

FFGear Backend requires the deffcode library

FFGear API MUST have the deffcode library installed, along with a valid FFmpeg executable. Any failure in detection will raise ImportError/RuntimeError immediately.

Install via pip:

pip install deffcode

For FFmpeg installation, see FFmpeg Installation ➶

The usage example below demonstrates hardware-accelerated decoding and stabilization together using the FFGear backend:

This example demonstrates how to use the VideoGear API in a similar manner to the FFGear's NVIDIA CUVID Decoding example. Any FFGear usage example can be implemented using the VideoGear API in a similar way.

For hardware-accelerated decoding options (CUDA/CUVID etc.) and advanced FFmpeg filter pipelines, see FFGear Hardware-Accelerated Decoding ➶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# import required libraries
from vidgear.gears import VideoGear
from vidgear.gears.helper import Backend
import cv2

# pass FFmpeg hardware-acceleration and filter options via `options`
# use H.264 CUVID hardware decoder; enable OpenCV patch for YUV frames
options = {
    "-vcodec": "h264_cuvid",  # NVIDIA CUVID hardware decoder
    "-enforce_cv_patch": True,  # auto-convert YUV420p → BGR in FFGear
    "-vf": "scale=1280:720",  # apply scale filter
}

# open video with FFGear backend using hardware acceleration and stabilization enabled
stream = VideoGear(
    api=Backend.FFGEAR, source="myvideo.mp4", stabilize=True, logging=True, **options
).start()

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

Advanced VideoGear usage with Stabilizer Backend

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.

When stabilization is enabled, VideoGear forwards Stabilizer parameters via the options dictionary:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# import required libraries
from vidgear.gears.stabilizer import StabilizerMode
from vidgear.gears import VideoGear
import cv2

# configure the stabilizer backend + tuning parameters
options = {
    "STABILIZER_MODE": StabilizerMode.ASW,  # default
    "SMOOTHING_RADIUS": 30,
    "BORDER_SIZE": 5,
    "CROP_N_ZOOM": True,
}

# open any valid video stream with stabilization enabled
stream_stab = VideoGear(
    source="test.mp4", stabilize=True, logging=True, **options
).start()

# loop over
while True:

    # read stabilized frames
    frame_stab = stream_stab.read()

    # check for stabilized frame if None-type
    if frame_stab is None:
        break

    # {do something with the frame here}

    cv2.imshow("Stabilized Output", frame_stab)
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

cv2.destroyAllWindows()
stream_stab.stop()

For zero-latency real-time stabilization, switch to the Kalman backend with PROCESS_NOISE/MEASUREMENT_NOISE tuning instead of SMOOTHING_RADIUS:

options = {
    "STABILIZER_MODE": StabilizerMode.KALMAN,
    "PROCESS_NOISE": 4e-3,  # default
    "MEASUREMENT_NOISE": 0.25,  # default
    "BORDER_SIZE": 5,
    "CROP_N_ZOOM": True,
}

Non-StabilizerMode values passed via STABILIZER_MODE silently fall back to StabilizerMode.ASW.

 

Using VideoGear with Colorspace Manipulation

VideoGear API also supports Colorspace Manipulation but NOT Direct like other VideoCapture Gears.

Important: color_space global variable is NOT Supported in VideoGear API

  • color_space global variable is NOT Supported in VideoGear API, calling it will result in AttribueError. More details can be found here ➶
  • Any incorrect or None-type value on colorspace parameter will be skipped automatically.

FFGear API Backend does not support colorspace parameter. See this ➶ for source pixel-format conversions.

In following example code, we will convert source colorspace to HSV on initialization:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# import required libraries
from vidgear.gears import VideoGear
import cv2

# Open any source of your choice, like Webcam first index(i.e. 0) 
# and change its colorspace to `HSV`
stream = VideoGear(source=0, colorspace="COLOR_BGR2HSV", logging=True).start()

# loop over
while True:

    # read HSV frames
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break

    # {do something with the HSV frame here}

    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for key if pressed
    key = cv2.waitKey(1) & 0xFF

    # check for 'q' key is pressed
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

Bonus Examples

Checkout more advanced VideoGear examples with unusual configuration here ➶