Skip to content

CamGear API Usage Examples:

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

 

Bare-Minimum Usage

Following is the bare-minimum code you need to get started with CamGear API:

 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 CamGear
import cv2


# open any valid video stream(for e.g `myvideo.avi` file)
stream = CamGear(source="myvideo.avi").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()

 

Using Camgear with Streaming Websites

CamGear internally implements yt_dlp backend class for seamlessly pipelining live video-frames and metadata from various streaming services like Twitch, Vimeo, Dailymotion, and many more ➶. All you have to do is to provide the desired Video's URL to its source parameter, and enable its stream_mode parameter.

The complete usage example for Dailymotion and Twitch URLs are as follows:

Bug in OpenCV's FFmpeg

To workaround a FFmpeg bug that causes video to freeze frequently in OpenCV, It is advised to always use GStreamer backend for Livestream videos.

Checkout this FAQ ➶ for compiling OpenCV with GStreamer support.

Not all resolutions are supported with GStreamer Backend. See issue #244

Exclusive CamGear Attributes for yt_dlp backend

CamGear also provides exclusive attributes:

  • STREAM_RESOLUTION (for specifying stream resolution)
  • STREAM_PARAMS (for specifying yt_dlp parameters)

with its options dictionary parameter. More information can be found here ➶

Supported Streaming Websites

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

Accessing Stream's Metadata

CamGear now provides ytv_metadata global parameter for accessing given Video's metadata as JSON Object. It can used as follows:

New in v0.2.4

ytv_metadata global parameter was added in v0.2.4.

# import required libraries
from vidgear.gears import CamGear

# Add YouTube Video URL as input source (for e.g https://www.dailymotion.com/video/x2yrnum)
# and enable Stream Mode (`stream_mode = True`)
stream = CamGear(
    source="https://www.dailymotion.com/video/x2yrnum", stream_mode=True, logging=True, **options
).start()

# get Video's metadata as JSON object
video_metadata =  stream.ytv_metadata

# print all available keys
print(video_metadata.keys())

# get data like `title`
print(video_metadata["title"])

 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 CamGear
import cv2

# set desired quality as 720p
options = {"STREAM_RESOLUTION": "720p"}

# Add any desire Video URL as input source
# for e.g https://vimeo.com/151666798
# and enable Stream Mode (`stream_mode = True`)
stream = CamGear(
    source="https://www.dailymotion.com/video/x2yrnum",
    stream_mode=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)

    # 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()

If Twitch user is offline, CamGear will throw ValueError.

 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 CamGear
import cv2

# set desired quality as 720p
options = {"STREAM_RESOLUTION": "720p"}

# Add any desire Video URL as input source
# for e.g hhttps://www.twitch.tv/shroud
# and enable Stream Mode (`stream_mode = True`)
stream = CamGear(
    source="https://www.twitch.tv/shroud",
    stream_mode=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)

    # 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 Camgear with Youtube Videos

CamGear API also provides out-of-the-box support for pipelining live video-frames and metadata from YouTube (Livestream + Normal) Videos.

YouTube Playlists are not supported yet.

The complete usage example is as follows:

Bug in OpenCV's FFmpeg

To workaround a FFmpeg bug that causes video to freeze frequently in OpenCV, It is advised to always use GStreamer backend for Livestream videos.

Checkout this FAQ ➶ for compiling OpenCV with GStreamer support.

Not all resolutions are supported with GStreamer Backend. See issue #244

Exclusive CamGear Attributes for yt_dlp backend

CamGear also provides exclusive attributes:

  • STREAM_RESOLUTION (for specifying stream resolution)
  • STREAM_PARAMS (for specifying yt_dlp parameters)

with its options dictionary parameter. More information can be found here ➶

Accessing Stream's Metadata

CamGear now provides ytv_metadata global parameter for accessing given Video's metadata as JSON Object. It can used as follows:

New in v0.2.4

ytv_metadata global parameter was added in v0.2.4.

# import required libraries
from vidgear.gears import CamGear

# Add YouTube Video URL as input source (for e.g https://youtu.be/uCy5OuSQnyA)
# and enable Stream Mode (`stream_mode = True`)
stream = CamGear(
    source="https://youtu.be/uCy5OuSQnyA", stream_mode=True, logging=True, **options
).start()

# get Video's metadata as JSON object
video_metadata =  stream.ytv_metadata

# print all available keys
print(video_metadata.keys())

# get data like `title`
print(video_metadata["title"])

 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 import CamGear
import cv2

# Add YouTube Video URL as input source (for e.g https://youtu.be/uCy5OuSQnyA)
# and enable Stream Mode (`stream_mode = True`)
stream = CamGear(
    source="https://youtu.be/uCy5OuSQnyA", 
    stream_mode=True,
    logging=True
).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()

 

Using CamGear with Variable Camera Properties

CamGear API also flexibly support various Source Tweak Parameters available within OpenCV's VideoCapture API. These tweak parameters can be used to transform input source Camera-Device properties (such as its brightness, saturation, framerate, resolution, gain etc.) seamlessly, and can be easily applied in CamGear API through its options dictionary parameter by formatting them as its attributes.

The complete usage example is as follows:

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
# import required libraries
from vidgear.gears import CamGear
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 = 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()

 

Using Camgear with Direct Colorspace Manipulation

CamGear API also supports Direct Colorspace Manipulation, which is ideal for changing source colorspace on the run.

A more detailed information on colorspace manipulation can be found here ➶

In following example code, we will start with HSV as source colorspace, and then we will switch to GRAY colorspace when W key is pressed, and then LAB colorspace when E key is pressed, finally default colorspace (i.e. BGR) when S key is pressed. Also, quit when Q key is pressed:

Any incorrect or None-type value, will immediately revert the colorspace to default i.e. BGR.

 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
45
46
47
48
# import required libraries
from vidgear.gears import CamGear
import cv2

# Open any source of your choice, like Webcam first index(i.e. 0)
# and change its colorspace to `HSV`
stream = CamGear(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)

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

    # check if 'w' key is pressed
    if key == ord("w"):
        # directly change colorspace at any instant
        stream.color_space = cv2.COLOR_BGR2GRAY  # Now colorspace is GRAY

    # check for 'e' key is pressed
    if key == ord("e"):
        stream.color_space = cv2.COLOR_BGR2LAB  # Now colorspace is CieLAB

    # check for 's' key is pressed
    if key == ord("s"):
        stream.color_space = None  # Now colorspace is default(ie BGR)

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

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()