0
# MSS
1

2
An ultra-fast cross-platform multiple screenshots module in pure Python using ctypes. MSS enables capturing screenshots from one or all monitors and saving them as PNG files, with seamless integration with PIL, NumPy, and OpenCV for image processing and computer vision applications. The library is optimized for performance using native platform APIs like BitBlt (Windows), Core Graphics (macOS), and X11 (Linux).
3

4
## Package Information
5

6
- **Package Name**: mss
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install mss`
10

11
## Core Imports
12

13
```python
14
from mss import mss, ScreenShotError
15
```
16

17
## Basic Usage
18

19
```python
20
from mss import mss
21

22
# The simplest use: save a screenshot of the 1st monitor
23
with mss() as sct:
24
    sct.shot()
25

26
# Take a screenshot of all monitors
27
with mss() as sct:
28
    for filename in sct.save():
29
        print(filename)
30

31
# Take a screenshot of a specific region
32
with mss() as sct:
33
    # Custom region
34
    region = {"top": 100, "left": 100, "width": 400, "height": 300}
35
    screenshot = sct.grab(region)
36
    
37
    # Access pixel data
38
    rgb_data = screenshot.rgb
39
    pixel_value = screenshot.pixel(50, 50)  # Get RGB value at (50, 50)
40
```
41

42
## Architecture
43

44
MSS uses a factory pattern to provide cross-platform screenshot functionality:
45

46
- **Factory Function (`mss`)**: Detects the current platform and returns the appropriate implementation
47
- **Platform Implementations**: Windows (MSS), macOS (MSS), Linux (MSS) classes that extend MSSBase
48
- **Screenshot Objects**: Contain raw pixel data with convenient properties for different formats (RGB, BGRA, pixels)
49
- **Native APIs**: Direct ctypes bindings to platform-specific APIs for optimal performance
50

51
The design enables zero-dependency operation while providing thread-safe, high-performance screenshot capture across all major platforms.
52

53
## Capabilities
54

55
### Factory Function
56

57
Creates a platform-specific MSS instance for taking screenshots.
58

59
```python { .api }
60
def mss(
61
    *,
62
    compression_level: int = 6,
63
    with_cursor: bool = False,
64
    display: bytes | str | None = None,  # Linux only
65
    max_displays: int = 32  # macOS only
66
) -> MSSBase:
67
    """
68
    Factory returning a proper MSS class instance.
69
    
70
    Parameters:
71
    - compression_level: PNG compression level (0-9, default 6)
72
    - with_cursor: Include mouse cursor in screenshots (default False)
73
    - display: X11 display string (Linux only, default None)  
74
    - max_displays: Maximum number of displays to detect (macOS only, default 32)
75
    
76
    Returns:
77
    Platform-specific MSS instance (MSSBase subclass)
78
    
79
    Raises:
80
    ScreenShotError: If platform is not supported
81
    """
82
```
83

84
### Screenshot Capture
85

86
Capture screenshots from monitors or custom regions.
87

88
```python { .api }
89
def grab(self, monitor: Monitor | tuple[int, int, int, int]) -> ScreenShot:
90
    """
91
    Retrieve screen pixels for a given monitor or region.
92
    
93
    Parameters:
94
    - monitor: Monitor dict with keys: left, top, width, height
95
              OR tuple (left, top, right, bottom) in PIL.Image.grab() style
96
              
97
    Returns:
98
    ScreenShot object containing pixel data and metadata
99
    """
100

101
def shot(self, **kwargs) -> str:
102
    """
103
    Helper to save screenshot of the 1st monitor.
104
    
105
    Parameters:
106
    - Same as save() method
107
    
108
    Returns:
109
    Filename of saved screenshot
110
    """
111
```
112

113
### Monitor Detection
114

115
Access available monitors and their properties.
116

117
```python { .api }
118
@property
119
def monitors(self) -> Monitors:
120
    """
121
    Get positions of all monitors.
122
    
123
    Returns:
124
    List of Monitor dicts where:
125
    - monitors[0]: Combined area of all monitors
126
    - monitors[1:]: Individual monitor areas
127
    
128
    Each Monitor dict contains:
129
    - left: x-coordinate of upper-left corner
130
    - top: y-coordinate of upper-left corner  
131
    - width: monitor width in pixels
132
    - height: monitor height in pixels
133
    """
134
```
135

136
### File Operations
137

138
Save screenshots to PNG files with flexible naming and callback support.
139

140
```python { .api }
141
def save(
142
    self,
143
    *,
144
    mon: int = 0,
145
    output: str = "monitor-{mon}.png", 
146
    callback: Callable[[str], None] | None = None
147
) -> Iterator[str]:
148
    """
149
    Grab screenshot(s) and save to file(s).
150
    
151
    Parameters:
152
    - mon: Monitor selection
153
           -1: All monitors as single image
154
            0: One screenshot per monitor (default)
155
            N: Screenshot of monitor N only
156
    - output: Filename pattern supporting format placeholders:
157
              {mon}: monitor number
158
              {top}, {left}, {width}, {height}: region coordinates
159
              {date}: current timestamp (supports strftime formatting)
160
    - callback: Function called before saving each file
161
    
162
    Returns:
163
    Generator yielding created filenames
164
    
165
    Raises:
166
    ScreenShotError: If no monitors found or invalid monitor number
167
    """
