QAudioSink Class

QFile sourceFile;  // Klassenmitglied.
QAudioSink* audio; // Klassenmitglied.
{
    sourceFile.setFileName("/tmp/test.raw");
    sourceFile.open(QIODevice::ReadOnly);

    QAudioFormat format;
    // Format einrichten, z. B.
    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 = new QAudioSink(format, this);
    connect(audio, QAudioSink::stateChanged, this, &AudioInputExample::handleStateChanged);
    audio->start(&sourceFile);
}

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

QAudioSink* audio; // Klassenmitglied.
float phase;       // Klassenmitglied.
{
    QAudioFormat format;
    // Format einrichten, z. B.
    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 = new QAudioSink(format, this);
    float phaseIncrement = 2 * M_PI * 220.0 / format.sampleRate(); // 220-Hz-Sinuswelle
    audio->start([&phase, phaseIncrement] (QSpan<float> interleavedAudioBuffer) {
        // Der Audio-Callback sollte keine Funktionen aufrufen, die möglicherweise blockieren könnten

        // Den Audio-Puffer mit einer Sinuswelle füllen
        const int sampleCount = interleavedAudioBuffer.size() / 2; // Stereo, daher durch 2 teilen
        for (int i = 0; i < sampleCount;++i) {
            float sample = std::sin(phase);
            interleavedAudioBuffer[i * 2] = sample;     // Linker Kanal
            interleavedAudioBuffer[i * 2 + 1] = sample; // Rechter Kanal
            phase+= phaseIncrement;                    // Phase für das nächste Sample erhöhen
        }
    });

   if (!audio->error()== QtAudio::Error::NoError) {
       // Zusätzlich zu den anderen `start()`-Signaturen schlägt der Start des Audio-Callbacks fehl, wenn
        // * das Backend keine callback-basierte E/A implementiert (die API ist auf allen wichtigen
        //   Plattformen  verfügbar )
        // * die Signatur des Audio-Callbacks nicht mit `format.sampleFormat()` übereinstimmt

        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;
    }
}

Dokumentation zu Mitgliedsfunktionen

[explicit] QAudioSink::QAudioSink(const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)

Erstellen Sie eine neue Audioausgabe und verknüpfen Sie diese mit ` parent`. Mit den Parametern ` format ` wird das Standard-Audioausgabegerät verwendet. Wenn ` format ` standardmäßig initialisiert ist, wird das Format auf das bevorzugte Format des Audiogeräts gesetzt.

[explicit] QAudioSink::QAudioSink(const QAudioDevice &audioDevice, const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)

Erstellen Sie eine neue Audioausgabe und verknüpfen Sie diese mit „ parent “. Das Gerät, auf das „ audioDevice “ verweist, wird mit den Parametern „ format “ der Ausgabe verwendet. Wenn „ format “ standardmäßig initialisiert wird, wird das Format auf das bevorzugte Format von „ audioDevice “ gesetzt.

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

Löscht diese Audioausgabe.

Dadurch werden alle verwendeten Systemressourcen freigegeben und alle Puffer geleert.

[since 6.10] qsizetype QAudioSink::bufferFrameCount() const

Gibt die Größe des Audio-Puffers in Frames zurück.

Wird vor „ start()“ aufgerufen, wird der plattformspezifische Standardwert zurückgegeben. Wird vor „ start() “ aufgerufen, aber zuvor wurden „ setBufferSize()“ oder „ setBufferFrameCount()“ aufgerufen, wird der durch „ setBufferSize() “ oder „ setBufferFrameCount() “ festgelegte Wert zurückgegeben. Wird nach „ start() “ aufgerufen, wird die tatsächlich verwendete Puffergröße zurückgegeben. Diese entspricht möglicherweise nicht dem Wert, der zuvor durch „ setBufferSize() “ oder „ setBufferFrameCount() “ festgelegt wurde.

Diese Funktion wurde in Qt 6.10 eingeführt.

Siehe auch „ setBufferFrameCount()“ und „ bufferSize “.

qsizetype QAudioSink::bufferSize() const

Gibt die Größe des Audiopuffers in Byte zurück.

Wird vor dem Aufruf von ` start()` aufgerufen, wird der plattformspezifische Standardwert zurückgegeben. Wird vor dem Aufruf von ` start() ` aufgerufen, aber zuvor wurden bereits ` setBufferSize()` oder ` setBufferFrameCount()` aufgerufen, wird der durch ` setBufferSize() ` oder ` setBufferFrameCount()` festgelegte Wert zurückgegeben. Wird nach dem Aufruf von ` start()` aufgerufen, wird die tatsächlich verwendete Puffergröße zurückgegeben. Diese entspricht möglicherweise nicht dem Wert, der zuvor durch ` setBufferSize() ` oder ` setBufferFrameCount()` festgelegt wurde.

