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

     2 **

     3 ** Copyright (C) 2010 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 Qt Mobility Components.

     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 "qaudio.h"

    44 #include "qaudiodeviceinfo.h"

    45 #include "qaudiosystem.h"

    46 #include "qaudioinput.h"

    47 

    48 #include "qaudiodevicefactory_p.h"

    49 

    50 QT_BEGIN_NAMESPACE

    51 

    52 /*!

    53     \class QAudioInput

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

    55 

    56     \inmodule QtMultimediaKit

    57     \ingroup  multimedia

    58     \since 4.6

    59 

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

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

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

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

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

    65     (see the QAudioFormat class description for details).

    66 

    67     To record to a file:

    68 

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

    70     default constructor of this class will use the systems default

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

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

    73     which you wish to record.

    74 

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

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

    77     file, you can:

    78 

    79     \code

    80       QFile outputFile;   // class member.

    81       QAudioInput* audio; // class member.

    82     \endcode

    83 

    84     \code

    85     {

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

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

    88 

    89       QAudioFormat format;

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

    91       format.setFrequency(8000);

    92       format.setChannels(1);

    93       format.setSampleSize(8);

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

    95       format.setByteOrder(QAudioFormat::LittleEndian);

    96       format.setSampleType(QAudioFormat::UnSignedInt);

    97 

    98       QAudioDeviceInfo info = QAudioDeviceInfo::defaultInputDevice();

    99       if (!info.isFormatSupported(format)) {

   100           qWarning()<<"default format not supported try to use nearest";

   101           format = info.nearestFormat(format);

   102       }

   103 

   104       audio = new QAudioInput(format, this);

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

   106       audio->start(&outputFile);

   107       // Records audio for 3000ms

   108     }

   109     \endcode

   110 

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

   112     the input device (you can check this with

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

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

   115     recording in the \c stopRecording() slot.

   116 

   117     \code

   118     void stopRecording()

   119     {

   120       audio->stop();

   121       outputFile->close();

   122       delete audio;

   123     }

   124     \endcode

   125 

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

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

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

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

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

   131     when the state changes (stateChanged()).

   132 

   133     QAudioInput provides several ways of measuring the time that has

   134     passed since the start() of the recording. The \c processedUSecs()

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

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

   137     The elapsedUSecs() function returns the time elapsed since start() was called regardless of

   138     which states the QAudioInput has been in.

   139 

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

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

   142     enum. The QAudioInput will enter the \l{QAudio::}{StoppedState} when

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

   144     handle the error:

   145 

   146     \code

   147         void stateChanged(QAudio::State newState)

   148         {

   149             switch(newState) {

   150             case QAudio::StopState:

   151                 if (input->error() != QAudio::NoError) {

   152                     // Error handling

   153                 } else {

   154 

   155                 }

   156                 break;

   157     \endcode

   158 

   159     \sa QAudioOutput, QAudioDeviceInfo

   160 

   161     \section1 Symbian Platform Security Requirements

   162 

   163     On Symbian, processes which use this class must have the

   164     \c UserEnvironment platform security capability.  If the client

   165     process lacks this capability, calls to either overload of start()

   166     will fail.

   167     This failure is indicated by the QAudioInput object setting

   168     its error() value to \l{QAudio::OpenError} and then emitting a

   169     \l{stateChanged()}{stateChanged}(\l{QAudio::StoppedState}) signal.

   170 

   171     Platform security capabilities are added via the

   172     \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}

   173     qmake variable.

   174 */

   175 

   176 /*!

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

   178     The default audio input device is used with the output

   179     \a format parameters.

   180 */

   181 

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

   183     QObject(parent)

   184 {

   185     d = QAudioDeviceFactory::createDefaultInputDevice(format);

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

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

   188 }

   189 

   190 /*!

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

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

   193     \a format parameters.

   194 */

   195 

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

   197     QObject(parent)

   198 {

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

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

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

   202 }

   203 

   204 /*!

   205     Destroy this audio input.

   206 */

   207 

   208 QAudioInput::~QAudioInput()

   209 {

   210     delete d;

   211 }

   212 

   213 /*!

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

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

   216      All that is required is to open the QIODevice.

   217 

   218      If able to successfully get audio data from the systems audio device the

   219      state() is set to either QAudio::ActiveState or QAudio::IdleState,

   220      error() is set to QAudio::NoError and the stateChanged() signal is emitted.

   221 

   222      If a problem occurs during this process the error() is set to QAudio::OpenError,

   223      state() is set to QAudio::StoppedState and stateChanged() signal is emitted.

   224 

   225      \l{QAudioInput#Symbian Platform Security Requirements}

   226 

   227      \sa QIODevice

   228 */

   229 

   230 void QAudioInput::start(QIODevice* device)

   231 {

   232     d->start(device);

   233 }

   234 

   235 /*!

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

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

   238     directly.

   239 

   240     If able to access the systems audio device the state() is set to

   241     QAudio::IdleState, error() is set to QAudio::NoError

   242     and the stateChanged() signal is emitted.

   243 

   244     If a problem occurs during this process the error() is set to QAudio::OpenError,

   245     state() is set to QAudio::StoppedState and stateChanged() signal is emitted.

   246 

   247     \l{QAudioInput#Symbian Platform Security Requirements}

   248 

   249     \sa QIODevice

   250 */

   251 

   252 QIODevice* QAudioInput::start()

   253 {

   254     return d->start();

   255 }

   256 

   257 /*!

   258     Returns the QAudioFormat being used.

   259 */

   260 

   261 QAudioFormat QAudioInput::format() const

   262 {

   263     return d->format();

   264 }

   265 

   266 /*!

   267     Stops the audio input, detaching from the system resource.

   268 

   269     Sets error() to QAudio::NoError, state() to QAudio::StoppedState and

   270     emit stateChanged() signal.

   271 */

   272 

   273 void QAudioInput::stop()

   274 {

   275     d->stop();

   276 }

   277 

   278 /*!

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

   280 */

   281 

   282 void QAudioInput::reset()

   283 {

   284     d->reset();

   285 }

   286 

   287 /*!

   288     Stops processing audio data, preserving buffered audio data.

   289 

   290     Sets error() to QAudio::NoError, state() to QAudio::SuspendedState and

   291     emit stateChanged() signal.

   292 */

   293 

   294 void QAudioInput::suspend()

   295 {

   296     d->suspend();

   297 }

   298 

   299 /*!

   300     Resumes processing audio data after a suspend().

   301 

   302     Sets error() to QAudio::NoError.

   303     Sets state() to QAudio::ActiveState if you previously called start(QIODevice*).

   304     Sets state() to QAudio::IdleState if you previously called start().

   305     emits stateChanged() signal.

   306 */

   307 

   308 void QAudioInput::resume()

   309 {

   310      d->resume();

   311 }

   312 

   313 /*!

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

   315 

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

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

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

   319     will return the actual buffer size being used.

   320 

   321 */

   322 

   323 void QAudioInput::setBufferSize(int value)

   324 {

   325     d->setBufferSize(value);

   326 }

   327 

   328 /*!

   329     Returns the audio buffer size in milliseconds.

   330 

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

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

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

   334     by setBufferSize().

   335 

   336 */

   337 

   338 int QAudioInput::bufferSize() const

   339 {

   340     return d->bufferSize();

   341 }

   342 

   343 /*!

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

   345 

   346     NOTE: returned value is only valid while in QAudio::ActiveState or QAudio::IdleState

   347     state, otherwise returns zero.

   348 */

   349 

   350 int QAudioInput::bytesReady() const

   351 {

   352     /*

   353     -If not ActiveState|IdleState, return 0

   354     -return amount of audio data available to read

   355     */

   356     return d->bytesReady();

   357 }

   358 

   359 /*!

   360     Returns the period size in bytes.

   361 

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

   363 */

   364 

   365 int QAudioInput::periodSize() const

   366 {

   367     return d->periodSize();

   368 }

   369 

   370 /*!

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

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

   373     not on actual real-time.

   374     The minimum resolution of the timer is platform specific and values

   375     should be checked with notifyInterval() to confirm actual value

   376     being used.

   377 */

   378 

   379 void QAudioInput::setNotifyInterval(int ms)

   380 {

   381     d->setNotifyInterval(ms);

   382 }

   383 

   384 /*!

   385     Returns the notify interval in milliseconds.

   386 */

   387 

   388 int QAudioInput::notifyInterval() const

   389 {

   390     return d->notifyInterval();

   391 }

   392 

   393 /*!

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

   395     was called in microseconds.

   396 */

   397 

   398 qint64 QAudioInput::processedUSecs() const

   399 {

   400     return d->processedUSecs();

   401 }

   402 

   403 /*!

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

   405     Suspend states.

   406 */

   407 

   408 qint64 QAudioInput::elapsedUSecs() const

   409 {

   410     return d->elapsedUSecs();

   411 }

   412 

   413 /*!

   414     Returns the error state.

   415 */

   416 

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

   418 {

   419     return d->error();

   420 }

   421 

   422 /*!

   423     Returns the state of audio processing.

   424 */

   425 

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

   427 {

   428     return d->state();

   429 }

   430 

   431 /*!

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

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

   434 */

   435 

   436 /*!

   437     \fn QAudioInput::notify()

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

   439     the interval set by setNotifyInterval(x).

   440 */

   441 

   442 QT_END_NAMESPACE

   443