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
  • captureMonitorByIndex
  • captureMonitorByIndexSync
  • captureMonitorByName
  • captureMonitorByNameSync
  • captureWindowByTitle
  • captureWindowByTitleSync
  • captureActiveWindow
  • captureActiveWindowSync
• Interfaces
  • Configuration
  • MonitorInfo
  • PlainRectangle
• Errors
  • NoMatchError
  • InvalidArgumentCountError
  • InvalidConfigurationError

Methods

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

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

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

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

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

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

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'

• (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

• 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.