Repository: electron/electron
Pull request: fix: address upstream Chromium shift to enable `CoreAudio Tap API` for audio capture used in electron's `desktopCapturer` (🍏 macOS). 

#### Description of Change

Refs https://github.com/electron/electron/issues/49607

1. This PR adds the `NSAudioCaptureUsageDescription` Info.plist key required for electron apps to use `desktopCapturer`. The key enables Apple's newer `CoreAudio Tap API` which is the new goto for chromium's plumbing responsible for `desktopCapturer` https://github.com/electron/electron/pull/49717/changes/1e3df011b50278a125a0a5efb38f4a73fced5d4a

2. Updates documentation for `desktopCapturer` page to bring it up to date with macOS developments. Page has been out of date since macOS 13 when Apple introduced methods for audio-capture w/o a signed kernel extension. https://github.com/electron/electron/pull/49717/changes/bc35ff5f560df3569a224e92a02fa9267299e5d3

3. Retro-actively adds a breaking change to the `V39.0.0 Breaking Changes` section. Breaking change is related to chromium's use of native Apple APIs used in audio capture. https://github.com/electron/electron/pull/49717/changes/bc35ff5f560df3569a224e92a02fa9267299e5d3

4. Minor lint fix that was tripping up pre-commit hook when I went to add aforementioned docs changes. https://github.com/electron/electron/pull/49717/changes/bc35ff5f560df3569a224e92a02fa9267299e5d3

####  🍎 : [CoreAudio Tap API Reference](https://github.com/insidegui/AudioCap) 

The new plist key is a required permission to use electron's `desktopCapturer` properly on macOS >= 14.2 && electron >= 39.0.0-beta4.

---

#### Additional Context

Apple quietly released a new API for doing native audio-capture and then didn't communicate well down-stream that a new `Info.plist` permission `NSAudioCaptureUsageDescription` is required.

Hope inclusion of config added in this PR can aid in downstream adoption and awareness of the new permission 🤝

In the Chromium version jump for `v39.0.0-beta.4` they [make the new native Apple audio API the default](https://source.chromium.org/chromium/chromium/src/+/ad17e8f8b93d5f34891b06085d373a668918255e). So `desktopCapturer` abruptly stops working without the new plist entry in that version and higher. This is b/c chromium has effectively retired the old native API which didn't have plist key reqs. No fallback to the old system exists if the new system fails.

Related Website PR : https://github.com/electron/website/pull/1010

<!--
Thank you for your Pull Request. Please provide a description above and review
the requirements below.

Contributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md
-->

#### Checklist
<!-- Remove items that do not apply. For completed items, change [ ] to [x]. -->

- [x] PR description included
- [x] I have built and tested this PR
- [x] `npm test` passes
- [x] [PR release notes](https://github.com/electron/clerk/blob/main/README.md) describe the change in a way relevant to app developers, and are [capitalized, punctuated, and past tense](https://github.com/electron/clerk/blob/main/README.md#examples).

#### Release Notes

Notes: Addressed upstream Chromium shift to enable `CoreAudio Tap API` for audio capture used in electron's `desktopCapturer` (🍏 macOS). 

Changed files:
filename: docs/api/desktop-capturer.md
patch: @@ -94,18 +94,45 @@ The `desktopCapturer` module has the following methods:
 Returns `Promise<DesktopCapturerSource[]>` - 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.
+---
+
+### 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 Soundflower and passing it through a virtual audio input device. This virtual device can then be queried with `navigator.mediaDevices.getUserMedia`.
+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`.

filename: docs/breaking-changes.md
patch: @@ -76,6 +76,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.

filename: docs/tutorial/menus.md
patch: @@ -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

filename: shell/browser/resources/mac/Info.plist
patch: @@ -50,6 +50,8 @@
     <string>This app needs access to the microphone</string>
     <key>NSCameraUsageDescription</key>
     <string>This app needs access to the camera</string>
+    <key>NSAudioCaptureUsageDescription</key>
+    <string>This app needs access to audio capture</string>
     <key>NSBluetoothAlwaysUsageDescription</key>
     <string>This app needs access to Bluetooth</string>
     <key>NSBluetoothPeripheralUsageDescription</key>