PySide6.QtMultimedia.QMediaRecorder

class QMediaRecorder

The QMediaRecorder class is used for encoding and recording a capture session. More…

Inheritance diagram of PySide6.QtMultimedia.QMediaRecorder

Synopsis

Properties

Methods

Slots

Signals

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

Use the QMediaRecorder class to encode and record media generated in QMediaCaptureSession . You can generate:

To record media, connect a generator to a corresponding media capture session.

Performance of video encoding and recording is limited by the hardware, the operating system, the installed graphic drivers, and the input video format. If QCamera, QScreenCapture, or QWindowCapture produces video frames faster than QMediaRecorder can encode and record them, the recorder may drop some frames. This is likely to occur if the input frame resolution is high, 4K for example, and hardware-accelerated encoding is unavailable. If you generate input video via QVideoFrameInput, the method QVideoFrameInput::sendVideoFrame will do nothing and return false whenever this limitation is reached and the internal frame queue is full. Rely on the signal QVideoFrameInput::readyToSendVideoFrame to know when the recorder is ready to receive new frames again. If you cannot change the rate of video frame generation and dropping frames is undesirable, we recommend implementing your own frame queue on top of QVideoFrameInput, considering the memory limitations of the hardware.

session = QMediaCaptureSession()
audioInput = QAudioInput()
session.setAudioInput(input)
recorder = QMediaRecorder()
session.setRecorder(recorder)
recorder.setQuality(QMediaRecorder.HighQuality)
recorder.setOutputLocation(QUrl.fromLocalFile("test.mp3"))
recorder.record()
class Quality

Enumerates quality encoding levels.

Constant

Description

QMediaRecorder.VeryLowQuality

QMediaRecorder.LowQuality

QMediaRecorder.NormalQuality

QMediaRecorder.HighQuality

QMediaRecorder.VeryHighQuality

Added in version 6.1.

class EncodingMode

Enumerates encoding modes.

Constant

Description

QMediaRecorder.ConstantQualityEncoding

Encoding will aim to have a constant quality, adjusting bitrate to fit.

QMediaRecorder.ConstantBitRateEncoding

Encoding will use a constant bit rate, adjust quality to fit.

QMediaRecorder.AverageBitRateEncoding

Encoding will try to keep an average bitrate setting, but will use more or less as needed.

QMediaRecorder.TwoPassEncoding

The media will first be processed to determine the characteristics, and then processed a second time allocating more bits to the areas that need it.

Added in version 6.1.

class RecorderState

Constant

Description

QMediaRecorder.StoppedState

The recorder is not active.

QMediaRecorder.RecordingState

The recording is requested.

QMediaRecorder.PausedState

The recorder is paused.

Added in version 6.1.

class Error

Constant

Description

QMediaRecorder.NoError

No Errors.

QMediaRecorder.ResourceError

Device is not ready or not available.

QMediaRecorder.FormatError

Current format is not supported.

QMediaRecorder.OutOfSpaceError

No space left on device.

QMediaRecorder.LocationNotWritable

The output location is not writable.

Added in version 6.1.

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property actualLocationᅟ: QUrl

This property holds The actual location of the last media content..

The actual location is reset when a new outputLocation or a non-null outputDevice is assigned. When record() is invoked and outputDevice is null or not writable, the recorder generates the actual location basing on the following rules.

  • If outputLocation is empty, a directory, or a file without an extension, the recorder generates the appropriate extension based on the selected media format and system MIME types.

  • If outputLocation is a directory, the recorder generates a new file name within it.

  • If outputLocation is empty, the recorder generates a new file name in the system-specific directory for audio or video.

  • The recorder generates the actual location before emitting recorderStateChanged(RecordingState).

Access functions:
property audioBitRateᅟ: int
Access functions:
property audioChannelCountᅟ: int
Access functions:
property audioSampleRateᅟ: int
Access functions:
property autoStopᅟ: bool

