QAudioSink Class
La clase QAudioSink ofrece una interfaz para enviar datos de audio a un dispositivo de salida de audio. Más información...
| Encabezado: | #include <QAudioSink> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake: | QT += multimedia |
| Heredado de: | QObject |
Funciones públicas
| QAudioSink(const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr) | |
| QAudioSink(const QAudioDevice &audioDevice, const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr) | |
| virtual | ~QAudioSink() override |
(since 6.10) qsizetype | bufferFrameCount() const |
| qsizetype | bufferSize() const |
| qsizetype | bytesFree() const |
| qint64 | elapsedUSecs() const |
| QtAudio::Error | error() const |
| QAudioFormat | format() const |
(since 6.10) qsizetype | framesFree() const |
| bool | isNull() const |
(since 6.12) qsizetype | nativePeriodFrameCount() const |
| qint64 | processedUSecs() const |
| void | reset() |
| void | resume() |
(since 6.10) void | setBufferFrameCount(qsizetype value) |
| void | setBufferSize(qsizetype value) |
(since 6.12) void | setNativePeriodFrameCount(qsizetype frameCount) |
| void | setVolume(qreal volume) |
| QIODevice * | start() |
(since 6.11) void | start(Callback &&cb) |
| void | start(QIODevice *device) |
| QtAudio::State | state() const |
| void | stop() |
| void | suspend() |
| qreal | volume() const |
Señales
| void | stateChanged(QtAudio::State state) |
Descripción detallada
Puedes crear una salida de audio con el dispositivo de salida de audio predeterminado del sistema. También es posible crear un `QAudioSink` con un ` QAudioDevice` específico. Al crear la salida de audio, también debes especificar el ` QAudioFormat ` que se utilizará para la reproducción (consulta la descripción de la clase ` QAudioFormat ` para obtener más detalles).
QAudioSink se puede utilizar en dos modos diferentes:
- Utilizando un QIODevice desde un hilo de la aplicación
- Utilizando una interfaz basada en callbacks desde el hilo de audio
Interfaz QIODevice
Para iniciar la reproducción de un flujo de audio basta con llamar a ` start()` con un ` QIODevice`. A continuación, `QAudioSink` obtendrá los datos que necesita del dispositivo de E/S. Así pues, reproducir un archivo de audio es tan sencillo como:
QFile sourceFile; // miembro de clase.
QAudioSink* audio; // miembro de la clase.
{
sourceFile.setFileName("/tmp/test.raw");
sourceFile.open(QIODevice::ReadOnly);
QAudioFormat format;
// Configurar el formato, p. ej.
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(formato, this);
connect(audio, QAudioSink::stateChanged, this, &AudioInputExample::handleStateChanged);
audio->start(&sourceFile);
}El archivo comenzará a reproducirse, siempre que el sistema de audio y el dispositivo de salida lo admitan. Si no tienes suerte, comprueba qué ocurre con la función error().
Una vez finalizada la reproducción del archivo, debemos detener el dispositivo:
void AudioOutputExample::stopAudioOutput()
{
audio->stop();
sourceFile.close();
delete audio;
}En cualquier momento dado, QAudioSink se encontrará en uno de estos cuatro estados: activo, suspendido, detenido o inactivo. Estos estados se describen mediante la enumeración QtAudio::State.
Modelo de subprocesos y almacenamiento en búfer
La interfaz ` QIODevice ` está diseñada para utilizarse desde el hilo de la aplicación. Se utiliza un búfer circular sin esperas para comunicarse con el hilo de audio. El tamaño de este búfer circular se puede configurar con ` setBufferSize()` y el valor por defecto es de 250 ms. El estado de este búfer se puede consultar con ` bytesFree()`. Si el búfer circular se queda sin datos, el hilo de audio enviará silencio al dispositivo de audio y el estado cambiará a « QtAudio::IdleState » y volverá a « QtAudio::ActiveState » cuando haya más datos disponibles en ` QIODevice`.
Interfaz de devolución de llamada
La forma recomendada de lograr una baja latencia de audio es utilizar la interfaz basada en callbacks. Permite escribir datos de audio directamente en el dispositivo de audio sin tener que pasar por un ` QIODevice`. Esto se hace llamando a ` start()` con una función de callback que será invocada desde el hilo de audio. Esta función de llamada de retorno se invocará con un QSpan<SampleType> cada vez que el backend de audio requiera datos.
QAudioSink* audio; // miembro de la clase.
float phase; // miembro de la clase.
{
QAudioFormat format;
// Configurar el formato, p. ej.:
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(); // Onda sinusoidal de 220 Hz
audio->start([&phase, phaseIncrement] (QSpan<float> interleavedAudioBuffer) {
// La llamada de retorno de audio no debe llamar a ninguna función que pueda bloquear el sistema
// Rellena el búfer de audio con una onda sinusoidal
const int sampleCount = interleavedAudioBuffer.size() / 2; // Es estéreo, así que se divide entre 2
for (int i = 0; i < sampleCount;++i) {
float sample = std::sin(phase);
interleavedAudioBuffer[i * 2] = sample; // Canal izquierdo
interleavedAudioBuffer[i * 2 + 1] = sample; // Canal derecho
phase+= phaseIncrement; // Incrementa la fase para la siguiente muestra
}
});
if (!audio->error()== QtAudio::Error::NoError) {
// además de las otras firmas de start(), la llamada de retorno de audio fallará si
// * el backend no implementa E/S basada en llamadas de retorno (la API está disponible en todas las principales
// plataformas)
// * la firma de la llamada de retorno de audio no coincide con format.sampleFormat()
qWarning() << "Error starting audio output:" << audio->errorString();
}
}A diferencia de la interfaz basada en ` QIODevice`, `QAudioSink` solo puede encontrarse en los estados «active», «suspended» y «stopped». La API ` setBufferSize()` no está disponible cuando se utiliza la función de devolución de llamada; el tamaño del argumento de la función de devolución de llamada viene determinado por el backend de audio.
Nota: Esta API solo está disponible en plataformas que admiten la API de callback: CoreAudio de Apple (macOS, iOS, etc.), Windows, Linux (utilizando el backend PulseAudio o PipeWire) y Android.
Nota: La llamada de retorno se ejecutará en un hilo de audio en tiempo real suave. Es importante asegurarse de que la llamada de retorno no se bloquee, ya que esto puede provocar fallos o cortes en el audio. Esto incluye realizar operaciones de E/S que bloqueen, bloquear mutexes, asignar memoria o cualquier otra operación que pueda provocar un bloqueo. Para conocer las mejores prácticas, consulta el artículo de Ross Bencina «Real-time audio programming 101: time waits for nothing». Considera también el uso del sanitizador en tiempo real de clang para validar la función de devolución de llamada de audio.
Gestión del estado y de los errores
Los cambios de estado se notifican a través de la señal « stateChanged()». Puedes utilizar esta señal para, por ejemplo, actualizar la interfaz gráfica de usuario (GUI) de la aplicación; un ejemplo sencillo sería cambiar el estado de un botón « play/pause ». Se solicita un cambio de estado directamente con « suspend()», « stop()», « reset()», « resume()» y « start()».
QAudioSink entrará en el estado « StoppedState » cuando se produzca un error. El estado « error type » se puede obtener mediante la función error(). Consulte la enumeración QtAudio::Error para obtener una descripción de los posibles errores que se notifican. Al llamar a stop() o reset(), se restablecerá el estado de error a NoError.
Puede comprobar si hay errores conectándose a la señal « stateChanged()»:
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;
}
}Véase también QAudioSource y QAudioDevice.
Documentación de las funciones miembro
[explicit] QAudioSink::QAudioSink(const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)
Crea una nueva salida de audio y asóciala a ` parent`. Se utiliza el dispositivo de salida de audio predeterminado con los parámetros de salida ` format `. Si ` format ` se inicializa con los valores predeterminados, el formato se establecerá en el formato preferido del dispositivo de audio.
[explicit] QAudioSink::QAudioSink(const QAudioDevice &audioDevice, const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)
Crea una nueva salida de audio y vincúlala a parent. El dispositivo al que hace referencia audioDevice se utiliza con los parámetros de salida format. Si format se inicializa con los valores por defecto, el formato se establecerá en el formato preferido de audioDevice.
[override virtual noexcept] QAudioSink::~QAudioSink()
Elimina esta salida de audio.
Esto liberará los recursos del sistema utilizados y desocupará los búferes.
[since 6.10] qsizetype QAudioSink::bufferFrameCount() const
Devuelve el tamaño del búfer de audio en fotogramas.
Si se invoca antes de start(), devuelve el valor predeterminado de la plataforma. Si se invoca antes de start(), pero se ha invocado previamente setBufferSize() o setBufferFrameCount(), devuelve el valor establecido por setBufferSize() o setBufferFrameCount(). Si se invoca después de start(), devuelve el tamaño real del búfer que se está utilizando. Es posible que este no sea el valor establecido previamente por setBufferSize() o setBufferFrameCount().
Esta función se introdujo en Qt 6.10.
Véase también setBufferFrameCount() y bufferSize.
qsizetype QAudioSink::bufferSize() const
Devuelve el tamaño del búfer de audio en bytes.
Si se invoca antes de start(), devuelve el valor predeterminado de la plataforma. Si se invoca antes de start() pero se ha invocado previamente setBufferSize() o setBufferFrameCount(), devuelve el valor establecido por setBufferSize() o setBufferFrameCount(). Si se invoca después de start(), devuelve el tamaño real del búfer que se está utilizando. Es posible que este no sea el valor establecido previamente por setBufferSize() o setBufferFrameCount().
Véase también setBufferSize() y bufferFrameCount.
qsizetype QAudioSink::bytesFree() const
Devuelve el número de bytes libres disponibles en el búfer de audio.
Nota: El valor devuelto solo es válido mientras se encuentre en estado « QtAudio::ActiveState » o « QtAudio::IdleState »; en caso contrario, devuelve cero.
Véase también framesFree.
qint64 QAudioSink::elapsedUSecs() const
Devuelve los microsegundos transcurridos desde que se llamó a ` start()`, incluido el tiempo en los estados «Idle» y «Suspend».
QtAudio::Error QAudioSink::error() const
Devuelve el estado de error.
QAudioFormat QAudioSink::format() const
Devuelve el objeto ` QAudioFormat ` que se está utilizando.
[since 6.10] qsizetype QAudioSink::framesFree() const
Devuelve el número de tramas libres disponibles en el búfer de audio.
Nota: El valor devuelto solo es válido mientras se encuentre en estado « QtAudio::ActiveState » o « QtAudio::IdleState »; en caso contrario, devuelve cero.
Esta función se introdujo en Qt 6.10.
Véase también bytesFree.
bool QAudioSink::isNull() const
Devuelve « true » si la instancia de « QAudioSink » es « null »; en caso contrario, devuelve « false ».
[since 6.12] qsizetype QAudioSink::nativePeriodFrameCount() const
Devuelve el recuento nativo de fotogramas del periodo.
Devuelve -1 si no está establecido; en caso contrario, devuelve el valor establecido previamente con setNativePeriodFrameCount().
Esta función se introdujo en Qt 6.12.
Véase también ` setNativePeriodFrameCount`.
qint64 QAudioSink::processedUSecs() const
Devuelve la cantidad de datos de audio procesados desde que se llamó a start() (en microsegundos).
void QAudioSink::reset()
Detiene inmediatamente la salida de audio y descarta cualquier dato de audio que se encuentre actualmente en los búferes. Se ignoran todos los datos de audio pendientes enviados a QIODevice.
Véase también ` stop()`.
void QAudioSink::resume()
Reanuda el procesamiento de datos de audio tras una llamada a ` suspend()`.
Establece state() en el estado que tenía el sumidero cuando se llamó a suspend(). Esta función no realiza ninguna acción si el estado del sumidero de audio no es QtAudio::SuspendedState.
[since 6.10] void QAudioSink::setBufferFrameCount(qsizetype value)
Establece el tamaño del búfer de audio en value en número de fotogramas.
Nota: Esta función se puede invocar en cualquier momento antes de « start()». Las llamadas a esta función se ignoran después de « start()». No debe darse por sentado que el tamaño de búfer establecido sea el tamaño real utilizado; invoque « bufferFrameCount()» en cualquier momento después de « start()» para obtener el tamaño real del búfer que se está utilizando.
Las propiedades bufferFrameCount() y bufferSize() indican el tamaño del búfer circular cuando se utilizan las API de QIODevice. El tamaño nativo del periodo se controla mediante setNativePeriodFrameCount().
Esta función se introdujo en Qt 6.10.
Véase también bufferFrameCount() y setBufferSize.
void QAudioSink::setBufferSize(qsizetype value)
Establece el tamaño del búfer de audio en value en bytes.
Nota: Esta función se puede invocar en cualquier momento antes de start(). Las llamadas a esta función se ignoran después de start(). No se debe dar por sentado que el tamaño del búfer establecido sea el tamaño real utilizado; invoque bufferSize() en cualquier momento después de start() para obtener el tamaño real del búfer que se está utilizando.
Las propiedades bufferFrameCount() y bufferSize() indican el tamaño del búfer circular cuando se utilizan las API de QIODevice. El tamaño nativo del periodo se controla mediante setNativePeriodFrameCount().
Véase también bufferSize() y setBufferFrameCount.
[since 6.12] void QAudioSink::setNativePeriodFrameCount(qsizetype frameCount)
Establece el número de fotogramas del periodo nativo en « frameCount ».
Ajusta el tamaño del búfer de audio utilizado por el sistema operativo y el hardware. Por defecto (cuando no se especifica), el sistema utiliza un valor que depende de la plataforma, normalmente 1024 fotogramas (~23 ms a 44 100 Hz).
Utiliza valores más pequeños (64-256) para reducir la latencia, o valores más grandes (2048-4096) para reducir el riesgo de que se produzcan «underruns» en el búfer (pérdidas de señal).
Los valores válidos son potencias de 2 entre 32 y 4096 (ambos inclusive), o -1 para desactivarlo. Solo se puede invocar cuando el receptor de audio está detenido.
Se corresponde con los ajustes específicos de cada plataforma: kAudioDevicePropertyBufferFrameSize (macOS), IAudioClient::bufferDuration (Windows), PW_KEY_NODE_FORCE_QUANTUM (PipeWire/Linux) y AAudioStreamBuilder_setBufferCapacityInFrames (Android).
Nota: Esto es independiente del búfer circular configurado con setBufferSize() o setBufferFrameCount().
Esta función se introdujo en Qt 6.12.
Véase también nativePeriodFrameCount.
void QAudioSink::setVolume(qreal volume)
Establece el volumen de salida en volume.
El volumen se escala linealmente desde 0.0 (silencio) hasta 1.0 (volumen máximo). Los valores fuera de este rango se limitarán.
El volumen por defecto es 1.0.
Nota: Los ajustes en el volumen modificarán el volumen de esta secuencia de audio, no el volumen global.
Los controles de volumen de la interfaz de usuario suelen escalarse de forma no lineal. Por ejemplo, el uso de una escala logarítmica producirá cambios lineales en el volumen percibido, que es lo que un usuario esperaría normalmente de un control de volumen. Consulta QtAudio::convertVolume() para obtener más detalles.
Véase también volume().
QIODevice *QAudioSink::start()
Devuelve un puntero al dispositivo de salida de audio interno ( QIODevice ) que se está utilizando para transferir datos a la salida de audio del sistema. El dispositivo ya estará abierto y la función ` write()` podrá escribir datos directamente en él.
Nota: El puntero dejará de ser válido una vez que se detenga la transmisión o si se inicia otra transmisión.
Si el QAudioSink puede acceder al dispositivo de audio del sistema, state() devuelve QtAudio::IdleState, error() devuelve QtAudio::NoError y se emite la señal stateChanged().
Si se produce un problema durante este proceso, error() devuelve QtAudio::OpenError, state() devuelve QtAudio::StoppedState y se emite la señal stateChanged().
Véase también QIODevice y QIODevice interface.
[since 6.11] template <typename Callback> requires QtAudio::if_audio_sink_callback<Callback> void QAudioSink::start(Callback &&cb)
Inicia el « QAudioSink » con una función de devolución de llamada que se ejecutará en un hilo de audio en tiempo real suave. La función de devolución de llamada es un objeto ejecutable que toma como argumento un objeto « QSpan » de tipo «<SampleType>»; «SampleType» debe coincidir con el « QAudioFormat::SampleFormat » del formato del « QAudioSink ». El «span» debe estar rellenado con datos de audio intercalados.
Si el QAudioSink se inicia correctamente, error() devuelve QtAudio::NoError.
Si se produce un problema durante este proceso, error() devuelve QtAudio::OpenError, state() devuelve QtAudio::StoppedState y se emite la señal stateChanged().
Nota: Esta API solo está disponible en plataformas que admitan la API de callback: CoreAudio de Apple (macOS, iOS, etc.), Windows, Linux (utilizando el backend PulseAudio o PipeWire) y Android.
Nota: La llamada de retorno se ejecutará en un hilo de audio en tiempo real suave. Es importante asegurarse de que la llamada de retorno no se bloquee, ya que esto puede provocar fallos o cortes en el audio. Esto incluye realizar operaciones de E/S que bloqueen, bloquear mutexes, asignar memoria o cualquier otra operación que pueda provocar un bloqueo. Para conocer las mejores prácticas, consulta el artículo de Ross Bencina «Programación de audio en tiempo real 101: el tiempo no espera a nadie». Considera también el uso del sanitizador en tiempo real de clang para validar la función de devolución de llamada de audio.
Esta función se introdujo en Qt 6.11.
Véase también Callback interface.
void QAudioSink::start(QIODevice *device)
Inicia la transferencia de datos de audio desde el « device » a la salida de audio del sistema. El « device » debe haberse abierto en los modos « ReadOnly » o « ReadWrite ».
Si el « QAudioSink » es capaz de emitir datos de audio correctamente, « state()» devuelve « QtAudio::ActiveState », « error()» devuelve « QtAudio::NoError » y se emite la señal « stateChanged()».
Si se produce un problema durante este proceso, error() devuelve QtAudio::OpenError, state() devuelve QtAudio::StoppedState y se emite la señal stateChanged().
Véase también QIODevice y QIODevice interface.
QtAudio::State QAudioSink::state() const
Devuelve el estado del procesamiento de audio.
[signal] void QAudioSink::stateChanged(QtAudio::State state)
Esta señal se emite cuando ha cambiado el dispositivo state. Este es el estado actual de la salida de audio.
Nota: El espacio de nombres « QtAudio » se denominaba «QAudio» hasta la versión Qt 6.6, incluida. Las conexiones basadas en cadenas a esta señal deben utilizar « QAudio::State » como tipo de parámetro: connect(source, SIGNAL(stateChanged(QAudio::State)), ...);
void QAudioSink::stop()
Detiene la salida de audio, desconectándose del recurso del sistema.
Establece ` error()` en ` QtAudio::NoError`, ` state()` en ` QtAudio::StoppedState ` y emite la señal ` stateChanged()`.
Nota: En Linux y Darwin, esta operación vacía de forma sincrónica el búfer de audio subyacente, lo que puede provocar retrasos en función de la carga útil del búfer. Para restablecer todos los búferes de forma inmediata, utilice en su lugar el método reset.
Véase también ` reset()`.
void QAudioSink::suspend()
Detiene el procesamiento de los datos de audio, conservando los datos de audio almacenados en el búfer.
Establece ` state()` en ` QtAudio::SuspendedState ` y emite la señal ` stateChanged()`.
qreal QAudioSink::volume() const
Devuelve el volumen entre 0,0 y 1,0, ambos inclusive.
Véase también setVolume().
© 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.