app/methods

526 notes in this subject, read out of this brain and free to use. This is page 3 of 9.

crashReporter extra parameter limits

Parameters passed in extra, globalExtra, or set with addExtraParameter have length limits: key names must be at most 39 bytes long, and values must be no longer than 127 bytes. For addExtraParameter specifically, values must be no longer than 20320 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.

macOS 14.2+: NSAudioCaptureUsageDescription missing creates silent failure

When NSAudioCaptureUsageDescription permission is not present on macOS 14.2 or higher, desktopCapturer will fail to start an audio stream but will create a dead audio stream with no warnings or errors displayed.

desktopCapturer.getSources requires screen access permission on macOS 10.15+

Capturing screen contents requires user consent on macOS 10.15 (Catalina) or higher. This can be detected using systemPreferences.getMediaAccessStatus().

macOS 12.7.6 and prior: audio capture not supported

navigator.mediaDevices.getUserMedia does not work on macOS versions 12.7.6 and prior for audio capture due to a fundamental limitation requiring a signed kernel extension. Only macOS 13 and onwards provides APIs to capture desktop audio without requiring a signed kernel extension. Workaround: use virtual audio apps like BlackHole or Soundflower to capture system audio and pass through a virtual audio input device.

macOS 14.2+: Force old Screen & System Audio Recording permissions

To continue using the older Screen & System Audio Recording permissions system on macOS 14.2 and later instead of CoreAudio Tap API, add this code in main.js beneath require/import statements: app.commandLine.appendSwitch('disable-features', 'MacCatapLoopbackAudioForScreenShare')

macOS 14.2+: CoreAudio Tap API is default, no fallback available

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

macOS 14.2+: NSAudioCaptureUsageDescription required for audio capture

On macOS 14.2 (Sonoma) and higher, the NSAudioCaptureUsageDescription Info.plist key must be added for audio to be captured by desktopCapturer. If running Electron from another program like a terminal or IDE, that parent program must contain the Info.plist key. This is required to use Apple's CoreAudio Tap API via Chromium.

desktopCapturer Linux caveat: Pipewire single source

On Linux using Pipewire, desktopCapturer.getSources(options) only returns a single source for both screens and windows combined. If you request both 'window' and 'screen' types, the selected source will be returned as a window capture.

getDisplayMedia does not support deviceId constraint

navigator.mediaDevices.getDisplayMedia does not permit the use of deviceId for selection of a source, as specified in the W3C mediacapture-screen-share specification.

desktopCapturer example: renderer-side display media capture

Example showing renderer process code that uses navigator.mediaDevices.getDisplayMedia({ audio: true, video: { width: 320, height: 240, frameRate: 30 } }).then() to get a display media stream, then plays it in a video element with stream.play(). Includes error handling with .catch().

desktopCapturer example: desktop capture with system picker

Example showing how to set up desktop capture using desktopCapturer.getSources with session.defaultSession.setDisplayMediaRequestHandler. The handler receives the media request and a callback, calls getSources({ types: ['screen'] }), and grants access via callback({ video: sources[0], audio: 'loopback' }). The { useSystemPicker: true } option enables the system picker if available (currently experimental).

desktopCapturer.getSources method signature

desktopCapturer.getSources(options) returns Promise<DesktopCapturerSource[]>. The options parameter is an Object with the following properties: types (required, string[] with values 'screen' or 'window'), thumbnailSize (optional, Size object with default 150x150, set width or height to 0 to skip thumbnails), and fetchWindowIcons (optional, boolean, default false, when false the appIcon property returns null for all sources).

downloadItem.pause() method

Pauses the download.

downloadItem.getETag() method

Returns a string representing the ETag header value. This method is useful specifically to resume a cancelled item when the session is restarted.

downloadItem.getMimeType() method

Returns a string representing the file's MIME type.

downloadItem.getCurrentBytesPerSecond() method

Returns an integer representing the current download speed in bytes per second.

