1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page audiooverview.html
\title Audio Overview
\brief Audio playback, recording and processing
\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 {Positional Audio}{Qt AudioEngine}
QML types offer high level 3D positional audio for QML applications.
See that documentation for more information.
\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.
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.
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
\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
\section2 Low Latency Sound Effects
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.
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.
For older, Qt 4.x based applications \l QSound is also available. Applications
are recommended to use QSoundEffect where possible.
\section2 Monitoring Audio Data During Playback or Recording
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.
Here's an example of installing a probe during recording:
\snippet multimedia-snippets/media.cpp Audio probe
\section2 Low Level Audio Playback and Recording
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
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
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
(using \l QIODevice::read()) when more audio data is required. Conversely,
for \c pull mode with QAudioInput, 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
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 (like mix multiple samples, or some custom digital signal
processing algorithms). Qt Multimedia 5.0 offers a preliminary API for this
case - the \l QAudioDecoder class. QAudioDecoder supports decoding local files
or from a QIODevice instances.
Here's an example of decoding a local file:
\snippet multimedia-snippets/audio.cpp Local audio decoding
Note: This API is preliminary at this time - the API may change or be
removed before the final 5.0 release.
\section1 Examples
There are both C++ and QML examples available.
\section2 C++ Examples
\annotatedlist audio_examples
\section1 Reference Documentation
\section2 C++ Classes
\annotatedlist multimedia_audio
\section2 QML Types
\annotatedlist multimedia_audio_qml
*/
|
