Skip to content

VideoGear API References

VideoGear API usage examples can be found here ➶

VideoGear API parameters are explained here ➶

VideoGear API provides a special internal wrapper around VidGear's exclusive Video Stabilizer class. VideoGear also acts as a Common Video-Capture API that provides internal access for both CamGear and PiGear APIs and their parameters with an exclusive enablePiCamera boolean flag.

VideoGear is ideal when you need to switch to different video sources without changing your code much. Also, it enables easy stabilization for various video-streams (real-time or not) with minimum effort and writing way fewer lines of code.

Source code in vidgear/gears/videogear.py
class VideoGear:
    """
    VideoGear API provides a special internal wrapper around VidGear's exclusive Video Stabilizer class.
    VideoGear also acts as a Common Video-Capture API that provides internal access for both CamGear and PiGear APIs and
    their parameters with an exclusive enablePiCamera boolean flag.

    VideoGear is ideal when you need to switch to different video sources without changing your code much. Also, it enables
    easy stabilization for various video-streams (real-time or not)
    with minimum effort and writing way fewer lines of code.
    """

    def __init__(
        self,
        # VideoGear parameters
        enablePiCamera: bool = False,
        stabilize: bool = False,
        # PiGear parameters
        camera_num: int = 0,
        resolution: Tuple[int, int] = (640, 480),
        framerate: Union[int, float] = 30,
        # CamGear parameters
        source: Any = 0,
        stream_mode: bool = False,
        backend: int = 0,
        # common parameters
        time_delay: int = 0,
        colorspace: str = None,
        logging: bool = False,
        **options: dict
    ):
        """
        This constructor method initializes the object state and attributes of the VideoGear class.

        Parameters:
            enablePiCamera (bool): provide access to PiGear(if True) or CamGear(if False) APIs respectively.
            stabilize (bool): enable access to Stabilizer Class for stabilizing frames.
            camera_num (int): selects the camera module index which will be used as Rpi source.
            resolution (tuple): sets the resolution (i.e. `(width,height)`) of the Rpi source.
            framerate (int/float): sets the framerate of the Rpi source.
            source (based on input): defines the source for the input stream.
            stream_mode (bool): controls the exclusive YouTube Mode.
            backend (int): selects the backend for OpenCV's VideoCapture class.
            colorspace (str): selects the colorspace of the input stream.
            logging (bool): enables/disables logging.
            time_delay (int): time delay (in sec) before start reading the frames.
            options (dict): provides ability to alter Tweak Parameters of CamGear, PiGear & Stabilizer.
        """
        # enable logging if specified
        self.__logging = logging if isinstance(logging, bool) else False

        # print current version
        logcurr_vidgear_ver(logging=self.__logging)

        # initialize stabilizer
        self.__stabilization_mode = stabilize

        # reformat dictionary
        options = {str(k).strip(): v for k, v in options.items()}

        if self.__stabilization_mode:
            from .stabilizer import Stabilizer

            s_radius = options.pop("SMOOTHING_RADIUS", 25)
            if not isinstance(s_radius, int):
                s_radius = 25

            border_size = options.pop("BORDER_SIZE", 0)
            if not isinstance(border_size, int):
                border_size = 0

            border_type = options.pop("BORDER_TYPE", "black")
            if not isinstance(border_type, str):
                border_type = "black"

            crop_n_zoom = options.pop("CROP_N_ZOOM", False)
            if not isinstance(crop_n_zoom, bool):
                crop_n_zoom = False

            self.__stabilizer_obj = Stabilizer(
                smoothing_radius=s_radius,
                border_type=border_type,
                border_size=border_size,
                crop_n_zoom=crop_n_zoom,
                logging=logging,
            )
            self.__logging and logger.debug(
                "Enabling Stabilization Mode for the current video source!"
            )  # log info

        if enablePiCamera:
            # only import the pigear module only if required
            from .pigear import PiGear

            # initialize the picamera stream by enabling PiGear API
            self.stream = PiGear(
                camera_num=camera_num,
                resolution=resolution,
                framerate=framerate,
                colorspace=colorspace,
                logging=logging,
                time_delay=time_delay,
                **options
            )
        else:
            # otherwise, we are using OpenCV so initialize the webcam
            # stream by activating CamGear API
            self.stream = CamGear(
                source=source,
                stream_mode=stream_mode,
                backend=backend,
                colorspace=colorspace,
                logging=logging,
                time_delay=time_delay,
                **options
            )

        # initialize framerate variable
        self.framerate = self.stream.framerate

    def start(self) -> T:
        """
        Launches the internal *Threaded Frames Extractor* daemon of API in use.

        **Returns:** A reference to the selected class object.
        """
        self.stream.start()
        return self

    def read(self) -> NDArray:
        """
        Extracts frames synchronously from selected API's monitored deque, while maintaining a fixed-length frame
        buffer in the memory, and blocks the thread if the deque is full.

        **Returns:** A n-dimensional numpy array.
        """
        while self.__stabilization_mode:
            frame = self.stream.read()
            if frame is None:
                break
            frame_stab = self.__stabilizer_obj.stabilize(frame)
            if not (frame_stab is None):
                return frame_stab
        return self.stream.read()

    def stop(self) -> None:
        """
        Safely terminates the thread, and release the respective multi-threaded resources.
        """
        self.stream.stop()
        # logged
        self.__logging and logger.debug("Terminating VideoGear.")
        # clean queue
        self.__stabilization_mode and self.__stabilizer_obj.clean()

__init__(self, enablePiCamera=False, stabilize=False, camera_num=0, resolution=(640, 480), framerate=30, source=0, stream_mode=False, backend=0, time_delay=0, colorspace=None, logging=False, **options) special

This constructor method initializes the object state and attributes of the VideoGear class.

