이 페이지에서

QAudioEngine Class

QAudioEngine은 3차원 음장을 관리합니다. 더 보기...

헤더: #include <QAudioEngine>
CMake: find_package(Qt6 REQUIRED COMPONENTS SpatialAudio)
target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio)
qmake: QT += spatialaudio
상속: QObject

공개 유형

enum OutputMode { Surround, Stereo, Headphone }

속성

공개 함수

QAudioEngine()
QAudioEngine(QObject *parent)
QAudioEngine(int sampleRate, QObject *parent = nullptr)
virtual ~QAudioEngine() override
float distanceScale() const
float masterVolume() const
QAudioDevice outputDevice() const
QAudioEngine::OutputMode outputMode() const
bool paused() const
bool roomEffectsEnabled() const
int sampleRate() const
void setDistanceScale(float scale)
void setMasterVolume(float volume)
void setOutputDevice(const QAudioDevice &device)
void setOutputMode(QAudioEngine::OutputMode mode)
void setPaused(bool paused)
void setRoomEffectsEnabled(bool enabled)

공개 슬롯

void pause()
void resume()
void start()
void stop()

신호

상세 설명

QAudioEngine 인스턴스를 사용하여 3차원 음장을 관리할 수 있습니다. 음장은 3차원 공간의 지정된 위치에서 소리를 정의하는 여러 개의 QSpatialSound 객체로 구성됩니다. 또한 QAmbientSound 를 사용하여 스테레오 오버레이를 추가할 수도 있습니다.

QAudioListener 를 사용하여 음원을 기준으로 음장을 듣는 사람의 위치를 정의할 수 있습니다. 청취자가 음원에서 멀어질수록 음원은 덜 들리게 됩니다. 또한 청취자와 음원 사이의 방향에 따라 해당 음원이 대응하는 스피커로 매핑됩니다.

QAudioEngine은 두 가지 출력 모드를 제공합니다. 첫 번째 모드는 사운드 필드를 스테레오 스피커 쌍이나 서라운드 구성과 같은 일련의 스피커로 렌더링합니다. 두 번째 모드는 헤드폰을 사용할 때 몰입감 있는 3D 사운드 경험을 제공합니다.

음원 위치 인식은 주로 두 가지 요인에 의해 결정됩니다. 첫 번째 요인은 왼쪽 귀와 오른쪽 귀 사이에서 발생하는 음파의 시간 차이입니다. 두 번째 요인은 서로 다른 방향에서 오는 소리가 귀와 머리에서 다양한 유형의 반사를 일으키는 방식에서 비롯됩니다. 자세한 내용은 https://en.wikipedia.org/wiki/Sound_localization을 참조하십시오.

