diff options
Diffstat (limited to 'src/multimedia/doc/src/audiooverview.qdoc')
| -rw-r--r-- | src/multimedia/doc/src/audiooverview.qdoc | 158 |
1 files changed, 78 insertions, 80 deletions
diff --git a/src/multimedia/doc/src/audiooverview.qdoc b/src/multimedia/doc/src/audiooverview.qdoc index d39738da4..40a6318a6 100644 --- a/src/multimedia/doc/src/audiooverview.qdoc +++ b/src/multimedia/doc/src/audiooverview.qdoc @@ -1,136 +1,130 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page audiooverview.html \title Audio Overview -\brief Audio playback, recording and processing +\inlineimage sound-wave-small.jpg +\brief Playback, recording and processing of Audio. +\ingroup explanations-graphicsandmultimedia \section1 Audio Features -Qt Multimedia offers a range of audio classes, covering both low and -high level approaches to audio input, output and processing. In -addition to traditional audio usage, the \l{Qt Audio Engine QML Types}{Qt Audio Engine} -QML types offer high level 3D positional audio for QML applications. -See that documentation for more information. +Qt Multimedia offers a range of audio classes that cover both low and +high level approaches to: audio input, output and processing. \section1 Audio Implementation Details \section2 Playing Compressed Audio -For playing media or audio files that are not simple, uncompressed audio, you can -use the \l QMediaPlayer C++ class, or the \l {Audio} and \l {MediaPlayer} QML types. + +For playing media or audio files that are not simple, uncompressed audio, you +can use the QMediaPlayer C++ class, or the \l{MediaPlayer} QML type. The QMediaPlayer class and associated QML types are also capable of playing -\l{multimedia-playing-video}{video}, if required. The compressed audio formats supported does depend -on the operating system environment, and also what media plugins the user -may have installed. +\l{multimedia-playing-video}{video}, if required. + +See \l{Supported Media Formats} for more detail. + +The media player needs to be connected to a QAudioOutput object (or the QML AudioOutput +element) to play back audio. Here is how you play a local file using C++: \snippet multimedia-snippets/media.cpp Local playback -You can also put files (even remote URLs) into a playlist: - \snippet multimedia-snippets/media.cpp Audio playlist +The same functionality in QML: + +\qml +MediaPlayer { + audioOutput: AudioOutput {} + source: "file:///path/to/my/music.mp3" + Component.onCompleted: { play() } +} +\endqml \section2 Recording Audio to a File -For recording audio to a file, the \l {QAudioRecorder} class allows you -to compress audio data from an input device and record it. - \snippet multimedia-snippets/media.cpp Audio recorder +To record audio to a file, you need to create a capture session and connect to it an audio +input and a recorder. These elements are implemented with the QMediaCaptureSession, +QAudioInput, and QMediaRecorder classes. The default constructed QAudioInput selects the +system default audio input. The recorder controls the recording process with a simple record() +and stop() functions. Additionally, you can use it to select the output location, audio +encoder, or file container format. -\section2 Low Latency Sound Effects +A session recording audio from the default microphone would look as follows in C++: + + \snippet multimedia-snippets/media.cpp Media recorder -In addition to the raw access to sound devices described above, the QSoundEffect class (and -\l {SoundEffect} QML type) offers a slightly higher level way to play -sounds. These classes allow you to specify a WAV format file which can -then be played with low latency when necessary. Both QSoundEffect and -SoundEffect have essentially the same API. +In QML, the same can be achieved by: -You can adjust the number of \l {QSoundEffect::loopCount()}{loops} a sound effect is played, as well as -the \l {QSoundEffect::setVolume()}{volume} (or \l {QSoundEffect::setMuted()}{muting}) of the effect. +\qml +CaptureSession { + audioInput: AudioInput {} + mediaRecorder: MediaRecorder { + id: recorder + outputLocation: "file:///path/to/test.mp3" + } + Component.onCompleted: { recorder.record() } +} +\endqml -For older, Qt 4.x based applications \l QSound is also available. Applications -are recommended to use QSoundEffect where possible. +QMediaCaptureSession also provides support for more complex use cases such as image +capturing or video recording. -\section2 Monitoring Audio Data During Playback or Recording +\section2 Low Latency Sound Effects -The \l QAudioProbe class allows you to monitor audio data being played or -recorded in the higher level classes like \l QMediaPlayer, \l QCamera and -\l QAudioRecorder. After creating your high level class, you can simply -set the source of the probe to your class, and receive audio buffers as they -are processed. This is useful for several audio processing tasks, particularly -for visualization or adjusting gain. You cannot modify the buffers, and -they may arrive at a slightly different time than the media pipeline -processes them. +In addition to \l{raw access} to sound devices, the QSoundEffect +class (and \l{SoundEffect} QML type) offers a more abstract way to play +sounds. This class allows you to specify a \b{WAV format} file, which can +then be played with low latency when necessary. -Here's an example of installing a probe during recording: - \snippet multimedia-snippets/media.cpp Audio probe +You can adjust the: +\list + \li \l{QSoundEffect::loopCount()}{Number of loops} in which a sound effect + is played. + \li \l{QSoundEffect::setVolume()}{Volume} of the sound effect. + \li \l{QSoundEffect::setMuted()}{Muting} of the sound effect. +\endlist +\target raw access \section2 Low Level Audio Playback and Recording -Qt Multimedia offers classes for raw access to audio input and output + +The C++ API of Qt Multimedia offers classes for raw access to audio input and output facilities, allowing applications to receive raw data from devices like -microphones, and to write raw data to speakers or other devices. Generally +microphones, and to write raw data to speakers or other devices. Generally these classes do not do any audio decoding, or other processing, but they can support different types of raw audio data. -The QAudioOutput class offers raw audio data output, while QAudioInput -offers raw audio data input. Both classes have adjustable buffers and -latency, so they are suitable for both low latency use cases (like games -or VOIP) and high latency (like music playback). The available hardware +The QAudioSink class offers raw audio data output, while QAudioSource +offers raw audio data input. The available hardware determines what audio outputs and inputs are available. \section3 Push and Pull The low level audio classes can operate in two modes - \c push and \c pull. In \c pull mode, the audio device is started by giving it a QIODevice. For -an output device, the QAudioOutput class will pull data from the QIODevice +an output device, the QAudioSink class will pull data from the QIODevice (using \l QIODevice::read()) when more audio data is required. Conversely, -for \c pull mode with QAudioInput, when audio data is available then the +for \c pull mode with QAudioSource, when audio data is available then the data will be written directly to the QIODevice. In \c push mode, the audio device provides a QIODevice instance that -can be written or read to as needed. Typically this results in simpler +can be written or read to as needed. Typically, this results in simpler code but more buffering, which may affect latency. \section2 Decoding Compressed Audio to Memory + In some cases you may want to decode a compressed audio file and do further -processing yourself (for example, mixing multiple samples or using custom -digital signal processing algorithms). QAudioDecoder supports decoding local +processing yourself. For example, mixing multiple samples or using custom +digital signal processing algorithms. QAudioDecoder supports decoding local files or data streams from QIODevice instances. Here's an example of decoding a local file: \snippet multimedia-snippets/audio.cpp Local audio decoding -\section1 Examples - -There are both C++ and QML examples available. +\section2 Spatial Audio -\section2 C++ Examples - -\annotatedlist audio_examples +The \l {Qt Spatial Audio} module provides an API for implementation sound +fields in 3D space. \section1 Reference Documentation @@ -142,4 +136,8 @@ There are both C++ and QML examples available. \annotatedlist multimedia_audio_qml +\section2 Examples + +\annotatedlist audio_examples */ + |