windows-ss


Take screenshots quickly on Windows by communicating directly with native API's.

> Did I mention that it's DPI aware too?

Benchmark

Using this repo. The numbers below were taken over 1000 runs, each at 2560x1440^\*, outputing bmp.

| Library | Save to buffer | Save to file |
| ------------------ | -------------- | ------------ |
| windows-ss | 52ms | 51ms |
| screenshot-desktop | 152ms | 141ms |
| desktop-screenshot | n/a | 63ms^\\ |

^\* Except for desktop-screenshot, it ran at 1706x960 as it's DPI unaware.

^\\ Times are relative to lower resolution of 1706x960. If interpolated back to 1440p according to a DPI of 1.5, 63 * (1.5 ^ 2) = 141ms

Installation

``bash
npm i windows-ss
`

> IMPORTANT: You'll need .NET 4.5 or .NET Core installed, as this library depends on edge-js. Refer here for more info regarding installation.

Usage

`ts
import { capturePrimaryMonitor } from 'windows-ss';

await capturePrimaryMonitor({
// The format of the returned Buffer & saved file.
format: 'png',

// How much to carve off the edges. (Left, Top, Right, Bottom)
crop: {
left: 0,
top: 0,
right: 0,
bottom: 0,
},

// The bounds where the screen will be captured. (Left, Top, Right, Bottom)
bounds: {
left: 0,
top: 0,
right: 0,
bottom: 0,
},

// The file the screenshot will be saved to.
save: './ss.png',
});
`

API

$3

* Methods
* getMonitorInfos
* getMonitorInfosSync
* captureMonitorByIndex
* captureMonitorByIndexSync
* captureMonitorByName
* captureMonitorByNameSync
* captureWindowByTitle
* captureWindowByTitleSync
* captureActiveWindow
* captureActiveWindowSync
* Interfaces
* Configuration
* MonitorInfo
* PlainRectangle
* Errors
* NoMatchError
* InvalidArgumentCountError
* InvalidConfigurationError

$3

#### getMonitorInfos

#### getMonitorInfosSync

Returns information about the the currently connected monitors.

##### Parameters

* n/a

##### Returns

* Promise\<MonitorInfo[]\> —— MonitorInfo[]
* An array of MonitorInfos gotten from the current system.

##### Throws

* n/a

##### Example

`ts
import { getMonitorInfos, getMonitorInfosSync } from 'windows-ss';

await getMonitorInfos();
getMonitorInfosSync();
/*
// Example output
[
{
monitor: { left: 0, top: 0, right: 2560, bottom: 1440 },
workArea: { left: 0, top: 0, right: 2560, bottom: 1380 },
deviceName: '\\\\.\\DISPLAY1'
},
{
monitor: { left: 304, top: -1080, right: 2224, bottom: 0 },
workArea: { left: 304, top: -1080, right: 2224, bottom: -40 },
deviceName: '\\\\.\\DISPLAY2'
}
]
*/
`



#### captureMonitorByIndex

#### captureMonitorByIndexSync

Captures a screenshot of the monitor matching the device index.

##### Parameters

* deviceIndex: number
* Index of monitor according to Windows.
(Optional)* config: Configuration
* Additional options for capturing the screenshot.

##### Returns

* Promise\<Buffer | null\> —— Buffer | null
* The binary image data of the screenshot, with the format specified in options.format. null is returned instead if save was passed into the config parameter.

##### Throws

* NoMatchError
* InvalidArgumentCountError
* InvalidConfigurationError

##### Example

`ts
import { captureMonitorByIndex, captureMonitorByIndexSync, getMonitorInfos } from 'windows-ss';

const monitorInfos = await getMonitorInfos();

await captureMonitorByIndex(monitorInfos.length - 1);
captureMonitorByIndexSync(0);
`



#### captureMonitorByName

#### captureMonitorByNameSync

Captures a screenshot of the monitor matching the device name.

##### Parameters

* deviceName: string
* Name of monitor according to Windows.
(Optional)* config: Configuration
* Additional options for capturing the screenshot.

##### Returns

* Promise\<Buffer | null\> —— Buffer | null
* The binary image data of the screenshot, with the format specified in options.format. null is returned instead if save was passed into the config parameter.

##### Throws

* NoMatchError
* InvalidArgumentCountError
* InvalidConfigurationError

##### Example

`ts
import { captureMonitorByName, captureMonitorByNameSync, getMonitorInfos } from 'windows-ss';

const monitorInfos = await getMonitorInfos();

