cross-capture

Capture screenshots programmatically. Cross-platform, with support for MacOS (Darwin), Windows, and Linux.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.

Install

Install with npm:

$ npm install --save cross-capture

Usage

import {
  capture, // Automatically detect platform
  captureLinux, // Capture on Linux
  captureDarwin, // Capture on MacOS
  captureWindows // Capture on Windows
} from 'cross-capture';

capture({
  cursor: true
  format: 'png', // this is the default
  window: { interactive: true } // this is the default
})

Requirements

• macOS: Built-in support
• Linux: One of:
  • grim + slurp (Wayland)
  • maim (X11)
  • ImageMagick (import command)
• Windows: PowerShell 5.0+

API

capture

Take a screenshot with the specified options. Returns a Promise that resolves to a base64-encoded image or an error object.

import { capture } from 'cross-capture';

// Take a full screen screenshot
const result = await capture();
console.log(result.data); // Base64 encoded PNG

// Take a screenshot of a specific region
const region = await capture({
  region: { x: 0, y: 0, width: 800, height: 600 }
});

captureDarwin

macOS-specific screenshot function using the screencapture command. Supports window capture by ID or title and includes interactive window selection.

import { captureDarwin } from 'cross-capture';

// Capture active window with cursor
const screenshot = await captureDarwin({
  window: { interactive: true },
  cursor: true
});

// Capture specific window by title
const terminal = await captureDarwin({
  window: { title: 'Terminal' }
});

// Capture window by ID
const byId = await captureDarwin({
  window: { id: '12345' }
});

captureLinux

Linux-specific screenshot function that automatically detects and uses the appropriate tools:

• Wayland: Uses grim for capture and slurp for selection
• X11: Uses maim for capture and xdotool for window management

import { captureLinux } from 'cross-capture';

// Capture window by title
const browser = await captureLinux({
  window: { title: 'Firefox' }
});

// Capture region with cursor
const region = await captureLinux({
  cursor: true,
  region: {
    x: 100,
    y: 100,
    width: 500,
    height: 300
  }
});

// Interactive selection (uses slurp on Wayland, maim -s on X11)
const selected = await captureLinux();

captureWindows

Windows-specific screenshot function using PowerShell and Windows Forms. Interactive selection is implemented via a semi-transparent form overlay. Window capture requires exact window title match.

import { captureWindows } from 'cross-capture';

// Interactive region selection
const region = await captureWindows();

// Capture specific window
const notepad = await captureWindows({
  window: { title: 'Untitled - Notepad' }
});

// Capture region as JPG
const jpg = await captureWindows({
  format: 'jpg',
  region: {
    x: 0,
    y: 0,
    width: 1920,
    height: 1080
  }
});

Options

The following options can be passed to the capture functions:

interactive

Type: boolean Default: false

Enable interactive selection mode (where supported).

const screenshot = await capture({ interactive: true });

cursor

Type: boolean Default: false

Include the cursor in the screenshot.

const withCursor = await capture({ cursor: true });

format

Type: string Default: 'png'

Output format for the screenshot. Supported values: 'png', 'jpg'.

const jpgScreenshot = await capture({ format: 'jpg' });

quality

Type: number Default: 100

JPEG quality (0-100) when using format: 'jpg'.

const compressed = await capture({
  format: 'jpg',
  quality: 80
});

region

Type: object

Capture a specific region of the screen.

Properties:

• x (number): X coordinate
• y (number): Y coordinate
• width (number): Width of region
• height (number): Height of region

const region = await capture({
  region: {
    x: 100,
    y: 100,
    width: 500,
    height: 300
  }
});

window

Type: object

Capture a specific window.

Properties:

• title (string): Window title to match
• id (string): Window ID (macOS only)
• interactive (boolean): Interactive window selection

// Capture by window title
const window = await capture({
  window: { title: 'Terminal' }
});

// Interactive window selection (macOS)
const selected = await capture({
  window: { interactive: true }
});

tempFile

Type: string

Custom temporary file path for the screenshot.

const custom = await capture({
  tempFile: '/tmp/my-screenshot.png'
});

Release History

v1.0.0

• Initial release with cross-platform support
• Basic screenshot capabilities
• Window and region capture support

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Running Tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

Copyright © 2025, Jon Schlinkert. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.8.0, on February 18, 2025.