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
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
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
Table of Contents
Methods
getMonitorInfos
getMonitorInfosSync
Returns information about the the currently connected monitors.
Parameters
- n/a
Returns
-
Promise<MonitorInfo[]>
——MonitorInfo[]
- An array of
MonitorInfo
s gotten from the current system.
- An array of
Throws
- n/a
Example
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 ifsave
was passed into theconfig
parameter.
- The binary image data of the screenshot, with the format specified in
Throws
Example
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 ifsave
was passed into theconfig
parameter.
- The binary image data of the screenshot, with the format specified in
Throws
Example
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 ifsave
was passed into theconfig
parameter.
- The binary image data of the screenshot, with the format specified in
Throws
Example
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 ifsave
was passed into theconfig
parameter.
- The binary image data of the screenshot, with the format specified in
Throws
Example
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 ifsave
was passed into theconfig
parameter.
- The binary image data of the screenshot, with the format specified in
Throws
Example
import { captureActiveWindow, captureActiveWindowSync } from 'windows-ss';
await captureActiveWindow();
captureActiveWindowSync();
Interfaces
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'
-
Default —
-
(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.
-
Errors
NoMatchError
Thrown when no match can be found with the provided arguments.
Extends
Properties
-
(Inherited)
paramName: string
-
(Inherited)
name: string
-
(Inherited)
stack: string
-
(Inherited)
raw: CSException
InvalidArgumentCountError
Thrown when an invalid amount of arguments were provided.
Extends
Properties
-
(Inherited)
paramName: string
-
(Inherited)
name: string
-
(Inherited)
stack: string
-
(Inherited)
raw: CSException
InvalidConfigurationError
Thrown when an invalid Configuration
object was provided.
Extends
Properties
-
(Inherited)
paramName: string
-
(Inherited)
name: string
-
(Inherited)
stack: string
-
(Inherited)
raw: CSException
CSArgumentError
(Internal) Based on C#'s ArgumentException
.
Extends
Properties
CSError
(Internal) Based on C#'s SystemException
.
Extends
-
ClientError
- An internal wrapper for
Error
- An internal wrapper for
Properties
-
raw: CSException
- The
InnerException
property of the rawError
object thrown byedge-js
- The
-
(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.