This property controls whether the media recorder stops automatically when all media inputs have reported the end of the stream or have been deactivated.

The end of the stream is reported by sending an empty media frame, which you can send explicitly via QVideoFrameInput or QAudioBufferInput .

Video inputs, specificly, QCamera , QScreenCapture and QWindowCapture , can be deactivated via the function setActive.

Defaults to false.

QMediaRecorder::autoStop is only supported with the FFmpeg backend.

Access functions:
property durationᅟ: int

This property holds the recorded media duration in milliseconds..

Access functions:
property encodingModeᅟ: QMediaRecorder.EncodingMode
Access functions:
property errorᅟ: QMediaRecorder.Error

Returns the current error state.

See also

errorString()

Access functions:
property errorStringᅟ: str

Returns a string describing the current error state.

See also

error()

Access functions:
property mediaFormatᅟ: QMediaFormat

This property holds This property holds the current QMediaFormat of the recorder..

The value of this property may change when invoking record() . If this happens, the mediaFormatChanged signal will be emitted. This will always happen if the audioCodec or fileFormat properties are set to unspecified. If a video source ( QCamera , QScreenCapture , or QVideoFrameInput ) is connected to the QMediaCaptureSession , videoCodec must also be specified. The audioCodec and videoCodec property values may also change if the media backend does not support the selected file format or codec.

The fileFormat property value may also change to an audio only format if a video format was requested, but QMediaCaptureSession does not have a video source connected. For example, if fileFormat is set to QMediaFormat::FileFormat::MPEG4, it may be changed to QMediaFormat::FileFormat::Mpeg4Audio.

Applications can determine if mediaFormat will change before recording starts by calling the isSupported() function. When recording without any video inputs, record() will not be changed the QMediaFormat if the following is true:

When recording with video input, mediaFormat will not be changed if the following is true:

Note

The QMediaRecorder does not take the file name extension from the outputLocation property into account when determining the fileFormat , and will not adjust the extension of the outputLocation QUrl to match the selected file format if an extension is specified. Applications should therefore make sure to set the QMediaRecorder::mediaFormat::fileFormat to match the file extension, or not specify a file extension. If no file extension is specified, the actualLocation file extension will be updated to match the file format used for recording.

See also

isSupported() actualLocation

Access functions:
property metaDataᅟ: QMediaMetaData

Returns the metaData associated with the recording.

Access functions:
property outputLocationᅟ: QUrl

This property holds The destination location of media content..

Setting the location can fail, for example when the service supports only local file system locations but a network URL was passed. If the operation fails, the errorOccured() signal is emitted.

The output location is ignored if a writable outputDevice has been assigned to the recorder. This behavior may change in the future, so we recommend setting only one output, either outputLocation or outputDevice.

The output location can be empty, a directory, or a file. The path to a directory or file can be relative or absolute. The record() method generates the actual location according to the specified output location and system-specific settings. Refer to the actualLocation property description for details.

Access functions:
property qualityᅟ: QMediaRecorder.Quality

Returns the recording quality.

Access functions:
property recorderStateᅟ: QMediaRecorder.RecorderState

This property holds The current state of the media recorder..

The state property represents the user request and is changed synchronously during record() , pause() or stop() calls. Recorder state may also change asynchronously when recording fails.

Access functions:
property videoBitRateᅟ: int
Access functions:
property videoFrameRateᅟ: float
Access functions:
property videoResolutionᅟ: QSize
Access functions:
__init__([parent=None])
Parameters:

parent – QObject

Constructs a media recorder. The media recorder is a child of parent.

actualLocation()
Return type:

QUrl

Getter of property actualLocationᅟ .

actualLocationChanged(location)
Parameters:

location – QUrl

Signals that the actual location of the recorded media has changed. This signal is usually emitted when recording starts.

Notification signal of property actualLocationᅟ .

addMetaData(metaData)
Parameters:

metaData – QMediaMetaData

Adds metaData to the recorded media.

audioBitRate()
Return type:

int

