windows-ss

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

Usage no npm install needed!

<script type="module">
  import windowsSs from 'https://cdn.skypack.dev/windows-ss';
</script>

README

windows-ss

npm version

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

(Internal) CSArgumentError

Based on C#'s ArgumentException.

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