Skip to content

ScreenGear API Parameters

 

monitor

This parameter enforces dxcam (if installed) and mss (otherwise) usage, and it is suitable for selecting index of a specific screen/monitor device (from where you want retrieve frames) in multi-monitor setup. For example, its value can be assign to 2, to fetch frames from a secondary monitor screen.

Implication of using monitor parameter

Any value on monitor parameter other than None in ScreenGear API:

  • Will enforce dxcam library backend on Windows platform (if installed), and mss library backend otherwise.
  • Will discard any value on its backend parameter.

Data-Type: Integer, Tuple (only if dxcam backend on Windows)

Default Value: Its default value is None (i.e. disabled by default).

Usage:

Using GPU acceleration on Windows

With dxcam library backend, you can also assign which GPU devices ids to use along with monitor device ids as tuple (monitor_idx, gpu_idx), as follows:

# open video stream with defined parameters with 
# monitor at index `1` and GPU at index `0`.
stream = ScreenGear(monitor=(1,0), logging=True).start()

Getting a complete list of monitor devices and GPUs

To get a complete list of monitor devices and outputs(GPUs), you can use dxcam library itself: 

>>> import dxcam
>>> dxcam.device_info()
'Device[0]:<Device Name:NVIDIA GeForce RTX 3090 Dedicated VRAM:24348Mb VendorId:4318>\n'
>>> dxcam.output_info()
'Device[0] Output[0]: Res:(1920, 1080) Rot:0 Primary:True\nDevice[0] Output[1]: Res:(1920, 1080) Rot:0 Primary:False\n'


# open video stream with defined parameters 
# with monitor at index `1` selected
ScreenGear(monitor=1)

With mss library backend, You can also assign monitor value to -1 to fetch frames from all connected multiple monitor screens with mss backend.

With mss library backend, API will output BGRA colorspace frames instead of default BGR.

# open video stream with defined parameters 
# with monitor at index `1` selected
ScreenGear(monitor=1)

 

backend

This parameter enables pyscreenshot usage and select suitable backend for extracting frames in ScreenGear. The user have the authority of selecting suitable backend which generates best performance as well as the most compatible with their machines. The possible values are: dxcam (Windows only), pil, mss, scrot, maim, imagemagick, pyqt5, pyqt, pyside2, pyside, wx, pygdk3, mac_screencapture, mac_quartz, gnome_dbus, gnome-screenshot, kwin_dbus.

Performance Benchmarking of all backend can be found here ➶ and here ➶

Remember to install backend library and all of its dependencies you're planning to use with ScreenGear API.

Any value on monitor parameter will disable the backend parameter. You cannot use both parameters at same time.

Backend defaults to dxcam library on Windows (if installed), and pyscreenshot otherwise.

Data-Type: String

Default Value: Its default value is "" (i.e. default backend).

Usage:

ScreenGear(backend="pil") # to enforce `pil` as backend for extracting frames.

 

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

ScreenGear(colorspace="COLOR_BGR2HSV")

Its complete usage example is given here ➶

 

options

This parameter provides the flexibility to manually set the dimensions of capture screen area.

Supported Dimensional Attributes

ScreenGear API takes left, top, width, height coordinates of the bounding box of capture screen area(ROI), similar to PIL.ImageGrab.grab, defined below:

ScreenGear ROI region

  • left: the x-coordinate of the upper-left corner of the region
  • top: the y-coordinate of the upper-left corner of the region
  • width: the width of the complete region from left to the bottom-right corner of the region.
  • height: the height of the complete region from top to the bottom-right corner of the region.

Data-Type: Dictionary

Default Value: Its default value is {}

Usage:

The desired dimensional coordinates parameters can be passed to ScreenGear API by formatting them as attributes, as follows:

# formatting dimensional parameters as dictionary attributes
options = {'top': 40, 'left': 0, 'width': 100, 'height': 100}
# assigning it
ScreenGear(**options)

 

logging

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

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

ScreenGear(logging=True)