PySide6.QtMultimedia.QWindowCapture

class QWindowCapture

This class is used for capturing a window. More…

Inheritance diagram of PySide6.QtMultimedia.QWindowCapture

Added in version 6.6.

Synopsis

Properties

Methods

Slots

Signals

Static functions

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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.

The following snippet shows how to select one of the capturable windows and display the result in a QVideoWidget :

session = QMediaCaptureSession()
windowCapture = QWindowCapture()
session.setWindowCapture(windowCapture)
videoWidget = QVideoWidget()
session.setVideoOutput(videoWidget)
videoWidget.show()
# A window must be selected before capturing can start.
windows = QWindowCapture.capturableWindows()
if not windows.isEmpty():
    windowCapture.setWindow(windows.first())
    windowCapture.start()

Window Capture Limitations

The following limitations apply to using QWindowCapture :

  • QWindowCapture is only supported with the FFmpeg backend.

  • On some platforms, no new video frames are emitted while the captured window content remains unchanged. Applications should therefore not rely on receiving a continuous stream of frames at the requested frame rate.

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 QCapturableWindow

class Error

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

Constant

Description

QWindowCapture.Error.NoError

No error

QWindowCapture.Error.InternalError

Internal window capturing driver error

QWindowCapture.Error.CapturingNotSupported

Window capturing is not supported

QWindowCapture.Error.CaptureFailed

Capturing window failed

QWindowCapture.Error.NotFound

Selected window not found

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property activeᅟ: bool

This property holds whether the capturing is currently active..

See also

start() stop()

Access functions:
property errorᅟ: QWindowCapture.Error

This property holds the code of the last error..

Access functions:
property errorStringᅟ: str

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

Access functions:
property maximumFrameRateᅟ: std::optional<qreal>

This property holds The window 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 window 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 QWindowCapture goes active.

Access functions:
property 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:
__init__([parent=None])
Parameters:

parent – QObject

Constructs a new QWindowCapture object with parent.

activeChanged(arg__1)
Parameters:

arg__1 – bool

Notification signal of property activeᅟ .

static capturableWindows()
Return type:

.list of QCapturableWindow

Returns a list of QCapturableWindow objects that are currently 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.

captureSession()
Return type:

QMediaCaptureSession

Returns the capture session this QWindowCapture is connected to.

Use setWindowCapture() to connect the window capture to a session.

error()
Return type:

Error

Getter of property errorᅟ .

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() .

Notification signal of property errorᅟ .

errorOccurred(error, errorString)
Parameters:

  • error – Error

  • errorString – str

Signals when an error occurs, along with the errorString.

errorString()
Return type:

str

Getter of property errorStringᅟ .

isActive()
Return type:

bool

Getter of property activeᅟ .

maximumFrameRate()
Return type:

~std::optional

See also

setMaximumFrameRate()

Getter of property maximumFrameRateᅟ .

maximumFrameRateChanged()

Notification signal of property maximumFrameRateᅟ .

setActive(active)
Parameters:

active – bool

See also

isActive()

Setter of property activeᅟ .

setMaximumFrameRate(frameRate)
Parameters:

frameRate – ~std::optional

See also

maximumFrameRate()

Setter of property maximumFrameRateᅟ .

setWindow(window)
Parameters:

window – QCapturableWindow

See also

window()

Setter of property windowᅟ .

start()

Starts capturing the window() .

This is equivalent to setting the active() property to true.

stop()

Stops capturing.

This is equivalent to setting the active() property to false.

window()
Return type:

QCapturableWindow

See also

setWindow()

Getter of property windowᅟ .

windowChanged(window)
Parameters:

window – QCapturableWindow

Notification signal of property windowᅟ .