alectrocute / aperture-node

Record the screen on macOS from Node.js

aperture-node

Record the screen on macOS from Node.js

Install

$ npm install aperture

Requires macOS 10.12 or later.

Usage

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

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

(async () => {
  await aperture.startRecording(options);
  await delay(3000);
  console.log(await aperture.stopRecording());
  //=> '/private/var/folders/3x/jf5977fn79j/T/cdf4f7df426c97880f8c10a1600879f7.mp4'
})();

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

API

aperture.screens() -> Promise<Object[]>

Get a list of screens. The first screen is the primary screen.

Example:

[{
  id: 69732482,
  name: 'Color LCD'
}]

aperture.audioDevices() -> Promise<Object[]>

Get a list of audio devices.

Example:

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

aperture.videoCodecs -> Map

Get a list of available video codecs. The key is the videoCodec option name and the value is the codec name. It only returns hevc if you're on macOS 10.13 or newer and your computer supports HEVC hardware encoding.

Example:

Map {
  'h264' => 'H264',
  'hevc' => 'HEVC',
  'proRes422' => 'Apple ProRes 422',
  'proRes4444' => 'Apple ProRes 4444'
}

recorder = aperture()

recorder.startRecording([options])

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

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

recorder.stopRecording()

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

Options

destinationPath

Type: string
Default: undefined

Destination of the output file. When undefined, destination will be generated using tempy (default).

destinationPath can be useful when needing to store temporary data on a different external network or local drive, allowing for higher capacity file storage (further discussion).

This option should only be used when necessary. If destinationPath is not defined, then tempy is used to generate an available filename and path in the user's temporary directory, eg. /private/var/folders/3x/jf5977fn79j/T/vid.mp4.

fps

Type: number
Default: 30

Number of frames per seconds.

cropArea

Type: Object
Default: undefined

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.

screenId

Type: number
Default: aperture.screens()[0] (Primary screen)

Screen to record.

audioDeviceId

Type: string
Default: undefined

Audio device to include in the screen recording. Should be one of the id's from aperture.audioDevices().

videoCodec

Type: string
Default: h264
Values: hevc h264 proRes422 proRes4444

The hevc codec requires macOS 10.13 or newer. A computer with Intel 6th generation processor or newer is strongly recommended, as otherwise it will use software encoding, which only produces 3 FPS fullscreen recording.

The proRes422 and proRes4444 codecs are uncompressed data. They will create huge files.

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:

Related

• Aperture - The Swift framework used in this package

License

MIT