En esta página

Descripción general del audio

Onda sonora

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:

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++

QAmbientSound

Sonido estéreo superpuesto

QAudioBuffer

Representa una colección de muestras de audio con un formato y una frecuencia de muestreo específicos

QAudioBufferInput

Se utiliza para proporcionar búferes de audio personalizados a QMediaRecorder a través de QMediaCaptureSession

QAudioBufferOutput

Se utiliza para capturar datos de audio proporcionados por QMediaPlayer

QAudioDecoder

Implementa la decodificación de audio

QAudioDevice

Información sobre los dispositivos de audio y su funcionalidad

QAudioEngine

Gestiona un campo sonoro tridimensional

QAudioFormat

Almacena información sobre los parámetros de la secuencia de audio

QAudioInput

Representa un canal de entrada de audio

QAudioListener

Define la posición y la orientación de la persona que escucha un campo sonoro definido por QAudioEngine

QAudioOutput

Representa un canal de salida de audio

QAudioRoom

QAudioSink

Interfaz para enviar datos de audio a un dispositivo de salida de audio

QAudioSource

Interfaz para recibir datos de audio desde un dispositivo de entrada de audio

QMediaCaptureSession

Permite la captura de contenido de audio y vídeo

QMediaRecorder

Se utiliza para codificar y grabar una sesión de captura

QSoundEffect

Forma de reproducir efectos de sonido con baja latencia

QSpatialSound

Un objeto de sonido en el espacio 3D

QtAudio

Contiene enumeraciones utilizadas por las clases de audio

Tipos QML

AmbientSound

Un sonido de superposición estéreo

AudioEngine

Gestiona objetos de sonido dentro de una escena 3D

AudioInput

Una entrada de audio que se utiliza para capturar audio en una sesión de captura

AudioListener

Define la posición y la orientación de la persona que escucha un campo sonoro definido por un AudioEngine

AudioOutput

Una salida de audio que se utilizará para la reproducción o la monitorización de una sesión de captura

AudioRoom

CaptureSession

Permite la captura de contenido de audio y vídeo

MediaPlayer

Añade la reproducción multimedia a una escena

MediaRecorder

Para codificar y grabar contenidos multimedia generados en una CaptureSession

PlaybackOptions

Opciones de reproducción multimedia de bajo nivel

SoundEffect

Este tipo permite reproducir efectos de sonido en QML

SpatialSound

Un objeto de sonido en el espacio 3D

audioDevice

Describe un dispositivo de audio

mediaMetaData

Proporciona metadatos para archivos multimedia

Ejemplos

Audio Devices Example

Enumera los dispositivos de audio disponibles y su configuración.

Audio Output Example

Habilitar la reproducción de audio mediante la clase QAudioSink.

Audio Recorder Example

Detectar los dispositivos disponibles y los códecs compatibles.

Audio Source Example

Grabar audio mediante la clase QAudioSource.

Spatial Audio Panning Example

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.