qgstreamerinterface.cpp

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 
#include "qgstreamerinterface.h"
 
#include <QtMultimedia/private/qplatformmediaintegration_p.h>
 
QT_BEGIN_NAMESPACE
 
/*!
    \class QGStreamerInterface
    \since 6.12
 
    \brief Provides GStreamer-specific integration points for Qt Multimedia.
 
    \inmodule QtMultimedia
    \ingroup multimedia
 
    \warning The QGStreamerInterface class offers limited compatibility guarantees.
    There are no source or binary compatibility guarantees for this API, meaning it
    is only guaranteed to work with the Qt version the application has been developed
    against. Incompatible changes are aimed to be kept at a minimum and will only be
    made in minor releases.
 
    To use this class in an application, link to \c Qt::MultimediaPrivate (if using
    CMake), and include the header
    \c{#include <QtMultimedia/spi/qgstreamerinterface.h>}.
 
    QGStreamerInterface is the entry point for customizing the GStreamer backend:
    wrapping custom pipeline elements as Qt audio and video devices, accessing the
    underlying \c GstPipeline of high-level Qt objects, and converting between
    \l QVideoFrame and GStreamer buffers.
 
    By default, the class is available in meta-qt6 builds. In custom builds
    with GStreamer support, the \c gstreamer_qt_api feature can enable it.
 
    QtMultimedia must be run with the \c gstreamer media backend to get a valid
    instance of the class.
*/
 
 
/*!
    Returns the GStreamer interface for the active Qt Multimedia backend, or
    \c nullptr if the GStreamer backend is not in use.
*/
QGStreamerInterface *QGStreamerInterface::instance()
{
    return QPlatformMediaIntegration::instance()->gstreamerInterface();
}
 
/*!
    \fn QGStreamerInterface::~QGStreamerInterface()
 
    Destroys the interface.
*/
 
/*!
    \fn QAudioDevice QGStreamerInterface::makeCustomGStreamerAudioInput(const QByteArray &gstreamerPipeline)
 
    Creates a custom audio input device from a GStreamer pipeline description.
 
    The \a gstreamerPipeline string is parsed as a GStreamer bin description. The
    resulting elements are connected as the audio source of a \l QMediaCaptureSession
    when the returned \l QAudioDevice is passed to \l QAudioInput and assigned with
    \l{QMediaCaptureSession::setAudioInput()}.
 
    Element names in the description can be used to locate nodes in the session
    pipeline via \c gst_bin_get_by_name() after the capture session is active.
 
    \code
    #include <QtMultimedia/spi/qgstreamerinterface.h>
 
    QMediaCaptureSession session;
    QAudioInput input{
        QGStreamerInterface::instance()->makeCustomGStreamerAudioInput(
            "audiotestsrc wave=2 freq=200 ! identity name=myConverter") };
    session.setAudioInput(&input);
    \endcode
 
    \sa makeCustomGStreamerAudioOutput(), QAudioInput, QMediaCaptureSession
*/
 
/*!
    \fn QAudioDevice QGStreamerInterface::makeCustomGStreamerAudioOutput(const QByteArray &gstreamerPipeline)
 
    Creates a custom audio output device from a GStreamer pipeline description.
 
    The \a gstreamerPipeline string is parsed as a GStreamer bin description. The
    resulting elements are connected as the audio sink of a \l QMediaCaptureSession
    when the returned \l QAudioDevice is passed to \l QAudioOutput and assigned with
    \l{QMediaCaptureSession::setAudioOutput()}.
 
    \sa makeCustomGStreamerAudioInput(), QAudioOutput, QMediaCaptureSession
*/
 
/*!
    \fn GstPipeline *QGStreamerInterface::gstPipeline(QMediaPlayer *player)
 
    Returns the underlying GStreamer pipeline for \a player, or \c nullptr if
    \a player is not backed by the GStreamer media backend.
 
    \warning The pipeline is still owned and driven by Qt Multimedia. Modifying its
    state or topology without coordinating with \l QMediaPlayer can cause undefined
    behavior.
 
    \sa QMediaPlayer
*/
 
/*!
    \fn GstPipeline *QGStreamerInterface::gstPipeline(QMediaCaptureSession *session)
 
    Returns the underlying GStreamer pipeline for \a session, or \c nullptr if
    \a session is not backed by the GStreamer media backend.
 
    \warning The pipeline is still owned and driven by Qt Multimedia. Modifying its
    state or topology without coordinating with the capture session can cause undefined
    behavior.
 
    \sa QMediaCaptureSession
*/
 
/*!
    \fn GstBuffer *QGStreamerInterface::gstBuffer(const QVideoFrame &frame)
 
    Returns the GStreamer buffer backing \a frame, or \c nullptr if \a frame does not
    hold GStreamer-backed video memory.
 
    Ownership of the returned buffer is \e not transferred.
 
    \sa createFrameFromGstBuffer()
*/
 
/*!
    \fn QVideoFrame QGStreamerInterface::createFrameFromGstBuffer(GstBuffer *buffer, const GstVideoInfo &videoInfo)
 
    Creates a \l QVideoFrame that wraps \a buffer using the format described by
    \a videoInfo.
 
    The created frame shares ownership of the specified \c GstBuffer with the caller.
 
    \sa createFrameFromGstBuffer(GstBuffer *, const GstVideoInfoDmaDrm &), gstBuffer()
*/
 
/*!
    \fn QVideoFrame QGStreamerInterface::createFrameFromGstBuffer(GstBuffer *buffer, const GstVideoInfoDmaDrm &videoInfo)
 
    Creates a \l QVideoFrame that wraps a DMA-BUF-backed \a buffer using the format
    described by \a videoInfo.
 
    Requires GStreamer 1.24 or later with DMA-BUF video format support. If unsupported,
    returns an invalid \l QVideoFrame and logs a warning.
 
    The created frame shares ownership of the specified \c GstBuffer with the caller.
 
    \sa createFrameFromGstBuffer(GstBuffer *, const GstVideoInfo &), gstBuffer()
*/
 
QGStreamerInterface::~QGStreamerInterface() = default;
 
QT_END_NAMESPACE