node-mac-recorder 2.20.17 → 2.21.0

package/AUDIO_CAPTURE.md

@@ -0,0 +1,84 @@
+# Audio Capture Guide
+
+This guide explains how to record microphone and/or system audio alongside the silent screen recording output.
+
+## 1. Enumerate audio devices
+
+```js
+const recorder = new MacRecorder();
+const devices = await recorder.getAudioDevices();
+/*
+[
+  {
+    id: "BuiltInMicDeviceID",
+    name: "MacBook Pro Microphone",
+    manufacturer: "Apple Inc.",
+    isDefault: true,
+    transportType: 0
+  },
+  ...
+]
+*/
+```
+
+Pick the `id` you want to capture. For system audio you typically need to select a loopback device (e.g. BlackHole, Loopback, VB-Cable).
+
+## 2. Configure the capture
+
+```js
+recorder.setAudioSettings({
+  microphone: true,
+  systemAudio: true,
+});
+
+recorder.setSystemAudioDevice("LoopbackDeviceID"); // optional
+recorder.setAudioDevice("BuiltInMicDeviceID");     // microphone device – use setOptions or setAudioSettings
+```
+
+If you only want system audio, disable the microphone flag. When both flags are true on macOS 15+, ScreenCaptureKit mixes the feeds automatically. On older macOS versions (where the module falls back to AVFoundation) you should provide a loopback device that already mixes both sources.
+
+## 3. Start recording
+
+```js
+await recorder.startRecording("./output.mov", {
+  includeMicrophone: true,
+  includeSystemAudio: true,
+  systemAudioDeviceId: "LoopbackDeviceID",
+  audioDeviceId: "BuiltInMicDeviceID",
+});
+```
+
+The recorder automatically creates `temp_audio_<timestamp>.webm` next to the main video file. The timestamp matches the cursor and camera companion files so you can synchronise them later.
+
+### File format fallback
+
+- macOS 15+ → Opus audio inside a WebM container.  
+- macOS 13–14 → Apple does not expose a WebM audio writer, so the clip is stored in a QuickTime container while keeping the `.webm` extension (transcode if you require a strict WebM file).
+
+## 4. Stop recording
+
+```js
+const result = await recorder.stopRecording();
+console.log(result.audioOutputPath); // temp_audio_<timestamp>.webm
+```
+
+The `audioCaptureStarted` / `audioCaptureStopped` events fire with the resolved path and shared session timestamp, letting you update your Electron UI instantly.
+
+## 5. Status helpers
+
+```js
+const status = recorder.getAudioCaptureStatus();
+// {
+//   isCapturing: true,
+//   outputFile: "/tmp/temp_audio_1720000000000.webm",
+//   deviceIds: { microphone: "...", system: "..." },
+//   includeMicrophone: true,
+//   includeSystemAudio: true,
+//   sessionTimestamp: 1720000000000
+// }
+```
+
+## 6. Limitations
+
+- On macOS versions that fall back to AVFoundation (13/14), system audio capture requires a virtual loopback device. The module records whichever device you select as `systemAudioDeviceId`.
+- ScreenCaptureKit automatically mixes microphone + system audio when both flags are enabled. If you need isolated stems, run separate recordings with different device selections.

package/CAMERA_CAPTURE.md