Siehe auch setBufferSize() und bufferFrameCount.

qsizetype QAudioSink::bytesFree() const

Gibt die Anzahl der im Audio-Puffer verfügbaren freien Bytes zurück.

Siehe auch „ framesFree “.

qint64 QAudioSink::elapsedUSecs() const

Gibt die Zeit in Mikrosekunden seit dem Aufruf von ` start()` zurück, einschließlich der Zeit in den Zuständen „Idle“ und „Suspend“.

QtAudio::Error QAudioSink::error() const

Gibt den Fehlerstatus zurück.

QAudioFormat QAudioSink::format() const

Gibt den derzeit verwendeten „ QAudioFormat “ zurück.

[since 6.10] qsizetype QAudioSink::framesFree() const

Gibt die Anzahl der im Audio-Puffer verfügbaren freien Frames zurück.

Diese Funktion wurde in Qt 6.10 eingeführt.

Siehe auch „ bytesFree “.

bool QAudioSink::isNull() const

Gibt „ true “ zurück, wenn die Instanz von „ QAudioSink “ „ null “ lautet; andernfalls wird „ false “ zurückgegeben.

[since 6.12] qsizetype QAudioSink::nativePeriodFrameCount() const

Gibt die native Anzahl der Perioden zurück.

Gibt -1 zurück, wenn nicht festgelegt; andernfalls wird der zuvor mit ` setNativePeriodFrameCount()` festgelegte Wert zurückgegeben.

Diese Funktion wurde in Qt 6.12 eingeführt.

Siehe auch „ setNativePeriodFrameCount “.

qint64 QAudioSink::processedUSecs() const

Gibt die Menge der seit dem Aufruf von ` start()` verarbeiteten Audiodaten zurück (in Mikrosekunden).

void QAudioSink::reset()

Die Audioausgabe wird sofort gestoppt und alle derzeit in den Puffern befindlichen Audiodaten werden verworfen. Alle an „ QIODevice “ übermittelten, noch ausstehenden Audiodaten werden ignoriert.

Siehe auch stop().

void QAudioSink::resume()

Setzt die Verarbeitung von Audiodaten nach einem Aufruf von ` suspend()` fort.

Setzt „ state()“ auf den Zustand, den der Sink zum Zeitpunkt des Aufrufs von „ suspend()“ hatte. Diese Funktion führt keine Aktion aus, wenn der Zustand des Audio-Sinks nicht „ QtAudio::SuspendedState “ ist.

[since 6.10] void QAudioSink::setBufferFrameCount(qsizetype value)

Stellt die Größe des Audio-Puffers auf „ value “ in Frame-Anzahl ein.

Die Eigenschaften „ bufferFrameCount()“ und „ bufferSize()“ geben die Ringpuffergröße bei Verwendung der „ QIODevice “-APIs an. Die native Periodengröße wird über „ setNativePeriodFrameCount()“ gesteuert.

Diese Funktion wurde in Qt 6.10 eingeführt.

Siehe auch bufferFrameCount() und setBufferSize.

void QAudioSink::setBufferSize(qsizetype value)

Legt die Größe des Audio-Puffers auf „ value “ in Byte fest.

Die Eigenschaften „ bufferFrameCount()“ und „ bufferSize()“ geben die Ringpuffergröße bei Verwendung der „ QIODevice “-APIs an. Die native Periodengröße wird über „ setNativePeriodFrameCount()“ gesteuert.

Siehe auch bufferSize() und setBufferFrameCount.

[since 6.12] void QAudioSink::setNativePeriodFrameCount(qsizetype frameCount)

Legt die native Perioden-Frame-Anzahl auf „ frameCount “ fest.

Passen Sie die vom Betriebssystem und der Hardware verwendete Größe des Audio-Puffers an. Standardmäßig (wenn nicht festgelegt) verwendet das System einen plattformabhängigen Wert, typischerweise 1024 Frames (~23 ms bei 44100 Hz).

Verwenden Sie kleinere Werte (64–256), um die Latenz zu verringern, oder größere Werte (2048–4096), um das Risiko von Pufferunterläufen (Dropouts) zu verringern.

Gültige Werte sind 2-Potenzen zwischen 32 und 4096 (einschließlich) oder -1, um die Einstellung zurückzusetzen. Kann nur aufgerufen werden, wenn der Audio-Sink angehalten ist.

Entspricht plattformspezifischen Einstellungen: kAudioDevicePropertyBufferFrameSize (macOS), IAudioClient::bufferDuration (Windows), PW_KEY_NODE_FORCE_QUANTUM (PipeWire/Linux) und AAudioStreamBuilder_setBufferCapacityInFrames (Android).

Diese Funktion wurde in Qt 6.12 eingeführt.

