An ultra fast cross-platform multiple screenshots module in pure python using ctypes.
Project description
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). '''
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.