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 = new QAudioSource(format, this);
    connect(audio, &QAudioSource::stateChanged, this, &AudioInputExample::handleStateChanged);

    QTimer::singleShot(3000, this, &AudioInputExample::stopRecording);
    audio->start(&destinationFile);
    // 3000ms 동안 오디오 녹음
}

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 = new QAudioSource(format, this);
    audio->start([&peakLevel] (QSpan<float> interleavedAudioBuffer) {
        float level = peakLevel.load();

        for (float sample : 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() 함수가 호출된 이후 경과한 시간을 마이크로초 단위로 반환하며, 여기에는 유휴(Idle) 및 일시 중지(Suspend) 상태의 시간도 포함됩니다.

QtAudio::Error QAudioSource::error() const

오류 상태를 반환합니다.

QAudioFormat QAudioSource::format() const

현재 사용 중인 QAudioFormat 를 반환합니다.

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

읽을 수 있는 오디오 데이터의 양을 프레임 단위로 반환합니다.

참고: 반환된 값은 ' QtAudio::ActiveState ' 또는 ' QtAudio::IdleState ' 상태일 때만 유효하며, 그 외의 경우에는 0을 반환합니다.

이 함수는 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 기준 약 23ms)입니다.

지연 시간을 줄이려면 더 작은 값(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()도 참조하십시오 .