downloadItem.getFilename() method

Returns a string representing the file name of the download item. The file name is not always the same as the actual one saved on the local disk. If the user changes the file name in a prompted download saving dialog, the actual name of the saved file will be different.

downloadItem.getURLChain() method

Returns a string array representing the complete URL chain of the item, including any redirects. This method is useful specifically to resume a cancelled item when the session is restarted.

downloadItem.getState() method

Returns a string representing the current state. Can be 'progressing', 'completed', 'cancelled', or 'interrupted'.

downloadItem.getContentDisposition() method

Returns a string representing the Content-Disposition field from the response header.

downloadItem.getPercentComplete() method

Returns an integer representing the download completion as a percentage.

downloadItem.getURL() method

Returns a string representing the origin URL where the item is downloaded from.

DownloadItem example usage

// In the main process. const { BrowserWindow } = require('electron') const win = new BrowserWindow() win.webContents.session.on('will-download', (event, item, webContents) => { // Set the save path, making Electron not to prompt a save dialog. item.setSavePath('/tmp/save.pdf') item.on('updated', (event, state) => { if (state === 'interrupted') { console.log('Download is interrupted but can be resumed') } else if (state === 'progressing') { if (item.isPaused()) { console.log('Download is paused') } else { console.log(`Received bytes: ${item.getReceivedBytes()}`) } } }) item.once('done', (event, state) => { if (state === 'completed') { console.log('Download successfully') } else { console.log(`Download failed: ${state}`) } }) })

downloadItem.getEndTime() method

Returns a double representing the number of seconds since the UNIX epoch when the download ended.

downloadItem.getReceivedBytes() method

Returns an integer representing the received bytes of the download item.

downloadItem.getLastModifiedTime() method

Returns a string representing the Last-Modified header value. This method is useful specifically to resume a cancelled item when the session is restarted.

downloadItem.getSaveDialogOptions() method

Returns a SaveDialogOptions object that was previously set by downloadItem.setSaveDialogOptions(options).

downloadItem.setSaveDialogOptions(options) method

Sets the save file dialog options for the download item. The options parameter is a SaveDialogOptions object with the same properties as the options parameter of dialog.showSaveDialog(). This API allows the user to set custom options for the save dialog that opens for the download item by default. The API is only available in the session's 'will-download' callback function.

downloadItem.getSavePath() method

Returns a string representing the save path of the download item. This will be either the path set via downloadItem.setSavePath(path) or the path selected from the shown save dialog.

downloadItem.setSavePath(path) method

Sets the save file path of the download item. The path parameter is a string. This API is only available in the session's 'will-download' callback function. If the path does not exist, Electron will try to make the directory recursively. If the user doesn't set the save path via this API, Electron will use the original routine to determine the save path, which usually prompts a save dialog.

downloadItem.cancel() method

Cancels the download operation.

downloadItem.getTotalBytes() method

Returns an integer representing the total size in bytes of the download item. If the size is unknown, it returns 0.

downloadItem.canResume() method

Returns a boolean indicating whether the download can resume.

downloadItem.resume() method

Resumes the download that has been paused. To enable resumable downloads, the server being downloaded from must support range requests and provide both Last-Modified and ETag header values. Otherwise, resume() will dismiss previously received bytes and restart the download from the beginning.

downloadItem.isPaused() method

Returns a boolean indicating whether the download is paused.

downloadItem.hasUserGesture() method

Returns a boolean indicating whether the download has user gesture.

dialog sheets on macOS

On macOS, dialogs are presented as sheets attached to a window if a BaseWindow reference is provided in the window parameter, or modals if no window is provided. You can call BaseWindow.getCurrentWindow().setSheetOffset(offset) to change the offset from the window frame where sheets are attached.

dialog window argument behavior

The window argument in dialog methods allows the dialog to attach itself to a parent window, making it modal. If window is not shown, the dialog will not be attached to it and will be displayed as an independent window.

