1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40
41#include "qaudio.h"
42#include "qaudiodeviceinfo.h"
43#include "qaudiosystem.h"
44#include "qaudioinput.h"
45
46#include "qaudiodevicefactory_p.h"
47
48QT_BEGIN_NAMESPACE
49
50/*!
51 \class QAudioInput
52 \brief The QAudioInput class provides an interface for receiving audio data from an audio input device.
53
54 \inmodule QtMultimedia
55 \ingroup multimedia
56 \ingroup multimedia_audio
57
58 You can construct an audio input with the system's
59 \l{QAudioDeviceInfo::defaultInputDevice()}{default audio input
60 device}. It is also possible to create QAudioInput with a
61 specific QAudioDeviceInfo. When you create the audio input, you
62 should also send in the QAudioFormat to be used for the recording
63 (see the QAudioFormat class description for details).
64
65 To record to a file:
66
67 QAudioInput lets you record audio with an audio input device. The
68 default constructor of this class will use the systems default
69 audio device, but you can also specify a QAudioDeviceInfo for a
70 specific device. You also need to pass in the QAudioFormat in
71 which you wish to record.
72
73 Starting up the QAudioInput is simply a matter of calling start()
74 with a QIODevice opened for writing. For instance, to record to a
75 file, you can:
76
77 \snippet multimedia-snippets/audio.cpp Audio input class members
78
79 \snippet multimedia-snippets/audio.cpp Audio input setup
80
81 This will start recording if the format specified is supported by
82 the input device (you can check this with
83 QAudioDeviceInfo::isFormatSupported(). In case there are any
84 snags, use the error() function to check what went wrong. We stop
85 recording in the \c stopRecording() slot.
86
87 \snippet multimedia-snippets/audio.cpp Audio input stop recording
88
89 At any point in time, QAudioInput will be in one of four states:
90 active, suspended, stopped, or idle. These states are specified by
91 the QAudio::State enum. You can request a state change directly through
92 suspend(), resume(), stop(), reset(), and start(). The current
93 state is reported by state(). QAudioOutput will also signal you
94 when the state changes (stateChanged()).
95
96 QAudioInput provides several ways of measuring the time that has
97 passed since the start() of the recording. The \c processedUSecs()
98 function returns the length of the stream in microseconds written,
99 i.e., it leaves out the times the audio input was suspended or idle.
100 The elapsedUSecs() function returns the time elapsed since start() was called regardless of
101 which states the QAudioInput has been in.
102
103 If an error should occur, you can fetch its reason with error().
104 The possible error reasons are described by the QAudio::Error
105 enum. The QAudioInput will enter the \l{QAudio::}{StoppedState} when
106 an error is encountered. Connect to the stateChanged() signal to
107 handle the error:
108
109 \snippet multimedia-snippets/audio.cpp Audio input state changed
110
111 \sa QAudioOutput, QAudioDeviceInfo
112*/
113
114/*!
115 Construct a new audio input and attach it to \a parent.
116 The default audio input device is used with the output
117 \a format parameters.
118*/
119
120QAudioInput::QAudioInput(const QAudioFormat &format, QObject *parent):
121 QObject(parent)
122{
123 d = QAudioDeviceFactory::createDefaultInputDevice(format);
124 connect(asender: d, SIGNAL(notify()), SIGNAL(notify()));
125 connect(asender: d, SIGNAL(stateChanged(QAudio::State)), SIGNAL(stateChanged(QAudio::State)));
126}
127
128/*!
129 Construct a new audio input and attach it to \a parent.
130 The device referenced by \a audioDevice is used with the input
131 \a format parameters.
132*/
133
134QAudioInput::QAudioInput(const QAudioDeviceInfo &audioDevice, const QAudioFormat &format, QObject *parent):
135 QObject(parent)
136{
137 d = QAudioDeviceFactory::createInputDevice(device: audioDevice, format);
138 connect(asender: d, SIGNAL(notify()), SIGNAL(notify()));
139 connect(asender: d, SIGNAL(stateChanged(QAudio::State)), SIGNAL(stateChanged(QAudio::State)));
140}
141
142/*!
143 Destroy this audio input.
144*/
145
146QAudioInput::~QAudioInput()
147{
148 delete d;
149}
150
151/*!
152 Starts transferring audio data from the system's audio input to the \a device.
153 The \a device must have been opened in the \l{QIODevice::WriteOnly}{WriteOnly},
154 \l{QIODevice::Append}{Append} or \l{QIODevice::ReadWrite}{ReadWrite} modes.
155
156 If the QAudioInput is able to successfully get audio data, state() returns
157 either QAudio::ActiveState or QAudio::IdleState, error() returns QAudio::NoError
158 and the stateChanged() signal is emitted.
159
160 If a problem occurs during this process, error() returns QAudio::OpenError,
161 state() returns QAudio::StoppedState and the stateChanged() signal is emitted.
162
163 \sa QIODevice
164*/
165
166void QAudioInput::start(QIODevice* device)
167{
168 d->start(device);
169}
170
171/*!
172 Returns a pointer to the internal QIODevice being used to transfer data from
173 the system's audio input. The device will already be open and
174 \l{QIODevice::read()}{read()} can read data directly from it.
175
176 \note The pointer will become invalid after the stream is stopped or
177 if you start another stream.
178
179 If the QAudioInput is able to access the system's audio device, state() returns
180 QAudio::IdleState, error() returns QAudio::NoError
181 and the stateChanged() signal is emitted.
182
183 If a problem occurs during this process, error() returns QAudio::OpenError,
184 state() returns QAudio::StoppedState and the stateChanged() signal is emitted.
185
186 \sa QIODevice
187*/
188
189QIODevice* QAudioInput::start()
190{
191 return d->start();
192}
193
194/*!
195 Returns the QAudioFormat being used.
196*/
197
198QAudioFormat QAudioInput::format() const
199{
200 return d->format();
201}
202
203/*!
204 Stops the audio input, detaching from the system resource.
205
206 Sets error() to QAudio::NoError, state() to QAudio::StoppedState and
207 emit stateChanged() signal.
208*/
209
210void QAudioInput::stop()
211{
212 d->stop();
213}
214
215/*!
216 Drops all audio data in the buffers, resets buffers to zero.
217*/
218
219void QAudioInput::reset()
220{
221 d->reset();
222}
223
224/*!
225 Stops processing audio data, preserving buffered audio data.
226
227 Sets error() to QAudio::NoError, state() to QAudio::SuspendedState and
228 emit stateChanged() signal.
229*/
230
231void QAudioInput::suspend()
232{
233 d->suspend();
234}
235
236/*!
237 Resumes processing audio data after a suspend().
238
239 Sets error() to QAudio::NoError.
240 Sets state() to QAudio::ActiveState if you previously called start(QIODevice*).
241 Sets state() to QAudio::IdleState if you previously called start().
242 emits stateChanged() signal.
243*/
244
245void QAudioInput::resume()
246{
247 d->resume();
248}
249
250/*!
251 Sets the audio buffer size to \a value bytes.
252
253 Note: This function can be called anytime before start(), calls to this
254 are ignored after start(). It should not be assumed that the buffer size
255 set is the actual buffer size used, calling bufferSize() anytime after start()
256 will return the actual buffer size being used.
257
258*/
259
260void QAudioInput::setBufferSize(int value)
261{
262 d->setBufferSize(value);
263}
264
265/*!
266 Returns the audio buffer size in bytes.
267
268 If called before start(), returns platform default value.
269 If called before start() but setBufferSize() was called prior, returns value set by setBufferSize().
270 If called after start(), returns the actual buffer size being used. This may not be what was set previously
271 by setBufferSize().
272
273*/
274
275int QAudioInput::bufferSize() const
276{
277 return d->bufferSize();
278}
279
280/*!
281 Returns the amount of audio data available to read in bytes.
282
283 Note: returned value is only valid while in QAudio::ActiveState or QAudio::IdleState
284 state, otherwise returns zero.
285*/
286
287int QAudioInput::bytesReady() const
288{
289 /*
290 -If not ActiveState|IdleState, return 0
291 -return amount of audio data available to read
292 */
293 return d->bytesReady();
294}
295
296/*!
297 Returns the period size in bytes.
298
299 Note: This is the recommended read size in bytes.
300*/
301
302int QAudioInput::periodSize() const
303{
304 return d->periodSize();
305}
306
307/*!
308 Sets the interval for notify() signal to be emitted.
309 This is based on the \a ms of audio data processed
310 not on actual real-time.
311 The minimum resolution of the timer is platform specific and values
312 should be checked with notifyInterval() to confirm actual value
313 being used.
314*/
315
316void QAudioInput::setNotifyInterval(int ms)
317{
318 d->setNotifyInterval(ms);
319}
320
321/*!
322 Returns the notify interval in milliseconds.
323*/
324
325int QAudioInput::notifyInterval() const
326{
327 return d->notifyInterval();
328}
329
330/*!
331 Sets the input volume to \a volume.
332
333 The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
334 range will be clamped.
335
336 If the device does not support adjusting the input
337 volume then \a volume will be ignored and the input
338 volume will remain at 1.0.
339
340 The default volume is \c 1.0.
341
342 Note: Adjustments to the volume will change the volume of this audio stream, not the global volume.
343*/
344void QAudioInput::setVolume(qreal volume)
345{
346 qreal v = qBound(min: qreal(0.0), val: volume, max: qreal(1.0));
347 d->setVolume(v);
348}
349
350/*!
351 Returns the input volume.
352
353 If the device does not support adjusting the input volume
354 the returned value will be 1.0.
355*/
356qreal QAudioInput::volume() const
357{
358 return d->volume();
359}
360
361/*!
362 Returns the amount of audio data processed since start()
363 was called in microseconds.
364*/
365
366qint64 QAudioInput::processedUSecs() const
367{
368 return d->processedUSecs();
369}
370
371/*!
372 Returns the microseconds since start() was called, including time in Idle and
373 Suspend states.
374*/
375
376qint64 QAudioInput::elapsedUSecs() const
377{
378 return d->elapsedUSecs();
379}
380
381/*!
382 Returns the error state.
383*/
384
385QAudio::Error QAudioInput::error() const
386{
387 return d->error();
388}
389
390/*!
391 Returns the state of audio processing.
392*/
393
394QAudio::State QAudioInput::state() const
395{
396 return d->state();
397}
398
399/*!
400 \fn QAudioInput::stateChanged(QAudio::State state)
401 This signal is emitted when the device \a state has changed.
402*/
403
404/*!
405 \fn QAudioInput::notify()
406 This signal is emitted when x ms of audio data has been processed
407 the interval set by setNotifyInterval(x).
408*/
409
410QT_END_NAMESPACE
411
412#include "moc_qaudioinput.cpp"
413
414

source code of qtmultimedia/src/multimedia/audio/qaudioinput.cpp