Aperture

Record the screen on macOS

Install

$ npm install aperture

Requires macOS 10.10 or later.

Usage

const aperture = require('aperture')();

const options = {
  fps: 30,
  cropArea: {
    x: 100,
    y: 100,
    width: 500,
    height: 500
  }
};

aperture.startRecording(options).then(filePath => {
  setTimeout(() => {
      aperture.stopRecording().then(console.log);
      //=> '/var/folders/r9/65knbqts47x3yg055cd739qh0000gn/T/tmp-15694AAzbYX1vzi2X.mp4'
  }, 3000);
});

See example.js if you want to quickly try it out. (The example requires Node.js 7+)

API

instance = aperture()

instance.startRecording([options])

Returns a Promise for the path to the screen recording file.

Fullfills when the recording starts or rejects if the recording didn't start after 5 seconds.

instance.stopRecording()

Returns a Promise for the path to the screen recording file.

instance.getAudioSources()

Get a list of audio sources.

Example:

[{
  id: 'AppleHDAEngineInput:1B,0,1,0:1',
  name: 'Built-in Microphone'
}]

options

fps

Type: number
Default: 30

Number of frames per seconds.

cropArea

Type: Object string
Default: 'none'

Record only an area of the screen. Accepts an object with x, y, width, height properties.

showCursor

Type: boolean
Default: true

Show the cursor in the screen recording.

highlightClicks

Type: boolean
Default: false

Highlight cursor clicks in the screen recording.

Enabling this will also enable the showCursor option.

displayId

Type: string
Default: main

Display to record.

audioSourceId

Type: Object string
Default: 'none'

Audio source to include in the screen recording. Should be one of the id's from instance.getAudioSources().

Why

Aperture was built to fulfill the needs of Kap, providing a JavaScript interface to the best available method for recording the screen. That's why it's currently a wrapper for a Swift script that records the screen using the AVFoundation framework.

But you can use ffmpeg -f avfoundation...

Yes, we can, but the performance is terrible:

Recording the entire screen with ffmpeg -f avfoundation -i 1 -y test.mp4:

Recording the entire screen with aperture:

Linux and Windows

We want to bring Aperture to Linux and Windows, but we don't have time or resources for such tasks (we're Mac users), so any help is more than welcome. We just want to enforce two things: performance and quality – it doesn't matter how (ffmpeg, custom built native lib, etc) they are achieved.

Upcoming

Aperture is in its early days. We're working on adding more features, such as export to GIF, compression options, support for multiple displays, support for audio, and much more. Check out our Aperture issues on Kap to learn more.