dialog.showCertificateTrustDialog Windows behavior

On Windows, the options for dialog.showCertificateTrustDialog are more limited due to Win32 APIs used. The message argument is not used, as the OS provides its own confirmation dialog. The window argument is ignored since it is not possible to make this confirmation dialog modal.

dialog.showCertificateTrustDialog macOS behavior

On macOS, dialog.showCertificateTrustDialog displays a modal dialog that shows a message and certificate information, and gives the user the option of trusting/importing the certificate. If a window argument is provided, the dialog will be attached to the parent window, making it modal.

dialog.showCertificateTrustDialog options

dialog.showCertificateTrustDialog accepts an options object with: certificate (Certificate, required - The certificate to trust/import) and message (string, required - The message to display to the user).

dialog.showCertificateTrustDialog signature and return

dialog.showCertificateTrustDialog([window, ]options) returns Promise<void> that resolves when the certificate trust dialog is shown.

dialog.showCertificateTrustDialog platform support

dialog.showCertificateTrustDialog is available on macOS and Windows.

dialog.showErrorBox signature

dialog.showErrorBox(title, content) displays a modal dialog that shows an error message. title is a string for the title to display in the error box. content is a string for the text content to display in the error box.

dialog.showMessageBox options

dialog.showMessageBox accepts an options object with: message (string, required - Content of the message box), type (string, optional - Can be 'none', 'info', 'error', 'question' or 'warning'. On Windows, 'question' displays same icon as 'info' unless icon option is set. On macOS, 'warning' and 'error' display same warning icon.), buttons (string[], optional - Array of texts for buttons. On Windows, empty array results in one button labeled 'OK'.), defaultId (Integer, optional - Index of button in buttons array selected by default when message box opens), signal (AbortSignal, optional - Pass AbortSignal instance to optionally close message box, behaves as if cancelled by user; on macOS does not work with message boxes without parent window due to platform limitations), title (string, optional - Title of the message box, some platforms will not show it), detail (string, optional - Extra information of the message), checkboxLabel (string, optional - If provided, message box includes checkbox with given label), checkboxChecked (boolean, optional, defaults to false - Initial checked state of checkbox), icon (NativeImage | string, optional), textWidth (Integer, optional, macOS only - Custom width of text in message box), cancelId (Integer, optional - Index of button to be used to cancel dialog via Esc key; defaults to first button with 'cancel' or 'no' label; if none exists and not set, 0 used as return value), noLink (boolean, optional - On Windows, Electron tries to determine common buttons and show others as command links; set to true to disable this behavior), normalizeAccessKeys (boolean, optional, defaults to false - Normalize keyboard access keys across platforms using & in button labels; & removed on macOS, converted to _ on Linux, unchanged on Windows).

dialog.showMessageBox signature and return

dialog.showMessageBox([window, ]options) returns Promise<Object> with response (number - index of clicked button) and checkboxChecked (boolean - checked state of checkbox if checkboxLabel was set, otherwise false).

dialog.showMessageBoxSync signature and return

dialog.showMessageBoxSync([window, ]options) returns Integer, the index of the clicked button. It blocks the process until the message box is closed.

dialog.showSaveDialog macOS async recommendation

On macOS, using the asynchronous version of showSaveDialog is recommended to avoid issues when expanding and collapsing the dialog.

dialog.showSaveDialog options

