1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtMultimedia module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 

    43 #include <QtMultimedia/qaudio.h>

    44 #include <QtMultimedia/qaudiodeviceinfo.h>

    45 #include <QtMultimedia/qaudioengine.h>

    46 #include <QtMultimedia/qaudioinput.h>

    47 

    48 #include "qaudiodevicefactory_p.h"

    49 

    50 

    51 QT_BEGIN_NAMESPACE

    52 

    53 /*!

    54     \class QAudioInput

    55     \brief The QAudioInput class provides an interface for receiving audio data from an audio input device.

    56 

    57     \inmodule QtMultimedia

    58     \ingroup  multimedia

    59     \since 4.6

    60 

    61     You can construct an audio input with the system's

    62     \l{QAudioDeviceInfo::defaultInputDevice()}{default audio input

    63     device}. It is also possible to create QAudioInput with a

    64     specific QAudioDeviceInfo. When you create the audio input, you

    65     should also send in the QAudioFormat to be used for the recording

    66     (see the QAudioFormat class description for details).

    67 

    68     To record to a file:

    69 

    70     QAudioInput lets you record audio with an audio input device. The

    71     default constructor of this class will use the systems default

    72     audio device, but you can also specify a QAudioDeviceInfo for a

    73     specific device. You also need to pass in the QAudioFormat in

    74     which you wish to record.

    75 

    76     Starting up the QAudioInput is simply a matter of calling start()

    77     with a QIODevice opened for writing. For instance, to record to a

    78     file, you can:

    79 

    80     \code

    81     {

    82       QFile outputFile;

    83       outputFile.setFileName("/tmp/test.raw");

    84       outputFile.open( QIODevice::WriteOnly | QIODevice::Truncate );

    85 

    86       QAudioFormat format;

    87       // set up the format you want, eg.

    88       format.setFrequency(8000);

    89       format.setChannels(1);

    90       format.setSampleSize(8);

    91       format.setCodec("audio/pcm");

    92       format.setByteOrder(QAudioFormat::LittleEndian);

    93       format.setSampleType(QAudioFormat::UnSignedInt);

    94 

    95       QAudioInput *audio = new QAudioInput(format, this);

    96       QTimer::singleShot(3000, this, SLOT(stopRecording()));

    97       audio->start(outputFile);

    98       // Records audio for 3000ms

    99     }

   100     \endcode

   101 

   102     This will start recording if the format specified is supported by

   103     the input device (you can check this with

   104     QAudioDeviceInfo::isFormatSupported(). In case there are any

   105     snags, use the error() function to check what went wrong. We stop

   106     recording in the \c stopRecording() slot.

   107 

   108     \code

   109     void stopRecording()

   110     {

   111       audio->stop();

   112       outputFile->close();

   113     }

   114     \endcode

   115 

   116     At any point in time, QAudioInput will be in one of four states:

   117     active, suspended, stopped, or idle. These states are specified by

   118     the QAudio::State enum. You can request a state change directly through

   119     suspend(), resume(), stop(), reset(), and start(). The current

   120     state is reported by state(). QAudioOutput will also signal you

   121     when the state changes (stateChanged()).

   122 

   123     QAudioInput provides several ways of measuring the time that has

   124     passed since the start() of the recording. The \c totalTime()

   125     function returns the length of the stream in microseconds written,

   126     i.e., it leaves out the times the audio input was suspended or idle.

   127     The clock() function returns the time elapsed since start() was called regardless of

   128     which states the QAudioInput has been in.

   129 

   130     If an error should occur, you can fetch its reason with error().

   131     The possible error reasons are described by the QAudio::Error

   132     enum. The QAudioInput will enter the \l{QAudio::}{StopState} when

   133     an error is encountered.  Connect to the stateChanged() signal to

   134     handle the error:

   135 

   136     \snippet doc/src/snippets/audio/main.cpp 0

   137 

   138     \sa QAudioOutput, QAudioDeviceInfo

   139 */

   140 

   141 /*!

   142     Construct a new audio input and attach it to \a parent.

   143     The default audio input device is used with the output

   144     \a format parameters.

   145 */

   146 

   147 QAudioInput::QAudioInput(const QAudioFormat &format, QObject *parent):

   148     QObject(parent)

   149 {

   150     d = QAudioDeviceFactory::createDefaultInputDevice(format);

   151     connect(d, SIGNAL(notify()), SIGNAL(notify()));

   152     connect(d, SIGNAL(stateChanged(QAudio::State)), SIGNAL(stateChanged(QAudio::State)));

   153 }

   154 

   155 /*!

   156     Construct a new audio input and attach it to \a parent.

   157     The device referenced by \a audioDevice is used with the input

   158     \a format parameters.

   159 */

   160 

   161 QAudioInput::QAudioInput(const QAudioDeviceInfo &audioDevice, const QAudioFormat &format, QObject *parent):

   162     QObject(parent)

   163 {

   164     d = QAudioDeviceFactory::createInputDevice(audioDevice, format);

   165     connect(d, SIGNAL(notify()), SIGNAL(notify()));

   166     connect(d, SIGNAL(stateChanged(QAudio::State)), SIGNAL(stateChanged(QAudio::State)));

   167 }

   168 

   169 /*!

   170     Destroy this audio input.

   171 */

   172 

   173 QAudioInput::~QAudioInput()

   174 {

   175     delete d;

   176 }

   177 

   178 /*!

   179     Uses the \a device as the QIODevice to transfer data.

   180     If \a device is null then the class creates an internal QIODevice.

   181     Returns a pointer to the QIODevice being used to handle the data

   182     transfer. This QIODevice can be used to read() audio data

   183     directly.

   184     Passing a QIODevice allows the data to be transfered without any extra code.

   185     All that is required is to open the QIODevice.

   186 

   187     \sa QIODevice

   188 */

   189 

   190 QIODevice* QAudioInput::start(QIODevice* device)

   191 {

   192     /*

   193     PULL MODE (valid QIODevice)

   194     -If currently not StopState, stop

   195     -If previous start was push mode, delete internal QIODevice.

   196     -open audio input.

   197     If ok, NoError and ActiveState, else OpenError and StopState.

   198     -emit stateChanged()

   199     -return device

   200 

   201     PUSH MODE (device = 0)

   202     -If currently not StopState, stop

   203     -If no internal QIODevice, create one.

   204     -open audio input.

   205     -If ok, NoError and IdleState, else OpenError and StopState

   206     -emit stateChanged()

   207     -return internal QIODevice

   208     */

   209     return d->start(device);

   210 }

   211 

   212 /*!

   213     Returns the QAudioFormat being used.

   214 */

   215 

   216 QAudioFormat QAudioInput::format() const

   217 {

   218     return d->format();

   219 }

   220 

   221 /*!

   222     Stops the audio input.

   223 */

   224 

   225 void QAudioInput::stop()

   226 {

   227     /*

   228     -If StopState, return

   229     -set to StopState

   230     -detach from audio device

   231     -emit stateChanged()

   232     */

   233     d->stop();

   234 }

   235 

   236 /*!

   237     Drops all audio data in the buffers, resets buffers to zero.

   238 */

   239 

   240 void QAudioInput::reset()

   241 {

   242     /*

   243     -drop all buffered audio, set buffers to zero.

   244     -call stop()

   245     */

   246     d->reset();

   247 }

   248 

   249 /*!

   250     Stops processing audio data, preserving buffered audio data.

   251 */

   252 

   253 void QAudioInput::suspend()

   254 {

   255     /*

   256     -If not ActiveState|IdleState, return

   257     -stop processing audio, saving all buffered audio data

   258     -set NoError and SuspendState

   259     -emit stateChanged()

   260     */

   261     d->suspend();

   262 }

   263 

   264 /*!

   265     Resumes processing audio data after a suspend().

   266 */

   267 

   268 void QAudioInput::resume()

   269 {

   270     /*

   271     -If SuspendState, return

   272     -resume audio

   273     -(PULL MODE): set ActiveState, NoError

   274     -(PUSH MODE): set IdleState, NoError

   275     -kick start audio if needed

   276     -emit stateChanged()

   277     */

   278      d->resume();

   279 }

   280 

   281 /*!

   282     Sets the audio buffer size to \a value milliseconds.

   283 

   284     Note: This function can be called anytime before start(), calls to this

   285     are ignored after start(). It should not be assumed that the buffer size

   286     set is the actual buffer size used, calling bufferSize() anytime after start()

   287     will return the actual buffer size being used.

   288 

   289 */

   290 

   291 void QAudioInput::setBufferSize(int value)

   292 {

   293     d->setBufferSize(value);

   294 }

   295 

   296 /*!

   297     Returns the audio buffer size in milliseconds.

   298 

   299     If called before start(), returns platform default value.

   300     If called before start() but setBufferSize() was called prior, returns value set by setBufferSize().

   301     If called after start(), returns the actual buffer size being used. This may not be what was set previously

   302     by setBufferSize().

   303 

   304 */

   305 

   306 int QAudioInput::bufferSize() const

   307 {

   308     return d->bufferSize();

   309 }

   310 

   311 /*!

   312     Returns the amount of audio data available to read in bytes.

   313 */

   314 

   315 int QAudioInput::bytesReady() const

   316 {

   317     /*

   318     -If not ActiveState|IdleState, return 0

   319     -return amount of audio data available to read

   320     */

   321     return d->bytesReady();

   322 }

   323 

   324 /*!

   325     Returns the period size in bytes.

   326 

   327     Note: This is the recommended read size in bytes.

   328 */

   329 

   330 int QAudioInput::periodSize() const

   331 {

   332     return d->periodSize();

   333 }

   334 

   335 /*!

   336     Sets the interval for notify() signal to be emitted.

   337     This is based on the \a ms of audio data processed

   338     not on actual real-time. The resolution of the timer is platform specific.

   339 */

   340 

   341 void QAudioInput::setNotifyInterval(int ms)

   342 {

   343     d->setNotifyInterval(ms);

   344 }

   345 

   346 /*!

   347     Returns the notify interval in milliseconds.

   348 */

   349 

   350 int QAudioInput::notifyInterval() const

   351 {

   352     return d->notifyInterval();

   353 }

   354 

   355 /*!

   356     Returns the amount of audio data processed since start()

   357     was called in microseconds.

   358 */

   359 

   360 qint64 QAudioInput::totalTime() const

   361 {

   362     return d->totalTime();

   363 }

   364 

   365 /*!

   366     Returns the microseconds since start() was called, including time in Idle and

   367     Suspend states.

   368 */

   369 

   370 qint64 QAudioInput::clock() const

   371 {

   372     return d->clock();

   373 }

   374 

   375 /*!

   376     Returns the error state.

   377 */

   378 

   379 QAudio::Error QAudioInput::error() const

   380 {

   381     return d->error();

   382 }

   383 

   384 /*!

   385     Returns the state of audio processing.

   386 */

   387 

   388 QAudio::State QAudioInput::state() const

   389 {

   390     return d->state();

   391 }

   392 

   393 /*!

   394     \fn QAudioInput::stateChanged(QAudio::State state)

   395     This signal is emitted when the device \a state has changed.

   396 */

   397 

   398 /*!

   399     \fn QAudioInput::notify()

   400     This signal is emitted when x ms of audio data has been processed

   401     the interval set by setNotifyInterval(x).

   402 */

   403 

   404 QT_END_NAMESPACE

   405