QAudioSource Class

QFile destinationFile;// 类成员
QAudioSource*audio;   // 类成员
{
    destinationFile.setFileName("/tmp/test.raw");
    destinationFile.open( QIODevice::WriteOnly|QIODevice::Truncate );

    QAudioFormat format;
    // 设置所需的格式，例如：
    format.setSampleRate(44100);
    format.setChannelCount(1);
    format.setSampleFormat(QAudioFormat::Int16);

    QAudioDevice info=QMediaDevices::defaultAudioInput();
    if(!info.isFormatSupported(format)) {
        qWarning() << "Default format not supported, trying to use the nearest.";
    }

    audio= newQAudioSource(格式, this);
    connect(audio, &QAudioSource::stateChanged, this, &AudioInputExample::handleStateChanged);

    QTimer::singleShot(3000, this, &AudioInputExample::stopRecording);
    audio->start(&destinationFile);
    // 录制音频 3000 毫秒
}

void AudioInputExample::stopRecording()
{
    audio->stop();
    destinationFile.close();
    delete audio;
}

QAudioSource*audio;          // 类成员。
std::atomic<float>peakLevel;// 类成员。
{
    QAudioFormat format;
    // 配置格式，例如：
    format.setSampleRate(44100);
    format.setChannelCount(2);
    format.setSampleFormat(QAudioFormat::Float);

    QAudioDevice info(QMediaDevices::defaultAudioOutput());
    if(!info.isFormatSupported(format)) {
        qWarning() << "Raw audio format not supported by backend, cannot capture audio.";
       return;
    }

    audio= newQAudioSource(format, this);
    audio->start([&peakLevel](QSpan<float>interleavedAudioBuffer) {
        floatlevel=peakLevel.load();

        for(floatsample : interleavedAudioBuffer) {
            // 根据音频采样计算峰值电平
            level=std::max(level,std::abs(sample));
        }

        peakLevel.store(level);
        // 注意：如果需要通知应用程序线程，则需格外谨慎，因为
        // 音频回调不应使用任何可能导致阻塞的系统调用。
       // 推荐的方案包括自动重置事件（Windows）、eventfd（Linux）或 macOS 上的 kqueue/EVFILT_USER。
    });

    if(!audio->error()== QtAudio::Error::NoError) {
       // 除了其他 start() 签名外，如果出现以下情况，启动音频回调将失败：
        // * 后端未实现基于回调的 I/O（该 API 在所有主要
        //   平台上均 可用 ）
        // * 音频回调的签名与 format.sampleFormat() 不匹配

        qWarning() << "Error starting audio output:" << audio->errorString();
    }
}

void AudioInputExample::handleStateChanged(QtAudio::State newState)
{
    switch (newState) {
        case QtAudio::StoppedState:
            if (audio->error() != QtAudio::NoError) {
                // Error handling
            } else {
                // Finished recording
            }
            break;

        case QtAudio::ActiveState:
            // Started recording - read from IO device
            break;

        default:
            // ... other cases as appropriate
            break;
    }
}

成员函数文档

[explicit] QAudioSource::QAudioSource(const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)

创建一个新的音频输入，并将其连接到parent 。该参数将使用默认的音频输入设备，其输出参数为format 。如果format 采用默认初始化，则格式将设置为该音频设备的首选格式。

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

创建一个新的音频输入，并将其连接到parent 。audioDevice 所引用的设备将与输入参数format 配合使用。如果format 采用默认初始化，则格式将设置为audioDevice 的首选格式。

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

销毁这个音频输入。

[since 6.10] qsizetype QAudioSource::bufferFrameCount() const

返回以帧为单位的音频缓冲区大小。

如果在调用start()之前调用此函数，则返回平台的默认值。如果在调用start() 之前调用此函数，但此前已调用setBufferSize()或setBufferFrameCount()，则返回由setBufferSize() 或setBufferFrameCount() 设置的值。如果在调用start() 之后调用此函数，则返回当前实际使用的缓冲区大小。该值可能与先前通过setBufferSize() 或setBufferFrameCount() 设置的值不一致。

该函数在 Qt 6.10 中引入。

另请参阅 setBufferFrameCount() 和bufferSize 。

qsizetype QAudioSource::bufferSize() const

返回音频缓冲区的大小（以字节为单位）。

如果在调用 `start()` 之前调用本函数，则返回平台的默认值。如果在调用 `start() ` 之前调用本函数，但此前已调用过 `setBufferSize()` 或 `setBufferFrameCount()`，则返回由 `setBufferSize() ` 或 `setBufferFrameCount()` 设置的值。如果在调用 `start()` 之后调用本函数，则返回当前实际使用的缓冲区大小。该值可能与先前通过 `setBufferSize() ` 或 `setBufferFrameCount()` 设置的值不一致。

另请参阅 setBufferSize() 和bufferFrameCount 。

qsizetype QAudioSource::bytesAvailable() const

返回可供读取的音频数据量（以字节为单位）。

另请参阅 framesAvailable 。

qint64 QAudioSource::elapsedUSecs() const

返回自调用start()以来经过的微秒数，包括处于空闲和挂起状态的时间。

QtAudio::Error QAudioSource::error() const

返回错误状态。

QAudioFormat QAudioSource::format() const

返回当前正在使用的QAudioFormat 。

[since 6.10] qsizetype QAudioSource::framesAvailable() const

返回可按帧读取的音频数据量。

注意：返回值仅在处于QtAudio::ActiveState 或QtAudio::IdleState 状态时有效，否则返回零。

该函数于 Qt 6.10 中引入。

另请参阅 bytesAvailable 。