@@ -0,0 +1,77 @@
+# Camera Capture Guide
+
+This guide shows how to capture an external or built‑in camera feed alongside the standard screen recording workflow.
+
+## 1. Discover available cameras
+
+Use the new helper to list all video-capable devices. Each entry includes the best resolution Apple reports for that device.
+
+```js
+const cameras = await recorder.getCameraDevices();
+/* Example entry:
+{
+  id: "BuiltInCameraID",
+  name: "FaceTime HD Camera",
+  position: "front",
+  maxResolution: { width: 1920, height: 1080, maxFrameRate: 60 }
+}
+*/
+```
+
+Pick an `id` and store it for future sessions (it is stable across restarts).
+
+## 2. Enable camera capture
+
+```js
+recorder.setCameraDevice(selectedCameraId); // optional – default camera is used otherwise
+recorder.setCameraEnabled(true);
+```
+
+Camera recording is completely independent from system audio and microphone settings; only video frames are captured.
+
+The companion file is always silent—no audio tracks are written.
+
+## 3. Start recording
+
+When you call `startRecording`, the module automatically creates a file named `temp_camera_<timestamp>.webm` next to the main screen recording output:
+
+```js
+await recorder.startRecording("/tmp/output.mov", {
+  includeSystemAudio: true,
+  captureCamera: true,          // shorthand for enabling camera inside options
+  cameraDeviceId: selectedCameraId,
+});
+```
+
+Internally this mirrors the cursor workflow: the camera file is placed in the same directory as `/tmp/output.mov`, sharing the same timestamp that the cursor JSON uses. No extra cleanup is required.
+
+### File format fallback
+
+- macOS 15+ → VP9 video inside a real WebM container.  
+- macOS 13–14 → Apple does not expose a WebM writer, so the clip is stored in a QuickTime container even though the filename remains `.webm`. Transcode to another format if you need a strict WebM file.
+
+The `cameraCaptureStarted` and `cameraCaptureStopped` events include the resolved path and the shared `sessionTimestamp` so the UI can react immediately.
+
+## 4. Stop recording
+
+`stopRecording()` stops the screen capture and the camera recorder together:
+
+```js
+const result = await recorder.stopRecording();
+console.log(result.outputPath);        // screen video
+console.log(result.cameraOutputPath);  // companion camera clip (or null if disabled)
+```
+
+## 5. Integrating with Electron live previews
+
+Use the same `cameraDeviceId` with `navigator.mediaDevices.getUserMedia({ video: { deviceId } })` to show a live preview while the native module records in the background. The native pipeline does not consume the camera stream, so sharing the device with Electron is supported as long as the hardware allows concurrent access.
+
+## 6. API quick reference
+
+- `getCameraDevices()`  
+- `setCameraEnabled(enabled)` / `isCameraEnabled()`  
+- `setCameraDevice(deviceId)`  
+- `getCameraCaptureStatus()` – returns `{ isCapturing, outputFile, deviceId, sessionTimestamp }`  
+- Events: `cameraCaptureStarted`, `cameraCaptureStopped`
+
+With these helpers you can drive the camera UI inside an Electron app while preserving the high-resolution screen capture handled by ScreenCaptureKit or AVFoundation.

package/MACOS_PERMISSIONS.md

