音频概述

音频功能

Qt Multimedia 提供一系列音频类，涵盖音频输入、输出和处理的低级和高级方法。

音频实现细节

播放压缩音频

要播放非简单、未压缩音频的媒体或音频文件，可使用QMediaPlayer C++ 类或MediaPlayer QML 类型。如果需要，QMediaPlayer 类和相关 QML 类型也能播放视频。

媒体播放器需要连接到QAudioOutput 对象（或 QMLAudioOutput 元素）才能播放音频。

以下是使用 C++ 播放本地文件的方法：

player = new QMediaPlayer;
audioOutput = new QAudioOutput;
player->setAudioOutput(audioOutput);
// ...
player->setSource(QUrl::fromLocalFile("/Users/me/Music/coolsong.mp3"));
audioOutput->setVolume(0.5);
player->play();

QML 中的相同功能：

MediaPlayer {
    audioOutput: AudioOutput {}
    source: "file:///path/to/my/music.mp3"
    Component.onCompleted: { play() }
}

将音频录制到文件

要将音频录制到文件，您需要创建一个捕获会话，并连接音频输入和录音机。这些元素通过QMediaCaptureSession 、QAudioInput 和QMediaRecorder 类实现。默认构建的QAudioInput 选择系统默认的音频输入。录音机通过简单的 record() 和 stop() 函数控制录音过程。此外，您还可以用它来选择输出位置、音频编码器或文件容器格式。

在 C++ 中，使用默认麦克风录制音频的会话如下：

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

在 QML 中，可以通过以下方式实现同样的效果：

CaptureSession {
    audioInput: AudioInput {}
    mediaRecorder: MediaRecorder {
        id: recorder
        outputLocation: "file:///path/to/test.mp3"
    }
    Component.onCompleted: { recorder.record() }
}

QMediaCaptureSession QML 还支持更复杂的用例，如图像捕捉或视频录制。

低延迟音效

除了对声音设备的原始访问外，QSoundEffect 类（和SoundEffect QML 类型）还提供了一种更抽象的声音播放方式。通过该类，您可以指定WAV 格式文件，然后在必要时以低延迟方式播放。

您可以调整

Number of loops 以何种方式播放音效。
Volume 的音效。
Muting 的声音效果。

低电平音频输入和输出

Qt Multimedia 的 C++ API 提供了用于原始访问音频输入和输出设备的类，允许应用程序从麦克风等设备接收原始数据，并将原始数据写入扬声器或其他设备。一般来说，这些类不进行任何音频解码或其他处理，但它们可以支持不同类型的原始音频数据。

QAudioSink 类提供原始音频数据输出，而QAudioSource 则提供原始音频数据输入。可用的硬件决定了哪些音频输出和输入可用。

使用 QIODevice 进行推拉操作

低级音频类可在两种模式下运行--push 和pull 。在pull 模式下，音频设备通过给它一个QIODevice 来启动。对于输出设备，当需要更多音频数据时，QAudioSink 类将从QIODevice （使用QIODevice::read() ）中提取数据。相反，对于带有QAudioSource 的pull 模式，当音频数据可用时，数据将直接写入QIODevice 。

在push 模式下，音频设备会提供一个QIODevice 实例，可根据需要写入或读取。

注意： QIODevice 不会立即访问音频设备，而是在内部缓冲数据。这意味着QIODevice 可随时用于从应用线程写入或读取数据，并增加了通常为 250 毫秒的缓冲时间。如果应用程序向QIODevice 传输音频数据的速度不够快（对于QAudioSink ），或者读取QIODevice 的速度不够快，就会出现音频中断。

基于回调的接口

除了使用基于QIODevice 的接口外，低级音频类还提供了基于回调的接口，允许用户注册一个回调，当音频设备需要或提供更多数据时，音频线程就会调用该回调。这样可以大大降低音频处理的延迟，因为应用程序可以直接在音频线程上处理数据。

{ QAudioFormatformat;// 设置格式，例如format.setSampleRate(44100); format.setChannelCount(2); format.setSampleFormat(QAudioFormat::Float)；    QAudioDeviceinfo(QMediaDevices::defaultAudioOutput());if(!info.isFormatSupported(format)) {        qWarning() << "Raw audio format not supported by backend, cannot play audio.";
       return; } audio= newQAudioSink(format, this);floatphaseIncrement= 2 *M_PI* 220.0 /format.sampleRate();// 220 Hz 正弦波 audio->start([&phase,phaseIncrement](QSpan<float>interleavedAudioBuffer) {// 音频回调不应调用任何可能阻塞的函数 // 用正弦波填充音频缓冲区 const intsampleCount=interleavedAudioBuffer.size()/ 2;// 立体声，所以除以 2 for(inti= 0; i<sampleCount;++i) {floatsample=std::sin(phase); interleavedAudioBuffer[i* 2] =sample;// 左声道interleavedAudioBuffer[i* 2 + 1] =sample;// 右声道phase+=phaseIncrement;// 为下一个采样增加相位} });if(!audio->error()==});if(!QtAudio::Error::NoError) {// 除了其他 start() 签名外，如果 // * 后端没有实现基于回调的 IO（所有主要 // 平台 都有该 API ）， 则启动音频回调将失败 // * 音频回调的签名与 format.sampleFormat() 不匹配
        qWarning() << "Error starting audio output:" << audio->errorString();
    } }

注：该 API 仅适用于支持回调 API 的平台：Apple 的 CoreAudio（macOS、iOS 等）、Windows、Linux（使用 PulseAudio 或 PipeWire 后端）和 Android。

注意： 回调将在软实时音频线程上调用。必须确保回调不会阻塞，因为这可能会导致音频中断或掉线。这包括执行阻塞 IO、锁定互斥、分配内存或任何其他可能阻塞的操作。有关最佳实践，请参考 Ross Bencina 的文章《实时音频编程 101：时间不等人。还可以考虑使用 clang 的实时 sanitizer验证音频回调。

解码压缩音频到内存

在某些情况下，您可能希望解码压缩音频文件并自行进行进一步处理。例如，混合多个样本或使用自定义数字信号处理算法。QAudioDecoder 支持解码本地文件或来自QIODevice 实例的数据流。

下面是一个解码本地文件的示例：

QAudioFormat desiredFormat;
desiredFormat.setChannelCount(2);
desiredFormat.setSampleFormat(QAudioFormat::Int16);
desiredFormat.setSampleRate(48000);

QAudioDecoder *decoder = new QAudioDecoder(this);
decoder->setAudioFormat(desiredFormat);
decoder->setSource("level1.mp3");

connect(decoder, &QAudioDecoder::bufferReady, this, &AudioDecodingExample::readBuffer);
decoder->start();

// Now wait for bufferReady() signal and call decoder->read()

空间音频

空间音频 Qt Spatial Audio模块提供了在三维空间中执行声场的应用程序接口。

参考文档

C++ 类

QAmbientSound	立体声叠加音效
QAudioBuffer	代表具有特定格式和采样率的音频样本集合
QAudioBufferInput	用于通过 QMediaCaptureSession 向 QMediaRecorder 提供自定义音频缓冲区
QAudioBufferOutput	用于捕获 QMediaPlayer 提供的音频数据
QAudioDecoder	实现音频解码
QAudioDevice	有关音频设备及其功能的信息
QAudioEngine	管理三维声场
QAudioFormat	存储音频流参数信息
QAudioInput	代表音频输入通道
QAudioListener	定义收听 QAudioEngine 所定义声场的人的位置和方向
QAudioOutput	代表音频的输出通道
QAudioRoom
QAudioSink	向音频输出设备发送音频数据的接口
QAudioSource	从音频输入设备接收音频数据的接口
QMediaCaptureSession	允许捕获音频和视频内容
QMediaRecorder	用于编码和录制捕获会话
QSoundEffect	播放低延迟音效的方式
QSpatialSound	三维空间中的声音对象
QtAudio	包含音频类使用的枚举

QML 类型

AmbientSound	立体声覆盖声音
AudioEngine	管理 3D 场景内的声音对象
AudioInput	在捕获会话中用于捕获音频的音频输入
AudioListener	定义聆听音频引擎所定义声场的人的位置和方向
AudioOutput	音频输出，用于回放或监控捕捉会话
AudioRoom
CaptureSession	允许捕捉音频和视频内容
MediaPlayer	为场景添加媒体回放
MediaRecorder	用于编码和记录捕捉会话中生成的媒体
PlaybackOptions	低级媒体播放选项
SoundEffect	该类型提供了在 QML 中播放音效的方法
SpatialSound	三维空间中的声音对象
audioDevice	描述音频设备
mediaMetaData	为媒体文件提供元数据

实例

Audio Devices Example	列出可用的音频设备及其配置。
Audio Output Example	使用 QAudioSink 类启用音频播放。
Audio Recorder Example	发现可用设备和支持的编解码器。
Audio Source Example	使用 QAudioSource 类录制音频。
Spatial Audio Panning Example	展示 Qt Spatial Audio 引擎的部分功能

多媒体概述视频概述

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