bool QAudioSource::isNull() const

如果音频源为null ，则返回true ；否则返回false 。

[since 6.12] qsizetype QAudioSource::nativePeriodFrameCount() const

返回本机周期帧数。

若未设置，则返回 -1；否则返回先前通过 `setNativePeriodFrameCount()` 设置的值。

该函数自 Qt 6.12 起引入。

另请参阅 setNativePeriodFrameCount 。

qint64 QAudioSource::processedUSecs() const

返回自调用start()以来处理的音频数据量，单位为微秒。

void QAudioSource::reset()

清除缓冲区中的所有音频数据，并将缓冲区重置为零。

void QAudioSource::resume()

在调用suspend()之后，恢复处理音频数据。

将state() 设置为调用suspend() 时音频接收端所处的状态。如果音频接收端的状态不是QtAudio::SuspendedState ，则此函数不执行任何操作。

[since 6.10] void QAudioSource::setBufferFrameCount(qsizetype value)

将音频缓冲区大小设置为value 帧。

bufferFrameCount() 和bufferSize() 属性表示使用QIODevice API 时的环形缓冲区大小。原生周期大小通过setNativePeriodFrameCount() 进行控制。

该函数在 Qt 6.10 中引入。

另请参阅 bufferFrameCount() 和setBufferSize 。

void QAudioSource::setBufferSize(qsizetype value)

将音频缓冲区大小设置为value 字节。

bufferFrameCount() 和bufferSize() 属性表示使用QIODevice API 时的环形缓冲区大小。原生周期大小通过setNativePeriodFrameCount() 进行控制。

另请参阅 bufferSize() 和setBufferFrameCount 。

[since 6.12] void QAudioSource::setNativePeriodFrameCount(qsizetype frameCount)

将原生周期帧数设置为frameCount 。

调整操作系统和硬件使用的音频缓冲区大小。默认情况下（未设置时），系统使用一个与平台相关的值，通常为 1024 个帧（在 44100 Hz 时约为 23 毫秒）。

使用较小的数值（64-256）可降低延迟，使用较大的数值（2048-4096）可降低缓冲区溢出（音频丢失）的风险。

有效值为 32 到 4096 之间的 2 的幂（含边界值），或 -1 表示未设置。仅可在音频源已停止时调用。

映射到平台特定的设置：kAudioDevicePropertyBufferFrameSize （macOS）、IAudioClient::bufferDuration （Windows）、PW_KEY_NODE_FORCE_QUANTUM （PipeWire/Linux）和AAudioStreamBuilder_setBufferCapacityInFrames （Android）。

该函数在 Qt 6.12 中引入。

另请参阅 nativePeriodFrameCount 。

void QAudioSource::setVolume(qreal volume)

将输入音量设置为volume 。

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

如果设备不支持调节输入音量，则volume 将被忽略，输入音量将保持在1.0。

默认音量为1.0 。

另请参阅 volume()。

QIODevice *QAudioSource::start()

返回一个指向内部QIODevice 的指针，该指针用于从系统的音频输入端传输数据。该设备此时已处于打开状态，可直接调用read()从其读取数据。

如果QAudioSource 能够访问系统的音频设备，则state()将返回QtAudio::IdleState ，error()将返回QtAudio::NoError ，并发出stateChanged()信号。

如果在此过程中发生问题，error() 将返回QtAudio::OpenError ，state() 将返回QtAudio::StoppedState ，并触发stateChanged() 信号。

另请参阅 QIODevice 和QIODevice interface 。

[since 6.11] template <typename Callback> requires QtAudio::if_audio_source_callback<Callback> void QAudioSource::start(Callback &&cb)

使用一个回调函数启动QAudioSource ，该回调函数将在软实时音频线程上被调用。该回调函数是一个可调用对象，其参数为QSpan<const SampleType>，其中SampleType必须与QAudioSource 格式的QAudioFormat::SampleFormat 相匹配。该span包含交织的音频数据。

如果QAudioSource 能够成功启动，则error()会返回QtAudio::NoError 。

如果在此过程中发生问题，error() 将返回QtAudio::OpenError ，state() 将返回QtAudio::StoppedState ，并触发stateChanged() 信号。

该函数于 Qt 6.11 中引入。

另请参阅 Callback interface 。

void QAudioSource::start(QIODevice *device)

开始将音频数据从系统的音频输入端传输到device 。device 必须已在WriteOnly 、Append 或ReadWrite 模式下被打开。

如果QAudioSource 能够成功获取音频数据，则state()将返回QtAudio::ActiveState 或QtAudio::IdleState ，error()将返回QtAudio::NoError ，并触发stateChanged()信号。

如果在此过程中发生问题，error() 将返回QtAudio::OpenError ，state() 将返回QtAudio::StoppedState ，并发出stateChanged() 信号。

另请参阅 QIODevice 和QIODevice interface 。

QtAudio::State QAudioSource::state() const

返回音频处理的状态。

[signal] void QAudioSource::stateChanged(QtAudio::State state)

当设备state 发生变化时，会发出此信号。

void QAudioSource::stop()

停止音频输入，并从系统资源中断开连接。

将error()设置为QtAudio::NoError ，将state()设置为QtAudio::StoppedState ，并触发stateChanged()信号。

void QAudioSource::suspend()

停止处理音频数据，同时保留缓冲的音频数据。

将error()设置为QtAudio::NoError ，将state()设置为QtAudio::SuspendedState ，并发出stateChanged()信号。

qreal QAudioSource::volume() const

返回输入音量。

如果设备不支持调节输入音量，则返回值为 1.0。

另请参阅 setVolume()。