QSoundEffect Class

QSoundEffect 类提供了一种播放低延迟音效的方法。更多内容...

标题：	`#include <QSoundEffect>`

CMake：	`find_package(Qt6 REQUIRED COMPONENTS Multimedia)` `target_link_libraries(mytarget PRIVATE Qt6::Multimedia)`
qmake：	`QT += multimedia`
在 QML 中：	SoundEffect
继承自：	QObject

所有成员列表（包括继承的成员）

公共类型

enum	Loop { Infinite }
enum	Status { Null, Loading, Ready, Error }

属性

audioDevice : QAudioDevice
loops : int
loopsRemaining : int
muted : bool

playing : bool
source : QUrl
status : Status
volume : float

公共函数

	QSoundEffect(QObject *parent = nullptr)
	QSoundEffect(const QAudioDevice &audioDevice, QObject *parent = nullptr)
virtual	~QSoundEffect() override
QAudioDevice	audioDevice()
bool	isLoaded() const
bool	isMuted() const
bool	isPlaying() const
int	loopCount() const
int	loopsRemaining() const
void	setAudioDevice(const QAudioDevice &device)
void	setLoopCount(int loopCount)
void	setMuted(bool muted)
void	setSource(const QUrl &url)
void	setVolume(float volume)
QUrl	source() const
QSoundEffect::Status	status() const
float	volume() const

公共插槽

void	play()
void	stop()

信号

void	audioDeviceChanged()
void	loadedChanged()
void	loopCountChanged()
void	loopsRemainingChanged()
void	mutedChanged()
void	playingChanged()
void	sourceChanged()
void	statusChanged()
void	volumeChanged()

静态公共成员

QStringList supportedMimeTypes()

详细说明

此类允许您以通常较低的延迟播放未压缩的音频文件（通常是 WAV 文件），适用于响应用户操作的“反馈”类型声音（例如虚拟键盘声音、弹出对话框的肯定或否定反馈，或者游戏声音）。如果低延迟并非关键因素，请考虑改用QMediaPlayer 类，因为它支持更多种类的媒体格式，且对资源的消耗较小。

本示例演示了如何播放一个循环播放、音量较小的音效：

QSoundEffect effect;
effect.setSource(QUrl::fromLocalFile("engine.wav"));
effect.setLoopCount(QSoundEffect::Infinite);
effect.setVolume(0.25f);
effect.play();

通常应重复使用该音效，这样可以预先完成所有解析和准备工作，仅在必要时触发播放。这有助于实现低延迟的音频播放。

    MyGame()
        : m_explosion(this)
    {
        m_explosion.setSource(QUrl::fromLocalFile("explosion.wav"));
        m_explosion.setVolume(0.25f);

        // Set up click handling etc.
        connect(clickSource, &QPushButton::clicked, &m_explosion, &QSoundEffect::play);
    }
private:
    QSoundEffect m_explosion;

由于 QSoundEffect 为实现低延迟播放需要消耗稍多的资源，平台可能会限制同时播放的声音效果数量。

成员类型文档

enum QSoundEffect::Loop

常数	值	描述
`QSoundEffect::Infinite`	`-2`	用作setLoopCount()函数的参数，用于实现无限循环

enum QSoundEffect::Status

常数	值	描述
`QSoundEffect::Null`	`0`	未设置源，或者源为空。
`QSoundEffect::Loading`	`1`	SoundEffect 正在尝试加载源文件。
`QSoundEffect::Ready`	`2`	源已加载并准备就绪，可以播放。
`QSoundEffect::Error`	`3`	操作过程中发生错误，例如加载源失败。

属性文档

audioDevice : QAudioDevice

返回QAudioDevice 实例。

访问函数：

QAudioDevice	audioDevice()
void	setAudioDevice(const QAudioDevice &device)

通知器信号：

void	audioDeviceChanged()

loops : int

该属性用于指定声音的播放次数。值为 0 或 1 表示声音仅播放一次；设置为SoundEffect.Infinite 可启用无限循环。

该值可在音效播放过程中进行修改，此时系统会将剩余循环次数更新为新值。

访问函数：

int	loopCount() const
void	setLoopCount(int loopCount)

通知信号：

