WindowCapture QML Type

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

• List of all members, including inherited members

Properties

• active : bool
• error : enumeration
• errorString : string
• maximumFrameRate : real (since 6.12)
• window : Window

Signals

• errorChanged()
• errorOccurred(int error, string errorString)

Methods

• list<CapturableWindow> capturableWindows()
• void start()
• void stop()

Detailed Description

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

The code below shows a simple capture session that captures one of the available windows with WindowCapture and plays it back in a VideoOutput.

CaptureSession {
    id: captureSession
    windowCapture: WindowCapture {
        id: capture
    }
    videoOutput: VideoOutput {
        id: videoOutput
    }

    Component.onCompleted: {
        let windows = capture.capturableWindows()
        if (windows.length > 0) {
            capture.window = windows[0]
            capture.active = true
        }
    }
}

Window Capture Limitations

The following limitations apply to using WindowCapture:

• WindowCapture 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 CaptureSession and CapturableWindow.

Property Documentation

active : bool

Describes whether the capturing is currently active.

See also start() and stop().

error : enumeration [read-only]

Returns a code of the last error.

errorString : string [read-only]

Returns a human readable string describing the cause of error.

maximumFrameRate : real [since 6.12]

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.

If -1, a platform-dependent default is used.

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

This property was introduced in Qt 6.12.

window : Window

Describes the window for capturing.

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

See also capturableWindows.

Signal Documentation

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.

errorOccurred(int error, string errorString)

Signals when an error occurs, along with the errorString.

For the error parameter, see the enumeration table in error for what values may be passed.

See also error.

Method Documentation

list<CapturableWindow> capturableWindows()

Returns a list of CapturableWindow objects that are currently available for capturing.

void start()

Starts capturing the window.

This is equivalent to setting the active property to true.

void stop()

Stops capturing.

This is equivalent to setting the active property to false.