Wondering what’s next for npm?Check out our public roadmap! »

    aperture
    TypeScript icon, indicating that this package has built-in type declarations

    6.0.1 • Public • Published

    aperture-node

    Record the screen on macOS from Node.js

    Install

    $ npm install aperture
    

    Requires macOS 10.13 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<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 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 that fullfills when the recording starts or rejects if the recording didn't start after 5 seconds.

    recorder.isFileReady

    Promise that fullfills with the path to the screen recording file when it's ready. This will never reject.

    Only available while a recording is happening, undefined otherwise.

    Usually, this resolves around 1 second before the recording starts, but that's not guaranteed.

    recorder.pause()

    Pauses the recording. To resume, call recorder.resume().

    Returns a Promise that fullfills when the recording has been paused.

    recorder.resume()

    Resumes the recording if it's been paused.

    Returns a Promise that fullfills when the recording has been resumed.

    recorder.isPaused()

    Returns a Promise that resolves with a boolean indicating whether or not the recording is currently paused.

    recorder.stopRecording()

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

    Options

    Type: object

    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'

    A computer with Intel 6th generation processor or newer is strongly recommended for the hevc codec, 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:

    ffmpeg

    Recording the entire screen with Aperture:

    aperture

    Related

    • Aperture - The Swift framework used in this package

    Keywords

    none

    Install

    npm i aperture

    DownloadsWeekly Downloads

    345

    Version

    6.0.1

    License

    MIT

    Unpacked Size

    1.84 MB

    Total Files

    6

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar