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= newQAudioSink(format, this);
    connect(audio,QAudioSink::stateChanged, this, &AudioInputExample::handleStateChanged);
    audio->start(&sourceFile);
}

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

QAudioSink*audio;// クラスメンバー。
floatphase;       // クラスメンバー。
{
    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();
    }
}

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() が呼び出されてからの経過時間をマイクロ秒単位で返します。これには、アイドル状態およびサスペンド状態での時間も含まれます。

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

QAudioSink が のインスタンスであり、null である場合は、true を返します。それ以外の場合は、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で約23 ms）を使用します。

レイテンシを低減するには小さい値（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 までの範囲（両端を含む）のボリュームを返します。

setVolume()も参照してください 。