Saltar al contenido principal

desktopCapturer

Access information about media sources that can be used to capture audio and video from the desktop using the navigator.mediaDevices.getUserMedia API.

Proceso: principal

En el siguiente ejemplo se muestra cómo capturar vídeo desde una ventana de escritorio cuyo título es 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' })
        },
        () => {
          // Deny the request if no sources could be retrieved, for example
          // when the user cancels the PipeWire picker on Linux.
          callback(null)
        }
      )
      // 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>

See navigator.mediaDevices.getDisplayMedia for more information.

Nota

navigator.mediaDevices.getDisplayMedia does not permit the use of deviceId for selection of a source - see specification.

Métodos​

El módulo desktopCapturer tiene los siguientes métodos:

desktopCapturer.getSources(options)​

History
  • options Object
    • types string[] - An array of strings that lists the types of desktop sources to be captured, available types can be screen and window.
    • thumbnailSize Size (optional) - The size that the media source thumbnail should be scaled to. Por defecto es 150 x 150. Establecer ancho o alto a 0 cuando no necesitas las miniaturas. Esto guardara el tiempo de procesamiento requerido para capturar el contenido de cada ventana y pantalla.
    • fetchWindowIcons boolean (optional) - Set to true to enable fetching window icons. El valor por defecto es falso. Cuando es false la propiedad appIcon de las fuentes devuelve null. Mismo si una fuente tiene el tipo pantalla.

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

Nota
  • Capturing audio requires NSAudioCaptureUsageDescription Info.plist key on macOS 14.2 Sonoma and higher - read more. * Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, which can detected by systemPreferences.getMediaAccessStatus.

Advertencias​

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.

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 facilitate use of Apple's CoreAudio Tap API by Chromium, which is gated behind the "System Audio Recording" privacy permission. macOS attributes that permission to the responsible process, so when running unpackaged from a terminal or IDE it is the terminal or IDE that must be granted access.

[!WARNING] If the permission is missing or has been denied, desktopCapturer still produces an audio track, but it is created in the ended state and never delivers samples. No warning or error is surfaced to JavaScript.

Since Electron 39, Chromium uses the CoreAudio Tap API by default for system audio capture on macOS 14.2 and later. There is no automatic fallback to the older ScreenCaptureKit-based "Screen & System Audio Recording" path if tap creation fails, and as of Electron 45 the MacCatapLoopbackAudioForScreenShare feature flag that previously allowed opting back into it has been removed upstream and no longer has any effect.

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. Chromium, y por extensión Electron, no proporciona esto. 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 or Soundflower and passing it through a virtual audio input device. This virtual device can then be queried with navigator.mediaDevices.getUserMedia.