How Safari Handles getDisplayMedia Screen Sharing Prompts

This article provides an overview of how the screen sharing permission prompt functions in the Safari web browser when a website invokes the navigator.mediaDevices.getDisplayMedia() API. It covers the strict security prerequisites required to trigger the prompt, the user selection process, how macOS system-level permissions impact the browser, and how Safari manages the lifecycle and privacy of the screen sharing session.

Security Prerequisites to Trigger the Prompt

Before Safari will display the screen sharing prompt to a user, two strict security conditions must be met by the website:

  1. Secure Context: The website calling the API must be served over HTTPS, or be running locally on localhost.
  2. Transient User Activation: The navigator.mediaDevices.getDisplayMedia() method must be called directly in response to an explicit user gesture, such as clicking a button.

If a website attempts to call this API automatically upon page load or inside an asynchronous callback that has lost the context of the user gesture, Safari will block the prompt entirely and immediately reject the JavaScript Promise with a NotAllowedError.

The Browser Permission Flow

When the API is called correctly, Safari interrupts the user with a native permission dialog. Unlike camera and microphone requests, which only ask to "Allow" or "Don't Allow" access, the screen sharing prompt requires the user to actively choose the media source.

Safari presents the user with the following options:

  • Allow to Share Window: The user can select a specific open application window to share. This prevents the website from seeing the rest of the user's desktop, notifications, or other open applications.
  • Allow to Share Screen: The user can choose to share their entire display. If multiple monitors are connected, the user selects which specific screen to capture.
  • Don't Allow / Cancel: Rejects the request. Safari will not capture any media and will return a NotAllowedError to the website.

In newer versions of macOS and Safari, this prompt integrates directly with the native macOS system window picker, allowing the user to visually hover over and click the exact window they wish to stream.

macOS System-Level Permissions

Safari’s internal permission prompt is subordinate to the macOS operating system's security model. Even if a user grants permission inside the Safari prompt, the stream will fail if Safari itself does not have permission from the operating system to record the screen.

If it is the user's first time sharing their screen in Safari, macOS will trigger a system dialog instructing the user to open System Settings > Privacy & Security > Screen Recording. The user must toggle the switch to allow Safari to record the contents of the screen. Until this system-level permission is granted, getDisplayMedia() calls in Safari will fail.

No Permission Persistence

To protect user privacy, Safari never remembers or saves getDisplayMedia() permissions. While a user can configure Safari settings to "Always Allow" a trusted website to access their camera or microphone, this option does not exist for screen sharing.

Safari forces the permission prompt to appear every single time getDisplayMedia() is called, even if the user just granted permission a few seconds prior or simply refreshed the webpage.

Active Session Indicators and Revocation

Once the user selects a window or screen and the MediaStream begins, Safari provides persistent visual indicators to remind the user they are being recorded. A screen-sharing icon appears inside the Safari tab, and a corresponding indicator appears in the macOS menu bar at the top of the screen.

The user retains full control to revoke this permission at any moment. Clicking the icon in the Safari tab or the macOS menu bar provides an option to "Stop Sharing." When the user stops the share from the browser UI, Safari immediately cuts off the video feed and triggers the ended event on the JavaScript MediaStreamTrack, signaling to the website that the session has been terminated by the user.