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 | distanceScaleChanged() |
| void | masterVolumeChanged() |
| void | outputDeviceChanged() |
| void | outputModeChanged() |
| void | pausedChanged() |
詳細な説明
QAudioEngineのインスタンスを使用すると、3次元空間における音場を管理できます。音場は、3次元空間内の指定された位置での音を定義する、複数のQSpatialSound オブジェクトによって構成されます。また、QAmbientSound を使用してステレオオーバーレイを追加することも可能です。
QAudioListener を使用すると、音源に対する音場の聴取者の位置を定義できます。聴取者が音源から離れるほど、音源からの音は小さく聞こえます。また、音源と聴取者の間の方向に応じて、音源は対応するスピーカーにマッピングされます。
QAudioEngineには2つの出力モードがあります。1つ目のモードでは、音場をステレオスピーカーペアまたはサラウンド構成といった一連のスピーカーにレンダリングします。2つ目のモードでは、ヘッドフォンを使用した際に没入感のある3Dサウンド体験を提供します。
音の定位の知覚は、主に2つの要因によって左右されます。1つ目の要因は、左右の耳に届く音波の到達時間の違いです。2つ目の要因は、異なる方向から届く音が、耳や頭部でさまざまな種類の反射音を生み出すことに起因します。 詳細については、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::Surround | 0 | サウンドを出力デバイスのスピーカー構成に合わせてマッピングします。通常はステレオまたはサラウンドスピーカー構成です。 注：OutputMode ::Surround を指定すると、QAmbientSound |
QAudioEngine::Stereo | 1 | サウンドを出力デバイスのステレオスピーカー構成にマッピングします。これにより、追加のスピーカーは無視され、左右のチャンネルのみを使用して音場のステレオレンダリングが生成されます。 |
QAudioEngine::Headphone | 2 | ヘッドフォン空間化を使用して、ヘッドフォンで音場を聴く際に 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 オブジェクトを1つ以上作成し、リスナーが少なくとも1つのルーム内にある場合のみです。リスナーが複数のルーム内にある場合は、体積が最も小さいルームが使用されます。
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.