@@ -0,0 +1,56 @@
+# macOS Permission Checklist
+
+This project relies on system-level frameworks (ScreenCaptureKit, AVFoundation) that require explicit permissions. When integrating the native module into an app (Electron, standalone macOS app, etc.), make sure the host application's `Info.plist` defines the usage descriptions below.
+
+## Required `Info.plist` keys
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Allow camera access for screen recording companion video.</string>
+
+<key>NSMicrophoneUsageDescription</key>
+<string>Allow microphone access for audio capture.</string>
+
+<key>NSCameraUseContinuityCameraDeviceType</key>
+<true/>
+
+<key>com.apple.security.device.audio-input</key>
+<true/>
+
+<key>com.apple.security.device.camera</key>
+<true/>
+```
+
+> `NSCameraUseContinuityCameraDeviceType` removes the runtime warning when Continuity Camera devices are detected. macOS 14+ expects this key whenever Continuity Camera APIs are used.
+> The `com.apple.security.*` entitlements are only required for sandboxed / hardened runtime builds. Omit them if your distribution does not use the macOS sandbox.
+
+### Screen recording
+
+Screen recording permissions are granted by the user via the OS **Screen Recording** privacy panel. There is no `Info.plist` key to request it, but your app should guide the user to approve it.
+
+## Electron apps
+
+Add the keys above to `Info.plist` (located under `electron-builder` config or the generated app bundle). For example, with `electron-builder`, use the `mac.plist` option:
+
+```jsonc
+// package.json
+{
+  "build": {
+    "mac": {
+      "extendInfo": {
+        "NSCameraUsageDescription": "Allow camera access...",
+        "NSMicrophoneUsageDescription": "Allow microphone access...",
+        "NSCameraUseContinuityCameraDeviceType": true,
+        "com.apple.security.device.audio-input": true,
+        "com.apple.security.device.camera": true
+      }
+    }
+  }
+}
+```
+
+## Native permission prompts
+
+The module proactively requests camera and microphone permissions when recording starts (`AVCaptureDevice requestAccess`). If access is denied, the native start call fails with an explanatory error.
+
+Make sure to run your app once, respond to the permission prompts, and instruct testers to do the same.

package/README.md

@@ -14,6 +14,8 @@ A powerful native macOS screen recording Node.js package with advanced window se
 - 🖱️ **Multi-Display Support** - Automatic display detection and selection
 - 🎨 **Cursor Control** - Toggle cursor visibility in recordings
 - 🖱️ **Cursor Tracking** - Track mouse position, cursor types, and click events
+- 📷 **Camera Recording** - Capture silent camera video alongside screen recordings
+- 🔊 **Audio Capture** - Record microphone/system audio into synchronized companion files
 - 🚫 **Automatic Overlay Exclusion** - Overlay windows automatically excluded from recordings
 - ⚡ **Electron Compatible** - Enhanced crash protection for Electron applications
 
@@ -39,6 +41,8 @@ A powerful native macOS screen recording Node.js package with advanced window se
 - 📁 **Flexible Output** - Custom output paths and formats
 - 🔐 **Permission Management** - Built-in permission checking
 
+> **Note**: The screen recording container remains silent. Audio is saved separately as `temp_audio_<timestamp>.webm` so you can remix microphone and system sound in post-processing.
+
 ## ScreenCaptureKit Technology
 
 This package leverages Apple's modern **ScreenCaptureKit** framework (macOS 12.3+) for superior recording capabilities:
@@ -126,6 +130,10 @@ await recorder.startRecording("./recording.mov", {
 	quality: "high", // 'low', 'medium', 'high'
 	frameRate: 30, // FPS (15, 30, 60)
 	captureCursor: false, // Show cursor (default: false)
+
+	// Camera Capture
+	captureCamera: true, // Enable simultaneous camera recording (video-only WebM)
+	cameraDeviceId: "built-in-camera-id", // Use specific camera (optional)
 });
 ```
 
@@ -136,7 +144,11 @@ Stops the current recording.
 ```javascript
 const result = await recorder.stopRecording();
 console.log("Recording saved to:", result.outputPath);
+console.log("Camera clip saved to:", result.cameraOutputPath);
+console.log("Audio clip saved to:", result.audioOutputPath);
+console.log("Shared session timestamp:", result.sessionTimestamp);
 ```
+The result object always contains `cameraOutputPath` and `audioOutputPath`. If either feature is disabled the corresponding value is `null`. The shared `sessionTimestamp` matches every automatically generated temp file name (`temp_cursor_*`, `temp_camera_*`, and `temp_audio_*`).
 
 #### `getWindows()`
 
@@ -184,15 +196,70 @@ const devices = await recorder.getAudioDevices();
 console.log(devices);
 // [
 //   {
-//     id: "device-id",
-//     name: "Built-in Microphone",
+//     id: "BuiltInMicDeviceID",
+//     name: "MacBook Pro Microphone",
 //     manufacturer: "Apple Inc.",
