diff --git a/docs/api/desktop-capturer.md b/docs/api/desktop-capturer.md index 63f647c474..adcc0a0fbd 100644 --- a/docs/api/desktop-capturer.md +++ b/docs/api/desktop-capturer.md @@ -94,18 +94,45 @@ The `desktopCapturer` module has the following methods: Returns `Promise` - Resolves with an array of [`DesktopCapturerSource`](structures/desktop-capturer-source.md) objects, each `DesktopCapturerSource` represents a screen or an individual window that can be captured. > [!NOTE] -> Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, -> which can detected by [`systemPreferences.getMediaAccessStatus`][]. + +> * Capturing audio requires `NSAudioCaptureUsageDescription` Info.plist key on macOS 14.2 Sonoma and higher - [read more](#macos-versions-142-or-higher). +> * Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, which can detected by [`systemPreferences.getMediaAccessStatus`][]. [`navigator.mediaDevices.getUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/MediaDevices/getUserMedia [`systemPreferences.getMediaAccessStatus`]: system-preferences.md#systempreferencesgetmediaaccessstatusmediatype-windows-macos ## Caveats +### Linux + `desktopCapturer.getSources(options)` only returns a single source on Linux when using Pipewire. PipeWire supports a single capture for both screens and windows. If you request the window and screen type, the selected source will be returned as a window capture. -`navigator.mediaDevices.getUserMedia` does not work on macOS for audio capture due to a fundamental limitation whereby apps that want to access the system's audio require a [signed kernel extension](https://developer.apple.com/library/archive/documentation/Security/Conceptual/System_Integrity_Protection_Guide/KernelExtensions/KernelExtensions.html). Chromium, and by extension Electron, does not provide this. +--- -It is possible to circumvent this limitation by capturing system audio with another macOS app like Soundflower and passing it through a virtual audio input device. This virtual device can then be queried with `navigator.mediaDevices.getUserMedia`. +### MacOS versions 14.2 or higher + +`NSAudioCaptureUsageDescription` Info.plist key must be added in-order for audio to be captured by `desktopCapturer`. If instead you are running electron from another program like a terminal or IDE then that parent program must contain the Info.plist key. + +This is in order to facillitate use of Apple's new [CoreAudio Tap API](https://developer.apple.com/documentation/CoreAudio/capturing-system-audio-with-core-audio-taps#Configure-the-sample-code-project) by Chromium. + +> [!WARNING] +> Failure of `desktopCapturer` to start an audio stream due to `NSAudioCaptureUsageDescription` permission not present will still create a dead audio stream however no warnings or errors are displayed. + +As of electron `v39.0.0-beta.4` Chromium [made Apple's new `CoreAudio Tap API` the default](https://source.chromium.org/chromium/chromium/src/+/ad17e8f8b93d5f34891b06085d373a668918255e) for desktop audio capture. There is no fallback to the older `Screen & System Audio Recording` permissions system even if [CoreAudio Tap API](https://developer.apple.com/documentation/CoreAudio/capturing-system-audio-with-core-audio-taps) stream creation fails. + +If you need to continue using `Screen & System Audio Recording` permissions for `desktopCapturer` on macOS versions 14.2 and later, you can apply a chromium feature flag to force use of that older permissions system: + +```js +// main.js (right beneath your require/import statments) +app.commandLine.appendSwitch('disable-features', 'MacCatapLoopbackAudioForScreenShare') +``` + +--- + +### MacOS versions 12.7.6 or lower + +`navigator.mediaDevices.getUserMedia` does not work on macOS versions 12.7.6 and prior for audio capture due to a fundamental limitation whereby apps that want to access the system's audio require a [signed kernel extension](https://developer.apple.com/library/archive/documentation/Security/Conceptual/System_Integrity_Protection_Guide/KernelExtensions/KernelExtensions.html). Chromium, and by extension Electron, does not provide this. Only in macOS 13 and onwards does Apple provide APIs to capture desktop audio without the need for a signed kernel extension. + +It is possible to circumvent this limitation by capturing system audio with another macOS app like [BlackHole](https://existential.audio/blackhole/) or [Soundflower](https://rogueamoeba.com/freebies/soundflower/) and passing it through a virtual audio input device. This virtual device can then be queried with `navigator.mediaDevices.getUserMedia`. diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index 11980098d5..2afb9607c2 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -37,6 +37,22 @@ webContents.setWindowOpenHandler((details) => { }) ``` +### Behavior Changed: `NSAudioCaptureUsageDescription` should be included in your app's Info.plist file to use `desktopCapturer` (🍏 macOS ≥14.2) + +Per [Chromium update](https://source.chromium.org/chromium/chromium/src/+/ad17e8f8b93d5f34891b06085d373a668918255e) which enables Apple's newer [CoreAudio Tap API](https://developer.apple.com/documentation/CoreAudio/capturing-system-audio-with-core-audio-taps#Configure-the-sample-code-project) by default, you now must have `NSAudioCaptureUsageDescription` defined in your `Info.plist` to use `desktopCapturer`. + +Electron's `desktopCapturer` will create a dead audio stream if the new permission is absent however no errors or warnings will occur. This is partially a side-effect of Chromium not falling back to the older `Screen & System Audio Recording` permissions system if the new system fails. + +To restore previous behavior: + +```js +// main.js (right beneath your require/import statments) +app.commandLine.appendSwitch( + 'disable-features', + 'MacCatapLoopbackAudioForScreenShare' +) +``` + ### Behavior Changed: shared texture OSR `paint` event data structure When using shared texture offscreen rendering feature, the `paint` event now emits a more structured object. diff --git a/docs/tutorial/menus.md b/docs/tutorial/menus.md index 27d7e038fb..82567568cb 100644 --- a/docs/tutorial/menus.md +++ b/docs/tutorial/menus.md @@ -200,7 +200,7 @@ macOS has a number of platform-specific menu roles available. Many of these map * `recentDocuments` - The submenu is an "Open Recent" menu. * `clearRecentDocuments` - Map to the [`clearRecentDocuments`](https://developer.apple.com/documentation/appkit/nsdocumentcontroller/clearrecentdocuments(_:)) action. -* `shareMenu` - The submenu is [share menu][ShareMenu]. The `sharingItem` property must also be set to indicate the item to share. +* `shareMenu` - The submenu is [share menu](../api/share-menu.md). The `sharingItem` property must also be set to indicate the item to share. > [!IMPORTANT] > When specifying a `role` on macOS, `label` and `accelerator` are the only diff --git a/shell/browser/resources/mac/Info.plist b/shell/browser/resources/mac/Info.plist index 0ae99ab321..8039ff91df 100644 --- a/shell/browser/resources/mac/Info.plist +++ b/shell/browser/resources/mac/Info.plist @@ -50,6 +50,8 @@ This app needs access to the microphone NSCameraUsageDescription This app needs access to the camera + NSAudioCaptureUsageDescription + This app needs access to audio capture NSBluetoothAlwaysUsageDescription This app needs access to Bluetooth NSBluetoothPeripheralUsageDescription