1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page audiooverview.html
7\inlineimage sound-wave-small.jpg
8\brief Playback, recording and processing of Audio.
9\ingroup explanations-graphicsandmultimedia
11\section1 Audio Features
13Qt Multimedia offers a range of audio classes that cover both low and
14high level approaches to: audio input, output and processing.
16\section1 Audio Implementation Details
18\section2 Playing Compressed Audio
20For playing media or audio files that are not simple, uncompressed audio, you
21can use the QMediaPlayer C++ class, or the \l{MediaPlayer} QML type.
22The QMediaPlayer class and associated QML types are also capable of playing
23\l{multimedia-playing-video}{video}, if required.
25See \l{Supported Media Formats} for more detail.
27The media player needs to be connected to a QAudioOutput object (or the QML AudioOutput
28element) to play back audio.
30Here is how you play a local file using C++:
32 \snippet multimedia-snippets/media.cpp Local playback
34The same functionality in QML:
38 audioOutput: AudioOutput {}
39 source: "file:///path/to/my/music.mp3"
40 Component.onCompleted: { play() }
44\section2 Recording Audio to a File
46To record audio to a file, you need to create a capture session and connect to it an audio
47input and a recorder. These elements are implemented with the QMediaCaptureSession,
48QAudioInput, and QMediaRecorder classes. The default constructed QAudioInput selects the
49system default audio input. The recorder controls the recording process with a simple record()
50and stop() functions. Additionally, you can use it to select the output location, audio
51encoder, or file container format.
53A session recording audio from the default microphone would look as follows in C++:
55 \snippet multimedia-snippets/media.cpp Media recorder
57In QML, the same can be achieved by:
61 audioInput: AudioInput {}
62 mediaRecorder: MediaRecorder {
64 outputLocation: "file:///path/to/test.mp3"
66 Component.onCompleted: { recorder.record() }
70QMediaCaptureSession also provides support for more complex use cases such as image
71capturing or video recording.
73\section2 Low Latency Sound Effects
75In addition to \l{raw access} to sound devices, the QSoundEffect
76class (and \l{SoundEffect} QML type) offers a more abstract way to play
77sounds. This class allows you to specify a \b{WAV format} file, which can
78then be played with low latency when necessary.
82 \li \l{QSoundEffect::loopCount()}{Number of loops} in which a sound effect
84 \li \l{QSoundEffect::setVolume()}{Volume} of the sound effect.
85 \li \l{QSoundEffect::setMuted()}{Muting} of the sound effect.
89\section2 Low Level Audio Playback and Recording
91The C++ API of Qt Multimedia offers classes for raw access to audio input and output
92facilities, allowing applications to receive raw data from devices like
93microphones, and to write raw data to speakers or other devices. Generally
94these classes do not do any audio decoding, or other processing, but they
95can support different types of raw audio data.
97The QAudioSink class offers raw audio data output, while QAudioSource
98offers raw audio data input. The available hardware
99determines what audio outputs and inputs are available.
101\section3 Push and Pull
102The low level audio classes can operate in two modes - \c push and \c pull.
103In \c pull mode, the audio device is started by giving it a QIODevice. For
104an output device, the QAudioSink class will pull data from the QIODevice
105(using \l QIODevice::read()) when more audio data is required. Conversely,
106for \c pull mode with QAudioSource, when audio data is available then the
107data will be written directly to the QIODevice.
109In \c push mode, the audio device provides a QIODevice instance that
110can be written or read to as needed. Typically, this results in simpler
111code but more buffering, which may affect latency.
113\section2 Decoding Compressed Audio to Memory
115In some cases you may want to decode a compressed audio file and do further
116processing yourself. For example, mixing multiple samples or using custom
117digital signal processing algorithms. QAudioDecoder supports decoding local
118files or data streams from QIODevice instances.
120Here's an example of decoding a local file:
122 \snippet multimedia-snippets/audio.cpp Local audio decoding
124\section2 Spatial Audio
126The \l {Qt Spatial Audio} module provides an API for implementation sound
129\section1 Reference Documentation
133\annotatedlist multimedia_audio
137\annotatedlist multimedia_audio_qml
141\annotatedlist audio_examples