-//     isDefault: true
+//     isDefault: true,
+//     transportType: 0
+//   },
+//   ...
+// ]
+```
+
+#### `getCameraDevices()`
+
+Lists available camera devices with resolution metadata.
+
+```javascript
+const cameras = await recorder.getCameraDevices();
+console.log(cameras);
+// [
+//   {
+//     id: "FaceTime HD Camera",
+//     name: "FaceTime HD Camera",
+//     position: "front",
+//     maxResolution: { width: 1920, height: 1080, maxFrameRate: 60 }
 //   },
 //   ...
 // ]
 ```
 
+### Camera Capture Helpers
+
+- `setCameraEnabled(enabled)` – toggles simultaneous camera recording (video-only)
+- `setCameraDevice(deviceId)` – selects the camera by unique macOS identifier
+- `isCameraEnabled()` – returns current camera toggle state
+- `getCameraCaptureStatus()` – returns `{ isCapturing, outputFile, deviceId, sessionTimestamp }`
+
+A typical workflow looks like this:
+
+```javascript
+const cameras = await recorder.getCameraDevices();
+const selectedCamera = cameras.find((camera) => camera.position === "front") || cameras[0];
+
+recorder.setCameraDevice(selectedCamera?.id);
+recorder.setCameraEnabled(true);
+
+await recorder.startRecording("./output.mov");
+// ...
+const status = recorder.getCameraCaptureStatus();
+console.log("Camera stream:", status.outputFile); // temp_camera_<timestamp>.webm
+await recorder.stopRecording();
+```
+
+> The camera clip is saved alongside the screen recording as `temp_camera_<timestamp>.webm`. The file contains video frames only (no audio). Use the same device IDs in Electron to power live previews (`navigator.mediaDevices.getUserMedia({ video: { deviceId } })`). On macOS versions prior to 15, Apple does not expose a WebM encoder; the module falls back to a QuickTime container while keeping the same filename, so transcode or rename if an actual WebM container is required.
+
+See `CAMERA_CAPTURE.md` for a deeper walkthrough and Electron integration tips.
+
+### Audio Capture Helpers
+
+- `setAudioDevice(deviceId)` – select the microphone input
+- `setSystemAudioEnabled(enabled)` / `isSystemAudioEnabled()`
+- `setSystemAudioDevice(deviceId)` – prefer loopback devices when you need system audio only
+- `getAudioCaptureStatus()` – returns `{ isCapturing, outputFile, deviceIds, includeMicrophone, includeSystemAudio, sessionTimestamp }`
+
+See `AUDIO_CAPTURE.md` for a step-by-step guide on enumerating devices, enabling microphone/system capture, and consuming the audio companion files.
+
 #### `checkPermissions()`
 
 Checks macOS recording permissions.
@@ -217,6 +284,11 @@ console.log(status);
 // {
 //   isRecording: true,
 //   outputPath: "./recording.mov",
+//   cameraOutputPath: "./temp_camera_1720000000000.webm",
+//   audioOutputPath: "./temp_audio_1720000000000.webm",
+//   cameraCapturing: true,
+//   audioCapturing: true,
+//   sessionTimestamp: 1720000000000,
 //   options: { ... },
 //   recordingTime: 15
 // }
@@ -800,3 +872,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 ---
 
 **Made for macOS** 🍎 | **Built with AVFoundation** 📹 | **Node.js Ready** 🚀
+> 🛡️ **Permissions:** Ensure your host application's `Info.plist` declares camera and microphone usage descriptions (see `MACOS_PERMISSIONS.md`).

package/binding.gyp

@@ -6,7 +6,8 @@
         "src/mac_recorder.mm",
         "src/screen_capture_kit.mm",
         "src/avfoundation_recorder.mm",
-        "src/audio_capture.mm",
+        "src/camera_recorder.mm",
+        "src/audio_recorder.mm",
         "src/cursor_tracker.mm",
         "src/window_selector.mm"
       ],
@@ -44,4 +45,4 @@
       "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ]
     }
   ]
-} 
+}