本页内容

QMediaRecorder Class

QMediaRecorder 类用于对捕获会话进行编码和录制。更多内容...

头文件: #include <QMediaRecorder>
CMake: find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(mytarget PRIVATE Qt6::Multimedia)
qmake: QT += multimedia
在 QML 中: MediaRecorder
继承自: QObject

公共类型

enum EncodingMode { ConstantQualityEncoding, ConstantBitRateEncoding, AverageBitRateEncoding, TwoPassEncoding }
enum Error { NoError, ResourceError, FormatError, OutOfSpaceError, LocationNotWritable }
enum Quality { VeryLowQuality, LowQuality, NormalQuality, HighQuality, VeryHighQuality }
enum RecorderState { StoppedState, RecordingState, PausedState }

属性

公共函数

QMediaRecorder(QObject *parent = nullptr)
virtual ~QMediaRecorder() override
QUrl actualLocation() const
void addMetaData(const QMediaMetaData &metaData)
int audioBitRate() const
int audioChannelCount() const
int audioSampleRate() const
bool autoStop() const
QMediaCaptureSession *captureSession() const
qint64 duration() const
QMediaRecorder::EncodingMode encodingMode() const
QMediaRecorder::Error error() const
QString errorString() const
bool isAvailable() const
QMediaFormat mediaFormat() const
QMediaMetaData metaData() const
QIODevice *outputDevice() const
QUrl outputLocation() const
QMediaRecorder::Quality quality() const
QMediaRecorder::RecorderState recorderState() const
void setAudioBitRate(int bitRate)
void setAudioChannelCount(int channels)
void setAudioSampleRate(int sampleRate)
void setAutoStop(bool autoStop)
void setEncodingMode(QMediaRecorder::EncodingMode mode)
void setMediaFormat(const QMediaFormat &format)
void setMetaData(const QMediaMetaData &metaData)
void setOutputDevice(QIODevice *device)
void setOutputLocation(const QUrl &location)
void setQuality(QMediaRecorder::Quality quality)
void setVideoBitRate(int bitRate)
void setVideoFrameRate(qreal frameRate)
void setVideoResolution(const QSize &size)
void setVideoResolution(int width, int height)
int videoBitRate() const
qreal videoFrameRate() const
QSize videoResolution() const

公共插槽

void pause()
void record()
void stop()

信号

void actualLocationChanged(const QUrl &location)
void audioBitRateChanged()
void audioChannelCountChanged()
void audioSampleRateChanged()
void autoStopChanged()
void durationChanged(qint64 duration)
void encodingModeChanged()
void errorChanged()
void errorOccurred(QMediaRecorder::Error error, const QString &errorString)
void mediaFormatChanged()
void metaDataChanged()
void qualityChanged()
void recorderStateChanged(QMediaRecorder::RecorderState state)
void videoBitRateChanged()
void videoFrameRateChanged()
void videoResolutionChanged()

详细说明

使用 QMediaRecorder 类对在QMediaCaptureSession 中生成的媒体进行编码和录制。您可以生成:

要录制媒体,请将生成器连接到相应的媒体捕获会话。

视频编码和录制的性能受硬件、操作系统、已安装的图形驱动程序以及输入视频格式的限制。如果QCamera 、QScreenCapture 或QWindowCapture 生成的视频帧速度快于QMediaRecorder 的编码和录制速度,录像器可能会丢弃一些帧。 当输入帧分辨率较高(例如 4K)且无法使用硬件加速编码时,这种情况很可能发生。如果您通过QVideoFrameInput 生成输入视频,当达到此限制且内部帧队列已满时,方法QVideoFrameInput::sendVideoFrame 将不执行任何操作,并返回false 。请依靠信号QVideoFrameInput::readyToSendVideoFrame 来判断录像器何时准备好再次接收新帧。 如果您无法更改视频帧的生成速率,且不希望出现丢帧情况,我们建议您在QVideoFrameInput 的基础上实现自己的帧队列,同时需考虑硬件的内存限制。

QMediaCaptureSession session;
QAudioInput audioInput;
session.setAudioInput(&audioInput);
QMediaRecorder recorder;
session.setRecorder(&recorder);
recorder.setQuality(QMediaRecorder::HighQuality);
recorder.setOutputLocation(QUrl::fromLocalFile("test.mp3"));
recorder.record();

成员类型文档

enum QMediaRecorder::EncodingMode

枚举编码模式。

