Skip to main content

desktopCapturer

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

进程：主进程

🌐 Process: Main

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

🌐 The following example shows how to capture video from a desktop window whose title is 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。

🌐 See navigator.mediaDevices.getDisplayMedia for more information.

note

navigator.mediaDevices.getDisplayMedia 不允许使用 deviceId 来选择来源 - 参见 规范。

方法​

🌐 Methods

desktopCapturer 模块具有以下方法：

🌐 The desktopCapturer module has the following methods:

desktopCapturer.getSources(options)​

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

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

🌐 Returns Promise<DesktopCapturerSource[]> - Resolves with an array of DesktopCapturerSource objects, each DesktopCapturerSource represents a screen or an individual window that can be captured.

[!注意]

  • 在 macOS 14.2 Sonoma 及更高版本中，捕获音频需要 NSAudioCaptureUsageDescription Info.plist 键 - 阅读更多。
  • 在 macOS 10.15 Catalina 及更高版本中，捕获屏幕内容需要用户同意，可以通过 systemPreferences.getMediaAccessStatus 检测。

注意事项​

🌐 Caveats

Linux​

desktopCapturer.getSources(options) 在使用 Pipewire 时在 Linux 上只返回一个源。

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.

MacOS 版本 14.2 或更高​

🌐 MacOS versions 14.2 or higher

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

这是为了方便 Chromium 使用 Apple 的新 CoreAudio Tap API。

🌐 This is in order to facillitate use of Apple's new CoreAudio Tap API by Chromium.

warning

desktopCapturer无法启动音频流，因为缺少NSAudioCaptureUsageDescription权限，仍然会创建一个无效音频流，但不会显示任何警告或错误。

从 Electron v39.0.0-beta.4 开始，Chromium 将苹果的新 CoreAudio Tap API 设置为桌面音频捕获的默认选项。即使 CoreAudio Tap API 流创建失败，也不会回退到旧的 Screen & System Audio Recording 权限系统。

🌐 As of electron v39.0.0-beta.4 Chromium made Apple's new CoreAudio Tap API the default for desktop audio capture. There is no fallback to the older Screen & System Audio Recording permissions system even if CoreAudio Tap API stream creation fails.

如果你需要在 macOS 14.2 及更高版本上继续对 desktopCapturer 使用 Screen & System Audio Recording 权限，你可以应用 Chromium 功能标志来强制使用较旧的权限系统：

🌐 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:

// main.js (right beneath your require/import statments)
app.commandLine.appendSwitch('disable-features', 'MacCatapLoopbackAudioForScreenShare')

MacOS 版本 12.7.6 或更低​

🌐 MacOS versions 12.7.6 or lower

navigator.mediaDevices.getUserMedia 在 macOS 12.7.6 及更早版本中无法进行音频捕获，这是由于一个根本性限制：想要访问系统音频的应用需要一个签名内核扩展。Chromium，以及由此衍生的 Electron，并未提供此功能。只有在 macOS 13 及更高版本中，苹果才提供无需签名内核扩展即可捕获桌面音频的 API。

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

🌐 It is possible to circumvent this limitation by capturing system audio with another macOS app like BlackHole or Soundflower and passing it through a virtual audio input device. This virtual device can then be queried with navigator.mediaDevices.getUserMedia.