diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 0000000..cb05b8a --- /dev/null +++ b/index.d.ts @@ -0,0 +1,156 @@ +declare namespace aperture { + type Screen = { + id: number; + name: string; + }; + + type AudioDevice = { + id: string; + name: string; + }; + + type VideoCodec = 'h264' | 'hevc' | 'proRes422' | 'proRes4444'; + + type RecordingOptions = { + /** + Number of frames per seconds. + */ + readonly fps?: number; + + /** + Record only an area of the screen. + */ + readonly cropArea?: { + x: number; + y: number; + width: number; + height: number; + }; + + /** + Show the cursor in the screen recording. + */ + readonly showCursor?: boolean; + + /** + Highlight cursor clicks in the screen recording. + + Enabling this will also enable the `showCursor` option. + */ + readonly highlightClicks?: boolean; + + /** + Screen to record. + + Defaults to primary screen. + */ + readonly screenId?: number; + + /** + Audio device to include in the screen recording. + + Should be one of the `id`'s from `aperture.audioDevices()`. + */ + readonly audioDeviceId?: string; + + /** + Video codec to use. + + 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. + */ + readonly videoCodec?: VideoCodec; + }; + + interface Recorder { + /** + Returns a `Promise` that fullfills when the recording starts or rejects if the recording didn't start after 5 seconds. + */ + startRecording: (options?: RecordingOptions) => Promise; + + /** + `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. + */ + isFileReady: Promise | undefined; + + /** + Pauses the recording. To resume, call `recorder.resume()`. + + Returns a `Promise` that fullfills when the recording has been paused. + */ + pause: () => Promise; + + /** + Resumes the recording if it's been paused. + + Returns a `Promise` that fullfills when the recording has been resumed. + */ + resume: () => Promise; + + /** + Returns a `Promise` that resolves with a boolean indicating whether or not the recording is currently paused. + */ + isPaused: () => Promise; + + /** + Returns a `Promise` for the path to the screen recording file. + */ + stopRecording: () => Promise; + } +} + +declare const aperture: (() => aperture.Recorder) & { + /** + 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' + } + ``` + */ + videoCodecs: Map; + + /** + Get a list of screens. + + The first screen is the primary screen. + + @example + ``` + [{ + id: 69732482, + name: 'Color LCD' + }] + ``` + */ + screens: () => Promise; + + /** + Get a list of audio devices. + + @example + ``` + [{ + id: 'AppleHDAEngineInput:1B,0,1,0:1', + name: 'Built-in Microphone' + }] + ``` + */ + audioDevices: () => Promise; +}; + +export = aperture; diff --git a/index.test-d.ts b/index.test-d.ts new file mode 100644 index 0000000..94fbb15 --- /dev/null +++ b/index.test-d.ts @@ -0,0 +1,20 @@ +import {expectType, expectError} from 'tsd'; +import {Recorder, Screen, AudioDevice, VideoCodec} from './index.js'; + +import aperture = require('./index.js'); + +const recorder = aperture(); + +expectType(recorder); + +expectType(await aperture.audioDevices()); + +expectType(await aperture.screens()); + +expectError(recorder.startRecording({videoCodec: 'random'})); + +expectType(await recorder.isFileReady); + +expectType(await recorder.stopRecording()); + +expectType>(aperture.videoCodecs); diff --git a/package.json b/package.json index f48a33f..37f9047 100644 --- a/package.json +++ b/package.json @@ -8,13 +8,14 @@ "node": ">=10" }, "scripts": { - "test": "xo && ava", + "test": "xo && ava && tsd", "build": "swift build --configuration=release && mv .build/release/aperture .", "prepublish": "npm run build" }, "files": [ "index.js", - "aperture" + "aperture", + "index.d.ts" ], "dependencies": { "electron-util": "^0.14.2", @@ -28,6 +29,7 @@ "delay": "^5.0.0", "file-type": "^12.0.0", "read-chunk": "^3.2.0", + "tsd": "^0.14.0", "xo": "^0.38.2" }, "xo": {