常量值描述
QMediaRecorder::ConstantQualityEncoding0编码将力求保持恒定质量,并相应调整比特率。
QMediaRecorder::ConstantBitRateEncoding1编码将使用恒定比特率,并相应调整质量。
QMediaRecorder::AverageBitRateEncoding2编码将尝试保持平均比特率设置,但会根据需要增减比特率。
QMediaRecorder::TwoPassEncoding3媒体文件将首先经过处理以确定其特性,然后进行第二次处理,向需要的地方分配更多的比特。

enum QMediaRecorder::Error

常量值描述
QMediaRecorder::NoError0无错误。
QMediaRecorder::ResourceError1设备尚未就绪或不可用。
QMediaRecorder::FormatError2不支持当前格式。
QMediaRecorder::OutOfSpaceError3设备上没有剩余空间。
QMediaRecorder::LocationNotWritable4输出位置不可写。

enum QMediaRecorder::Quality

列举质量编码级别。

常量值
QMediaRecorder::VeryLowQuality0
QMediaRecorder::LowQuality1
QMediaRecorder::NormalQuality2
QMediaRecorder::HighQuality3
QMediaRecorder::VeryHighQuality4

enum QMediaRecorder::RecorderState

常量值描述
QMediaRecorder::StoppedState0记录器未处于活动状态。
QMediaRecorder::RecordingState1已请求录制。
QMediaRecorder::PausedState2录像机已暂停。

属性文档

[read-only] actualLocation : QUrl

该属性保存了最后一个媒体内容的实际位置。

当分配新的 `outputLocation ` 或非空的 `outputDevice ` 时,实际位置将被重置。当调用 `record()` 且 `outputDevice ` 为 `null ` 或不可写时,记录器将根据以下规则生成实际位置。

  • 如果outputLocation 为空、是一个目录或是一个没有扩展名的文件,则记录器会根据所选媒体格式和系统 MIME 类型生成相应的扩展名。
  • 如果outputLocation 是一个目录,录制器将在其中生成一个新文件名。
  • 如果 `outputLocation ` 为空、是一个目录或是一个没有扩展名的文件,则记录器会根据所选媒体格式和系统 MIME 类型生成一个适当的扩展名。如果 ` ` 是一个目录,则记录器会在该目录中生成一个新文件名。
  • 录制器会在输出 `recorderStateChanged(RecordingState)` 之前生成实际位置。

访问函数:

QUrl actualLocation() const

通知信号:

void actualLocationChanged(const QUrl &location)

audioBitRate : int

该属性存储压缩音频流的比特率,单位为比特/秒。

访问函数:

int audioBitRate() const
void setAudioBitRate(int bitRate)

通知信号:

audioChannelCount : int

该属性表示音频通道的数量。

访问函数:

int audioChannelCount() const
void setAudioChannelCount(int channels)

通知信号:

audioSampleRate : int

该属性存储音频采样率(单位:赫兹)。

访问函数:

int audioSampleRate() const
void setAudioSampleRate(int sampleRate)

通知信号:

autoStop : bool

此属性控制当所有媒体输入均已报告流结束或已被停用时,媒体录制器是否自动停止。

流结束通过发送一个空媒体帧来报告,您可以通过 `QVideoFrameInput ` 或 `QAudioBufferInput` 显式发送该帧。

视频输入(具体为QCamera 、QScreenCapture 和QWindowCapture )可通过函数setActive 禁用。

默认值为false 。

QMediaRecorder::autoStop 仅在 FFmpeg 后端下受支持。

访问函数:

bool autoStop() const
void setAutoStop(bool autoStop)

通知信号:

void autoStopChanged()

另请参见 QCamera 、QScreenCapture 和QWindowCapture 。

[read-only] duration : qint64

该属性存储以毫秒为单位的录制媒体时长。

访问函数:

qint64 duration() const

通知信号:

void durationChanged(qint64 duration)

encodingMode : QMediaRecorder::EncodingMode

该属性用于存储编码模式。

访问函数:

QMediaRecorder::EncodingMode encodingMode() const
void setEncodingMode(QMediaRecorder::EncodingMode mode)

通知信号:

另请参阅 EncodingMode 。

[read-only] error : QMediaRecorder::Error

返回当前的错误状态。

访问函数:

QMediaRecorder::Error error() const

通知信号:

void errorChanged()

另请参阅 errorString()。

[read-only] errorString : QString

返回一个描述当前错误状态的字符串。

访问函数:

QString errorString() const

通知信号:

void errorChanged()

另请参阅 error()。

mediaFormat : QMediaFormat

该属性存储录音机的当前QMediaFormat 。

