このページでは

オーディオの概要

音波

オーディオ機能

Qt Multimedia オーディオ入力、出力、および処理について、低レベルおよび高レベルの両方のアプローチを網羅した、さまざまなオーディオクラスを提供しています。

オーディオの実装の詳細

圧縮オーディオの再生

単純な非圧縮オーディオ以外のメディアやオーディオファイルを再生するには、QMediaPlayer というC++クラス、またはMediaPlayer というQML型を使用できます。QMediaPlayer クラスおよび関連するQML型は、必要に応じてビデオの再生も可能です。

詳細については、「サポートされているメディア形式」を参照してください。

オーディオを再生するには、メディアプレーヤーをQAudioOutput オブジェクト(またはQMLのAudioOutput 要素)に接続する必要があります。

C++ を使用してローカルファイルを再生する方法は以下の通りです。

player = new QMediaPlayer;
audioOutput = new QAudioOutput;
player->setAudioOutput(audioOutput);
// ...
player->setSource(QUrl::fromLocalFile("/Users/me/Music/coolsong.mp3"));
audioOutput->setVolume(0.5);
player->play();

QMLでの同様の機能は以下の通りです:

MediaPlayer {
    audioOutput: AudioOutput {}
    source: "file:///path/to/my/music.mp3"
    Component.onCompleted: { play() }
}

オーディオをファイルに録音する

オーディオをファイルに録音するには、キャプチャセッションを作成し、そこにオーディオ入力とレコーダーを接続する必要があります。これらの要素は、QMediaCaptureSession 、QAudioInput 、およびQMediaRecorder クラスによって実装されています。デフォルトで生成されたQAudioInput は、システムのデフォルトのオーディオ入力を選択します。 レコーダーは、シンプルな record() および stop() 関数を用いて録音プロセスを制御します。さらに、これを使用して、出力先、オーディオエンコーダー、またはファイルコンテナ形式を選択することもできます。

デフォルトのマイクから音声を録音するセッションは、C++では次のように記述されます。

QMediaCaptureSession session;
QAudioInput audioInput;
session.setAudioInput(&audioInput);
QMediaRecorder recorder;
session.setRecorder(&recorder);
recorder.setQuality(QMediaRecorder::HighQuality);
recorder.setOutputLocation(QUrl::fromLocalFile("test.mp3"));
recorder.record();

QMLでは、次のように記述することで同じ結果が得られます:

CaptureSession {
    audioInput: AudioInput {}
    mediaRecorder: MediaRecorder {
        id: recorder
        outputLocation: "file:///path/to/test.mp3"
    }
    Component.onCompleted: { recorder.record() }
}

QMediaCaptureSession また、画像のキャプチャや動画の録画など、より複雑なユースケースにも対応しています。

低遅延の効果音

サウンドデバイスへの直接アクセスに加え、QSoundEffect クラス(およびSoundEffect というQMLタイプ)は、サウンドを再生するためのより抽象的な方法を提供します。このクラスを使用すると、WAV形式のファイルを指定することができ、必要に応じて低遅延で再生することができます。

以下の項目を調整できます:

低レベルのオーディオ入出力

Qt Multimedia のC++ APIには、オーディオ入出力機能への生データアクセスを行うためのクラスが用意されており、アプリケーションはマイクなどのデバイスから生データを受信したり、スピーカーやその他のデバイスに生データを書き込んだりすることができます。一般的に、これらのクラスはオーディオのデコードやその他の処理は行いませんが、さまざまな種類の生オーディオデータをサポートしています。

QAudioSink クラスは生のオーディオデータの出力を提供し、QAudioSource クラスは生のオーディオデータの入力を提供します。利用可能なハードウェアによって、どのオーディオ出力および入力が利用可能かが決まります。

QIODevice を使用したプッシュおよびプル

低レベルのオーディオクラスは、push モードとpull モードの2つのモードで動作します。pull モードでは、QIODevice を指定することでオーディオデバイスが起動されます。出力デバイスについては、QAudioSink クラスが、さらなるオーディオデータが必要になった際に、QIODevice::read()を使用してQIODevice からデータをプルします。一方、QAudioSource を使用したpull モードでは、オーディオデータが利用可能になると、そのデータがQIODevice に直接書き込まれます。

push モードでは、オーディオデバイスはQIODevice インスタンスを提供し、必要に応じて書き込みや読み取りを行うことができます。

注: QIODevice は オーディオデバイスに即座にアクセスするのではなく、データを内部でバッファリングします。つまり、QIODevice を使用すれば、アプリケーションスレッドからいつでもデータの書き込みや読み取りが可能ですが、通常250msのバッファリング時間が追加されます。 アプリケーションがQIODevice にオーディオデータを十分に速く送信していない場合(QAudioSink の場合)、またはQIODevice から十分に速く読み込んでいない場合、音声の途切れが発生します。

コールバックベースのインターフェース

QIODevice ベースのインターフェースに加え、低レベルオーディオクラスは、オーディオデバイスがデータを必要とする場合や、より多くのデータを送信する際にオーディオスレッド上で呼び出されるコールバックをユーザーが登録できる、コールバックベースのインターフェースを提供します。これにより、アプリケーションがオーディオスレッド上で直接データを処理できるため、はるかに低レイテンシなオーディオ処理が可能になります。

