QtAudio Namespace

QtAudio 命名空间包含音频类所使用的枚举。更多内容...

头文件：	`#include <QtAudio>`

CMake：	`find_package(Qt6 REQUIRED COMPONENTS Multimedia)` `target_link_libraries(mytarget PRIVATE Qt6::Multimedia)`
qmake：	`QT += multimedia`

类型

enum	Error { NoError, OpenError, IOError, UnderrunError, FatalError }
enum	State { ActiveState, SuspendedState, StoppedState, IdleState }
enum	VolumeScale { LinearVolumeScale, CubicVolumeScale, LogarithmicVolumeScale, DecibelVolumeScale }

函数

float convertVolume(float volume, QtAudio::VolumeScale from, QtAudio::VolumeScale to)

详细说明

类型文档

enum QtAudio::Error

常数	值	描述
`QtAudio::NoError`	`0`	未发生错误
`QtAudio::OpenError`	`1`	打开音频设备时发生错误
`QtAudio::IOError`	`2`	在读写音频设备时发生错误。例如，当外部音频接口断开连接时，可能会发生这种情况。
`QtAudio::UnderrunError`	`3`	该值在 Qt-6.11 中已被废弃，且 Qt 不再触发此错误。请改观察QtAudio::State::IdleState 。音频数据传输到音频设备的速率不够快。
`QtAudio::FatalError`	`4`	发生不可恢复的错误，音频设备目前无法使用。

enum QtAudio::State

常数	值	描述
`QtAudio::ActiveState`	`0`	正在处理音频数据，该状态在调用 start() 之后设置，且在有可处理的音频数据期间保持有效。
`QtAudio::SuspendedState`	`1`	音频流处于暂停状态。在调用 suspend() 后，或当另一个流接管音频设备时进入此状态。在后一种情况下，调用 resume 将把音频设备的控制权交还给此流。通常仅应在用户请求时执行此操作。
`QtAudio::StoppedState`	`2`	音频设备已关闭，且未处理任何音频数据
`QtAudio::IdleState`	`3`	此状态表示音频系统因缓冲状况而暂时处于空闲状态。对于QAudioSink ，IdleState表示无法从QIODevice 读取足够的数据。对于QAudioSource ，当向QIODevice 提供数据的环形缓冲区已满时，系统将进入IdleState。此时，来自音频接口的任何新音频数据都将被丢弃，直到应用程序从QIODevice 读取数据，从而释放缓冲区空间。

enum QtAudio::VolumeScale

此枚举定义了不同的音量刻度。

常量	值	描述
`QtAudio::LinearVolumeScale`	`0`	线性刻度。`0.0` （0%）表示静音，`1.0` （100%）表示最大音量。所有具有音频音量的Qt Multimedia 类均采用线性刻度。
`QtAudio::CubicVolumeScale`	`1`	立方刻度。`0.0` （0%）表示静音，`1.0` （100%）表示最大音量。
`QtAudio::LogarithmicVolumeScale`	`2`	对数刻度。`0.0` (0%) 表示静音，`1.0` (100%) 表示最大音量。UI 音量控制通常应采用对数刻度。
`QtAudio::DecibelVolumeScale`	`3`	分贝（dB，振幅）对数刻度。`-200` 表示静音，`0` 表示最大音量。

另请参阅 QtAudio::convertVolume()。

函数文档

float QtAudio::convertVolume(float volume, QtAudio::VolumeScale from, QtAudio::VolumeScale to)

将音频volume from 为一个音量刻度to 另一个音量刻度，并返回结果。

根据具体情况，会使用不同的量表来表示音频音量。所有具有音频音量的Qt Multimedia 类都使用线性量表，原因是扬声器的响度是通过在线性量表上调节其电压来控制的。另一方面，人耳对响度的感知则是对数式的。因此，在大多数应用中，使用对数刻度进行音量控制更为合适。分贝刻度本质上是对数刻度，通常用于定义声级，在专业音频应用中常被用于用户界面音量控制。立方刻度是对对数刻度的一种计算成本较低的近似，它能对较低音量级别提供更精细的控制。

以下示例演示了如何在将音量值传递给QMediaPlayer 之前，对其进行转换。这样，当将音量滑块从 20 调至 30 时，听觉上感受到的音量增加程度与从 50 调至 60 时相同：

void applyVolume(int volumeSliderValue)
{
    // volumeSliderValue is in the range [0..100]

    qreal linearVolume = QtAudio::convertVolume(volumeSliderValue / qreal(100.0),
                                                QtAudio::LogarithmicVolumeScale,
                                                QtAudio::LinearVolumeScale);

    player.setVolume(qRound(linearVolume * 100));
}

另请参阅 VolumeScale 、QAudioSink::setVolume()、QAudioSource::setVolume() 以及QSoundEffect::setVolume()。

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