- Qt 6.12
- Qt Multimedia
- C++ Classes
- QtMultimedia
- QScreenCapture
- Qt 6.12.0 Reference Documentation

# QScreenCapture Class

This class is used for capturing a screen. More...

Header: | `#include <QScreenCapture>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Multimedia)` `target_link_libraries(mytarget PRIVATE Qt6::Multimedia)`
qmake: | `QT += multimedia`
Since: | Qt 6.5
In QML: | ScreenCapture
Inherits: | QObject

- List of all members, including inherited members

## Public Types

enum | Error { NoError, InternalError, CapturingNotSupported, CaptureFailed, NotFound }

## Properties

active : bool error : Error errorString : QString | `(since 6.12)` maximumFrameRate : std::optional<qreal> screen : QScreen*

## Public Functions

QMediaCaptureSession * | captureSession() const
QScreenCapture::Error | error() const
QString | errorString() const
bool | isActive() const
std::optional<qreal> | maximumFrameRate() const
QScreen * | screen() const
void | setMaximumFrameRate(std::optional<qreal> frameRate)
void | setScreen(QScreen *screen)

## Public Slots

void | setActive(bool active)
void | start()
void | stop()

## Signals

void | activeChanged(bool)
void | errorChanged()
void | errorOccurred(QScreenCapture::Error error, const QString &errorString)
void | maximumFrameRateChanged()
void | screenChanged(QScreen *)

## Detailed Description

The class captures a screen. It is managed by the QMediaCaptureSession class where the captured screen can be displayed in a video preview object or recorded to a file.

The following snippet shows how to capture the primary screen and display the result in a QVideoWidget:

     QMediaCaptureSession session;
     QScreenCapture screenCapture;
     session.setScreenCapture(&screenCapture);

     QVideoWidget videoWidget;
     session.setVideoOutput(&videoWidget);
     videoWidget.show();

     // With no screen set, the primary screen is captured once capturing starts.
     screenCapture.start();

### Screen Capture Limitations

On Qt 6.5.2 and above, the following limitations apply to using QScreenCapture:

- It is only supported with the FFmpeg backend.
- On some platforms, no new video frames are emitted while the captured screen content remains unchanged. Applications should therefore not rely on receiving a continuous stream of frames at the requested frame rate.
- On Linux systems using the Wayland compositor, the screen capture implementation is experimental and comes with the following limitations. Due to restrictions of the Wayland protocol, it's impossible to set and get the target screen via the API of the `QScreenCapture` class. Instead, the OS will show a screen selection wizard upon invoking `QScreenCapture::setActive(true)`. The screen capture feature requires the installation of the ScreenCast service supported via XDG Desktop Portal and PipeWire (0.3). These limitations might change in the future.
- It is not supported on mobile operating systems, except on Android. Screen Capture on Android needs additional Android foreground service permission to be added to the `AndroidManifest.xml` file:

       <manifest ...>
       <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
       <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
       <application ...>
           <service android:name="org.qtproject.qt.android.multimedia.QtScreenCaptureService"
               android:foregroundServiceType="mediaProjection"
               android:exported="false"/>
           </service>
       </application>
       </manifest>

- On embedded with EGLFS, it has limited functionality. For Qt Quick applications, the class is currently implemented via QQuickWindow::grabWindow, which can cause performance issues.
- In most cases, we set a screen capture frame rate that equals the screen refresh rate, except on Windows, where the rate might be flexible. Such a frame rate (75/120 FPS) might cause performance issues on weak CPUs if the captured screen is of 4K resolution. On EGLFS, the capture frame rate is currently locked to 30 FPS.

See also QWindowCapture and QMediaCaptureSession.

## Member Type Documentation

### enum QScreenCapture::Error

Enumerates error codes that can be signaled by the QScreenCapture class. errorString() provides detailed information about the error cause.

Constant | Value | Description
--- | --- | ---
`QScreenCapture::NoError` | `0` | No error
`QScreenCapture::InternalError` | `1` | Internal screen capturing driver error
`QScreenCapture::CapturingNotSupported` | `2` | Capturing is not supported
`QScreenCapture::CaptureFailed` | `4` | Capturing screen failed
`QScreenCapture::NotFound` | `5` | Selected screen not found

## Property Documentation

### active : bool

This property holds whether the capturing is currently active.

Access functions:

bool | isActive() const
void | setActive(bool active)

Notifier signal:

void | activeChanged(bool)

See also start() and stop().

### `[read-only]` error : Error

This property holds the code of the last error.

Access functions:

QScreenCapture::Error | error() const

Notifier signal:

void | errorChanged()

### `[read-only]` errorString : QString

This property holds a human readable string describing the cause of error.

Access functions:

QString | errorString() const

Notifier signal:

void | errorChanged()

### `[since 6.12]` maximumFrameRate : std::optional<qreal>

This property holds the screen capture frame rate upper limit.

This can be set to override the capture frame rate used by default based on e.g. display refresh rate, but only as an upper limit since screen capture produces frames at a variable rate. Setting this higher than the display refresh rate is not recommended and can cause errors.

Any changes to this property are applied the next time the QScreenCapture goes active.

This enumeration was introduced in Qt 6.12.

Access functions:

std::optional<qreal> | maximumFrameRate() const
void | setMaximumFrameRate(std::optional<qreal> frameRate)

Notifier signal:

void | maximumFrameRateChanged()

### screen : QScreen*

This property holds the screen for capturing.

If null QScreen is set, QGuiApplication::primaryScreen will be selected when the `QScreenCapture` instance gets activated.

Access functions:

QScreen * | screen() const
void | setScreen(QScreen *screen)

Notifier signal:

void | screenChanged(QScreen *)

See also QGuiApplication::screens() and QGuiApplication::primaryScreen().

## Member Function Documentation

### QMediaCaptureSession *QScreenCapture::captureSession() const

Returns the capture session this QScreenCapture is connected to.

Use QMediaCaptureSession::setScreenCapture() to connect the screen capture to a session.

### `[signal]` void QScreenCapture::errorChanged()

This signal is emitted when the error or errorString properties are changed.

This signal is not emitted whenever multiple identical errors are raised. To track such errors, use the signal errorOccurred.

Note: Notifier signal for properties error and errorString.

### `[signal]` void QScreenCapture::errorOccurred(QScreenCapture::Error error, const QString &errorString)

Signals when an error occurs, along with the errorString.

### `[slot]` void QScreenCapture::start()

Starts capturing the screen.

This is equivalent to setting the active property to true.

### `[slot]` void QScreenCapture::stop()

Stops capturing.

This is equivalent to setting the active property to false.