Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/guide/video/desktop-capture.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,12 @@ screenCapturer.dispose();
windowCapturer.dispose();
```

### Capturing on macOS

On macOS 14 and newer, screens and windows are captured with ScreenCaptureKit; older releases use the earlier Core Graphics capture. Both need the app to have Screen Recording permission (System Settings → Privacy & Security → Screen & System Audio Recording). Without it, the windows of other apps are listed without their titles and their content cannot be captured. Windows of the app's own process need no permission, and are captured with Core Graphics.

While a captured window is minimized or hidden, its last image repeats. When it is closed, capture stops.

## Conclusion

This guide has demonstrated how to set up a WebRTC peer connection with desktop video capture capabilities.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
/*
* Copyright 2026 Alex Andres
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

#ifndef JNI_WEBRTC_MEDIA_DESKTOP_MACOS_SCREEN_CAPTURER_H_
#define JNI_WEBRTC_MEDIA_DESKTOP_MACOS_SCREEN_CAPTURER_H_

#include "modules/desktop_capture/desktop_capture_options.h"
#include "modules/desktop_capture/desktop_capturer.h"

#include <memory>

namespace jni
{
// Creates a capturer for one screen, or for the whole desktop, that picks
// its backend when started. A single screen is captured with
// ScreenCaptureKit on macOS 14 and newer, which draws the cursor itself.
// The whole desktop, which ScreenCaptureKit cannot capture, and every
// screen on older macOS, are captured with WebRTC's CGDisplayStream
// capturer. That capturer also lists the screens, since ScreenCaptureKit
// lists none without its system picker; both name a screen by its
// CGDirectDisplayID.
std::unique_ptr<webrtc::DesktopCapturer> CreateMacOSScreenCapturer(const webrtc::DesktopCaptureOptions & options);
}

#endif
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
/*
* Copyright 2026 Alex Andres
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

#ifndef JNI_WEBRTC_MEDIA_DESKTOP_MACOS_SCREEN_CAPTURE_KIT_WINDOW_CAPTURER_H_
#define JNI_WEBRTC_MEDIA_DESKTOP_MACOS_SCREEN_CAPTURE_KIT_WINDOW_CAPTURER_H_

#include "modules/desktop_capture/desktop_capture_options.h"
#include "modules/desktop_capture/desktop_capturer.h"

#include <memory>

namespace jni
{
// Creates a capturer for one window, selected by its CGWindowID, that
// streams it with ScreenCaptureKit instead of taking a
// CGWindowListCreateImage snapshot for every frame, as WebRTC's window
// capturer does. Windows of this process, and windows ScreenCaptureKit
// cannot capture, for example without screen recording permission, are
// captured with WebRTC's window capturer instead. Returns null before
// macOS 14.
std::unique_ptr<webrtc::DesktopCapturer> CreateScreenCaptureKitWindowCapturer(const webrtc::DesktopCaptureOptions & options);
}

#endif
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@
#include "modules/desktop_capture/desktop_and_cursor_composer.h"
#include "modules/desktop_capture/mouse_cursor_monitor.h"

#if defined(WEBRTC_MAC)
#include "media/video/desktop/macos/MacOSScreenCapturer.h"
#include "media/video/desktop/macos/ScreenCaptureKitWindowCapturer.h"
#endif

#include <algorithm>
#include <cmath>

Expand Down Expand Up @@ -257,15 +262,6 @@ namespace jni

#if defined(WEBRTC_MAC)
options.set_allow_iosurface(true);
// Screens are captured with ScreenCaptureKit on macOS 14 and newer.
// The CGDisplayStream capturer otherwise used gets new pixels only
// when its stream calls back, and when that stops it keeps sending the
// first frame with a live cursor on top (issue #344). Older macOS
// falls back to it. Only screens: window capture ignores this, and the
// source list stays with the CGDisplayStream capturer in
// DesktopCapturer, since ScreenCaptureKit lists no screens without its
// system picker. Both name a screen by its CGDirectDisplayID.
options.set_allow_sck_capturer(true);
#endif
#if defined(WEBRTC_WIN)
options.set_allow_directx_capturer(true);
Expand All @@ -281,6 +277,22 @@ namespace jni

std::unique_ptr<webrtc::DesktopCapturer> inner;

#if defined(WEBRTC_MAC)
if (sourceIsWindow) {
// Streams the window with ScreenCaptureKit on macOS 14 and newer,
// instead of a CGWindowListCreateImage snapshot per frame.
inner = CreateScreenCaptureKitWindowCapturer(options);
}
else {
// A screen is captured with ScreenCaptureKit on macOS 14 and newer.
// The CGDisplayStream capturer otherwise used gets new pixels only
// when its stream calls back, and when that stops it keeps sending
// the first frame with a live cursor on top (issue #344). It still
// captures the whole desktop, which ScreenCaptureKit cannot.
inner = CreateMacOSScreenCapturer(options);
}
#endif

#if defined(WEBRTC_USE_PIPEWIRE)
// Wayland: request "any screen content" so the xdg-desktop-portal picker
// offers both monitors and application windows in a single dialog (the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@
#include "modules/desktop_capture/desktop_and_cursor_composer.h"
#include "rtc_base/logging.h"

#if defined(WEBRTC_MAC)
#include "media/video/desktop/macos/MacOSScreenCapturer.h"
#include "media/video/desktop/macos/ScreenCaptureKitWindowCapturer.h"
#endif

namespace jni
{
DesktopCapturer::DesktopCapturer(bool screenCapturer) :
Expand All @@ -47,9 +52,21 @@ namespace jni
options.set_prefer_cursor_embedded(true);
#endif

std::unique_ptr<webrtc::DesktopCapturer> inner = screenCapturer
? webrtc::DesktopCapturer::CreateScreenCapturer(options)
: webrtc::DesktopCapturer::CreateWindowCapturer(options);
std::unique_ptr<webrtc::DesktopCapturer> inner;

#if defined(WEBRTC_MAC)
// Both list their sources as WebRTC's capturers do, and capture with
// ScreenCaptureKit on macOS 14 and newer.
inner = screenCapturer
? CreateMacOSScreenCapturer(options)
: CreateScreenCaptureKitWindowCapturer(options);
#endif

if (!inner) {
inner = screenCapturer
? webrtc::DesktopCapturer::CreateScreenCapturer(options)
: webrtc::DesktopCapturer::CreateWindowCapturer(options);
}

if (!inner) {
RTC_LOG(LS_ERROR) << (screenCapturer
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
/*
* Copyright 2026 Alex Andres
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

#include "media/video/desktop/macos/MacOSScreenCapturer.h"

#include "modules/desktop_capture/mac/screen_capturer_sck.h"
#include "rtc_base/logging.h"

namespace jni
{
namespace
{
class MacOSScreenCapturer final : public webrtc::DesktopCapturer
{
public:
MacOSScreenCapturer(const webrtc::DesktopCaptureOptions & options,
std::unique_ptr<webrtc::DesktopCapturer> displayStream) :
options(options),
displayStream(std::move(displayStream)),
active(nullptr),
screen(webrtc::kFullDesktopScreenId),
maxFrameRate(0)
{
}

void Start(Callback * callback) override
{
if (screen != webrtc::kFullDesktopScreenId && webrtc::ScreenCapturerSckAvailable()) {
webrtc::DesktopCaptureOptions sckOptions = options;
sckOptions.set_allow_sck_capturer(true);
// ScreenCaptureKit's frames do not say where the screen
// lies on the desktop, which DesktopAndCursorComposer
// needs to place its cursor on any but the first screen.
sckOptions.set_prefer_cursor_embedded(true);

screenCaptureKit = webrtc::DesktopCapturer::CreateScreenCapturer(sckOptions);
}

if (screenCaptureKit && screenCaptureKit->SelectSource(screen)) {
active = screenCaptureKit.get();
}
else {
active = displayStream.get();
}

if (maxFrameRate > 0) {
active->SetMaxFrameRate(maxFrameRate);
}

active->Start(callback);
}

void SetMaxFrameRate(uint32_t maxFrameRate) override
{
this->maxFrameRate = maxFrameRate;

if (active) {
active->SetMaxFrameRate(maxFrameRate);
}
}

void CaptureFrame() override
{
if (active) {
active->CaptureFrame();
}
}

bool GetSourceList(SourceList * sources) override
{
return displayStream->GetSourceList(sources);
}

bool SelectSource(SourceId id) override
{
if (active) {
// Selected after Start(): stays with the backend chosen
// then.
return active->SelectSource(id);
}

if (!displayStream->SelectSource(id)) {
return false;
}

screen = id;

return true;
}

bool FocusOnSelectedSource() override
{
return active ? active->FocusOnSelectedSource() : false;
}

bool IsOccluded(const webrtc::DesktopVector & pos) override
{
return active ? active->IsOccluded(pos) : false;
}

private:
const webrtc::DesktopCaptureOptions options;

// Lists the screens, and captures where ScreenCaptureKit does not.
const std::unique_ptr<webrtc::DesktopCapturer> displayStream;
std::unique_ptr<webrtc::DesktopCapturer> screenCaptureKit;
webrtc::DesktopCapturer * active;

SourceId screen;
uint32_t maxFrameRate;
};
}

std::unique_ptr<webrtc::DesktopCapturer> CreateMacOSScreenCapturer(const webrtc::DesktopCaptureOptions & options)
{
webrtc::DesktopCaptureOptions displayStreamOptions = options;
displayStreamOptions.set_allow_sck_capturer(false);

std::unique_ptr<webrtc::DesktopCapturer> displayStream =
webrtc::DesktopCapturer::CreateScreenCapturer(displayStreamOptions);

if (!displayStream) {
return nullptr;
}

return std::make_unique<MacOSScreenCapturer>(options, std::move(displayStream));
}
}
Loading
Loading