공간 오디오 엔진은 머리 관련 전달 함수(HRTF, https://en.wikipedia.org/wiki/Head-related_transfer_function 참조)를 통해 이러한 시간 차이와 반사를 모사합니다. 사용된 함수는 평균적인 사람의 귀와 머리에 대한 이러한 효과를 모사합니다. 이를 통해 헤드폰을 사용할 때 대부분의 사용자에게 훌륭하고 몰입감 있는 3D 사운드 위치 인식 경험을 제공합니다.

이 엔진은 다용도로 사용할 수 있어, 다양한 유형의 공간을 모사하기 위해 공간 속성과 잔향 설정을 정의할 수 있습니다.

또한 음원을 가림으로써 해당 음원에서 나오는 소리의 강도를 약화시킬 수도 있습니다.

이 오디오 엔진은 기본적으로 센티미터 단위의 좌표계를 사용합니다. 축은 3D에서 일반적으로 사용되는 좌표계와 일치합니다. 양의 x축은 오른쪽을, 양의 y축은 위쪽을, 양의 z축은 뒤쪽을 가리킵니다.

멤버 유형 문서

enum QAudioEngine::OutputMode

상수값설명
QAudioEngine::Surround0사운드를 출력 장치의 스피커 구성에 매핑합니다. 일반적으로 스테레오 또는 서라운드 스피커 설정입니다.

참고: OutputMode ::Surround를 설정하면 다음의 재생이 비활성화됩니다. QAmbientSound

QAudioEngine::Stereo1사운드를 출력 장치의 스테레오 라우드스피커 구성에 매핑합니다. 이 경우 추가 스피커는 모두 무시되고, 좌우 채널만을 사용하여 음장의 스테레오 렌더링을 생성합니다.
QAudioEngine::Headphone2헤드폰 공간화 기능을 사용하여 헤드폰을 통해 음장을 들을 때 3D 오디오 효과를 생성합니다.

속성 설명서

distanceScale : float

공간 오디오 엔진에서 사용하는 좌표계의 척도를 정의합니다. 기본적으로 모든 단위는 센티미터로 설정되며, 이는 Qt Quick 3D 에서 사용하는 기본 단위와 일치합니다.

거리 척도를 QAudioEngine::DistanceScaleMeter로 설정하면 단위가 미터로 표시됩니다.

액세스 함수:

float distanceScale() const
void setDistanceScale(float scale)

알림 신호:

void distanceScaleChanged()

masterVolume : float

사운드 필드를 렌더링하는 데 사용되는 볼륨을 설정하거나 반환합니다.

액세스 함수:

float masterVolume() const
void setMasterVolume(float volume)

알림 신호:

void masterVolumeChanged()

outputDevice : QAudioDevice

사운드 필드 재생에 사용 중인 장치를 설정하거나 반환합니다.

액세스 함수:

QAudioDevice outputDevice() const
void setOutputDevice(const QAudioDevice &device)

알림 신호:

void outputDeviceChanged()

outputMode : OutputMode

엔진의 현재 출력 모드를 설정하거나 가져옵니다.

액세스 함수:

QAudioEngine::OutputMode outputMode() const
void setOutputMode(QAudioEngine::OutputMode mode)

알림 신호:

void outputModeChanged()

QAudioEngine::OutputMode도 참조하십시오 .

paused : bool

공간 오디오 엔진을 일시 중지합니다.

접근 기능:

bool paused() const
void setPaused(bool paused)

알림 신호:

void pausedChanged()

멤버 함수 문서

QAudioEngine::QAudioEngine()

[explicit] QAudioEngine::QAudioEngine(QObject *parent)

[explicit] QAudioEngine::QAudioEngine(int sampleRate, QObject *parent = nullptr)

parent 가 지정된 경우, 이를 사용하여 공간 오디오 엔진을 생성합니다.

이 엔진은 sampleRate 로 지정된 샘플 레이트로 작동합니다. 지정된 값이 없는 경우 기본 샘플 레이트는 44100(44.1kHz)입니다.

해당 샘플 레이트로 제공되지 않은 사운드 콘텐츠는 엔진에서 처리될 때 자동으로 sampleRate 로 리샘플링됩니다. 대부분의 경우 기본 샘플 레이트로 충분하지만, 사운드 파일의 대부분이 다른 레이트로 샘플링된 경우 다른 레이트를 정의하여 리샘플링에 따른 CPU 오버헤드를 줄일 수 있습니다.

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

공간 오디오 엔진을 삭제합니다.

[slot] void QAudioEngine::pause()

재생을 일시 중지합니다.

[slot] void QAudioEngine::resume()

재생이 재개됩니다.

bool QAudioEngine::roomEffectsEnabled() const

룸 효과가 활성화되어 있으면 true를 반환합니다.

setRoomEffectsEnabled()도 참조하십시오 .

int QAudioEngine::sampleRate() const

엔진에 설정된 샘플 레이트를 반환합니다.

void QAudioEngine::setRoomEffectsEnabled(bool enabled)

에코 및 리버브와 같은 실내 효과를 활성화합니다.

enabled 가 true인 경우 실내 효과를 활성화합니다. 실내 효과는 하나 이상의 QAudioRoom 객체를 생성하고 청취자가 적어도 하나의 방 안에 있을 때만 적용됩니다. 청취자가 여러 방 안에 있는 경우, 볼륨이 가장 작은 방이 사용됩니다.

roomEffectsEnabled()도 참조하십시오 .

[slot] void QAudioEngine::start()

엔진을 시동합니다.

[slot] void QAudioEngine::stop()

엔진을 정지시킵니다.

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