QVideoFrameInput Class

The QVideoFrameInput class is used for providing custom video frames to QMediaRecorder or a video output through QMediaCaptureSession. More...

Header:	`#include <QVideoFrameInput>`
CMake:	`find_package(Qt6 REQUIRED COMPONENTS Multimedia)` `target_link_libraries(mytarget PRIVATE Qt6::Multimedia)`
qmake:	`QT += multimedia`
Since:	Qt 6.8
Inherits:	QObject

List of all members, including inherited members

Public Functions

	QVideoFrameInput(QObject *parent = nullptr)
	QVideoFrameInput(const QVideoFrameFormat &format, QObject *parent = nullptr)
virtual	~QVideoFrameInput() override
QMediaCaptureSession *	captureSession() const
QVideoFrameFormat	format() const
bool	sendVideoFrame(const QVideoFrame &frame)

Signals

void	readyToSendVideoFrame()

Detailed Description

QVideoFrameInput is only supported with the FFmpeg backend.

Custom video frames can be recorded by connecting a QVideoFrameInput and a QMediaRecorder to a QMediaCaptureSession. For a pull mode implementation, call sendVideoFrame() in response to the readyToSendVideoFrame() signal. In the snippet below this is done by connecting the signal to a slot in a custom media generator class. The slot function emits a another signal with a new video frame, which is connected to sendVideoFrame():

QMediaCaptureSession session;
QMediaRecorder recorder;
QVideoFrameInput videoInput;

session.setRecorder(&recorder);
session.setVideoFrameInput(&videoInput);

MediaGenerator generator; // Custom class providing video frames

connect(&videoInput, &QVideoFrameInput::readyToSendVideoFrame,
        &generator, &MediaGenerator::nextVideoFrame);
connect(&generator, &MediaGenerator::videoFrameReady,
        &videoInput, &QVideoFrameInput::sendVideoFrame);

recorder.record();

Here's a minimal implementation of the slot function that provides video frames:

void MediaGenerator::nextVideoFrame()
{
    QVideoFrame frame = nextFrame();
    emit videoFrameReady(frame);
}

For more details see readyToSendVideoFrame() and sendVideoFrame().

See also QMediaRecorder, QMediaCaptureSession, and QVideoSink.

Member Function Documentation

`[explicit]` QVideoFrameInput::QVideoFrameInput(QObject **parent* = nullptr)

Constructs a new QVideoFrameInput object with parent.

`[explicit]` QVideoFrameInput::QVideoFrameInput(const QVideoFrameFormat &format, QObject **parent* = nullptr)

Constructs a new QVideoFrameInput object with video frame format and parent.

The specified format will work as a hint for the initialization of the matching video encoder upon invoking QMediaRecorder::record(). If the format is not specified or not valid, the video encoder will be initialized upon sending the first frame. Sending of video frames with another pixel format and size after initialization of the matching video encoder might cause a performance penalty during recording.

We recommend specifying the format if you know in advance what kind of frames you're going to send.

`[override virtual noexcept]` QVideoFrameInput::~QVideoFrameInput()

Destroys the object.

QMediaCaptureSession *QVideoFrameInput::captureSession() const

Returns the capture session this video frame input is connected to, or a nullptr if the video frame input is not connected to a capture session.

Use QMediaCaptureSession::setVideoFrameInput() to connect the video frame input to a session.

QVideoFrameFormat QVideoFrameInput::format() const

Returns the video frame format that was specified upon construction of the video frame input.

`[signal]` void QVideoFrameInput::readyToSendVideoFrame()

Signals that a new frame can be sent to the video frame input. After receiving the signal, if you have frames to be sent, invoke sendVideoFrame once or in a loop until it returns false.

See also sendVideoFrame().

bool QVideoFrameInput::sendVideoFrame(const QVideoFrame &frame)

Sends QVideoFrame to QMediaRecorder or a video output through QMediaCaptureSession.

Returns true if the specified frame has been sent successfully to the destination. Returns false, if the frame hasn't been sent, which can happen if the instance is not assigned to QMediaCaptureSession, the session doesn't have video outputs or a media recorder, the media recorder is not started or its queue is full. The signal readyToSendVideoFrame will be sent as soon as the destination is able to handle a new frame.

Sending of an empty video frame is treated by QMediaRecorder as an end of the input stream. QMediaRecorder stops the recording automatically if QMediaRecorder::autoStop is true and all the inputs have reported the end of the stream.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.