desktopCapturer¶

使用 [navigator.mediaDevices.getUserMedia][] API 访问可用于从桌面捕获音频和视频的媒体源信息。

进程：主进程

以下示例展示了如何捕获标题为 Electron 的桌面窗口的视频：

// main.js
const { app, BrowserWindow, desktopCapturer, session } = require('electron')

app.whenReady().then(() => {
  const mainWindow = new BrowserWindow()

  session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
    desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
      // Grant access to the first screen found.
      callback({ video: sources[0], audio: 'loopback' })
    })
    // If true, use the system picker if available.
    // Note: this is currently experimental. If the system picker
    // is available, it will be used and the media request handler
    // will not be invoked.
  }, { useSystemPicker: true })

  mainWindow.loadFile('index.html')
})

// renderer.js
const startButton = document.getElementById('startButton')
const stopButton = document.getElementById('stopButton')
const video = document.querySelector('video')

startButton.addEventListener('click', () => {
  navigator.mediaDevices.getDisplayMedia({
    audio: true,
    video: {
      width: 320,
      height: 240,
      frameRate: 30
    }
  }).then(stream => {
    video.srcObject = stream
    video.onloadedmetadata = (e) => video.play()
  }).catch(e => console.log(e))
})

stopButton.addEventListener('click', () => {
  video.pause()
})

<!-- index.html -->
<html>
<meta http-equiv="content-security-policy" content="script-src 'self' 'unsafe-inline'" />
  <body>
    <button id="startButton" class="button">Start</button>
    <button id="stopButton" class="button">Stop</button>
    <video width="320" height="240" autoplay></video>
    <script src="renderer.js"></script>
  </body>
</html>

有关更多信息，请参阅 navigator.mediaDevices.getDisplayMedia。

[!NOTE] navigator.mediaDevices.getDisplayMedia 不允许使用 deviceId 来选择源 - 请参阅 规范。

方法¶

desktopCapturer 模块具有以下方法：

desktopCapturer.getSources(options)¶

• options Object
• types string[] - 一个字符串数组，列出要捕获的桌面源类型，可用类型可以是 screen 和 window。
• thumbnailSize Size（可选）- 媒体源缩略图应缩放到的尺寸。默认值为 150 x 150。当不需要缩略图时，将宽度或高度设置为 0。这将节省捕获每个窗口和屏幕内容所需的处理时间。
• fetchWindowIcons boolean（可选）- 设置为 true 以启用获取窗口图标。默认值为 false。当为 false 时，源的 appIcon 属性返回 null。如果源的类型为 screen，则同样如此。

返回 Promise<DesktopCapturerSource[]> - 解析为一个 DesktopCapturerSource 对象数组，每个 DesktopCapturerSource 表示一个可捕获的屏幕或单个窗口。

[!NOTE]

• 捕获音频需要在 macOS 14.2 Sonoma 及更高版本上提供 NSAudioCaptureUsageDescription Info.plist 键 - 阅读更多。
• 在 macOS 10.15 Catalina 或更高版本上捕获屏幕内容需要用户授权，可以通过 [systemPreferences.getMediaAccessStatus][] 检测。

注意事项¶

Linux¶

在 Linux 上使用 Pipewire 时，desktopCapturer.getSources(options) 仅返回单个源。

PipeWire 对屏幕和窗口均支持单个捕获。如果你请求 window 和 screen 类型，所选源将作为窗口捕获返回。

macOS 14.2 或更高版本¶

必须添加 NSAudioCaptureUsageDescription Info.plist 键，desktopCapturer 才能捕获音频。如果你是从终端或 IDE 等其他程序运行 Electron，则父程序必须包含该 Info.plist 键。

这是为了便于 Chromium 使用 Apple 的 CoreAudio Tap API，该 API 受“System Audio Recording”隐私权限控制。macOS 会将该权限归属于负责进程，因此当从终端或 IDE 以未打包方式运行时，必须授予终端或 IDE 访问权限。

[!WARNING] 如果缺少该权限或已被拒绝，desktopCapturer 仍会生成音频轨道，但该轨道以 ended 状态创建，并且永远不会提供采样。JavaScript 不会收到任何警告或错误。

自 Electron 39 起，Chromium 在 macOS 14.2 及更高版本上默认 使用 CoreAudio Tap API 进行系统音频捕获。如果 tap 创建失败，不会自动回退到基于 ScreenCaptureKit 的旧版“Screen & System Audio Recording”路径；并且自 Electron 45 起，之前允许重新启用该路径的 MacCatapLoopbackAudioForScreenShare 功能标志已在上游 移除，不再有任何效果。

macOS 版本 12.7.6 或更低¶

navigator.mediaDevices.getUserMedia 在 macOS 12.7.6 及更早版本上无法用于音频捕获，这是由于一项根本性限制：想要访问系统音频的应用程序需要一个已签名的内核扩展。Chromium，以及由此延伸的 Electron，并不提供此功能。只有在 macOS 13 及更高版本中，Apple 才提供了无需已签名内核扩展即可捕获桌面音频的 API。

可以通过使用另一个 macOS 应用（如 BlackHole 或 Soundflower）捕获系统音频，并通过虚拟音频输入设备传递，来绕过此限制。然后可以使用 navigator.mediaDevices.getUserMedia 查询该虚拟设备。