{
    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= newQAudioSink(format, this);
    floatphaseIncrement= 2 *M_PI* 220.0 /format.sampleRate();// 220 Hzの正弦波
    audio->start([&phase,phaseIncrement](QSpan<float>interleavedAudioBuffer) {
        // オーディオコールバックでは、ブロックする可能性のある関数を呼び出してはならない

        // オーディオバッファに正弦波を格納する
        const intsampleCount=interleavedAudioBuffer.size()/ 2;// ステレオなので、2で割る
        for(inti= 0; i<sampleCount;++i) {
            floatsample=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();
    }
}

注:このAPIは 、コールバックAPIをサポートするプラットフォーム(AppleのCoreAudio(macOS、iOSなど)、Windows、Linux(PulseAudioまたはPipeWireバックエンドを使用する場合)、およびAndroid)でのみ利用可能です。

注:コールバックは ソフトリアルタイムのオーディオスレッド上で呼び出されます。コールバックがブロックしないようにすることが重要です。ブロックすると、オーディオのグリッチや音切れの原因となる可能性があります。これには、ブロックするI/Oの実行、ミューテックスのロック、メモリの割り当て、その他ブロックを引き起こす可能性のある操作が含まれます。 ベストプラクティスについては、Ross Bencina氏の記事『Real-time audio programming 101: time waits for nothing』を参照してください。また、オーディオコールバックの検証には、clangのRealtime sanitizerの使用も検討してください。

圧縮オーディオのメモリへのデコード

場合によっては、圧縮されたオーディオファイルをデコードし、さらなる処理を自身で行う必要があるかもしれません。例えば、複数のサンプルをミキシングしたり、カスタムなデジタル信号処理アルゴリズムを使用したりする場合などです。QAudioDecoder は、ローカルファイルやQIODevice インスタンスからのデータストリームのデコードをサポートしています。

以下に、ローカルファイルのデコード例を示します:

QAudioFormat desiredFormat;
desiredFormat.setChannelCount(2);
desiredFormat.setSampleFormat(QAudioFormat::Int16);
desiredFormat.setSampleRate(48000);

QAudioDecoder *decoder = new QAudioDecoder(this);
decoder->setAudioFormat(desiredFormat);
decoder->setSource("level1.mp3");

connect(decoder, &QAudioDecoder::bufferReady, this, &AudioDecodingExample::readBuffer);
decoder->start();

// Now wait for bufferReady() signal and call decoder->read()

空間オーディオ

この Qt Spatial Audio モジュールは、3D空間における音場を実装するためのAPIを提供します。

リファレンスドキュメント

C++ クラス

QAmbientSound

ステレオオーバーレイサウンド

QAudioBuffer

特定のフォーマットとサンプリングレートを備えたオーディオサンプルの集合を表します

QAudioBufferInput

QMediaCaptureSessionを介してQMediaRecorderにカスタムオーディオバッファを提供するために使用される

QAudioBufferOutput

QMediaPlayerから提供されるオーディオデータのキャプチャに使用されます

QAudioDecoder

オーディオのデコードを実装する

QAudioDevice

オーディオデバイスおよびその機能に関する情報

QAudioEngine

3次元音場を管理する

QAudioFormat

オーディオストリームのパラメータ情報を保存します

QAudioInput

オーディオの入力チャンネルを表す

QAudioListener

QAudioEngineによって定義された音場を聞く人の位置と向きを定義する

QAudioOutput

オーディオの出力チャンネルを表します

QAudioRoom

QAudioSink

オーディオ出力デバイスへオーディオデータを送信するためのインターフェース

QAudioSource

オーディオ入力デバイスからオーディオデータを受信するためのインターフェース

QMediaCaptureSession

オーディオおよびビデオコンテンツのキャプチャを可能にする

QMediaRecorder

キャプチャセッションのエンコードおよび記録に使用されます

QSoundEffect

低遅延のサウンドエフェクトを再生する方法

QSpatialSound

3D空間内のサウンドオブジェクト

QtAudio

オーディオクラスで使用される列挙型を含む

QMLの型

AmbientSound

ステレオオーバーレイサウンド

AudioEngine

3Dシーン内のサウンドオブジェクトを管理する

AudioInput

キャプチャセッションでオーディオをキャプチャするために使用されるオーディオ入力

AudioListener

AudioEngineによって定義された音場を聴いている人物の位置と向きを定義する

AudioOutput

キャプチャセッションの再生またはモニタリングに使用するオーディオ出力

AudioRoom

CaptureSession

オーディオおよびビデオコンテンツのキャプチャを可能にする

MediaPlayer

シーンにメディア再生機能を追加する

MediaRecorder

CaptureSessionで生成されたメディアのエンコードおよび記録用

PlaybackOptions

低レベルのメディア再生オプション

SoundEffect

この型は、QMLで効果音を再生する方法を提供します

SpatialSound

3D空間におけるサウンドオブジェクト

audioDevice

オーディオデバイスを記述します

mediaMetaData

メディアファイルのメタデータを提供します

例

Audio Devices Example

利用可能なオーディオデバイスとその設定を一覧表示します。

Audio Output Example

QAudioSink クラスを使用したオーディオ再生を有効にする。

Audio Recorder Example

利用可能なデバイスとサポートされているコーデックを特定する。

Audio Source Example

QAudioSource クラスを使用したオーディオの録音。

Spatial Audio Panning Example

Qt Spatial Audioの機能の一部を紹介します。

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