await captureMonitorByName(monitorInfos[0].deviceName);
captureMonitorByNameSync(String.raw\\.\DISPLAY1);
`



#### capturePrimaryMonitor

#### capturePrimaryMonitorSync

Captures a screenshot of the primary monitor.

##### Parameters

(Optional)* config: Configuration
* Additional options for capturing the screenshot.

##### Returns

* Promise\<Buffer | null\> —— Buffer | null
* The binary image data of the screenshot, with the format specified in options.format. null is returned instead if save was passed into the config parameter.

##### Throws

* InvalidConfigurationError

##### Example

`ts
import { capturePrimaryMonitor, capturePrimaryMonitorSync } from 'windows-ss';

await capturePrimaryMonitor();
capturePrimaryMonitorSync();
`



#### captureWindowByTitle

#### captureWindowByTitleSync

Captures a screenshot of the window matching the title.

##### Parameters

* title: string
* Title of window.
(Optional)* config: Configuration
* Additional options for capturing the screenshot.

##### Returns

* Promise\<Buffer | null\> —— Buffer | null
* The binary image data of the screenshot, with the format specified in options.format. null is returned instead if save was passed into the config parameter.

##### Throws

* NoMatchError
* InvalidArgumentCountError
* InvalidConfigurationError

##### Example

`ts
import { captureWindowByTitle, captureWindowByTitleSync } from 'windows-ss';

await captureWindowByTitle('Task Manager');
captureWindowByTitleSync('Notepad');
`



#### captureActiveWindow

#### captureActiveWindowSync

Captures a screenshot of the currently active/focused window.

##### Parameters

(Optional)* config: Configuration
* Additional options for capturing the screenshot.

##### Returns

* Promise\<Buffer | null\> —— Buffer | null
* The binary image data of the screenshot, with the format specified in options.format. null is returned instead if save was passed into the config parameter.

##### Throws

* InvalidConfigurationError

##### Example

`ts
import { captureActiveWindow, captureActiveWindowSync } from 'windows-ss';

await captureActiveWindow();
captureActiveWindowSync();
`

$3

#### Configuration

Contains options that can be provided by the user when taking a screenshot.

##### Properties

(Optional)* format: string — The format of the returned buffer & saved file.

* Default — 'png'
* Valid Values
* 'png'
* 'jpg'
* 'jpeg'
* 'bmp'
* 'emf'
* 'exif'
* 'gif'
* 'icon'
* 'tiff'
* 'wmf'

(Optional)* crop: PlainRectangle — How much to carve off the edges.

(Optional)* bounds: PlainRectangle — The bounds where the screen will be captured.

(Optional)* save: string — The path to where the screenshot will be saved to.

* > Note: If this property is not provided, the screenshot is simply returned as a Buffer.



#### MonitorInfo

Contains a description of a monitor.

##### Properties

* monitor: PlainRectangle — The resolution of the entire monitor.
* workArea: PlainRectangle — The resolution of the entire monitor excluding the taskbar.
* deviceName: string — The device name of the monitor.



#### PlainRectangle

Contains properties to form a plain rectangle.

##### Properties

* left: number — The left edge of the rectangle.

* > IMPORTANT: This must be of int type, meaning no decimals. Else, it will fail applying configuration.

* top: number — The top edge of the rectangle.

* > IMPORTANT: This must be of int type, meaning no decimals. Else, it will fail applying configuration.

* right: number — The right edge of the rectangle.

* > IMPORTANT: This must be of int type, meaning no decimals. Else, it will fail applying configuration.

* bottom: number — The bottom edge of the rectangle.

* > IMPORTANT: This must be of int type, meaning no decimals. Else, it will fail applying configuration.

$3

#### NoMatchError

Thrown when no match can be found with the provided arguments.

##### Extends

* CSArgumentError

##### Properties

(Inherited)* paramName: string
(Inherited)* name: string
(Inherited)* stack: string
(Inherited)* raw: CSException



#### InvalidArgumentCountError

Thrown when an invalid amount of arguments were provided.

##### Extends

* CSArgumentError

##### Properties

(Inherited)* paramName: string
(Inherited)* name: string
(Inherited)* stack: string
(Inherited)* raw: CSException



#### InvalidConfigurationError

Thrown when an invalid Configuration object was provided.

##### Extends

* CSArgumentError

##### Properties

(Inherited)* paramName: string
(Inherited)* name: string
(Inherited)* stack: string
(Inherited)* raw: CSException



#### (Internal) CSArgumentError

Based on C#'s ArgumentException.

##### Extends

* CSError

##### Properties

* paramName: string
(Inherited)* name: string
(Inherited)* stack: string
(Inherited)* raw: CSException



#### (Internal) CSError

Based on C#'s SystemException.

##### Extends

* ClientError
* An internal wrapper for Error

##### Properties

* raw: CSException
* The InnerException property of the raw Error object thrown by edge-js`
(Inherited)* name: string
(Inherited)* stack: string

Contributing

All contributions are welcome. File an issue if you find something wrong, & a pull request if you can fix it.

License

MIT.