void	loopCountChanged()

`[read-only]` loopsRemaining : int

该属性包含音效自动停止前剩余的循环次数，或者如果loops 中设置了QSoundEffect::Infinite ，则为。

访问函数：

int	loopsRemaining() const

通知信号：

void	loopsRemainingChanged()

muted : bool

此属性用于控制静音功能。当值为true 时，将静音此效果。

访问函数：

bool	isMuted() const
void	setMuted(bool muted)

通知信号：

void	mutedChanged()

`[read-only]` playing : bool

该属性用于指示音效是否正在播放。

访问函数：

bool	isPlaying() const

通知信号：

void	playingChanged()

source : QUrl

该属性存储要播放的音频的 URL。为了让SoundEffect 尝试加载该音频源，该 URL 必须存在，且应用程序必须对指定目录具有读取权限。

访问函数：

QUrl	source() const
void	setSource(const QUrl &url)

通知器信号：

void	sourceChanged()

`[read-only]` status : Status

该属性表示音效的当前状态，取值来自QSoundEffect::Status 枚举。

访问函数：

QSoundEffect::Status status() const

通知信号：

void	statusChanged()

volume : float

该属性控制音效播放的音量，范围从 0.0（静音）到 1.0（最大音量）。

访问函数：

float	volume() const
void	setVolume(float volume)

通知信号：

void	volumeChanged()

成员函数文档

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

使用给定的parent 创建一个QSoundEffect。

`[explicit]` QSoundEffect::QSoundEffect(const QAudioDevice &audioDevice, QObject **parent* = nullptr)

使用给定的audioDevice 和parent 创建一个QSoundEffect。

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

销毁此音效。

bool QSoundEffect::isLoaded() const

返回该音效是否已完成加载，source()。

bool QSoundEffect::isMuted() const

返回此音效是否已被静音

注：这是属性muted 的获取函数。

bool QSoundEffect::isPlaying() const

如果音效当前正在播放，则返回 true；否则返回 false

注意： 这是属性playing 的获取器 函数。

`[signal]` void QSoundEffect::loadedChanged()

当加载状态发生变化时，会发出loadedChanged 信号。

int QSoundEffect::loopCount() const

返回该音效在停止播放前将被播放的总次数。

有关当前剩余循环次数，请参阅loopsRemaining()方法。

注意： 这是属性loops 的获取器 函数。

另请参阅 setLoopCount()。

`[signal]` void QSoundEffect::loopCountChanged()

当初始循环次数发生变化时，会触发loopCountChanged 信号。

注意： 这是属性loops 的通知器 信号。

`[signal]` void QSoundEffect::loopsRemainingChanged()

当剩余循环次数发生变化时，会触发loopsRemainingChanged 信号。

注意： 这是属性loopsRemaining 的通知器 信号。

`[signal]` void QSoundEffect::mutedChanged()

当静音状态发生变化时，会触发mutedChanged 信号。

注意： 这是属性muted的通知信号。

`[slot]` void QSoundEffect::play()

开始播放音效，并根据 loops 属性中指定的次数循环播放该音效。

`[signal]` void QSoundEffect::playingChanged()

当播放属性发生变化时，会触发playingChanged 信号。

注意： 这是属性 `playing`的通知器 信号。

void QSoundEffect::setLoopCount(int loopCount)

将此音效的总播放次数设置为loopCount 。

将循环次数设置为 0 或 1 表示该音效仅播放一次；传入QSoundEffect::Infinite 则表示无限循环播放。在音效播放过程中可以更改循环次数，此时剩余循环次数将更新为新的loopCount 。

注意： 这是属性loops 的设置函数。

另请参阅 loopCount() 和loopsRemaining()。

void QSoundEffect::setMuted(bool muted)

设置是否静音此音效的播放。

如果muted 为true，则播放将被静音（关闭声音）；否则，播放将使用当前指定的volume()进行。

注意： 这是属性muted 的设置函数。

另请参阅 isMuted()。

void QSoundEffect::setSource(const QUrl &url)

将当前要播放的 URL 设置为url 。

注意： 这是属性source 的设置函数。

另请参阅 source()。

void QSoundEffect::setVolume(float volume)

将音效音量设置为volume 。

