mss 2.0.0

An ultra fast cross-platform multiple screenshots module in pure python using ctypes.

An ultra fast cross-platform multiple screenshots module in pure python using ctypes

Very basic, it will grab one screen shot by monitor or a screen shot of all monitors and save it to a PNG file, Python 2.6/3.5 compatible & PEP8 compliant. It could be easily embedded into games and other softwares which require fast and plateforme optimized methods to grab screenshots.

MSS stands for Multiple ScreenShots.

It’s under zlib/libpng licence.

Installation

You can install it with pip:

$ pip install --upgrade mss

Support

Python	GNU/Linux	MacOS X	Windows
3.5	Yes	Yes	Yes
3.4	yes	yes	yes
3.3	yes	???	yes
3.2	yes	???	yes
3.1	yes	???	yes
3.0	yes	???	yes
2.7	Yes	Yes	Yes
2.6	yes	yes	yes

Feel free to try MSS on a system we had not tested, and let report us by creating an issue.

Testing

You can try the MSS module directly from the console:

$ python tests.py

Instance the good class

So MSS can be used as simply as:

from mss import mss


# Then ...
with mss() as screenshotter:
    # ...

Or import the good one (choose one):

# MacOS X
from mss.darwin import MSS

# GNU/Linux
from mss.linux import MSS

# Microsoft Windows
from mss.windows import MSS


# Then ...
with MSS() as screenshotter:
    # ...

Of course, you can use it the old way:

from mss import mss
# or from mss.linux import MSS as mss


# Then ...
screenshotter = mss()
# ...

Errors

If an error occures, the ScreenshotError exception is raised.

Examples

One screenshot per monitor:

for filename in screenshotter.save():
    print(filename)

Screenshot of the monitor 1:

print(next(screenshotter.save(mon=1)))

Screenshot of the monitor 1, with callback:

def on_exists(fname):
    ''' Callback example when we try to overwrite an existing
        screenshot.
    '''

    from os import rename
    from os.path import isfile

    if isfile(fname):
        newfile = fname + '.old'
        print('{0} -> {1}'.format(fname, newfile))
        rename(fname, newfile)
    return True

print(next(screenshotter.save(mon=1, callback=on_exists)))

A screenshot to grab them all:

print(next(screenshotter.save(mon=-1, output='fullscreen.png')))

Example into the Python’s console —

>>> from mss import mss
>>> sct = mss(display=b':0')

# Retrieve monitors informations
>>> displays = sct.enum_display_monitors()
>>> displays
[{'width': 1920, 'top': 0, 'height': 1080, 'left': 0}, {'width': 1920, 'top': 0, 'height': 1080, 'left': 0}]
# You can access monitors list via `monitors`:
>>> sct.monitors
[{'width': 1920, 'top': 0, 'height': 1080, 'left': 0}, {'width': 1920, 'top': 0, 'height': 1080, 'left': 0}]

# Retrieve pixels from the first monitor
>>> pixels = sct.get_pixels(displays[1])
>>> pixels
<ctypes.c_char_Array_6220800 object at 0x7fe82e9007a0>
# You can access pixels data via `image`:
>>> sct.image
<ctypes.c_char_Array_6220800 object at 0x7fe82e9007a0>

# Save pixels to a PNG file: option 1
>>> files = sct.save(mon=1)
>>> next(files)
'monitor-1.png'
>>> next(files)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
StopIteration

# Save pixels to a PNG file: option 2
>>> mon = displays[1]
>>> sct.to_png(data=pixels, width=mon[b'width'], height=mon[b'height'], output='monitor-1.png')

---

API

enum_display_monitors => list of dicts

>>> enum_display_monitors(force=False)
''' Get positions and dimensions of monitors.
    If `force` is set to `True`, it will rescan for monitors informations.
    It stocks monitors informations into `monitors` and returns it.
    `monitors[0]` is a dict of all monitors together
    `monitors[N]` is a dict of the monitor N (with N > 0)
'''

get_pixels => array of ctypes.c_char

>>> get_pixels(monitor)
''' Retrieve screen pixels for a given monitor.
    `monitor` is a dict generated by `enum_display_monitors()`.
    This method has to define `width` and `height`.
    It stocks pixels data into `image` (RGB) and returns it.
'''

save => generator

>>> save(mon=0, output='monitor-%d', callback=lambda *x: True)
''' Grab a screenshot and save it to a file.

    `mon` is an integer:
        -1: grab one screenshot of all monitors
         0: grab one screenshot by monitor
         N: grab the screenshot of the monitor N

    `output` is a string:
        The output filename.
        %d, if presents, will be replaced by the monitor number.

    `callback` is a method:
        Callback called before saving the screenshot to a file.
        Takes `output` argument as parameter.

    This is a generator which returns created files.
'''

to_png

>>> to_png(data, width, height, output)
''' Dump raw `data` into PNG `output` file. `data` is bytes(RGBRGB...RGB). '''