调用record() 时,该属性的值可能会发生变化。若发生这种情况,将触发 mediaFormatChanged() 信号。当QMediaFormat::audioCodec 或QMediaFormat::fileFormat 属性被设置为 unspecified 时,此情况必然发生。如果视频源(QCamera 、QScreenCapture 或QVideoFrameInput )连接到QMediaCaptureSession ,则必须同时指定QMediaFormat::videoCodec 。 如果媒体后端不支持所选的文件格式或编解码器,QMediaFormat::audioCodec 和QMediaFormat::videoCodec 属性的值也可能发生变化。

如果请求了视频格式,但QMediaCaptureSession 没有连接视频源,则QMediaFormat::fileFormat 属性值也可能更改为仅支持audio 的格式。例如,如果QMediaFormat::fileFormat 设置为QMediaFormat::MPEG4 ,它可能会更改为QMediaFormat::Mpeg4Audio 。

应用程序可通过调用QMediaFormat::isSupported()函数,在录制开始前判断mediaFormat 是否会发生变化。在无任何视频输入的情况下进行录制时,若满足以下条件,record()将不会更改QMediaFormat :

在有视频输入的情况下进行录制时,若满足以下条件,mediaFormat 将保持不变:

注意: QMediaRecorder 在确定QMediaFormat::fileFormat 时,不会考虑outputLocation 属性中的文件名扩展名;如果指定了扩展名,则不会调整outputLocation QUrl 的扩展名以匹配所选文件格式。 因此,应用程序应确保将QMediaRecorder::mediaFormat::fileFormat 设置为与文件扩展名一致,或者不指定文件扩展名。如果未指定文件扩展名,actualLocation 文件扩展名将更新为与录制所用的文件格式一致。

访问函数:

QMediaFormat mediaFormat() const
void setMediaFormat(const QMediaFormat &format)

通知信号:

void mediaFormatChanged()

另请参阅 QMediaFormat::isSupported() 和actualLocation 。

metaData : QMediaMetaData

返回与该录制内容关联的元数据。

访问函数:

QMediaMetaData metaData() const
void setMetaData(const QMediaMetaData &metaData)

通知信号:

outputLocation : QUrl

该属性存储媒体内容的目标位置。

设置位置可能会失败,例如当服务仅支持本地文件系统位置,但传入的却是网络 URL 时。如果操作失败,将触发errorOccurred() 信号。

如果已为录制器分配了一个可写入的outputDevice ,则会忽略输出位置。此行为将来可能会发生变化,因此我们建议仅设置一个输出,即outputLocation 或outputDevice 。

输出位置可以为空、一个目录或一个文件。目录或文件的路径可以是相对路径或绝对路径。record() 方法会根据指定的输出位置和系统特定设置生成实际位置。详情请参阅actualLocation 属性的说明。

访问函数:

QUrl outputLocation() const
void setOutputLocation(const QUrl &location)

另请参阅 actualLocation 和outputDevice()。

quality : Quality

返回录音质量。

访问函数:

QMediaRecorder::Quality quality() const
void setQuality(QMediaRecorder::Quality quality)

通知信号:

[read-only] recorderState : QMediaRecorder::RecorderState

该属性保存了媒体录制器的当前状态。

state 属性代表用户请求,并在调用record()、pause() 或stop() 时同步更新。当录制失败时,录制器的状态也可能异步发生变化。

访问函数:

QMediaRecorder::RecorderState recorderState() const

通知信号:

void recorderStateChanged(QMediaRecorder::RecorderState state)

[since 6.6] videoBitRate : int

该属性以比特/秒为单位存储压缩视频流的比特率。

该枚举在 Qt 6.6 中引入。

访问函数:

int videoBitRate() const
void setVideoBitRate(int bitRate)

通知信号:

[since 6.6] videoFrameRate : qreal

该属性存储编码时使用的视频帧率。

如果将此属性设置为正帧率,QMediaRecorder 将尝试以该帧率进行编码。如果视频源和编码器的帧率不同,为了达到目标帧率,源视频中的帧可能会被丢弃或重复。

如果保留默认值(-1)或设置为其他非正值,QMediaRecorder 将根据视频源和编解码器的限制尝试做出最佳选择。

此枚举类型在 Qt 6.6 中引入。

访问函数:

qreal videoFrameRate() const
void setVideoFrameRate(qreal frameRate)

通知器信号:

[since 6.6] videoResolution : QSize

该属性存储编码后视频的分辨率。

若QSize 为空,则表示录像机将根据视频源的可用信息和编解码器的限制,选择最佳分辨率。

该枚举类型自 Qt 6.6 起引入。

访问函数:

QSize videoResolution() const
void setVideoResolution(const QSize &size)
void setVideoResolution(int width, int height)

