Record the screen on macOS
aperture
Record the screen on macOS.
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/jf5977fn79jbglr7rk0tq4d00000gn/T/cdf4f7df426c97880f8c10a1600879f7.mp4'
})();
See example.js
if you want to quickly try it out. (The example requires Node.js 8+)
API
aperture.screens() -> Promise<Array>
Get a list of screens. The first screen is the primary screen.
Example:
[{
id: 69732482,
name: 'Color LCD'
}]
aperture.audioDevices() -> Promise<Array>
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.
Fullfills 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
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:
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.