Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jitsi/robotjs
Node.js Desktop Automation.
https://github.com/jitsi/robotjs
Last synced: 8 days ago
JSON representation
Node.js Desktop Automation.
- Host: GitHub
- URL: https://github.com/jitsi/robotjs
- Owner: jitsi
- License: mit
- Fork: true (octalmage/robotjs)
- Created: 2017-06-29T15:47:21.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-09-08T20:18:27.000Z (2 months ago)
- Last Synced: 2024-10-31T02:34:40.347Z (13 days ago)
- Language: C
- Homepage: http://robotjs.io
- Size: 758 KB
- Stars: 67
- Watchers: 14
- Forks: 23
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Important note
This repository is a fork of the original robotjs so we can generate prebuilt packages. All changes have been upstreamed, and should they be applied and prebuilt packages provided this fork shall be abandoned.
> Node.js Desktop Automation. Control the mouse, keyboard, and read the screen.
RobotJS supports Mac, [Windows](https://github.com/octalmage/robotjs/issues/2), and [Linux](https://github.com/octalmage/robotjs/issues/17).
This is a work in progress so the exported functions could change at any time before the first stable release (1.0.0). [Ideas?](https://github.com/octalmage/robotjs/issues/4)
[Check out some of the cool things people are making with RobotJS](https://github.com/octalmage/robotjs/wiki/Projects-using-RobotJS)! Have your own rad RobotJS project? Feel free to add it!
## Contents
- [Installation](#installation)
- [Examples](#examples)
- [API](https://robotjs.io/docs/syntax)
- [Building](#building)
- [Plans](#plans)
- [Progress](#progress)
- [FAQ](#faq)
- [License](#license)
## Installation
Install RobotJS using npm:
```
npm install @jitsi/robotjs
```
It's that easy! npm will download one of the prebuilt [binaries](https://github.com/jitsi/robotjs/releases/latest) for your OS.
You can get npm [here](https://nodejs.org/en/download/) if you don't have it installed.
If you need to build RobotJS, see the [building](#building) section. Instructions for [Electron](https://github.com/octalmage/robotjs/wiki/Electron).
## Examples
##### [Mouse](https://github.com/octalmage/robotjs/wiki/Syntax#mouse)
```JavaScript
// Move the mouse across the screen as a sine wave.
var robot = require("@jitsi/robotjs");
// Speed up the mouse.
robot.setMouseDelay(2);
var twoPI = Math.PI * 2.0;
var screenSize = robot.getScreenSize();
var height = (screenSize.height / 2) - 10;
var width = screenSize.width;
for (var x = 0; x < width; x++)
{
y = height * Math.sin((twoPI * x) / width) + height;
robot.moveMouse(x, y);
}
```
##### [Keyboard](https://github.com/octalmage/robotjs/wiki/Syntax#keyboard)
```JavaScript
// Type "Hello World" then press enter.
var robot = require("@jitsi/robotjs");
// Type "Hello World".
robot.typeString("Hello World");
// Press enter.
robot.keyTap("enter");
```
##### [Screen](https://github.com/octalmage/robotjs/wiki/Syntax#screen)
```JavaScript
// Get pixel color under the mouse.
var robot = require("@jitsi/robotjs");
// Get mouse position.
var mouse = robot.getMousePos();
// Get pixel color in hex format.
var hex = robot.getPixelColor(mouse.x, mouse.y);
console.log("#" + hex + " at x:" + mouse.x + " y:" + mouse.y);
```
Read the [Wiki](https://github.com/octalmage/robotjs/wiki) for more information!
## [API](http://robotjs.io/docs/syntax)
The RobotJS API is hosted at .
## Building
Please ensure you have the required dependencies before installing:
* Windows
* windows-build-tools npm package (`npm install --global --production windows-build-tools` from an elevated PowerShell or CMD.exe)
* Mac
* Xcode Command Line Tools.
* Linux
* Python (v2.7 recommended, v3.x.x is not supported).
* make.
* A C/C++ compiler like GCC.
* libxtst-dev and libpng++-dev (`sudo apt-get install libxtst-dev libpng++-dev`).
Install node-gyp using npm:
```
npm install -g node-gyp
```
Then build:
```
node-gyp rebuild
```
See the [node-gyp readme](https://github.com/nodejs/node-gyp#installation) for more details.
## Plans
* √ Control the mouse by changing the mouse position, left/right clicking, and dragging.
* √ Control the keyboard by pressing keys, holding keys down, and typing words.
* √ Read pixel color from the screen and capture the screen.
* Find an image on screen, read pixels from an image.
* Possibly include window management?
## Progress
| Module | Status | Notes |
| ------------- |-------------: | ------- |
| Mouse | 100% | All planned features implemented. |
| Keyboard | 100% | All planned features implemented. |
| Screen | 85% | Image search, pixel search. |
| Bitmap | 0% | Saving/opening, png support. |
## FAQ
#### Does RobotJS support global hotkeys?
Not currently, and I don't know if it ever will. I personally use [Electron](http://electron.atom.io/)/[NW.js](http://nwjs.io/) for global hotkeys, and this works well. Later on I might add hotkey support or create a separate module. See [#55](https://github.com/octalmage/robotjs/issues/55) for details.
#### Can I take a screenshot with RobotJS?
Soon! This is a bit more complicated than the rest of the features, so I saved it for last. Luckily the code is already there, I just need to write the bindings, and I've already started. Subscribe to [#13](https://github.com/octalmage/robotjs/issues/13) for updates.
#### Why is <insert key> missing from the keyboard functions?
We've been implementing keys as we need them. Feel free to create an issue or submit a pull request!
#### How about multi-monitor support?
The library doesn't have explicit multi-monitor support, so anything that works is kind of on accident. Subscribe to [#88](https://github.com/octalmage/robotjs/issues/88) for updates.
For any other questions please [submit an issue](https://github.com/octalmage/robotjs/issues/new).
## Story
I'm a huge fan of [AutoHotkey](https://www.autohotkey.com/), and I've used it for a very long time. AutoHotkey is great for automation and it can do a bunch of things that are very difficult in other languages. For example, it's [imagesearch](https://www.autohotkey.com/docs/commands/ImageSearch.htm) and [pixel](https://www.autohotkey.com/docs/commands/PixelGetColor.htm) related functions are hard to reproduce on Mac, especially in scripting languages. These functions are great for automating apps that can't be automated like [Netflix](http://blueshirtdesign.com/apps/autoflix/). This has never been a big deal since I've always used Windows at work, but for the past few years I've been using Mac exclusively.
I like AutoHotkey, but I like Node.js more. By developing RobotJS I get an AutoHotkey replacement on Mac (finally!), and I get to use my favorite language.
**TLDR:** There's nothing like AutoHotkey on Mac, so I'm making it.
## Publishing
On every push to main branch, the .github/workflows/ci.yml will create a new version and publish to npm.
If a major or minor release is required, use respective key words in the commit message, see https://github.com/phips28/gh-action-bump-version#workflow
## License
MIT
Based on [autopy](https://github.com/msanders/autopy).
Maintained by [Jason Stallings](http://jason.stallin.gs).