通知信号:

成员函数文档

QMediaRecorder::QMediaRecorder(QObject *parent = nullptr)

创建一个媒体记录器。该媒体记录器是parent 的子类。

[override virtual noexcept] QMediaRecorder::~QMediaRecorder()

销毁一个媒体录制器对象。

[signal] void QMediaRecorder::actualLocationChanged(const QUrl &location)

表示录制媒体的实际location 已发生变化。该信号通常在录制开始时发出。

注意: 这是属性actualLocation的通知 信号。

void QMediaRecorder::addMetaData(const QMediaMetaData &metaData)

将metaData 添加到录制的媒体中。

int QMediaRecorder::audioBitRate() const

返回压缩音频流的比特率,单位为比特/秒。

注意: 这是 audioBitRate 属性的获取器 函数。

另请参阅 setAudioBitRate()。

[signal] void QMediaRecorder::audioBitRateChanged()

当录音音频比特率发生变化时触发该信号。

注意: 这是属性audioBitRate的通知 信号。

int QMediaRecorder::audioChannelCount() const

返回音频通道的数量。

注意: 这是属性 audioChannelCount 的获取器 函数。

另请参阅 setAudioChannelCount()。

[signal] void QMediaRecorder::audioChannelCountChanged()

当录音音频通道数量发生变化时触发该信号。

注意: 这是属性 `audioChannelCount`的通知 信号。

int QMediaRecorder::audioSampleRate() const

返回音频采样率(单位:赫兹)。

注意: 这是属性 audioSampleRate 的获取 函数。

另请参阅 ` setAudioSampleRate()`。

[signal] void QMediaRecorder::audioSampleRateChanged()

当录音的音频采样率发生变化时触发该信号。

注意: 这是属性 `audioSampleRate`的通知 信号。

QMediaCaptureSession *QMediaRecorder::captureSession() const

返回媒体捕获会话。

[signal] void QMediaRecorder::durationChanged(qint64 duration)

表示已录制媒体的duration 属性已发生变化。

注意: 这是属性“duration”的通知 信号。

QMediaRecorder::EncodingMode QMediaRecorder::encodingMode() const

返回编码模式。

注意: 这是对属性 encodingMode的获取 函数。

另请参阅 setEncodingMode() 和EncodingMode 。

[signal] void QMediaRecorder::encodingModeChanged()

当编码模式发生变化时触发该信号。

注意: 这是属性encodingMode的通知 信号。

[signal] void QMediaRecorder::errorOccurred(QMediaRecorder::Error error, const QString &errorString)

表示已发生error 错误,且errorString 中包含该错误的描述。

bool QMediaRecorder::isAvailable() const

如果媒体录制服务已准备就绪,则返回true 。

[signal] void QMediaRecorder::metaDataChanged()

表示媒体对象的元数据已发生变化。

如果多个元数据元素发生变化,则仅触发一次 metaDataChanged() 信号。

注意: 这是属性metaData 的Notifier 信号。

QIODevice *QMediaRecorder::outputDevice() const

返回媒体内容的输出 I/O 设备。

另请参阅 setOutputDevice()。

[slot] void QMediaRecorder::pause()

暂停录音。

录制器的状态将变为QMediaRecorder::PausedState 。

根据平台的不同,可能不支持暂停录制。在这种情况下,录制器的状态保持不变。

[signal] void QMediaRecorder::qualityChanged()

当录制质量发生变化时发出信号。

注意: 这是属性quality的通知器 信号。

[slot] void QMediaRecorder::record()

开始录制。

虽然记录器的状态会立即变为 c{QMediaRecorder::RecordingState},但录制可能以异步方式开始。

如果录制失败,则会发出error() 信号,并将录制器的状态重置回QMediaRecorder::StoppedState 。

此方法会根据其生成规则更新actualLocation 。

注意:在 移动设备上 ,录制将按照调用 record 时设备的方向进行,并在录制期间锁定该方向。为避免用户界面出现异常,建议在录制进行期间,使用QWindow 的 contentOrientation 属性将用户界面锁定为与设备相同的方向,并在录制完成后再次解锁。

QMediaRecorder::RecorderState QMediaRecorder::recorderState() const

返回当前媒体录制器的状态。

注意: 这是 recorderState 属性的获取 函数。

另请参阅 QMediaRecorder::RecorderState 。

[signal] void QMediaRecorder::recorderStateChanged(QMediaRecorder::RecorderState state)

表示媒体录制器的state 属性已发生变化。

注意: 这是属性recorderState的通知 信号。

void QMediaRecorder::setAudioBitRate(int bitRate)

