ScreenGear API

With ScreenGear, we can easily define an area on the computer screen or an open window to record the live screen frames in real-time at the expense of insignificant latency. To achieve this, ScreenGear provides a high-level multi-threaded wrapper around mss python library API and also supports the flexible direct parameter manipulation. Furthermore, ScreenGear relies on Threaded Queue mode for ultra-fast live frame handling and which is enabled by default.

Important:

Python-mss dropped support for legacy Python 2.7 in the latest release (Related PR). Therefore latest Python-mss/ScreenGear may not work with python 2.7 builds, but you can surely try older versions of mss instead at your own risk!

Importing:

You can easily import ScreenGear as follows:

from vidgear.gears import ScreenGear

Usage:

1. Basic Usage:

Below is a snapshot of a ScreenGear API in action:

ScreenGear in action!

Code to generate the above result:

# import libraries
from vidgear.gears import ScreenGear
import cv2

stream = ScreenGear().start()

# infinite loop
while True:
  
  frame = stream.read()
  # read frames

  # check if frame is None
  if frame is None:
    #if True break the infinite loop
    break
  
  cv2.imshow("Output Frame", frame)
  # Show output window

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

cv2.destroyAllWindows()
# close output window

stream.stop()
# safely close video stream.

2. ScreenGear with flexible parameter control:

ScreenGear contains certain parameters which allow us to directly control/set the input dimensions of screen and monitor to grab screen from. Here's an example:

# import libraries
from vidgear.gears import ScreenGear
import cv2


options = {'top': 40, 'left': 0, 'width': 100, 'height': 100} # define dimensions of screen w.r.t to given monitor to be captured
stream = ScreenGear(monitor=1, logging=True, **options).start() #Open Live Screencast on current monitor 

# infinite loop
while True:
	
	frame = stream.read()
	# read frames

	# check if frame is None
	if frame is None:
		#if True break the infinite loop
		break
	

	# {do something with frame here}
       
        # Show output window
	cv2.imshow("Output Frame", frame)

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

cv2.destroyAllWindows()
# close output window

stream.stop()
# safely close video stream

3. ScreenGear with WriteGear API:

ScreenGear can be used with WriteGear API directly without any compatibility issues as follows:

# import libraries
from vidgear.gears import ScreenGear
from vidgear.gears import WriteGear
import cv2


options = {'top': 40, 'left': 0, 'width': 100, 'height': 100} # define dimensions of screen w.r.t to given monitor to be captured

output_params = {"-vcodec":"libx264", "-crf": 0, "-preset": "fast"} #define (Codec,CRF,preset) FFmpeg tweak parameters for writer


stream = ScreenGear(monitor=1, logging=True, **options).start() #Open Live Screencast on current monitor 

writer = WriteGear(output_filename = 'Output.mp4', compression_mode = True, logging = True, **output_params) #Define writer with output filename 'Output.mp4' 

# infinite loop
while True:
	
	frame = stream.read()
	# read frames

	# check if frame is None
	if frame is None:
		#if True break the infinite loop
		break
	

	# {do something with frame here}
        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)

	# write a modified frame to writer
        writer.write(gray) 
       
        # Show output window
	cv2.imshow("Output Frame", frame)

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

cv2.destroyAllWindows()
# close output window

stream.stop()
# safely close video stream
writer.close()
# safely close writer

Parameters and Attributes:

monitor(int): sets the index of the monitor where to grab a frame from. More information can be found here. Its default value is 1 (means the current monitor will be used).

monitor value cannot be negative, Otherwise, it will throw ValueError
colorspace(string): set the colorspace of the video stream. Its default value is None. Check out its detailed Usage here
**options(dict): can be used to pass tweaked parameters to ScreenGear API. This dictionary parameter provides us the flexibility to directly set the dimensions of the given monitor's region which are going to be cast (More information can be found here) and also supports various special parameter to tweak internal properties of ScreenGear. All these parameters can be passed using **option attribute as follows*:
```
options = {'top': 40, 'left': 0, 'width': 100, 'height': 100} # define dimensions of screen w.r.t to given monitor to be captured
```
- Currently supported valid parameters for a given monitor(default is 1) are as follows:
  - 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 region
  - height: the height of the region
logging(boolean): set this flag to enable/disable error logging essential for debugging. Its default value is False.

Notes 🗒

This Wiki and the Readme contains a lot of detailed information, please take your time to read the information.
There is a heavily detailed Changelog and Release changes.
If you run into any trouble or have any questions, or want to share some information, or you've come up with some new feature, then do not hesitate to report an Issue.
Always be sure to read the FAQ & Troubleshooting and Contributing Guide before opening a issue or pull request to VidGear.

Become Stargazer

If you think VidGear library is helpful and would like to help in return - then you can be a stargazer. By starring this project, you're making it easier for others to find & trust this library. Thank you.

Donate to Project development

If you would like to help the continued efforts of this project, any size donations are welcomed and highly appreciated: