MSS API¶

Classes¶

macOS¶

mss.darwin.CFUNCTIONS¶: New in version 6.1.0.

mss.darwin.cgfloat()¶

class mss.darwin.CGPoint¶

class mss.darwin.CGSize¶

class mss.darwin.CGRect¶

class mss.darwin.MSS¶

core¶

max_displays¶

GNU/Linux¶

mss.linux.CFUNCTIONS¶: New in version 6.1.0.

mss.linux.PLAINMASK¶

mss.linux.ZPIXMAP¶

class mss.linux.Display¶: Structure that serves as the connection to the X server, and that contains all the information about that X server.

class mss.linux.Event¶: XErrorEvent to debug eventual errors.

class mss.linux.XFixesCursorImage¶: Cursor structure

class mss.linux.XImage¶: Description of an image as it exists in the client’s memory.

class mss.linux.XRRCrtcInfo¶: Structure that contains CRTC information.

class mss.linux.XRRModeInfo¶

class mss.linux.XRRScreenResources¶: Structure that contains arrays of XIDs that point to the available outputs and associated CRTCs.

class mss.linux.XWindowAttributes¶: Attributes for the specified window.

class mss.linux.MSS¶

close()¶: Clean-up method.

New in version 8.0.0.

Windows¶

mss.windows.CAPTUREBLT¶

mss.windows.CFUNCTIONS¶: New in version 6.1.0.

mss.windows.DIB_RGB_COLORS¶

mss.windows.SRCCOPY¶

class mss.windows.BITMAPINFOHEADER¶

class mss.windows.BITMAPINFO¶

mss.windows.MONITORNUMPROC¶: New in version 6.1.0.

class mss.windows.MSS¶

gdi32¶

user32¶

Methods¶

mss.base.lock¶: New in version 6.0.0.

class mss.base.MSSBase¶

The parent’s class for every OS implementation.

cls_image¶

compression_level¶: PNG compression level used when saving the screenshot data into a file (see zlib.compress() for details).

New in version 3.2.0.

with_cursor¶: Include the mouse cursor in screenshots.

New in version 8.0.0.

__init__(compression_level=6, display=None, max_displays=32, with_cursor=False)¶

Parameters:	compression_level (int) – PNG compression level. display (bytes, str or None) – The display to use. Only effective on GNU/Linux. max_displays (int) – Maximum number of displays. Only effective on macOS. with_cursor (bool) – Include the mouse cursor in screenshots.

New in version 8.0.0: compression_level, display, max_displays, and with_cursor, keyword arguments.

close()¶: Clean-up method.

New in version 4.0.0.

grab(region)¶

Parameters:	monitor (dict) – region’s coordinates.
Return type:	`ScreenShot`

Retrieve screen pixels for a given region. Subclasses need to implement this.

Note

monitor can be a tuple like PIL.Image.grab() accepts, it will be converted to the appropriate dict.

save([mon=1][, output='mon-{mon}.png'][, callback=None])¶

Parameters:	mon (int) – the monitor’s number. output (str) – the output’s file name. callback (callable or None) – callback called before saving the screen shot to a file. Takes the output argument as parameter.
Return type:	iterable
Returns:	Created file(s).

Grab a screen shot and save it to a file. The output parameter can take several keywords to customize the filename:

{mon}: the monitor number

{top}: the screen shot y-coordinate of the upper-left corner

{left}: the screen shot x-coordinate of the upper-left corner

{width}: the screen shot’s width

{height}: the screen shot’s height

{date}: the current date using the default formatter

As it is using the format() function, you can specify formatting options like {date:%Y-%m-%s}.

Warning

On Windows, the default date format may result with a filename containing ‘:’ which is not allowed:

IOerror: [Errno 22] invalid mode ('wb') or filename: 'sct_1-2019-01-01 21:20:43.114194.png'

To fix this, you must provide a custom date formatting.

shot()¶

Return str:	The created file.

Helper to save the screen shot of the first monitor, by default. You can pass the same arguments as for save().

New in version 3.0.0.

class mss.base.ScreenShot¶

Screen shot object.

Note

A better name would have been Image, but to prevent collisions with PIL.Image, it has been decided to use ScreenShot.

classmethod from_size(cls, data, width, height)¶

Parameters:	data (bytearray) – raw BGRA pixels retrieved by ctypes OS independent implementations. width (int) – the monitor’s width. height (int) – the monitor’s height.
Return type:	`ScreenShot`

Instantiate a new class given only screen shot’s data and size.

pixel(coord_x, coord_y)¶

Parameters:	coord_x (int) – The x coordinate. coord_y (int) – The y coordinate.
Return type:	tuple(int, int, int)

Get the pixel value at the given position.

New in version 3.0.0.

mss.tools.to_png(data, size, level=6, output=None)¶

Parameters:	data (bytes) – RGBRGB…RGB data. size (tuple) – The (width, height) pair. level (int) – PNG compression level. output (str) – output’s file name.
Raises:	ScreenShotError – On error when writing data to output. zlib.error – On bad compression level.

Dump data to the image file. Pure Python PNG implementation. If output is None, create no file but return the whole PNG data.

New in version 3.0.0.

Changed in version 3.2.0: The level keyword argument to control the PNG compression level.

Properties¶

class mss.base.MSSBase¶

monitors¶

Positions of all monitors. If the monitor has rotation, you have to deal with it inside this method.

This method has to fill self._monitors with all information and use it as a cache:

self._monitors[0] is a dict of all monitors together
self._monitors[N] is a dict of the monitor N (with N > 0)

Each monitor is a dict with:

left: the x-coordinate of the upper-left corner
top: the y-coordinate of the upper-left corner
width: the width
height: the height

Subclasses need to implement this.

Return type:	list[dict[str, int]]

class mss.base.ScreenShot¶

__array_interface__¶

Numpy array interface support. It uses raw data in BGRA form.

Return type:	dict[str, Any]

bgra¶

BGRA values from the BGRA raw pixels.

Return type:	bytes

New in version 3.2.0.

height¶

The screen shot’s height.

Return type:	int

left¶

The screen shot’s left coordinate.

Return type:	int

pixels¶

List of RGB tuples.

Return type:	list[tuple(int, int, int)]

pos¶

The screen shot’s coordinates.

Return type:	`collections.namedtuple()`

rgb¶

Computed RGB values from the BGRA raw pixels.

Return type:	bytes

New in version 3.0.0.

size¶

The screen shot’s size.

Return type:	`collections.namedtuple()`

top¶

The screen shot’s top coordinate.

Return type:	int

width¶

The screen shot’s width.

Return type:	int

Exception¶

exception mss.exception.ScreenShotError¶

Base class for MSS exceptions.

details¶

On GNU/Linux, and if the error comes from the XServer, it contains XError details. This is an empty dict by default.

For XErrors, you can find information on Using the Default Error Handlers.

Return type:	dict[str, Any]

New in version 3.3.0.

Factory¶

mss.factory.mss()¶: Factory function to instance the appropriate MSS class.