将音频bitRate 设置为每秒比特数。

注意: 这是属性audioBitRate 的设置 函数。

另请参阅 audioBitRate()。

void QMediaRecorder::setAudioChannelCount(int channels)

设置音频channels 的数量。

值为 -1 表示录音机应根据音频源的可用信息和编解码器的限制进行最佳选择。

注意: 属性audioChannelCount 的设置 函数。

另请参阅 audioChannelCount()。

void QMediaRecorder::setAudioSampleRate(int sampleRate)

设置音频sampleRate (单位:赫兹)。

-1 表示录音机应根据音频源提供的信息以及编解码器的限制,做出最佳选择。

注意: 这是属性audioSampleRate 的设置 函数。

另请参阅 audioSampleRate()。

void QMediaRecorder::setEncodingMode(QMediaRecorder::EncodingMode mode)

设置编码mode 参数。

如果设置了ConstantQualityEncoding ,则使用质量编码参数并忽略比特率;否则,使用比特率。

注意: 这是属性encodingMode 的设置 函数。

另请参阅 encodingMode() 和EncodingMode 。

void QMediaRecorder::setMetaData(const QMediaMetaData &metaData)

将元数据设置为metaData 。

注意:为 确保元数据设置正确,应在开始录制前进行设置。一旦开始录制,所设置的任何元数据都将附加到下一次录制中。

注意: 这是属性metaData 的设置 函数。

另请参阅 metaData()。

void QMediaRecorder::setOutputDevice(QIODevice *device)

设置媒体内容的输出I/O设备。

在开始录制之前,必须已以WriteOnly 或ReadWrite 模式打开device 。

媒体录制器不会获取指定device 的所有权。如果录制已开始,则必须保持该设备处于活动状态并保持打开,直到发出recorderStateChanged(StoppedState) 信号为止。

除非指定的device 为null ,否则此方法会立即重置actualLocation 。

如果为录制器分配了可写输出设备,则会忽略 `outputLocation `,且在录制开始时不会生成 `actualLocation `。此行为未来可能会发生变化,因此我们建议仅设置一个输出,即 `outputLocation ` 或 `outputDevice` 之一。

QMediaRecorder::setOutputDevice 仅在 FFmpeg 后端下受支持。

另请参阅 outputDevice() 和outputLocation 。

void QMediaRecorder::setVideoBitRate(int bitRate)

将视频bitRate 设置为每秒比特数。

注意: 这是属性videoBitRate 的设置 函数。

另请参阅 videoBitRate()。

void QMediaRecorder::setVideoFrameRate(qreal frameRate)

设置视频编码为frameRate 。

注意: 这是属性videoFrameRate 的设置 函数。

另请参阅 videoFrameRate()。

void QMediaRecorder::setVideoResolution(const QSize &size)

将编码视频的分辨率设置为size 。

传递一个空的QSize ,以让录像机根据视频源的可用信息和编解码器的限制来选择最佳分辨率。

注意: 这是属性videoResolution 的设置 函数。

另请参阅 videoResolution()。

void QMediaRecorder::setVideoResolution(int width, int height)

设置编码视频分辨率的width 和height 属性。

注意: 这是属性videoResolution 的设置 函数。

这是一个重载函数。

[slot] void QMediaRecorder::stop()

录像机将停止录制。不过,处理待处理的视频和音频数据可能仍需一些时间。当媒体录像机的状态变为“QMediaRecorder::StoppedState ”时,录制即告完成。

int QMediaRecorder::videoBitRate() const

返回压缩视频流的比特率(单位:比特/秒)。

注意: 这是 videoBitRate 属性的获取 函数。

另请参阅 setVideoBitRate()。

[signal] void QMediaRecorder::videoBitRateChanged()

当录制视频的比特率发生变化时触发信号。

注意: 这是属性videoBitRate的通知 信号。

qreal QMediaRecorder::videoFrameRate() const

返回视频编码的帧率。

注意: 这是 videoFrameRate 属性的获取 函数。

另请参阅 ` setVideoFrameRate()`。

[signal] void QMediaRecorder::videoFrameRateChanged()

当视频编码帧率发生变化时触发该信号。

注意: 这是属性videoFrameRate的通知 信号。

QSize QMediaRecorder::videoResolution() const

返回编码后视频的分辨率。

注意: 这是 videoResolution 属性的获取器 函数。

另请参阅 ` setVideoResolution()`。

[signal] void QMediaRecorder::videoResolutionChanged()

当视频录制分辨率发生变化时触发该信号。

注意: 这是属性videoResolution的通知 信号。

© 2026 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.