Siehe auch nativePeriodFrameCount.

void QAudioSink::setVolume(qreal volume)

Stellt die Ausgangslautstärke auf „ volume “ ein.

Die Lautstärke wird linear von 0.0 (Stille) bis 1.0 (volle Lautstärke) skaliert. Werte außerhalb dieses Bereichs werden begrenzt.

Die Standardlautstärke beträgt 1.0.

Lautstärkeregler in der Benutzeroberfläche sollten in der Regel nichtlinear skaliert werden. Die Verwendung einer logarithmischen Skala führt beispielsweise zu linearen Änderungen der wahrgenommenen Lautstärke, was ein Benutzer normalerweise von einem Lautstärkeregler erwarten würde. Weitere Details finden Sie unter QtAudio::convertVolume().

Siehe auch volume().

QIODevice *QAudioSink::start()

Gibt einen Zeiger auf das interne „ QIODevice “ zurück, das zur Übertragung von Daten an den Audioausgang des Systems verwendet wird. Das Gerät ist bereits geöffnet, und mit ` write()` können Daten direkt in dieses geschrieben werden.

Wenn der „ QAudioSink “ auf das Audiogerät des Systems zugreifen kann, gibt „ state()“ „ QtAudio::IdleState “ zurück, „ error()“ gibt „ QtAudio::NoError “ zurück und das Signal „ stateChanged()“ wird ausgelöst.

Tritt während dieses Vorgangs ein Problem auf, gibt error() den Wert „ QtAudio::OpenError “ zurück, state() den Wert „ QtAudio::StoppedState “ und das Signal „ stateChanged()“ wird ausgelöst.

Siehe auch QIODevice und QIODevice interface.

[since 6.11] template <typename Callback> requires QtAudio::if_audio_sink_callback<Callback> void QAudioSink::start(Callback &&cb)

Startet den „ QAudioSink “ mit einer Callback-Funktion, die in einem Soft-Realtime-Audio-Thread aufgerufen wird. Der Callback ist ein Callable, das ein „ QSpan<SampleType>“ als Argument entgegennimmt; „SampleType“ muss mit dem „ QAudioFormat::SampleFormat “ des Formats des „ QAudioSink “ übereinstimmen. Der Bereich muss mit verschachtelten Audiodaten gefüllt sein.

Wenn der „ QAudioSink “ erfolgreich gestartet werden kann, gibt „ error()“ „ QtAudio::NoError “ zurück.

Tritt während dieses Vorgangs ein Problem auf, gibt „ error()“ „ QtAudio::OpenError “ zurück, „ state()“ gibt „ QtAudio::StoppedState “ zurück und das Signal „ stateChanged()“ wird ausgelöst.

Diese Funktion wurde in Qt 6.11 eingeführt.

Siehe auch „ Callback interface “.

void QAudioSink::start(QIODevice *device)

Startet die Übertragung von Audiodaten vom „ device “ an den Audioausgang des Systems. Das „ device “ muss im Modus „ ReadOnly “ oder „ ReadWrite “ geöffnet worden sein.

Wenn der „ QAudioSink “ Audiodaten erfolgreich ausgeben kann, gibt „ state()“ „ QtAudio::ActiveState “ zurück, „ error()“ gibt „ QtAudio::NoError “ zurück und das Signal „ stateChanged()“ wird ausgelöst.

Tritt während dieses Vorgangs ein Problem auf, gibt error() den Wert „ QtAudio::OpenError “ zurück, state() den Wert „ QtAudio::StoppedState “ und das Signal „ stateChanged()“ wird ausgelöst.

Siehe auch „ QIODevice “ und „ QIODevice interface “.

QtAudio::State QAudioSink::state() const

Gibt den Status der Audioverarbeitung zurück.

[signal] void QAudioSink::stateChanged(QtAudio::State state)

Dieses Signal wird ausgelöst, wenn sich die Eigenschaft „ state “ des Geräts geändert hat. Dies ist der aktuelle Zustand des Audioausgangs.

void QAudioSink::stop()

Beendet die Audioausgabe und trennt die Verbindung zur Systemressource.

Setzt „ error “ () auf „ QtAudio::NoError “, „ state “ () auf „ QtAudio::StoppedState “ und sendet das Signal „ stateChanged “ ().

Siehe auch ` reset()`.

void QAudioSink::suspend()

Beendet die Verarbeitung von Audiodaten, wobei die gepufferten Audiodaten erhalten bleiben.

Setzt „ state()“ auf „ QtAudio::SuspendedState “ und gibt das Signal „ stateChanged()“ aus.

qreal QAudioSink::volume() const

Gibt den Lautstärkewert zwischen 0,0 und 1,0 (einschließlich) zurück.

Siehe auch „ setVolume()“.