Parameters:

Name Type Description Default
enablePiCamera bool

provide access to PiGear(if True) or CamGear(if False) APIs respectively.

False
stabilize bool

enable access to Stabilizer Class for stabilizing frames.

False
camera_num int

selects the camera module index which will be used as Rpi source.

0
resolution tuple

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

(640, 480)
framerate int/float

sets the framerate of the Rpi source.

30
source based on input

defines the source for the input stream.

0
stream_mode bool

controls the exclusive YouTube Mode.

False
backend int

selects the backend for OpenCV's VideoCapture class.

0
colorspace str

selects the colorspace of the input stream.

None
logging bool

enables/disables logging.

False
time_delay int

time delay (in sec) before start reading the frames.

0
options dict

provides ability to alter Tweak Parameters of CamGear, PiGear & Stabilizer.

{}
Source code in vidgear/gears/videogear.py
def __init__(
    self,
    # VideoGear parameters
    enablePiCamera: bool = False,
    stabilize: bool = False,
    # PiGear parameters
    camera_num: int = 0,
    resolution: Tuple[int, int] = (640, 480),
    framerate: Union[int, float] = 30,
    # CamGear parameters
    source: Any = 0,
    stream_mode: bool = False,
    backend: int = 0,
    # common parameters
    time_delay: int = 0,
    colorspace: str = None,
    logging: bool = False,
    **options: dict
):
    """
    This constructor method initializes the object state and attributes of the VideoGear class.

    Parameters:
        enablePiCamera (bool): provide access to PiGear(if True) or CamGear(if False) APIs respectively.
        stabilize (bool): enable access to Stabilizer Class for stabilizing frames.
        camera_num (int): selects the camera module index which will be used as Rpi source.
        resolution (tuple): sets the resolution (i.e. `(width,height)`) of the Rpi source.
        framerate (int/float): sets the framerate of the Rpi source.
        source (based on input): defines the source for the input stream.
        stream_mode (bool): controls the exclusive YouTube Mode.
        backend (int): selects the backend for OpenCV's VideoCapture class.
        colorspace (str): selects the colorspace of the input stream.
        logging (bool): enables/disables logging.
        time_delay (int): time delay (in sec) before start reading the frames.
        options (dict): provides ability to alter Tweak Parameters of CamGear, PiGear & Stabilizer.
    """
    # enable logging if specified
    self.__logging = logging if isinstance(logging, bool) else False

    # print current version
    logcurr_vidgear_ver(logging=self.__logging)

    # initialize stabilizer
    self.__stabilization_mode = stabilize

    # reformat dictionary
    options = {str(k).strip(): v for k, v in options.items()}

    if self.__stabilization_mode:
        from .stabilizer import Stabilizer

        s_radius = options.pop("SMOOTHING_RADIUS", 25)
        if not isinstance(s_radius, int):
            s_radius = 25

        border_size = options.pop("BORDER_SIZE", 0)
        if not isinstance(border_size, int):
            border_size = 0

        border_type = options.pop("BORDER_TYPE", "black")
        if not isinstance(border_type, str):
            border_type = "black"

        crop_n_zoom = options.pop("CROP_N_ZOOM", False)
        if not isinstance(crop_n_zoom, bool):
            crop_n_zoom = False

        self.__stabilizer_obj = Stabilizer(
            smoothing_radius=s_radius,
            border_type=border_type,
            border_size=border_size,
            crop_n_zoom=crop_n_zoom,
            logging=logging,
        )
        self.__logging and logger.debug(
            "Enabling Stabilization Mode for the current video source!"
        )  # log info

    if enablePiCamera:
        # only import the pigear module only if required
        from .pigear import PiGear

        # initialize the picamera stream by enabling PiGear API
        self.stream = PiGear(
            camera_num=camera_num,
            resolution=resolution,
            framerate=framerate,
            colorspace=colorspace,
            logging=logging,
            time_delay=time_delay,
            **options
        )
    else:
        # otherwise, we are using OpenCV so initialize the webcam
        # stream by activating CamGear API
        self.stream = CamGear(
            source=source,
            stream_mode=stream_mode,
            backend=backend,
            colorspace=colorspace,
            logging=logging,
            time_delay=time_delay,
            **options
        )

    # initialize framerate variable
    self.framerate = self.stream.framerate

read(self)

Extracts frames synchronously from selected API's monitored deque, while maintaining a fixed-length frame buffer in the memory, and blocks the thread if the deque is full.

Returns: A n-dimensional numpy array.

Source code in vidgear/gears/videogear.py
def read(self) -> NDArray:
    """
    Extracts frames synchronously from selected API's monitored deque, while maintaining a fixed-length frame
    buffer in the memory, and blocks the thread if the deque is full.

    **Returns:** A n-dimensional numpy array.
    """
    while self.__stabilization_mode:
        frame = self.stream.read()
        if frame is None:
            break
        frame_stab = self.__stabilizer_obj.stabilize(frame)
        if not (frame_stab is None):
            return frame_stab
    return self.stream.read()

start(self)

Launches the internal Threaded Frames Extractor daemon of API in use.

Returns: A reference to the selected class object.

Source code in vidgear/gears/videogear.py
def start(self) -> T:
    """
    Launches the internal *Threaded Frames Extractor* daemon of API in use.

    **Returns:** A reference to the selected class object.
    """
    self.stream.start()
    return self

stop(self)

Safely terminates the thread, and release the respective multi-threaded resources.

Source code in vidgear/gears/videogear.py
def stop(self) -> None:
    """
    Safely terminates the thread, and release the respective multi-threaded resources.
    """
    self.stream.stop()
    # logged
    self.__logging and logger.debug("Terminating VideoGear.")
    # clean queue
    self.__stabilization_mode and self.__stabilizer_obj.clean()