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

# QWindowCapture Class

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

Header: | `#include <QWindowCapture>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Multimedia)` `target_link_libraries(mytarget PRIVATE Qt6::Multimedia)`
qmake: | `QT += multimedia`
Since: | Qt 6.6
In QML: | WindowCapture
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)` frameRate : std::optional<qreal> window : QCapturableWindow

## Public Functions

| QWindowCapture(QObject *parent = nullptr)
virtual | ~QWindowCapture() override
QWindowCapture::Error | error() const
QString | errorString() const
std::optional<qreal> | frameRate() const
bool | isActive() const
void | resetFrameRate()
void | setFrameRate(std::optional<qreal> frameRate)
void | setWindow(QCapturableWindow window)
QCapturableWindow | window() const

## Public Slots

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

## Signals

void | activeChanged(bool)
void | errorChanged()
void | errorOccurred(QWindowCapture::Error error, const QString &errorString)
void | frameRateChanged()
void | windowChanged(QCapturableWindow window)

## Static Public Members

QList<QCapturableWindow> | capturableWindows()

## Detailed Description

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

### Window Capture Limitations

The following limitations apply to using QWindowCapture:

- QWindowCapture is only supported with the FFmpeg backend.

The following limitations apply when using `QWindowCapture` on X11 systems:

- On Linux X11 systems, when a window is moved partially outside the visible screen area, only the visible region is captured. As a result, the emitted video frames may have a size smaller than the window’s geometry.
- Windows that are outside the visible screen area cannot be captured, and an error signal is emitted in that case.
- The behavior of minimized windows or those located on an invisible virtual workspace depends on the window manager. For example, such windows can be captured on GNOME, whereas on WindowMaker or Xfwm such capturing is not allowed, and the window capture instance emits an error.

See also QMediaCaptureSession and QCapturableWindow.

## Member Type Documentation

### enum QWindowCapture::Error

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

Constant | Value | Description
--- | --- | ---
`QWindowCapture::NoError` | `0` | No error
`QWindowCapture::InternalError` | `1` | Internal window capturing driver error
`QWindowCapture::CapturingNotSupported` | `2` | Window capturing is not supported
`QWindowCapture::CaptureFailed` | `4` | Capturing window failed
`QWindowCapture::NotFound` | `5` | Selected window 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:

QWindowCapture::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]` frameRate : std::optional<qreal>

This property holds the target window capture framerate.

Actual frame rate depends on the platform. For platforms with fixed rate capture, this frame rate is followed. For platforms with variable rate capture, this frame rate is either used as the polling rate (maximum frame rate) or completely ignored.

If left unset, a platform-dependent default is used.

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

This enumeration was introduced in Qt 6.12.

Access functions:

std::optional<qreal> | frameRate() const
void | setFrameRate(std::optional<qreal> frameRate)
void | resetFrameRate()

Notifier signal:

void | frameRateChanged()

### window : QCapturableWindow

This property holds the window for capturing.

Setting this property to an invalid window on an active QWindowCapture will cause it to go inactive and emit an error.

Access functions:

QCapturableWindow | window() const
void | setWindow(QCapturableWindow window)

Notifier signal:

void | windowChanged(QCapturableWindow window)

See also QWindowCapture::capturableWindows.

## Member Function Documentation

### `[explicit]` QWindowCapture::QWindowCapture(QObject *parent = nullptr)

Constructs a new QWindowCapture object with parent.

### `[override virtual noexcept]` QWindowCapture::~QWindowCapture()

Destroys the object.

### `[static invokable]` QList<QCapturableWindow> QWindowCapture::capturableWindows()

Returns a list of QCapturableWindow objects that is available for capturing.

Note: On macOS, invoking this method will trigger the "Screen Recording" permission dialog. If permissions have not yet been granted, this method will return an empty list. Invoking it multiple times will bring this dialog to the foreground.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[signal]` void QWindowCapture::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 QWindowCapture::errorOccurred(QWindowCapture::Error error, const QString &errorString)

Signals when an error occurs, along with the errorString.

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

Starts capturing the window.

This is equivalent to setting the active property to true.

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

Stops capturing.

This is equivalent to setting the active property to false.