音量从0.0 （静音）线性调整至1.0 （最大音量）。超出此范围的值将被限制。

默认音量为1.0 。

UI 音量控件通常应采用非线性缩放。例如，使用对数刻度会产生感知响度的线性变化，这正是用户通常对音量控件的预期。更多详细信息请参阅QtAudio::convertVolume()。

注意： 属性volume 的设置函数。

另请参阅 volume()。

QUrl QSoundEffect::source() const

返回当前要播放的源的 URL

注意： 这是 source 属性的获取函数。

另请参阅 setSource()。

`[signal]` void QSoundEffect::sourceChanged()

当源发生变化时，会触发sourceChanged 信号。

注意： 这是属性source的通知信号。

QSoundEffect::Status QSoundEffect::status() const

返回此音效的当前状态。

注意： 这是 status 属性的获取函数。

`[signal]` void QSoundEffect::statusChanged()

当 status 属性发生变化时，会触发statusChanged 信号。

注意： 这是属性 `status`的通知 信号。

`[slot]` void QSoundEffect::stop()

停止当前播放。

`[static]` QStringList QSoundEffect::supportedMimeTypes()

返回该平台支持的 MIME 类型列表。

float QSoundEffect::volume() const

返回该音效的当前音量，范围为 0.0（静音）到 1.0（最大音量）。

注意： 这是 volume 属性的获取函数。

另请参阅 ` setVolume()`。

`[signal]` void QSoundEffect::volumeChanged()

当音量发生变化时，会触发volumeChanged 信号。

注意： 这是属性volume 的Notifier 信号。

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

QSoundEffect Class

公共类型

属性

公共函数

公共插槽

信号

静态公共成员

详细说明

成员类型文档

enum QSoundEffect::Loop

enum QSoundEffect::Status

属性文档

audioDevice : QAudioDevice

loops : int

[read-only] loopsRemaining : int

muted : bool

[read-only] playing : bool

source : QUrl

[read-only] status : Status

volume : float

成员函数文档

[explicit] QSoundEffect::QSoundEffect(QObject *parent = nullptr)

[explicit] QSoundEffect::QSoundEffect(const QAudioDevice &audioDevice, QObject *parent = nullptr)

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

bool QSoundEffect::isLoaded() const

bool QSoundEffect::isMuted() const

bool QSoundEffect::isPlaying() const

[signal] void QSoundEffect::loadedChanged()

int QSoundEffect::loopCount() const

[signal] void QSoundEffect::loopCountChanged()

[signal] void QSoundEffect::loopsRemainingChanged()

[signal] void QSoundEffect::mutedChanged()

[slot] void QSoundEffect::play()

[signal] void QSoundEffect::playingChanged()

void QSoundEffect::setLoopCount(int loopCount)

void QSoundEffect::setMuted(bool muted)

void QSoundEffect::setSource(const QUrl &url)

void QSoundEffect::setVolume(float volume)

QUrl QSoundEffect::source() const

[signal] void QSoundEffect::sourceChanged()

QSoundEffect::Status QSoundEffect::status() const

[signal] void QSoundEffect::statusChanged()

[slot] void QSoundEffect::stop()

[static] QStringList QSoundEffect::supportedMimeTypes()

float QSoundEffect::volume() const

[signal] void QSoundEffect::volumeChanged()

`[read-only]` loopsRemaining : int

`[read-only]` playing : bool

`[read-only]` status : Status

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

`[explicit]` QSoundEffect::QSoundEffect(const QAudioDevice &audioDevice, QObject **parent* = nullptr)

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

`[signal]` void QSoundEffect::loadedChanged()

`[signal]` void QSoundEffect::loopCountChanged()

`[signal]` void QSoundEffect::loopsRemainingChanged()

`[signal]` void QSoundEffect::mutedChanged()

`[slot]` void QSoundEffect::play()

`[signal]` void QSoundEffect::playingChanged()

`[signal]` void QSoundEffect::sourceChanged()

`[signal]` void QSoundEffect::statusChanged()

`[slot]` void QSoundEffect::stop()

`[static]` QStringList QSoundEffect::supportedMimeTypes()

`[signal]` void QSoundEffect::volumeChanged()