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次元の音場を管理することができます。音場は、3D空間の指定位置でサウンドを定義する複数のQSpatialSound オブジェクトによって定義されます。また、QAmbientSound を使ってステレオオーバーレイを追加することもできます。

QAudioListener を使って、音場を聴く人の音源に対する位置を定義できます。リスナーが音源から遠ざかれば、音源は聴こえにくくなります。また、リスナーと音源の方向によって、対応するラウドスピーカーにマッピングされます。

QAudioEngineには、2つの出力モードがあります。1つ目のモードは、ステレオスピーカーペアまたはサラウンド構成のいずれかのスピーカーセットに音場をレンダリングします。2つ目のモードは、ヘッドフォン使用時に没入感のある3Dサウンド体験を提供します。

音像定位の知覚は、主に2つの要因によって左右される。1つ目の要因は、左右の耳における音波のタイミングの違いです。2つ目の要因は、異なる方向から来る音が、私たちの耳や頭からどのように異なるタイプの反射を作り出すかという、様々な方法から来るものです。詳しくはhttps://en.wikipedia.org/wiki/Sound_localization。

空間オーディオエンジンは、Head related transfer functions (HRTF、https://en.wikipedia.org/wiki/Head-related_transfer_function 参照) を使って、これらのタイミングの違いと反射をエミュレートします。使用される関数は、平均的な人の耳と頭に対するこれらの効果をエミュレートします。これにより、ヘッドホンを使用しているほとんどの人に、没入感のある3Dサウンド定位体験を提供します。

このエンジンはかなり多機能で、部屋のプロパティやリバーブ設定を定義して、さまざまなタイプの部屋をエミュレートできます。

音源をオクルード(遮蔽)して、その音源からの音を減衰させることもできます。

オーディオエンジンは、デフォルトでセンチメートル単位の座標系を使用します。軸は、3Dで使用される一般的な座標系に合わせてあります。正のxは右向き、正のyは上向き、正のzは後ろ向きです。

メンバー型ドキュメント

enum QAudioEngine::OutputMode

定数説明
QAudioEngine::Surround0サウンドを出力デバイスのラウドスピーカー設定にマッピングする。これは通常、ステレオまたはサラウンドスピーカーの設定である。
QAudioEngine::Stereo1サウンドを出力デバイスのステレオラウドスピーカー設定にマッピングする。この場合、追加のスピーカーは無視され、左右のチャンネルだけを使用して音場のステレオレンダリングが作成されます。
QAudioEngine::Headphone2ヘッドフォンで音場を聴く時に3Dオーディオエフェクトを作成するために、ヘッドフォン空間化を使う。

プロパティの説明

distanceScale : float

空間オーディオエンジンが使用する座標系のスケールを定義します。デフォルトでは、すべての単位はセンチメートルで、Qt Quick 3Dで使用されているデフォルトの単位と同じです。

メートル単位を取得するには、距離スケールをQAudioEngine::DistanceScaleMeterに設定します。

アクセス関数

float distanceScale() const
void setDistanceScale(float scale)

Notifierシグナル:

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)

Notifier シグナル:

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 の場合、ルームエフェクトを有効にします。ルームエフェクトは、1つ以上のQAudioRoom オブジェクトを作成し、リスナーが少なくとも1つのルーム内にいる場合にのみ適用されます。リスナーが複数の部屋の中にいる場合、最も音量が小さい部屋が使用されます。

roomEffectsEnabled()も参照してください

[slot] void QAudioEngine::start()

エンジンをかける。

[slot] void QAudioEngine::stop()

エンジンを止める。

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