dialog.showSaveDialog accepts an options object with: title (string, optional - The dialog title, cannot be displayed on some Linux desktop environments), defaultPath (string, optional - Absolute directory path, absolute file path, or file name to use by default. If not provided, defaults to user's Downloads folder, or home directory if Downloads doesn't exist.), buttonLabel (string, optional - Custom label for confirmation button, default used if empty), filters (FileFilter[], optional), message (string, optional, macOS only - Message to display above text fields), nameFieldLabel (string, optional, macOS only - Custom label for text displayed in front of filename text field), showsTagField (boolean, optional, macOS only, defaults to true - Show the tags input box), properties (string[], optional - showHiddenFiles (macOS Windows), createDirectory (macOS), treatPackageAsDirectory (macOS), showOverwriteConfirmation (Linux), dontAddToRecent (Windows)), securityScopedBookmarks (boolean, optional, macOS mas only - Create security scoped bookmark when packaged for Mac App Store; if enabled and file doesn't exist, blank file created at chosen path).

dialog.showSaveDialog signature and return

dialog.showSaveDialog([window, ]options) returns Promise<Object> with canceled (boolean - whether dialog was canceled), filePath (string - empty string if cancelled), and bookmark (string, optional, macOS mas only - Base64 encoded string containing security scoped bookmark data for saved file).

dialog.showSaveDialogSync signature and return

dialog.showSaveDialogSync([window, ]options) returns string, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string.

dialog.showOpenDialog Linux defaultPath limitation

On Linux, defaultPath is not supported when using portal file chooser dialogs unless the portal backend is version 4 or higher. Use the --xdg-portal-required-version command-line switch to force gtk or kde dialogs.

dialog.showOpenDialog platform limitation: Windows and Linux

On Windows and Linux, an open dialog cannot be both a file selector and a directory selector. If properties are set to ['openFile', 'openDirectory'] on these platforms, a directory selector will be shown instead.

dialog.showErrorBox early stage

dialog.showErrorBox can be called safely before the 'ready' event the app module emits and is usually used to report errors in early stage of startup. If called before app 'ready' event on Linux, the message will be emitted to stderr and no GUI dialog will appear.

dialog file filter format

The filters option for open/save dialogs is an array of FileFilter objects. Each filter has a name property and extensions array. Extensions should be specified without wildcards or dots (e.g. 'png' is correct, '.png' and '*.png' are incorrect). To show all files, use the '*' wildcard. Example: { filters: [{ name: 'Images', extensions: ['jpg', 'png', 'gif'] }, { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] }, { name: 'All Files', extensions: ['*'] }] }

dialog.showOpenDialog options

dialog.showOpenDialog accepts an options object with: title (string, optional), defaultPath (string, optional - Absolute directory path, absolute file path, or file name to use by default. If not provided, defaults to user's Downloads folder, or home directory if Downloads doesn't exist.), buttonLabel (string, optional - Custom label for confirmation button, default used if empty), filters (FileFilter[], optional), properties (string[], optional - openFile, openDirectory, multiSelections, showHiddenFiles (macOS Windows), createDirectory (macOS), promptToCreate (Windows), noResolveAliases (macOS), treatPackageAsDirectory (macOS), dontAddToRecent (Windows)), message (string, optional, macOS only - Message to display above input boxes), securityScopedBookmarks (boolean, optional, macOS mas only - Create security scoped bookmarks when packaged for Mac App Store).

dialog.showOpenDialogSync signature and return

dialog.showOpenDialogSync([window, ]options) returns string[] | undefined. The filePaths are the file paths chosen by the user; if the dialog is cancelled it returns undefined.

dialog bookmarks array format

showOpenDialog and showSaveDialog resolve to an object with a bookmarks field (for showOpenDialog) or bookmark field (for showSaveDialog). These are arrays of Base64 encoded strings that contain security scoped bookmark data for the saved file. The securityScopedBookmarks option must be enabled for this to be present.

dialog bookmarks array return values

For showOpenDialog and showSaveDialog bookmarks/bookmark field: On macOS mas with securityScopedBookmarks true and success: ['LONGBOOKMARKSTRING']. On macOS mas with securityScopedBookmarks true and error: [''] (array of empty string). On macOS mas with securityScopedBookmarks false: [] (empty array). On non-mas builds: [] (empty array) regardless of securityScopedBookmarks setting.

dialog.showOpenDialog example

Example of showing a dialog to select multiple files: const { dialog } = require('electron') console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))

Give your agent this brain