Returns the bit rate of the compressed audio stream in bits per second.

Getter of property audioBitRateᅟ .

audioBitRateChanged()

Signals when the recording audio bit rate changes.

Notification signal of property audioBitRateᅟ .

audioChannelCount()
Return type:

int

Returns the number of audio channels.

Getter of property audioChannelCountᅟ .

audioChannelCountChanged()

Signals when the recording audio channel count changes.

Notification signal of property audioChannelCountᅟ .

audioSampleRate()
Return type:

int

Returns the audio sample rate in Hz.

Getter of property audioSampleRateᅟ .

audioSampleRateChanged()

Signals when the recording audio sample rate changes.

Notification signal of property audioSampleRateᅟ .

autoStop()
Return type:

bool

See also

setAutoStop()

Getter of property autoStopᅟ .

autoStopChanged()

Notification signal of property autoStopᅟ .

captureSession()
Return type:

QMediaCaptureSession

Returns the media capture session.

duration()
Return type:

int

Getter of property durationᅟ .

durationChanged(duration)
Parameters:

duration – int

Signals that the duration of the recorded media has changed.

Notification signal of property durationᅟ .

encoderSettingsChanged()

Note

This function is deprecated.

Signals when the encoder settings change.

encodingMode()
Return type:

EncodingMode

Returns the encoding mode.

Getter of property encodingModeᅟ .

encodingModeChanged()

Signals when the encoding mode changes.

Notification signal of property encodingModeᅟ .

error()
Return type:

Error

Getter of property errorᅟ .

errorChanged()

Notification signal of property errorᅟ .

errorOccurred(error, errorString)
Parameters:

  • error – Error

  • errorString – str

Signals that an error has occurred, with errorString containing a description of the error.

errorString()
Return type:

str

Getter of property errorStringᅟ .

isAvailable()
Return type:

bool

Returns true if media recorder service ready to use.

mediaFormat()
Return type:

QMediaFormat

See also

setMediaFormat()

Getter of property mediaFormatᅟ .

mediaFormatChanged()

Notification signal of property mediaFormatᅟ .

metaData()
Return type:

QMediaMetaData

See also

setMetaData()

Getter of property metaDataᅟ .

metaDataChanged()

Signals that a media object’s meta-data has changed.

If multiple meta-data elements are changed metaDataChanged() is emitted once.

Notification signal of property metaDataᅟ .

outputDevice()
Return type:

QIODevice

Returns the output IO device for media content.

outputLocation()
Return type:

QUrl

See also

setOutputLocation()

Getter of property outputLocationᅟ .

pause()

Pauses recording.

The recorder state is changed to PausedState .

Depending on the platform, pausing recording may be not supported. In this case the recorder state is unchanged.

quality()
Return type:

Quality

See also

setQuality()

Getter of property qualityᅟ .

qualityChanged()

Signals when the recording quality changes.

Notification signal of property qualityᅟ .

record()

Starts recording.

While the recorder state is changed immediately to c{ RecordingState }, recording may start asynchronously.

If recording fails error() signal is emitted with recorder state being reset back to QMediaRecorder::StoppedState.

This method updates actualLocation according to its generation rules.

Note

On mobile devices, recording will happen in the orientation the device had when calling record and is locked for the duration of the recording. To avoid artifacts on the user interface, we recommend to keep the user interface locked to the same orientation as long as the recording is ongoing using the contentOrientation property of QWindow and unlock it again once the recording is finished.

recorderState()
Return type:

RecorderState

Returns the current media recorder state.

See also

RecorderState

Getter of property recorderStateᅟ .

recorderStateChanged(state)
Parameters:

state – RecorderState

Signals that a media recorder’s state has changed.

Notification signal of property recorderStateᅟ .

setAudioBitRate(bitRate)
Parameters:

bitRate – int

Sets the audio bitRate in bits per second.

See also

audioBitRate()

Setter of property audioBitRateᅟ .

setAudioChannelCount(channels)
Parameters:

channels – int

Sets the number of audio channels.

A value of -1 indicates the recorder should make an optimal choice based on what is available from the audio source and the limitations of the codec.

Setter of property audioChannelCountᅟ .

setAudioSampleRate(sampleRate)
Parameters:

sampleRate – int

Sets the audio sampleRate in Hz.

A value of -1 indicates the recorder should make an optimal choice based on what is available from the audio source, and the limitations of the codec.

Setter of property audioSampleRateᅟ .

setAutoStop(autoStop)
Parameters:

autoStop – bool

See also

autoStop()

Setter of property autoStopᅟ .

setEncodingMode(mode)
Parameters:

mode – EncodingMode

Sets the encoding mode setting.

If ConstantQualityEncoding is set, the quality encoding parameter is used and bit rates are ignored, otherwise the bitrates are used.

Setter of property encodingModeᅟ .

setMediaFormat(format)
Parameters:

format – QMediaFormat

See also

mediaFormat()

Setter of property mediaFormatᅟ .

setMetaData(metaData)
Parameters:

metaData – QMediaMetaData

Sets the meta data to metaData.

Note

To ensure that meta-data is set correctly, it should be set before starting the recording. Once the recording is started, any meta-data set will be attached to the next recording.

See also

metaData()

Setter of property metaDataᅟ .

setOutputDevice(device)
Parameters:

device – QIODevice

Set the output IO device for media content.

The device must have been opened in the WriteOnly or ReadWrite modes before the recording starts.

The media recorder doesn’t take ownership of the specified device. If the recording has been started, the device must be kept alive and open until the signal recorderStateChanged(StoppedState) is emitted.

This method resets actualLocation immediately unless the specified device is null.

If a writable output device is assigned to the recorder, outputLocation is ignored, and actualLocation is not generated when recording starts. This behavior may change in the future, so we recommend setting only one output, either outputLocation or outputDevice.

QMediaRecorder::setOutputDevice is only supported with the FFmpeg backend.

setOutputLocation(location)
Parameters:

location – QUrl

See also

outputLocation()

Setter of property outputLocationᅟ .

setQuality(quality)
Parameters:

quality – Quality

See also

quality()

Setter of property qualityᅟ .

setVideoBitRate(bitRate)
Parameters:

bitRate – int

Sets the video bitRate in bits per second.

See also

videoBitRate()

Setter of property videoBitRateᅟ .

setVideoFrameRate(frameRate)
Parameters:

frameRate – float

Sets the video frameRate.

A value of 0 indicates the recorder should make an optimal choice based on what is available from the video source and the limitations of the codec.

See also

videoFrameRate()

Setter of property videoFrameRateᅟ .

setVideoResolution(size)
Parameters:

size – QSize

Sets the resolution of the encoded video to size.

Pass an empty QSize to make the recorder choose an optimal resolution based on what is available from the video source and the limitations of the codec.

Setter of property videoResolutionᅟ .

setVideoResolution(width, height)
Parameters:

  • width – int

  • height – int

Sets the width and height of the resolution of the encoded video.

This is an overloaded function.

stop()

The recorder will stop the recording. Processing pending video and audio data might however still take some time. The recording is finished, once the state of the media recorder changes to StoppedState .

videoBitRate()
Return type:

int

Returns the bit rate of the compressed video stream in bits per second.

Getter of property videoBitRateᅟ .

videoBitRateChanged()

Signals when the recording video bit rate changes.

Notification signal of property videoBitRateᅟ .

videoFrameRate()
Return type:

float

Returns the video frame rate.

Getter of property videoFrameRateᅟ .

videoFrameRateChanged()

Signals when the recording video frame rate changes.

Notification signal of property videoFrameRateᅟ .

videoResolution()
Return type:

QSize

Returns the resolution of the encoded video.

Getter of property videoResolutionᅟ .

videoResolutionChanged()

Signals when the video recording resolution changes.

Notification signal of property videoResolutionᅟ .