2015-12-08 13:09:36 +08:00
# desktopCapturer
2015-10-04 09:35:00 +08:00
2016-07-25 17:49:25 +07:00
> Access information about media sources that can be used to capture audio and
2023-01-16 01:22:49 -08:00
> video from the desktop using the [`navigator.mediaDevices.getUserMedia`][] API.
2016-07-25 17:49:25 +07:00
2021-10-03 20:16:00 -07:00
Process: [Main ](../glossary.md#main-process )
2016-11-01 16:35:31 -07:00
2016-07-25 17:49:25 +07:00
The following example shows how to capture video from a desktop window whose
title is `Electron` :
2015-10-04 09:35:00 +08:00
2023-11-20 23:50:08 -08:00
```js
2024-07-23 11:55:23 +02:00
// main.js
const { app, BrowserWindow, desktopCapturer, session } = require('electron')
2023-06-05 15:26:26 +08:00
2024-07-23 11:55:23 +02:00
app.whenReady().then(() => {
const mainWindow = new BrowserWindow()
2015-10-04 09:35:00 +08:00
2024-07-23 11:55:23 +02:00
session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
// Grant access to the first screen found.
callback({ video: sources[0], audio: 'loopback' })
})
2024-09-10 16:05:57 -07:00
// 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 })
2024-07-23 11:55:23 +02:00
mainWindow.loadFile('index.html')
2016-07-25 18:39:25 -07:00
})
2021-10-03 20:16:00 -07:00
```
2024-07-23 11:55:23 +02:00
```js
// 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))
2021-10-03 20:16:00 -07:00
})
2015-10-04 09:35:00 +08:00
2024-07-23 11:55:23 +02:00
stopButton.addEventListener('click', () => {
video.pause()
})
2015-10-04 09:35:00 +08:00
```
2024-07-23 11:55:23 +02:00
```html
<!-- 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 >
```
2015-12-15 14:07:55 -08:00
2024-07-23 11:55:23 +02:00
See [`navigator.mediaDevices.getDisplayMedia` ](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia ) for more information.
2017-05-15 13:42:47 -05:00
2025-05-09 17:46:11 -05:00
> [!NOTE]
> `navigator.mediaDevices.getDisplayMedia` does not permit the use of `deviceId` for
> selection of a source - see [specification](https://w3c.github.io/mediacapture-screen-share/#constraints).
2015-12-15 14:07:55 -08:00
2015-10-06 14:34:54 +08:00
## Methods
2015-10-04 09:35:00 +08:00
2015-10-06 14:34:54 +08:00
The `desktopCapturer` module has the following methods:
2015-10-04 09:35:00 +08:00
2019-01-18 15:29:32 -08:00
### `desktopCapturer.getSources(options)`
* `options` Object
2021-11-16 05:13:18 +01:00
* `types` string[] - An array of strings that lists the types of desktop sources
2023-07-31 16:32:59 +08:00
to be captured, available types can be `screen` and `window` .
2019-01-18 15:29:32 -08:00
* `thumbnailSize` [Size ](structures/size.md ) (optional) - The size that the media source thumbnail
2019-02-13 10:27:42 -08:00
should be scaled to. Default is `150` x `150` . Set width or height to 0 when you do not need
the thumbnails. This will save the processing time required for capturing the content of each
window and screen.
2021-11-16 05:13:18 +01:00
* `fetchWindowIcons` boolean (optional) - Set to true to enable fetching window icons. The default
2019-01-18 15:29:32 -08:00
value is false. When false the appIcon property of the sources return null. Same if a source has
the type screen.
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.
2025-05-09 17:46:11 -05:00
> [!NOTE]
> Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher,
> which can detected by [`systemPreferences.getMediaAccessStatus`][].
2019-11-13 22:47:51 +01:00
2019-01-18 15:29:32 -08:00
[`navigator.mediaDevices.getUserMedia` ]: https://developer.mozilla.org/en/docs/Web/API/MediaDevices/getUserMedia
2020-10-19 18:46:27 -07:00
[`systemPreferences.getMediaAccessStatus` ]: system-preferences.md#systempreferencesgetmediaaccessstatusmediatype -windows-macos
2019-04-16 10:49:31 -07:00
2019-05-06 08:29:01 -07:00
## Caveats
2019-04-16 10:49:31 -07:00
`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` .
