QGStreamerVideoSource Class | Qt Multimedia | Qt 6.12.0
Description: The QGStreamerVideoSource class provides a video source backed by a custom GStreamer element.
Keywords: class

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

# QGStreamerVideoSource Class

The QGStreamerVideoSource class provides a video source backed by a custom GStreamer element. More...

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

- List of all members, including inherited members

## Properties

- active : bool
- gstBinDescription : const QString

## Public Functions

| QGStreamerVideoSource(GstElement *gstElement, QObject *parent = nullptr)
| QGStreamerVideoSource(const QString &gstBinDescription, QObject *parent = nullptr)
QString | gstBinDescription() const
GstElement * | gstElement() const
bool | isActive() const

## Public Slots

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

## Signals

void | activeChanged(bool active)

## Detailed Description

Warning: The GStreamerVideoSource class offers limited compatibility guarantees. There are no source or binary compatibility guarantees for these classes, meaning the API is only guaranteed to work with the Qt version the application has been developed against. However, incompatible changes are aimed to be kept at a minimum and will only be made in minor releases. To use the class in an application, link to `Qt::MultimediaPrivate` (if using CMake), and include the header #include <spi/qgstreamervideosource.h>.

Construct QGStreamerVideoSource from a GStreamer bin description or from an existing `GstElement` and attach it to QMediaCaptureSession by QMediaCaptureSession::setNativeVideoSource().

For any standard case, we recommend using QCamera instead of this class, unless you need GStreamer-specific configuration to handle any custom video source.

By default, the class is available in meta-qt6 builds. In custom builds with GStreamer support, the `gstreamer_qt_api` feature can enable it.

QtMultimedia must be run with the `gstreamer` media backend for this class to work.

     QMediaCaptureSession session;
     QGStreamerVideoSource videoSource(QStringLiteral("videotestsrc name=testsrc"));

     session.setNativeVideoSource(&videoSource);
     videoSource.start();

See also QMediaCaptureSession and QCamera.

## Property Documentation

### active : bool

Describes whether the video source is currently active.

If the video source has been connected to a QMediaCaptureSession, this property indicates whether the underlying `GstElement` is attached to the `GstPipeline` within the media capture session.

Access functions:

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

Notifier signal:

void | activeChanged(bool active)

### `[read-only]` gstBinDescription : const QString

Describes the GStreamer bin description associated with the video source.

If the video source is non-functional or has been constructed from an existing `GstElement`, the property string is empty.

Access functions:

QString | gstBinDescription() const

## Member Function Documentation

### `[explicit]` QGStreamerVideoSource::QGStreamerVideoSource(GstElement *gstElement, QObject *parent = nullptr)

Constructs a QGStreamerVideoSource from an existing gstElement and a parent.

The element must provide a video source that a capture session can use. The `GstElement` type is forward-declared in the `QGStreamerVideoSource` header, so the corresponding type from the GStreamer library must be used.

If the specified element is null, the constructed video source is non-functional.

Note: The class doesn't perform any additional validation of the provided element, so if the specified element doesn't represent a video input for `GstPipeline`, QGStreamerVideoSource and the associated QMediaCaptureSession may misbehave.

Note: QGStreamerVideoSource shares ownership of the provided `GstElement` with the caller.

### `[explicit]` QGStreamerVideoSource::QGStreamerVideoSource(const QString &gstBinDescription, QObject *parent = nullptr)

Constructs a QGStreamerVideoSource from the GStreamer bin description gstBinDescription and a parent.

The GStreamer backend interprets the description and creates a bin that can act as a video source for a capture session. Use method gstElement() to access the created bin.

See GStreamer documentation for the syntax of the description string.

If it's unable to parse the specified description, preventing the `GstBin` from being created, the constructed QGStreamerVideoSource is non-functional, gstElement() returns `nullptr`, and gstBinDescription() returns an empty string.

Note: QGStreamerVideoSource doesn't perform any additional validation of the provided bin description, so if the created `GstBin` doesn't represent a video input for `GstPipeline`, QGStreamerVideoSource and the associated QMediaCaptureSession may misbehave.

For better control of the underlying GStreamer element, you can construct QGStreamerVideoSource from an existing `GstElement` instead.

See also gstElement() and gstBinDescription().

### GstElement *QGStreamerVideoSource::gstElement() const

Returns the underlying `GstElement` used by the video source, or `nullptr` if the video source is non-functional.

If the video source has been constructed from a GStreamer bin description, the returned `GstElement` is convertable to the `GstBin` subclass.

Note: The method does not transfer ownership of the `GstElement`.

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

Starts the video source.

Same as setting the active property to `true`.

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

Stops the video source.

Same as setting the active property to `false`.