Descripción general del audio

Características de audio
Qt Multimedia ofrece una serie de clases sobre audio que abarcan enfoques tanto de bajo como de alto nivel sobre: entrada, salida y procesamiento de audio.
Detalles de la implementación de audio
Reproducción de audio comprimido
Para reproducir archivos multimedia o de audio que no sean simples archivos de audio sin comprimir, puedes utilizar la clase C++ ` QMediaPlayer ` o el tipo QML ` MediaPlayer `. La clase ` QMediaPlayer ` y los tipos QML asociados también permiten reproducir vídeo, si fuera necesario.
Consulte Formatos multimedia compatibles para obtener más detalles.
El reproductor multimedia debe estar conectado a un objeto QAudioOutput (o al elemento QML AudioOutput ) para reproducir audio.
A continuación se explica cómo reproducir un archivo local utilizando 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();La misma funcionalidad en QML:
MediaPlayer {
audioOutput: AudioOutput {}
source: "file:///path/to/my/music.mp3"
Component.onCompleted: { play() }
}Grabación de audio en un archivo
Para grabar audio en un archivo, es necesario crear una sesión de captura y conectarle una entrada de audio y una grabadora. Estos elementos se implementan mediante las clases QMediaCaptureSession, QAudioInput y QMediaRecorder. La clase QAudioInput, creada por defecto, selecciona la entrada de audio predeterminada del sistema. La grabadora controla el proceso de grabación mediante las sencillas funciones record() y stop(). Además, puedes utilizarla para seleccionar la ubicación de salida, el codificador de audio o el formato del contenedor de archivos.
Una sesión de grabación de audio desde el micrófono predeterminado tendría el siguiente aspecto en 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();En QML, se puede conseguir lo mismo de la siguiente manera:
CaptureSession {
audioInput: AudioInput {}
mediaRecorder: MediaRecorder {
id: recorder
outputLocation: "file:///path/to/test.mp3"
}
Component.onCompleted: { recorder.record() }
}QMediaCaptureSession También ofrece compatibilidad con casos de uso más complejos, como la captura de imágenes o la grabación de vídeo.
Efectos de sonido de baja latencia
Además del acceso directo a los dispositivos de sonido, la clase ` QSoundEffect ` (y el tipo QML ` SoundEffect `) ofrece una forma más abstracta de reproducir sonidos. Esta clase permite especificar un archivo en formato WAV, que luego se puede reproducir con baja latencia cuando sea necesario.
Puedes ajustar:
- Number of loops en el que se reproduce un efecto de sonido.
- Volume del efecto de sonido.
- Muting del efecto de sonido.
Entrada y salida de audio de bajo nivel
La API en C++ de Qt Multimedia ofrece clases para el acceso sin procesar a los recursos de entrada y salida de audio, lo que permite a las aplicaciones recibir datos sin procesar de dispositivos como micrófonos y enviar datos sin procesar a altavoces u otros dispositivos. Por lo general, estas clases no realizan ninguna decodificación de audio ni ningún otro tipo de procesamiento, pero admiten diferentes tipos de datos de audio sin procesar.
La clase ` QAudioSink ` permite la salida de datos de audio sin procesar, mientras que ` QAudioSource ` permite la entrada de datos de audio sin procesar. El hardware disponible determina qué salidas y entradas de audio están disponibles.
Push y Pull con QIODevice
Las clases de audio de bajo nivel pueden funcionar en dos modos: « push » y « pull ». En el modo « pull », el dispositivo de audio se inicia proporcionándole un « QIODevice ». En el caso de un dispositivo de salida, la clase « QAudioSink » extraerá datos del « QIODevice » (utilizando « QIODevice::read()») cuando se necesiten más datos de audio. Por el contrario, en el modo « pull » con « QAudioSource », cuando haya datos de audio disponibles, estos se escribirán directamente en el « QIODevice ».
En el modo « push », el dispositivo de audio proporciona una instancia de « QIODevice » en la que se puede escribir o leer según sea necesario.
Nota: El QIODevice no accede inmediatamente al dispositivo de audio, sino que almacena los datos en un búfer interno. Esto significa que el QIODevice se puede utilizar para escribir o leer datos en cualquier momento desde el hilo de la aplicación, y se añade un tiempo de búfer de normalmente 250 ms. Si la aplicación no envía datos de audio a QIODevice con la suficiente rapidez (para QAudioSink) o no lee QIODevice con la suficiente rapidez, se producirán cortes en el audio.
Interfaz basada en callbacks
Además de utilizar una interfaz basada en QIODevice, las clases de audio de bajo nivel proporcionan una interfaz basada en callbacks que permite a los usuarios registrar un callback que se invoca en el hilo de audio cada vez que el dispositivo de audio necesita o envía más datos. Esto permite un procesamiento de audio con una latencia mucho menor, ya que la aplicación puede procesar los datos directamente en el hilo de audio.
{
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 proceso
// Llenar el búfer de audio con una onda sinusoidal
const int sampleCount = interleavedAudioBuffer.size() / 2; // Es estéreo, así que se divide por 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; // Incrementar la fase para la siguiente muestra
}
});
if (!audio->error()== QtAudio::Error::NoError) {
// además de las otras firmas de start(), la ejecución de la función de devolución de llamada de audio fallará si
// * el backend no implementa E/S basada en funciones de devolución de llamada (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();
}
}Nota: Esta API solo está disponible en plataformas que admitan la API de devolución de llamada: CoreAudio de Apple (macOS, iOS, etc.), Windows, Linux (utilizando el backend PulseAudio o PipeWire) y Android.
Nota: La función de devolución de llamada se ejecutará en un hilo de audio de tiempo real aproximado. Es importante asegurarse de que la función de devolución de llamada no bloquee, ya que esto puede provocar fallos o interrupciones en el audio. Esto incluye realizar operaciones de E/S que bloqueen, bloquear mutexes, asignar memoria o cualquier otra operación que pueda bloquear el sistema. 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 utilizar el sanitizador en tiempo real de Clang para validar la función de devolución de llamada de audio.
Decodificación de audio comprimido en memoria
En algunos casos, es posible que desees decodificar un archivo de audio comprimido y realizar tú mismo un procesamiento adicional. Por ejemplo, mezclar varias muestras o utilizar algoritmos personalizados de procesamiento de señales digitales. « QAudioDecoder » admite la decodificación de archivos locales o flujos de datos procedentes de instancias de « QIODevice ».
A continuación se muestra un ejemplo de decodificación de un archivo local:
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()Audio espacial
El Qt Spatial Audio módulo proporciona una API para implementar campos sonoros en el espacio 3D.
Documentación de referencia
Clases de C++
Sonido estéreo superpuesto | |
Representa una colección de muestras de audio con un formato y una frecuencia de muestreo específicos | |
Se utiliza para proporcionar búferes de audio personalizados a QMediaRecorder a través de QMediaCaptureSession | |
Se utiliza para capturar datos de audio proporcionados por QMediaPlayer | |
Implementa la decodificación de audio | |
Información sobre los dispositivos de audio y su funcionalidad | |
Gestiona un campo sonoro tridimensional | |
Almacena información sobre los parámetros de la secuencia de audio | |
Representa un canal de entrada de audio | |
Define la posición y la orientación de la persona que escucha un campo sonoro definido por QAudioEngine | |
Representa un canal de salida de audio | |
Interfaz para enviar datos de audio a un dispositivo de salida de audio | |
Interfaz para recibir datos de audio desde un dispositivo de entrada de audio | |
Permite la captura de contenido de audio y vídeo | |
Se utiliza para codificar y grabar una sesión de captura | |
Forma de reproducir efectos de sonido con baja latencia | |
Un objeto de sonido en el espacio 3D | |
Contiene enumeraciones utilizadas por las clases de audio |
Tipos QML
Un sonido de superposición estéreo | |
Gestiona objetos de sonido dentro de una escena 3D | |
Una entrada de audio que se utiliza para capturar audio en una sesión de captura | |
Define la posición y la orientación de la persona que escucha un campo sonoro definido por un AudioEngine | |
Una salida de audio que se utilizará para la reproducción o la monitorización de una sesión de captura | |
Permite la captura de contenido de audio y vídeo | |
Añade la reproducción multimedia a una escena | |
Para codificar y grabar contenidos multimedia generados en una CaptureSession | |
Opciones de reproducción multimedia de bajo nivel | |
Este tipo permite reproducir efectos de sonido en QML | |
Un objeto de sonido en el espacio 3D | |
Describe un dispositivo de audio | |
Proporciona metadatos para archivos multimedia |
Ejemplos
Enumera los dispositivos de audio disponibles y su configuración. | |
Habilitar la reproducción de audio mediante la clase QAudioSink. | |
Detectar los dispositivos disponibles y los códecs compatibles. | |
Grabar audio mediante la clase QAudioSource. | |
Muestra algunas de las capacidades del motor de audio espacial de Qt |
© 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.