168
```
169

170
### Context Management
171

172
MSS instances support context manager protocol for automatic resource cleanup.
173

174
```python { .api }
175
def __enter__(self) -> MSSBase:
176
    """Context manager entry - returns self"""
177

178
def __exit__(self, *_) -> None:
179
    """Context manager exit - calls close()"""
180

181
def close(self) -> None:
182
    """Clean up resources (platform-specific implementation)"""
183
```
184

185
### Screenshot Object
186

187
Container for screenshot data with multiple format accessors.
188

189
```python { .api }
190
class ScreenShot:
191
    """
192
    Screenshot object containing pixel data and metadata.
193
    
194
    Attributes:
195
    - raw: bytearray of raw BGRA pixels from native API
196
    - pos: Pos namedtuple with left, top coordinates
197
    - size: Size namedtuple with width, height dimensions
198
    """
199
    
200
    def __init__(self, data: bytearray, monitor: Monitor, *, size: Size | None = None):
201
        """
202
        Initialize screenshot object.
203
        
204
        Parameters:
205
        - data: Raw BGRA pixel data from platform API
206
        - monitor: Monitor dict with position and size
207
        - size: Override size (optional)
208
        """
209
    
210
    @classmethod
211
    def from_size(cls, data: bytearray, width: int, height: int) -> ScreenShot:
212
        """
213
        Create screenshot from data and dimensions only.
214
        
215
        Parameters:
216
        - data: Raw BGRA pixel data
217
        - width: Image width in pixels
218
        - height: Image height in pixels
219
        
220
        Returns:
221
        ScreenShot instance with zero position
222
        """
223
    
224
    def pixel(self, coord_x: int, coord_y: int) -> Pixel:
225
        """
226
        Get RGB pixel value at coordinates.
227
        
228
        Parameters:
229
        - coord_x: X coordinate (0 to width-1)
230
        - coord_y: Y coordinate (0 to height-1)
231
        
232
        Returns:
233
        RGB tuple (red, green, blue) with values 0-255
234
        
235
        Raises:
236
        ScreenShotError: If coordinates are out of bounds
237
        """
238

239
    # Properties for accessing pixel data in different formats
240
    @property
241
    def left(self) -> int:
242
        """Left coordinate of screenshot region"""
243
    
244
    @property  
245
    def top(self) -> int:
246
        """Top coordinate of screenshot region"""
247
        
248
    @property
249
    def width(self) -> int:
250
        """Width of screenshot in pixels"""
251
        
252
    @property
253
    def height(self) -> int:
254
        """Height of screenshot in pixels"""
255
        
256
    @property
257
    def bgra(self) -> bytes:
258
        """Raw BGRA pixel data as bytes"""
259
        
260
    @property
261
    def rgb(self) -> bytes:
262
        """RGB pixel data converted from BGRA"""
263
        
264
    @property
265
    def pixels(self) -> Pixels:
266
        """2D list of RGB tuples organized as [row][column]"""
267
        
268
    @property
269
    def __array_interface__(self) -> dict[str, Any]:
270
        """
271
        NumPy array interface for direct array creation.
272
        Returns BGRA data in shape (height, width, 4).
273
        
274
        Usage:
275
        import numpy as np
276
        screenshot = sct.grab(monitor)
277
        array = np.array(screenshot)  # Uses this interface
278
        """
279
```
280

281
### Utility Functions
282

283
Helper functions for image processing and format conversion (internal use only).
284

285
```python { .api }
286
# Note: to_png is not exported from main mss module
287
# Import directly from mss.tools
288
from mss.tools import to_png
289

290
def to_png(
291
    data: bytes, 
292
    size: tuple[int, int], 
293
    *, 
294
    level: int = 6, 
295
    output: Path | str | None = None
296
) -> bytes | None:
297
    """
298
    Convert RGB data to PNG format.
299
    Note: This function is not exported from the main mss module.
300
    Import directly from mss.tools if needed.
301
    
302
    Parameters:
303
    - data: RGB pixel data (3 bytes per pixel)
304
    - size: (width, height) tuple
305
    - level: PNG compression level (0-9, default 6)
306
    - output: Output file path, or None to return PNG bytes
307
    
308
    Returns:
309
    PNG bytes if output is None, otherwise None after writing file
310
    """
311
```
312

313
### Exception Handling
314

315
Custom exception class for screenshot-related errors.
316

317
```python { .api }
318
class ScreenShotError(Exception):
319
    """
320
    Exception raised for screenshot-related errors.
321
    
322
    Attributes:
323
    - details: dict containing additional error context
324
    """
325
    
326
    def __init__(self, message: str, /, *, details: dict[str, Any] | None = None):
