QAudioSource Class
La clase QAudioSource proporciona una interfaz para recibir datos de audio desde un dispositivo de entrada de audio. Más información...
| Encabezado: | #include <QAudioSource> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake: | QT += multimedia |
| Heredado de: | QObject |
Funciones públicas
| QAudioSource(const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr) | |
| QAudioSource(const QAudioDevice &audioDevice, const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr) | |
| virtual | ~QAudioSource() override |
(since 6.10) qsizetype | bufferFrameCount() const |
| qsizetype | bufferSize() const |
| qsizetype | bytesAvailable() const |
| qint64 | elapsedUSecs() const |
| QtAudio::Error | error() const |
| QAudioFormat | format() const |
(since 6.10) qsizetype | framesAvailable() 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 entrada de audio con el dispositivo de entrada de audio predeterminado del sistema. También es posible crear un objeto `QAudioSource` con un ` QAudioDevice` específico. Al crear la entrada de audio, también debes proporcionar el ` QAudioFormat ` que se utilizará para la grabació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
QAudioSource te permite grabar audio con un dispositivo de entrada de audio. El constructor por defecto de esta clase utilizará el dispositivo de audio predeterminado del sistema, pero también puedes especificar un ` QAudioDevice ` para un dispositivo concreto. Además, debes indicar el ` QAudioFormat ` en el que deseas grabar.
Para iniciar QAudioSource basta con llamar a ` start()` con un ` QIODevice ` abierto para escritura. Por ejemplo, para grabar en un archivo, puedes hacer lo siguiente:
QFile destinationFile; // Miembro de clase
QAudioSource* audio; // Miembro de la clase
{
destinationFile.setFileName("/tmp/test.raw");
destinationFile.open( QIODevice::WriteOnly | QIODevice::Truncate );
QAudioFormat format;
// Configura el formato deseado, por ejemplo:
format.setSampleRate(44100);
format.setChannelCount(1);
format.setSampleFormat(QAudioFormat::Int16);
QAudioDevice info = QMediaDevices::defaultAudioInput();
if (!info.isFormatSupported(format)) {
qWarning() << "Default format not supported, trying to use the nearest.";
}
audio = new QAudioSource(formato, this);
conectar(audio, &QAudioSource::stateChanged, this, &AudioInputExample::handleStateChanged);
QTimer::singleShot(3000, this, &AudioInputExample::stopRecording);
audio->start(&destinationFile);
// Graba audio durante 3000 ms
}Esto iniciará la grabación si el dispositivo de entrada admite el formato especificado (puedes comprobarlo con ` QAudioDevice::isFormatSupported()`. En caso de que surja algún problema, utiliza la función ` error()` para comprobar qué ha fallado. Detendremos la grabación en el slot ` stopRecording() `.
void AudioInputExample::stopRecording()
{
audio->stop();
destinationFile.close();
delete audio;
}En cualquier momento, QAudioSource se encontrará en uno de estos cuatro estados: activo, suspendido, detenido o inactivo. Estos estados se especifican mediante la enumeración QtAudio::State.
QAudioSource ofrece varias formas de medir el tiempo transcurrido desde el start() de la grabación. La función ` processedUSecs() ` devuelve la duración de la secuencia en microsegundos grabados; es decir, no tiene en cuenta los momentos en los que la entrada de audio estuvo suspendida o inactiva. La función ` elapsedUSecs()` devuelve el tiempo transcurrido desde que se llamó a ` start()`, independientemente de los estados en los que haya estado QAudioSource.
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 está lleno porque la aplicación no lee a tiempo desde el ` QIODevice `, el estado cambiará a « QtAudio::IdleState » y volverá a « QtAudio::ActiveState » una vez que la aplicación haya leído los datos del ` QIODevice`. Ten en cuenta que este cambio de estado provocará la pérdida de datos de audio, por lo que siempre debes leer desde el ` QIODevice ` lo más rápido posible para evitar interrupciones.
Interfaz de devolución de llamada
La forma recomendada de conseguir bajas latencias de audio es utilizar la interfaz basada en callbacks. Permite leer datos de audio directamente desde el dispositivo de audio sin tener que pasar por un QIODevice. Para ello, se llama a start() con una función de callback que se invocará desde el hilo de audio. Esta función de callback se invocará con un ` QSpan<const SampleType>` cada vez que el backend de audio genere datos.
QAudioSource* audio; // miembro de la clase.
std::atomic<float> peakLevel; // 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 capture audio.";
return;
}
audio = new QAudioSource(formato, esto);
audio->start([&nivelPico] (QSpan<float> interleavedAudioBuffer) {
float nivel = nivelPico.load();
for (float muestra : interleavedAudioBuffer) {
// Calcular el nivel pico a partir de las muestras de audio
level = std::max(level, std::abs(sample));
}
peakLevel.store(level);
// Nota: hay que tener cuidado si es necesario notificar al hilo de la aplicación, ya que la
// llamada de retorno de audio no debe utilizar ninguna llamada al sistema que pueda bloquear el sistema.
// Buenas opciones son los eventos de reinicio automático (Windows), eventfd (Linux) o kqueue/EVFILT_USER en macOS.
});
if (!audio->error()== QtAudio::Error::NoError) {
// Además de las otras firmas de start(), la ejecución de 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, QAudioSource 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 solicitar un cambio de estado directamente mediante « suspend()», « resume()», « stop()», « reset()» y « start()».
error type QAudioSource entrará en el estado « StoppedState » cuando se produzca un error. El estado « » 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 ».
void AudioInputExample::handleStateChanged(QtAudio::State newState)
{
switch (newState) {
case QtAudio::StoppedState:
if (audio->error() != QtAudio::NoError) {
// Error handling
} else {
// Finished recording
}
break;
case QtAudio::ActiveState:
// Started recording - read from IO device
break;
default:
// ... other cases as appropriate
break;
}
}Véase también QAudioSink y QAudioDevice.
Documentación de las funciones de miembro
[explicit] QAudioSource::QAudioSource(const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)
Crea una nueva entrada de audio y asígnala a parent. El dispositivo de entrada de audio predeterminado se utiliza 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] QAudioSource::QAudioSource(const QAudioDevice &audioDevice, const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)
Crea una nueva entrada de audio y asóciala a parent. El dispositivo al que hace referencia audioDevice se utiliza con los parámetros de entrada format. Si format se inicializa con los valores por defecto, el formato se establecerá en el formato preferido de audioDevice.
[override virtual noexcept] QAudioSource::~QAudioSource()
Elimina esta entrada de audio.
[since 6.10] qsizetype QAudioSource::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 QAudioSource::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 previamente se ha invocado 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 QAudioSource::bytesAvailable() const
Devuelve la cantidad de datos de audio disponibles para su lectura, expresada en bytes.
Nota: el valordevuelto solo es válido mientras se encuentre en estado « QtAudio::ActiveState » o « QtAudio::IdleState »; en caso contrario, devuelve cero.
Véase también framesAvailable.
qint64 QAudioSource::elapsedUSecs() const
Devuelve los microsegundos transcurridos desde que se llamó a start(), incluido el tiempo en los estados «Idle» y «Suspend».
QtAudio::Error QAudioSource::error() const
Devuelve el estado de error.
QAudioFormat QAudioSource::format() const
Devuelve el objeto ` QAudioFormat ` que se está utilizando.
[since 6.10] qsizetype QAudioSource::framesAvailable() const
Devuelve la cantidad de datos de audio disponibles para su lectura en tramas.
Nota: el valor devuelto solo es válido mientras se encuentre en el estado « QtAudio::ActiveState » o « QtAudio::IdleState »; en caso contrario, devuelve cero.
Esta función se introdujo en Qt 6.10.
Véase también « bytesAvailable ».
bool QAudioSource::isNull() const
Devuelve « true » si la fuente de audio es « null »; en caso contrario, devuelve « false ».
[since 6.12] qsizetype QAudioSource::nativePeriodFrameCount() const
Devuelve el recuento nativo de fotogramas por 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 QAudioSource::processedUSecs() const
Devuelve la cantidad de datos de audio procesados desde que se llamó a start() en microsegundos.
void QAudioSource::reset()
Elimina todos los datos de audio de los búferes y restablece los búferes a cero.
void QAudioSource::resume()
Reanuda el procesamiento de los datos de audio tras una llamada a ` suspend()`.
Establece state() en el estado que tenía el receptor cuando se llamó a suspend(). Esta función no realiza ninguna acción si el estado del receptor de audio no es QtAudio::SuspendedState.
[since 6.10] void QAudioSource::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 invocaciones 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 « 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 QAudioSource::setBufferSize(qsizetype value)
Establece el tamaño del búfer de audio en value bytes.
Nota: Esta función se puede invocar en cualquier momento antes de start(); las invocaciones posteriores a start() se ignoran. No debe darse por sentado que el tamaño de búfer establecido sea el tamaño real utilizado; al invocar bufferSize() en cualquier momento después de start() se obtendrá 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 QAudioSource::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 desbordamientos del 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 llamar a esta función cuando la fuente de audio está detenida.
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 QAudioSource::setVolume(qreal volume)
Establece el volumen de entrada 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.
Si el dispositivo no admite el ajuste del volumen de entrada, se ignorará volume y el volumen de entrada se mantendrá en 1,0.
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.
Véase también volume().
QIODevice *QAudioSource::start()
Devuelve un puntero al dispositivo de entrada de audio interno « QIODevice » que se está utilizando para transferir datos desde la entrada de audio del sistema. El dispositivo ya estará abierto y la función ` read()` podrá leer datos directamente de é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 ` QAudioSource ` 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_source_callback<Callback> void QAudioSource::start(Callback &&cb)
Inicia el « QAudioSource » 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 « QSpan<const SampleType>»; «SampleType» debe coincidir con el « QAudioFormat::SampleFormat » del formato del « QAudioSource ». El «span» contiene los datos de audio entrelazados.
Si el QAudioSource se inicia correctamente, error() devuelve QtAudio::NoError.
Si se produce algún 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 de PulseAudio o PipeWire) y Android.
Nota: La llamada de retorno se ejecutará en un hilo de audio de 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 llamada de retorno de audio.
Esta función se introdujo en Qt 6.11.
Véase también Callback interface.
void QAudioSource::start(QIODevice *device)
Inicia la transferencia de datos de audio desde la entrada de audio del sistema al ` device`. El ` device ` debe haberse abierto en los modos ` WriteOnly`, ` Append ` o ` ReadWrite `.
Si el « QAudioSource » consigue obtener datos de audio correctamente, « state()» devuelve « QtAudio::ActiveState » o « 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.
QtAudio::State QAudioSource::state() const
Devuelve el estado del procesamiento de audio.
[signal] void QAudioSource::stateChanged(QtAudio::State state)
Esta señal se emite cuando el dispositivo state ha cambiado.
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 QAudioSource::stop()
Detiene la entrada de audio y se desconecta del recurso del sistema.
Establece ` error()` en ` QtAudio::NoError`, ` state()` en ` QtAudio::StoppedState ` y emite la señal ` stateChanged()`.
void QAudioSource::suspend()
Detiene el procesamiento de los datos de audio, conservando los datos de audio almacenados en el búfer.
Establece ` error()` en ` QtAudio::NoError`, ` state()` en ` QtAudio::SuspendedState ` y emite la señal ` stateChanged()`.
qreal QAudioSource::volume() const
Devuelve el volumen de entrada.
Si el dispositivo no admite el ajuste del volumen de entrada, el valor devuelto será 1,0.
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.