ScreenCapture QML Type

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

• List of all members, including inherited members

Properties

• active : bool
• error : enumeration
• errorString : string
• screen : Screen

Signals

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

Methods

• void start()
• void stop()

Detailed Description

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

The code below shows a simple capture session with ScreenCapture playing back the captured primary screen view in VideoOutput.

CaptureSession {
    id: captureSession
    screenCapture: ScreenCapture {
        id: screenCapture
        active: true
    }
    videoOutput: VideoOutput {
        id: videoOutput
    }
}

Screen Capture Limitations

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

• 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 {https://pipewire.org/}{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 WindowCapture and CaptureSession.

Property Documentation

active : bool

Describes whether the capturing is currently active.

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.

screen : Screen

Describes the screen for capturing.

If null Screen is set, the primary screen will be selected when the ScreenCapture instance gets activated.

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

void start()

Starts capturing the screen.

This is equivalent to setting the active property to true.

void stop()

Stops capturing.

This is equivalent to setting the active property to false.