327
        """
328
        Initialize exception.
329
        
330
        Parameters:
331
        - message: Error description
332
        - details: Additional error context (optional)
333
        """
334
```
335

336
## Types
337

338
```python { .api }
339
# Type aliases for API clarity
340
Monitor = dict[str, int]  # Keys: left, top, width, height
341
Monitors = list[Monitor]  # List of Monitor dicts
342
Pixel = tuple[int, int, int]  # RGB values (0-255)
343
Pixels = list[tuple[Pixel, ...]]  # 2D pixel array
344
CFunctions = dict[str, tuple[str, list[Any], Any]]  # ctypes function definitions
345

346
# Named tuples for structured data
347
class Pos(NamedTuple):
348
    left: int
349
    top: int
350

351
class Size(NamedTuple):
352
    width: int  
353
    height: int
354

355
# Base class (abstract)
356
class MSSBase(metaclass=ABCMeta):
357
    """Abstract base class for platform-specific implementations"""
358
    
359
    compression_level: int
360
    with_cursor: bool
361
    cls_image: type[ScreenShot]
362

363
# Module constants
364
__version__: str = "10.1.0"  # Package version
365
__author__: str = "Mickaël Schoentgen"  # Package author  
366
__date__: str = "2013-2025"  # Copyright date range
367
__copyright__: str  # Full copyright notice
368
__all__: tuple = ("ScreenShotError", "mss")  # Public API exports
369
```
370

371
## Integration Examples
372

373
### PIL Integration
374

375
```python
376
from mss import mss
377
from PIL import Image
378

379
with mss() as sct:
380
    # Take screenshot and convert to PIL Image
381
    screenshot = sct.grab(sct.monitors[1])
382
    img = Image.frombytes("RGB", screenshot.size, screenshot.rgb)
383
    
384
    # Save in different formats
385
    img.save("screenshot.jpg", "JPEG")
386
    img.save("screenshot.bmp", "BMP")
387
```
388

389
### NumPy Integration
390

391
```python
392
from mss import mss
393
import numpy as np
394

395
with mss() as sct:
396
    # Screenshot as NumPy array (uses __array_interface__)
397
    screenshot = sct.grab(sct.monitors[1])
398
    array = np.array(screenshot)  # Shape: (height, width, 4) BGRA
399
    
400
    # Convert to RGB array
401
    rgb_array = array[:, :, [2, 1, 0]]  # Reverse BGR to RGB
402
```
403

404
### OpenCV Integration
405

406
```python
407
from mss import mss
408
import numpy as np
409
import cv2
410

411
with mss() as sct:
412
    screenshot = sct.grab(sct.monitors[1])
413
    
414
    # Convert to OpenCV format (BGR)
415
    img = np.array(screenshot)
416
    img = cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)
417
    
418
    # Process with OpenCV
419
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
420
    cv2.imwrite("screenshot.png", img)
421
```
422

423
## Command Line Usage
424

425
MSS provides a command-line interface for quick screenshots:
426

427
```bash
428
# Basic usage - screenshot all monitors
429
mss
430

431
# Screenshot specific monitor
432
mss --monitor 1
433

434
# Custom region (top,left,width,height)  
435
mss --coordinates "100,100,800,600"
436

437
# With cursor and custom compression
438
mss --with-cursor --level 9 --output "my_screenshot.png"
439

440
# Quiet mode (no output)
441
mss --quiet
442
```
443

444
## Platform-Specific Considerations
445

446
### Windows
447
- Uses BitBlt and related Win32 APIs
448
- Supports high-DPI displays with proper scaling
449
- May require elevation for some protected windows
450

451
### macOS  
452
- Uses Core Graphics APIs (CGDisplayCreateImage, etc.)
453
- Handles Retina displays automatically
454
- Respects macOS screenshot permissions
455

456
### Linux
457
- Uses X11 APIs (XGetImage, XGetWindowAttributes)
458
- Requires DISPLAY environment variable
459
- Works with most X11-compatible display servers
460

461
## Error Handling
462

463
Common error scenarios and handling:
464

465
```python
466
from mss import mss, ScreenShotError
467

468
try:
469
    with mss() as sct:
470
        # Monitor out of range
471
        screenshot = sct.grab(sct.monitors[99])
472
except ScreenShotError as e:
473
    print(f"Screenshot error: {e}")
474
    print(f"Details: {e.details}")
475

476
try:
477
    with mss() as sct:
478
        screenshot = sct.grab(sct.monitors[1])
479
        # Pixel coordinates out of bounds
480
        pixel = screenshot.pixel(9999, 9999)
481
except ScreenShotError as e:
482
    print(f"Pixel access error: {e}")
483
```
484

485
## Performance Considerations
486

487
- MSS is optimized for speed using native platform APIs
488
- Context managers (`with mss()`) are recommended for resource management  
489
- For repeated captures, reuse the same MSS instance
490
- Raw BGRA data access is fastest; RGB conversion adds overhead
491
- PNG compression levels 0-3 prioritize speed; 6-9 prioritize size