QAudioSink Class

QFile sourceFile;  // 클래스 멤버.
QAudioSink* audio; // 클래스 멤버.
{
    sourceFile.setFileName("/tmp/test.raw");
    sourceFile.open(QIODevice::ReadOnly);

    QAudioFormat format;
    // 포맷 설정, 예:
    format.setSampleRate(44100);
    format.setChannelCount(1);
    format.setSampleFormat(QAudioFormat::Int16);

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

    audio = new QAudioSink(format, this);
    connect(audio, QAudioSink::stateChanged, this, &AudioInputExample::handleStateChanged);
    audio->start(&sourceFile);
}

void AudioOutputExample::stopAudioOutput()
{
    audio->stop();
    sourceFile.close();
    delete audio;
}

QAudioSink* audio; // 클래스 멤버.
float phase;       // 클래스 멤버.
{
    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 play audio.";
       return;
    }

    audio = new QAudioSink(format, this);
    float phaseIncrement = 2 * M_PI * 220.0 / format.sampleRate(); // 220 Hz 사인파
    audio->start([&phase, phaseIncrement] (QSpan<float> interleavedAudioBuffer) {
        // 오디오 콜백은 잠재적으로 블록킹될 수 있는 함수를 호출해서는 안 됩니다

        // 오디오 버퍼를 사인파로 채웁니다
        const int sampleCount = interleavedAudioBuffer.size() / 2; // 스테레오이므로 2로 나눕니다
        for (int i = 0; i < sampleCount;++i) {
            float sample = std::sin(phase);
            interleavedAudioBuffer[i * 2] = sample;     // 왼쪽 채널
            interleavedAudioBuffer[i * 2 + 1] = sample; // 오른쪽 채널
            phase+= phaseIncrement;                    // 다음 샘플을 위한 위상 증가
        }
    });

   if (!audio->error()== QtAudio::Error::NoError) {
       // 다른 start() 시그니처 외에도, 다음의 경우 오디오  콜백  시작이 실패합니다.
        // * 백엔드가 콜백 기반 I/O를 구현하지 않은 경우 (이 API는 모든 주요
        //   플랫폼에서  사용할 수 있습니다 ) 
         // * 오디오 콜백의 시그니처가 format.sampleFormat()과 일치하지 않는 경우

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

void AudioOutputExample::handleStateChanged(QtAudio::State newState)
{
    switch (newState) {
        case QtAudio::IdleState:
            // Finished playing (no more data)
            AudioOutputExample::stopAudioOutput();
            break;

        case QtAudio::StoppedState:
            // Stopped for other reasons
            if (audio->error() != QtAudio::NoError) {
                // Error handling
            }
            break;

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

멤버 함수 문서

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

새로운 오디오 출력 장치를 생성하고 이를 ` parent`에 연결합니다. ` format ` 매개변수를 지정하면 기본 오디오 출력 장치가 사용됩니다. ` format `가 기본값으로 초기화되면 형식은 오디오 장치의 기본 형식으로 설정됩니다.

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

새로운 오디오 출력을 생성하고 이를 ` parent`에 연결합니다. ` audioDevice `가 참조하는 장치는 ` format ` 매개변수와 함께 사용됩니다. ` format `가 기본값으로 초기화되면, 형식은 ` audioDevice`의 기본 형식으로 설정됩니다.

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

이 오디오 출력을 해제합니다.

이렇게 하면 사용 중인 시스템 리소스가 해제되고 버퍼가 모두 비워집니다.

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

오디오 버퍼 크기를 프레임 단위로 반환합니다.

start() 호출 전에 호출된 경우, 플랫폼의 기본값을 반환합니다. start() 호출 전에 호출되었으나, 그 이전에 setBufferSize() 또는 setBufferFrameCount()이 호출된 경우, setBufferSize() 또는 setBufferFrameCount() 에서 설정된 값을 반환합니다. start() 호출 후에 호출된 경우, 현재 사용 중인 실제 버퍼 크기를 반환합니다. 이 값은 setBufferSize() 또는 setBufferFrameCount() 에서 이전에 설정된 값과 다를 수 있습니다.

이 함수는 Qt 6.10에서 도입되었습니다.

setBufferFrameCount() 및 bufferSize도 참조하십시오 .

qsizetype QAudioSink::bufferSize() const

오디오 버퍼의 크기를 바이트 단위로 반환합니다.

start() 호출 전에 호출된 경우, 플랫폼의 기본값을 반환합니다. start() 호출 전에 호출되었으나, 그 이전에 setBufferSize() 또는 setBufferFrameCount()가 호출된 경우, setBufferSize() 또는 setBufferFrameCount() 에서 설정된 값을 반환합니다. start() 호출 후에 호출된 경우, 현재 사용 중인 실제 버퍼 크기를 반환합니다. 이 값은 setBufferSize() 또는 setBufferFrameCount() 에서 이전에 설정된 값과 다를 수 있습니다.

setBufferSize() 및 bufferFrameCount도 참조하십시오 .

qsizetype QAudioSink::bytesFree() const

오디오 버퍼에 사용 가능한 여유 바이트 수를 반환합니다.

참조: framesFree.

qint64 QAudioSink::elapsedUSecs() const

start()이 호출된 이후 경과한 시간을 마이크로초 단위로 반환하며, 여기에는 유휴(Idle) 및 일시 중지(Suspend) 상태의 시간도 포함됩니다.

QtAudio::Error QAudioSink::error() const

오류 상태를 반환합니다.

QAudioFormat QAudioSink::format() const

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

[since 6.10] qsizetype QAudioSink::framesFree() const

오디오 버퍼에 사용 가능한 여유 프레임 수를 반환합니다.

이 함수는 Qt 6.10에서 도입되었습니다.

참조: bytesFree.

bool QAudioSink::isNull() const

true QAudioSink 가 인스턴스인 경우 를 반환하고, 그렇지 않은 경우 를 반환합니다. null false

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

네이티브 기간 프레임 수를 반환합니다.

설정되어 있지 않으면 -1을 반환하고, 그렇지 않으면 이전에 ` setNativePeriodFrameCount()`로 설정된 값을 반환합니다.

이 함수는 Qt 6.12에서 도입되었습니다.

setNativePeriodFrameCount도 참조하십시오 .

qint64 QAudioSink::processedUSecs() const

start()이 호출된 이후 처리된 오디오 데이터의 양을 (마이크로초 단위로) 반환합니다.

void QAudioSink::reset()

오디오 출력을 즉시 중지하고 버퍼에 현재 저장된 모든 오디오 데이터를 삭제합니다. QIODevice 로 전송된 모든 대기 중인 오디오 데이터는 무시됩니다.

stop()도 참조하십시오 .

void QAudioSink::resume()

suspend() 호출 후 오디오 데이터 처리를 재개합니다.

state()를 suspend()가 호출되었을 때 싱크가 가졌던 상태로 설정합니다. 오디오 싱크의 상태가 QtAudio::SuspendedState 이 아닌 경우 이 함수는 아무 작업도 수행하지 않습니다.

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

오디오 버퍼 크기를 프레임 수 기준으로 value 로 설정합니다.

bufferFrameCount() 및 bufferSize() 속성은 QIODevice API를 사용할 때의 링 버퍼 크기를 나타냅니다. 네이티브 주기 크기는 setNativePeriodFrameCount()를 통해 제어됩니다.

이 함수는 Qt 6.10에서 도입되었습니다.

bufferFrameCount() 및 setBufferSize도 참조하십시오 .

void QAudioSink::setBufferSize(qsizetype value)

오디오 버퍼 크기를 바이트 단위로 value 로 설정합니다.

bufferFrameCount() 및 bufferSize() 속성은 QIODevice API를 사용할 때의 링 버퍼 크기를 나타냅니다. 기본 주기 크기는 setNativePeriodFrameCount()을 통해 제어됩니다.

bufferSize() 및 setBufferFrameCount도 참조하십시오 .

[since 6.12] void QAudioSink::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 QAudioSink::setVolume(qreal volume)

출력 볼륨을 volume 로 설정합니다.

볼륨은 0.0 (무음)에서 1.0 (최대 볼륨)까지 선형적으로 조정됩니다. 이 범위 밖의 값은 제한됩니다.

기본 볼륨은 1.0 입니다.

UI 볼륨 컨트롤은 일반적으로 비선형적으로 스케일링되어야 합니다. 예를 들어, 로그 스케일을 사용하면 사용자가 볼륨 컨트롤에서 일반적으로 기대하는 대로 지각되는 음량이 선형적으로 변화합니다. 자세한 내용은 QtAudio::convertVolume()을 참조하십시오.

volume()도 참조하십시오 .

QIODevice *QAudioSink::start()

시스템의 오디오 출력으로 데이터를 전송하는 데 사용되는 내부 ` QIODevice `에 대한 포인터를 반환합니다. 이 장치는 이미 열려 있는 상태이므로 ` write()`를 통해 해당 장치에 직접 데이터를 쓸 수 있습니다.

QAudioSink 가 시스템의 오디오 장치에 액세스할 수 있는 경우, 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_sink_callback<Callback> void QAudioSink::start(Callback &&cb)

소프트 실시간 오디오 스레드에서 호출될 콜백 함수를 사용하여 QAudioSink 를 시작합니다. 이 콜백은 QSpan<SampleType>을 인수로 받는 호출 가능 객체이며, SampleType은 QAudioSink 의 포맷에 명시된 QAudioFormat::SampleFormat 과 일치해야 합니다. span에는 인터리브된 오디오 데이터가 채워져 있어야 합니다.

QAudioSink 가 성공적으로 시작될 수 있는 경우, error()은 QtAudio::NoError 를 반환합니다.

이 과정에서 문제가 발생하면, error()는 QtAudio::OpenError 를 반환하고, state()는 QtAudio::StoppedState 를 반환하며, stateChanged() 신호가 발생합니다.

이 함수는 Qt 6.11에서 도입되었습니다.

Callback interface도 참조하십시오 .

void QAudioSink::start(QIODevice *device)

device 에서 시스템의 오디오 출력으로 오디오 데이터 전송을 시작합니다. device 는 ReadOnly 또는 ReadWrite 모드로 열려 있어야 합니다.

QAudioSink 가 오디오 데이터를 성공적으로 출력할 수 있는 경우, state()는 QtAudio::ActiveState 를 반환하고, error()는 QtAudio::NoError 를 반환하며, stateChanged() 신호가 발생합니다.

이 과정에서 문제가 발생하면, error()은 QtAudio::OpenError 를 반환하고, state()은 QtAudio::StoppedState 를 반환하며, stateChanged() 신호가 발생합니다.

QIODevice 및 QIODevice interface도 참조하십시오 .

QtAudio::State QAudioSink::state() const

오디오 처리 상태를 반환합니다.

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

이 신호는 state 장치가 변경되었을 때 발생합니다. 이는 오디오 출력의 현재 상태입니다.

void QAudioSink::stop()

오디오 출력을 중지하고 시스템 리소스에서 분리합니다.

error()을 QtAudio::NoError 로, state()을 QtAudio::StoppedState 로 설정하고, stateChanged() 신호를 발생시킵니다.

참조: reset().

void QAudioSink::suspend()

오디오 데이터 처리를 중지하고, 버퍼에 저장된 오디오 데이터는 유지합니다.

state()를 QtAudio::SuspendedState 로 설정하고 stateChanged() 신호를 발생시킵니다.

qreal QAudioSink::volume() const

0.0에서 1.0 사이의 볼륨을 반환합니다(0.0 및 1.0 포함).

setVolume()도 참조하십시오 .