{"id":13612668,"url":"https://github.com/wulkano/aperture-node","last_synced_at":"2025-05-15T09:05:12.663Z","repository":{"id":33863749,"uuid":"163111863","full_name":"wulkano/aperture-node","owner":"wulkano","description":"Record the screen on macOS from Node.js","archived":false,"fork":false,"pushed_at":"2024-11-22T15:18:11.000Z","size":463,"stargazers_count":340,"open_issues_count":9,"forks_count":38,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-07T04:07:38.713Z","etag":null,"topics":["aperture","kap","macos","nodejs","npm-package","screen-recorder"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wulkano.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-25T21:15:11.000Z","updated_at":"2025-03-30T04:18:23.000Z","dependencies_parsed_at":"2024-06-18T15:36:56.287Z","dependency_job_id":"317a4de1-3843-498e-9e97-36d0c6cfe84f","html_url":"https://github.com/wulkano/aperture-node","commit_stats":{"total_commits":182,"total_committers":13,"mean_commits":14.0,"dds":0.4945054945054945,"last_synced_commit":"00c8b35df9e7b11041bf4b6127a82f00517f8764"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wulkano%2Faperture-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wulkano%2Faperture-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wulkano%2Faperture-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wulkano%2Faperture-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wulkano","download_url":"https://codeload.github.com/wulkano/aperture-node/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248890852,"owners_count":21178518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aperture","kap","macos","nodejs","npm-package","screen-recorder"],"created_at":"2024-08-01T20:00:32.972Z","updated_at":"2025-04-14T13:48:52.267Z","avatar_url":"https://github.com/wulkano.png","language":"Swift","readme":"# aperture-node\n\n\u003e Record the screen on macOS from Node.js\n\n## Install\n\n```sh\nnpm install aperture\n```\n\n*Requires macOS 10.13 or later.*\n\n## Usage\n\n```js\nimport {setTimeout} from 'node:timers/promises';\nimport {recorder} from 'aperture';\n\nconst options = {\n\tfps: 30,\n\tcropArea: {\n\t\tx: 100,\n\t\ty: 100,\n\t\twidth: 500,\n\t\theight: 500,\n\t},\n};\n\nawait recorder.startRecording(options);\n\nawait setTimeout(3000);\n\nconsole.log(await recorder.stopRecording());\n//=\u003e '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/cdf4f7df426c97880f8c10a1600879f7.mp4'\n```\n\nSee [`example.js`](example.js) if you want to quickly try it out. _(The example requires Node.js 18+)_\n\n## API\n\n#### screens() -\u003e `Promise\u003cObject[]\u003e`\n\nGet a list of screens. The first screen is the primary screen.\n\nExample:\n\n```js\n[\n\t{\n\t\tid: 69732482,\n\t\tname: 'Color LCD',\n\t},\n];\n```\n\n#### audioDevices() -\u003e `Promise\u003cObject[]\u003e`\n\nGet a list of audio devices.\n\nExample:\n\n```js\n[\n\t{\n\t\tid: 'AppleHDAEngineInput:1B,0,1,0:1',\n\t\tname: 'Built-in Microphone',\n\t},\n];\n```\n\n#### videoCodecs -\u003e `Map`\n\nGet 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.\n\nExample:\n\n```js\nMap {\n\t'h264' =\u003e 'H264',\n\t'hevc' =\u003e 'HEVC',\n\t'proRes422' =\u003e 'Apple ProRes 422',\n\t'proRes4444' =\u003e 'Apple ProRes 4444'\n}\n```\n\n#### recorder\n\n#### recorder.startRecording([options?](#options))\n\nReturns a `Promise` that fullfills when the recording starts or rejects if the recording didn't start after 5 seconds.\n\n#### recorder.isFileReady\n\n`Promise` that fullfills with the path to the screen recording file when it's ready. This will never reject.\n\nOnly available while a recording is happening, `undefined` otherwise.\n\nUsually, this resolves around 1 second before the recording starts, but that's not guaranteed.\n\n#### recorder.pause()\n\nPauses the recording. To resume, call `recorder.resume()`.\n\nReturns a `Promise` that fullfills when the recording has been paused.\n\n#### recorder.resume()\n\nResumes the recording if it's been paused.\n\nReturns a `Promise` that fullfills when the recording has been resumed.\n\n#### recorder.isPaused()\n\nReturns a `Promise` that resolves with a boolean indicating whether or not the recording is currently paused.\n\n#### recorder.stopRecording()\n\nReturns a `Promise` for the path to the screen recording file.\n\n## Options\n\nType: `object`\n\n#### fps\n\nType: `number`\\\nDefault: `30`\n\nNumber of frames per seconds.\n\n#### cropArea\n\nType: `object`\\\nDefault: `undefined`\n\nRecord only an area of the screen. Accepts an object with `x`, `y`, `width`, `height` properties.\n\n#### showCursor\n\nType: `boolean`\\\nDefault: `true`\n\nShow the cursor in the screen recording.\n\n#### highlightClicks\n\nType: `boolean`\\\nDefault: `false`\n\nHighlight cursor clicks in the screen recording.\n\nEnabling this will also enable the `showCursor` option.\n\n#### screenId\n\nType: `number`\\\nDefault: `aperture.screens()[0]` _(Primary screen)_\n\nScreen to record.\n\n#### audioDeviceId\n\nType: `string`\\\nDefault: `undefined`\n\nAudio device to include in the screen recording. Should be one of the `id`'s from `aperture.audioDevices()`.\n\n#### videoCodec\n\nType: `string`\\\nDefault: `'h264'`\\\nValues: `'hevc' | 'h264' | 'proRes422' | 'proRes4444'`\n\nA 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.\n\nThe [`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.\n\n## Why\n\nAperture was built to fulfill the needs of [Kap](https://github.com/wulkano/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](Sources/ApertureCLI/main.swift) that records the screen using the [AVFoundation framework](https://developer.apple.com/av-foundation/).\n\n#### But you can use `ffmpeg -f avfoundation...`\n\nYes, we can, but the performance is terrible:\n\n##### Recording the entire screen with `ffmpeg -f avfoundation -i 1 -y test.mp4`:\n\n![ffmpeg](https://cloud.githubusercontent.com/assets/4721750/19214740/f823d4b6-8d60-11e6-8af3-4726146ef29a.jpg)\n\n##### Recording the entire screen with Aperture:\n\n![aperture](https://cloud.githubusercontent.com/assets/4721750/19214743/11f4aaaa-8d61-11e6-9822-4e83bcdfab24.jpg)\n\n## Related\n\n- [Aperture](https://github.com/wulkano/Aperture) - The Swift framework used in this package\n","funding_links":[],"categories":["HarmonyOS","Swift"],"sub_categories":["Windows Manager"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwulkano%2Faperture-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwulkano%2Faperture-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwulkano%2Faperture-node/lists"}