From 50a8df8e35a630573ca1853bfd885c19a59b58da Mon Sep 17 00:00:00 2001 From: George Karagkiaouris Date: Wed, 20 Nov 2024 19:40:36 -0500 Subject: [PATCH] Update readme --- readme.md | 224 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 171 insertions(+), 53 deletions(-) diff --git a/readme.md b/readme.md index 8eebc13..5ddfa20 100644 --- a/readme.md +++ b/readme.md @@ -8,15 +8,18 @@ npm install aperture ``` -*Requires macOS 10.13 or later.* +*Requires macOS 13 or later.* ## Usage ```js import {setTimeout} from 'node:timers/promises'; -import {recorder} from 'aperture'; +import {recorder, screens} from 'aperture'; + +const allScreens = await screens(); const options = { + screenId: allScreens[0].id, fps: 30, cropArea: { x: 100, @@ -26,7 +29,7 @@ const options = { }, }; -await recorder.startRecording(options); +await recorder.startRecordingScreen(options); await setTimeout(3000); @@ -38,7 +41,7 @@ See [`example.js`](example.js) if you want to quickly try it out. _(The example ## API -#### screens() -> `Promise` +#### screens() -> `Promise` Get a list of screens. The first screen is the primary screen. @@ -47,13 +50,62 @@ Example: ```js [ { - id: 69732482, + id: '69732482', name: 'Color LCD', + width: 1280, + height: 800, + frame: { + x: 0, + y: 0, + width: 1280, + height: 800 + } }, ]; ``` -#### audioDevices() -> `Promise` +#### windows(options: WindowOptions) -> `Promise` + +Get a list of windows + +##### WindowOptions.excludeDesktopWindows + +Type: `Boolean`\ +Default: `true` + +Exclude desktop windows like Finder, Dock, and Desktop. + +##### WindowOptions.onScreenOnly + +Type: `Boolean`\ +Default: `true` + +Only include windows that are on screen. + + +Example: + +```js +[ + { + id: '69732482', + title: 'Unicorn', + applicationName: 'Safari', + applicationBundleIdentifier: 'com.apple.Safari', + isActive: true, + isOnScreen: true, + layer: 0, + frame: { + x: 0, + y: 0, + width: 1280, + height: 800 + } + } +]; +``` + +#### audioDevices() -> `Promise` Get a list of audio devices. @@ -68,6 +120,21 @@ Example: ]; ``` +#### externalDevices() -> `Promise` + +Get a list of external devices. + +Example: + +```js +[ + { + id: '9eb08da55a14244bf8044bf0f75247d2cb9c364c', + name: 'iPad Pro' + }, +]; +``` + #### 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. @@ -83,97 +150,148 @@ Map { } ``` -#### recorder +#### Audio Recording Options -#### recorder.startRecording([options?](#options)) +##### audioDeviceId -Returns a `Promise` that fullfills when the recording starts or rejects if the recording didn't start after 5 seconds. +Type: `string`\ +Default: `undefined` -#### recorder.isFileReady +Audio device to include in the screen recording. Should be one of the `id`'s from `aperture.audioDevices()`. -`Promise` that fullfills with the path to the screen recording file when it's ready. This will never reject. +##### losslessAudio -Only available while a recording is happening, `undefined` otherwise. +Type: `boolean`\ +Default: `false` -Usually, this resolves around 1 second before the recording starts, but that's not guaranteed. +Record audio in a lossless format (ALAC). Uses lossy (AAC) otherwise. -#### recorder.pause() +##### systemAudio -Pauses the recording. To resume, call `recorder.resume()`. +Type: `boolean`\ +Default: `false` -Returns a `Promise` that fullfills when the recording has been paused. +Record system audio. -#### recorder.resume() +#### Video Recording Options -Resumes the recording if it's been paused. +##### fps -Returns a `Promise` that fullfills when the recording has been resumed. +Type: `number`\ +Default: `30` -#### recorder.isPaused() +Number of frames per seconds. -Returns a `Promise` that resolves with a boolean indicating whether or not the recording is currently paused. +##### showCursor -#### recorder.stopRecording() +Type: `boolean`\ +Default: `true` -Returns a `Promise` for the path to the screen recording file. +Show the cursor in the screen recording. -## Options +##### highlightClicks -Type: `object` +Type: `boolean`\ +Default: `false` -#### fps +Highlight cursor clicks in the screen recording. -Type: `number`\ -Default: `30` +Enabling this will also enable the `showCursor` option. -Number of frames per seconds. +##### 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`](https://documentation.apple.com/en/finalcutpro/professionalformatsandworkflows/index.html#chapter=10%26section=2%26tasks=true) codecs are uncompressed data. They will create huge files. + +#### recorder + +#### recorder.startRecordingScreen(options) + +Returns a `Promise` that fullfills when the recording starts. + +Accepts all [video](#video-recording-options) and [audio](#audio-recording-options) options, along with + +##### screenId -#### cropArea +Type: `string` + +The id of the screen to record. + +Should be one of the `id`'s from `screens()`. + +##### cropArea Type: `object`\ Default: `undefined` Record only an area of the screen. Accepts an object with `x`, `y`, `width`, `height` properties. -#### showCursor +#### recorder.startRecordingWindow(options) -Type: `boolean`\ -Default: `true` +Returns a `Promise` that fullfills when the recording starts. -Show the cursor in the screen recording. +Accepts all [video](#video-recording-options) and [audio](#audio-recording-options) options, along with -#### highlightClicks +##### windowId -Type: `boolean`\ -Default: `false` +Type: `string` -Highlight cursor clicks in the screen recording. +The id of the screen to record. -Enabling this will also enable the `showCursor` option. +Should be one of the `id`'s from `windows()`. -#### screenId +#### recorder.startRecordingExternalDevice(options) -Type: `number`\ -Default: `aperture.screens()[0]` _(Primary screen)_ +Returns a `Promise` that fullfills when the recording starts. -Screen to record. +Accepts all [video](#video-recording-options) and [audio](#audio-recording-options) options, along with -#### audioDeviceId +##### deviceId -Type: `string`\ -Default: `undefined` +Type: `string` -Audio device to include in the screen recording. Should be one of the `id`'s from `aperture.audioDevices()`. +The id of the screen to record. -#### videoCodec +Should be one of the `id`'s from `externalDevices()`. -Type: `string`\ -Default: `'h264'`\ -Values: `'hevc' | 'h264' | 'proRes422' | 'proRes4444'` +#### recorder.startRecordingAudio(options) -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. +Returns a `Promise` that fullfills when the recording starts. -The [`proRes422` and `proRes4444`](https://documentation.apple.com/en/finalcutpro/professionalformatsandworkflows/index.html#chapter=10%26section=2%26tasks=true) codecs are uncompressed data. They will create huge files. +Accepts all [audio](#audio-recording-options) options + +#### 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. ## Why