inc/FMediaAudioIn.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                        FMediaAudioIn.h
  20  * @brief                       This is the header file for the %AudioIn class.
  21  *
  22  * This header file contains the declarations of the %AudioIn class.
  23  */
  24
  25 #ifndef _FMEDIA_AUDIO_IN_H_
  26 #define _FMEDIA_AUDIO_IN_H_
  27
  28 #include <FMediaAudioTypes.h>
  29 #include <FMediaIAudioInEventListener.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33 /**
  34  * @class       AudioIn
  35  * @brief               This class records directly from an audio device.
  36  *
  37  * @since               2.0
  38  *
  39  * The %AudioIn class records directly from an audio device by providing methods for capturing PCM data from an audio input device.
  40  * An application can capture audio data with the help of an event listener after preparing the %AudioIn class
  41  * with proper channel count, sample type, and sampling rate.
  42  * To minimize the overhead of the %AudioIn class,
  43  * it is recommended that you use optimal channel type, sample type, and sampling rate.
  44  * These can be retrieved with GetOptimizedChannelType(), GetOptimizedSampleType()
  45  * and GetOptimizedSampleRate().
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/recording_pcm_audio.htm">Recording PCM Audio</a>.
  48  *
  49  * The following example demonstrates how to use the %AudioIn class.
  50  *
  51  * @code
  52  *
  53  * #include <FBase.h>
  54  * #include <FIo.h>
  55  * #include <FMedia.h>
  56  *
  57  * using namespace Tizen::Base;
  58  * using namespace Tizen::Io;
  59  * using namespace Tizen::Media;
  60  *
  61  * #define MAX_BUFFER_COUNT       3
  62  *
  63  * class AudioInSample
  64  *       : public Tizen::Media::IAudioInEventListener
  65  * {
  66  * public:
  67  *       result Start(void);
  68  *       void Stop(void);
  69  *
  70  * protected:
  71  *       virtual void OnAudioInBufferIsFilled( Tizen::Base::ByteBuffer* pData);
  72  *       virtual void OnAudioInErrorOccurred(result r) {}
  73  *       virtual void OnAudioInInterrupted(void) {}
  74  *       virtual void OnAudioInReleased(void) {}
  75  *       virtual void OnAudioInAudioFocusChanged(void) {}
  76  *
  77  * private:
  78  *       AudioIn __audioIn;
  79  *       ByteBuffer __buffer[MAX_BUFFER_COUNT];
  80  * };
  81  *
  82  * result
  83  * AudioInSample::Start(void)
  84  * {
  85  *       result r;
  86  *       int minBufferSize;
  87  *       AudioInputDevice inputDevice = AUDIO_INPUT_DEVICE_MIC;
  88  *       AudioSampleType sampleType = AUDIO_TYPE_PCM_U8;
  89  *       AudioChannelType channelType = AUDIO_CHANNEL_TYPE_STEREO;
  90  *       int sampleRate = 8000;
  91  *
  92  *       // Constructs an AudioIn instance
  93  *       r = __audioIn.Construct(*this);
  94  *       if (IsFailed(r))
  95  *       {
  96  *               return r;
  97  *       }
  98  *
  99  *       // Prepares the AudioIn instance
 100  *       r = __audioIn.Prepare(inputDevice, sampleType, channelType, sampleRate);
 101  *       if (IsFailed(r))
 102  *       {
 103  *               return r;
 104  *       }
 105  *
 106  *       minBufferSize = __audioIn.GetMinBufferSize();
 107  *
 108  *       for (int i = 0; i < MAX_BUFFER_COUNT; i++)
 109  *       {
 110  *               // Prepares buffers to store PCM data
 111  *               r = __buffer[i].Construct(minBufferSize);
 112  *               if (IsFailed(r))
 113  *               {
 114  *                       return r;
 115  *               }
 116  *               // Adds buffer to the __audioIn
 117  *               __audioIn.AddBuffer(&__buffer[i]);
 118  *               if (IsFailed(r))
 119  *               {
 120  *                       return r;
 121  *               }
 122  *       }
 123  *
 124  *       // Starts capturing
 125  *       r = __audioIn.Start();
 126  *       if (IsFailed(r))
 127  *       {
 128  *               return r;
 129  *       }
 130  *
 131  *       return E_SUCCESS;
 132  * }
 133  *
 134  * void
 135  * AudioInSample::Stop(void)
 136  * {
 137  *       // Stops and unprepares the __audioIn
 138  *       __audioIn.Stop();
 139  *       __audioIn.Unprepare();
 140  * }
 141  *
 142  * void
 143  * AudioInSample::OnAudioInBufferIsFilled( Tizen::Base::ByteBuffer* pData)
 144  * {
 145  *       // Consumes filled data here
 146  *
 147  *       // Clears the buffer
 148  *       pData->Clear();
 149  *
 150  *       // Adds the byte buffer to the __audioIn to fill data again
 151  *       __audioIn.AddBuffer(pData);
 152  * }
 153  *
 154  *
 155  * @endcode
 156  *
 157  */
 158
 159 class _OSP_EXPORT_ AudioIn
 160         : public Tizen::Base::Object
 161 {
 162 public:
 163         /**
 164          *      The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 165          *
 166          *  @since              2.0
 167          *
 168          *      @remarks        After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 169          *      @see                    Construct()
 170          */
 171         AudioIn(void);
 172
 173         /**
 174          *      This destructor overrides Tizen::Base::Object::~Object().
 175          *      All allocated resources are deallocated with this method. @n
 176          *      This method must be called in the same thread as the Construct() method.
 177          *
 178          *  @since              2.0
 179          *
 180          *      @see            Construct()
 181          */
 182         virtual ~AudioIn(void);
 183
 184         /**
 185         *       Initializes this instance of %AudioIn with the specified IAudioInEventListener. @n
 186         *       This method creates an instance of %AudioIn in the subsystem.
 187         *
 188         *   @since              2.0
 189         *
 190         *       @return         An error code
 191         *       @param[in]      listener                                        An instance of IAudioInEventListener
 192         *       @exception      E_SUCCESS                                       The method is successful.
 193         *       @exception      E_DEVICE_BUSY                           The device cannot be approached because of other operations.
 194         *       @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 195         *       @exception      E_SYSTEM                                                        A system error has occurred.
 196         *       @remarks Only one instance of %AudioIn is operational at a given time.
 197         */
 198         result Construct(IAudioInEventListener& listener);
 199
 200         /**
 201         * @if OSPDEPREC
 202         *       Prepares the specified audio input device with the application-defined settings. @n
 203         *   When the caller finishes using the audio input device, the resources must be released by calling the Unprepare() method.
 204         *
 205         * @brief <i> [Deprecated]  </i>
 206         * @deprecated   This method is deprecated because AudioInputDevice is no longer used in %AudioIn class. @n
 207         *  Instead of using this method, use Prepare(AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate).
 208         *
 209         *   @since              2.0
 210         *
 211         *       @return         An error code
 212         *       @param[in]      audioInputDevice                                                An audio input device
 213         *       @param[in]      audioSampleType                                         The type of audio sample
 214         *       @param[in]      audioChannelType                                                The audio channel type
 215         *       @param[in]      audioSampleRate                                         The audio sample rate in hertz (Hz)
 216         *       @exception      E_SUCCESS                                                               The method is successful.
 217         *       @exception      E_INVALID_STATE                                         This instance is in an invalid state for this method.
 218         *       @exception      E_SYSTEM                                                                A system error has occurred.
 219         *       @exception      E_INVALID_ARG                                                   A specified input parameter is invalid.
 220         *       @exception      E_UNSUPPORTED_FORMAT                    The specified audio sample type is not supported.
 221         *       @see            Unprepare()
 222         * @endif
 223         */
 224         result Prepare(AudioInputDevice audioInputDevice, AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
 225
 226         /**
 227         *       Prepares the specified audio input device with the application-defined settings. @n
 228         *   When the caller finishes using the audio input device, the resources must be released by calling the Unprepare() method.
 229         *
 230         *   @since              2.0
 231         *
 232         *       @return         An error code
 233         *       @param[in]      audioSampleType                                         The type of audio sample
 234         *       @param[in]      audioChannelType                                                The audio channel type
 235         *       @param[in]      audioSampleRate                                         The audio sample rate in hertz (Hz)
 236         *       @exception      E_SUCCESS                                                                       The method is successful.
 237         *  @exception  E_DEVICE_FAILED                                          The device failed with unknown reason.
 238         *       @exception      E_INVALID_ARG                                                   A specified input parameter is invalid.
 239         *       @exception      E_UNSUPPORTED_FORMAT                    The specified audio sample type is not supported.
 240         *       @see            Unprepare()
 241         */
 242         result Prepare(AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
 243
 244         /**
 245         *       Stops the usage of the input device and releases the allocated resources during the execution of the Prepare() method. @n
 246         *   Resources allocated during Prepare() are released.
 247         *
 248         *   @since              2.0
 249         *
 250         *       @return         An error code
 251         *       @exception      E_SUCCESS                                               The method is successful.
 252         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 253         *       @exception      E_SYSTEM                                                        A system error has occurred.
 254         *       @see            Prepare()
 255         */
 256         result Unprepare(void);
 257
 258         /**
 259         *       Adds an input buffer to the specified audio input device. @n
 260         *       When the buffer is filled, the %AudioIn class returns the buffer to the caller
 261         *       by invoking IAudioInEventListener::OnAudioInBufferIsFilled().
 262         *
 263         *   @since              2.0
 264         *
 265         *       @return                 An error code
 266         *       @param[in]      pByteBuffer                                                             A pointer to the buffer
 267         *       @exception      E_SUCCESS                                                                       The method is successful.
 268         *       @exception      E_INVALID_ARG                                                   The input parameter is invalid.
 269         *       @exception      E_INVALID_STATE                                 This instance is in an invalid state for this method.
 270         *       @exception      E_SYSTEM                                                                                A system error has occurred.
 271         *       @exception      E_OUT_OF_MEMORY                                 The memory is insufficient.
 272         *       @remarks        The data size of @c pByteBuffer must be the same as every call of this method.
 273         *       @see            Start(), IAudioInEventListener::OnAudioInBufferIsFilled()
 274         */
 275         result AddBuffer(const Tizen::Base::ByteBuffer* pByteBuffer);
 276
 277         /**
 278         *       Starts reading the audio data from an audio input device and fills the data into the buffer.
 279         *
 280         *   @since              2.0
 281         *
 282         *       @return                 An error code
 283         *       @exception      E_SUCCESS                                                       The method is successful.
 284         *       @exception      E_INVALID_STATE                 This instance is in an invalid state for this method.
 285         *       @exception      E_DEVICE_BUSY                                   The device cannot be approached because of other operations.
 286         *       @exception      E_SYSTEM                                                                A system error has occurred.
 287         *       @remarks        Several buffers must be added to the queue with AddBuffer() before calling this method.
 288         *       @see            Stop(), IAudioInEventListener::OnAudioInBufferIsFilled()
 289         */
 290         result Start(void);
 291
 292         /**
 293         *       Stops using the audio input device. @n
 294         *       All pending and current buffers that are filled with audio data
 295         *   at the time of calling this method, are returned to the listener.
 296         *       Use Start() to start capturing audio input data again.
 297         *
 298         *   @since              2.0
 299         *
 300         *       @return                 An error code
 301         *       @exception      E_SUCCESS                                               The method is successful.
 302         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 303         *       @exception      E_SYSTEM                                                        A system error has occurred.
 304         *       @see            Start(), IAudioInEventListener::OnAudioInBufferIsFilled()
 305         */
 306         result Stop(void);
 307
 308         /**
 309         *       Resets using the audio input device without returning buffers to the caller. @n
 310         *       All pending and current buffers are released immediately without any notifications.
 311         *       The state is changed to AUDIOIN_STATE_PREPARED.
 312         *
 313         *   @since              2.0
 314         *
 315         *       @return                 An error code
 316         *       @exception      E_SUCCESS                                               The method is successful.
 317         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 318         *       @exception      E_SYSTEM                                                        A system error has occurred.
 319         */
 320         result Reset(void);
 321
 322         /**
 323         *       Gets the current state of this instance.
 324         *
 325         *   @since              2.0
 326         *
 327         *       @return                 The state of this instance
 328         *       @exception      E_SUCCESS                                               The method is successful.
 329         *       @exception      E_SYSTEM                                                        A system error has occurred.
 330         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 331         */
 332         AudioInState GetState(void) const;
 333
 334         /**
 335         *       Gets the maximum size of the buffer that can be used with AddBuffer(). @n
 336         *       This maximum value is set by Prepare() and reset to @c 0 by Unprepare().
 337         *
 338         *   @since              2.0
 339         *
 340         *       @return                 The maximum size of the buffer in bytes, @n
 341         *                               else @c -1 if an error occurs
 342         *       @exception      E_SUCCESS                                               The method is successful.
 343         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 344         *       @exception      E_SYSTEM                                                        A system error has occurred.
 345         *       @remarks        The return value is available after calling the Prepare() method.
 346         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 347         */
 348         int GetMaxBufferSize(void) const;
 349
 350         /**
 351         *       Gets the minimum size of the buffer that can be used with AddBuffer(). @n
 352         *       This minimum value is set by Prepare() and reset to @c 0 by Unprepare().
 353         *
 354         *   @since              2.0
 355         *
 356         *       @return                 The minimum size of the buffer in bytes,        @n
 357         *                               else @c -1 if an error occurs
 358         *       @exception      E_SUCCESS                                               The method is successful.
 359         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 360         *       @exception      E_SYSTEM                                                        A system error has occurred.
 361         *       @remarks        The return value is available after calling the Prepare() method.
 362         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 363         */
 364         int GetMinBufferSize(void) const;
 365
 366         /**
 367         *       Gets the optimized sample type of the audio input device.
 368         *
 369         *   @since              2.0
 370         *
 371         *       @return                 The audio encoding type
 372         *       @exception      E_SUCCESS                                               The method is successful.
 373         *       @exception      E_SYSTEM                                                        A system error has occurred.
 374         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 375         */
 376         AudioSampleType GetOptimizedSampleType(void) const;
 377
 378         /**
 379         *       Gets the optimized channel type of the audio input device.
 380         *
 381         *   @since              2.0
 382         *
 383         *       @return         The audio channel type
 384         *       @exception      E_SUCCESS                                               The method is successful.
 385         *       @exception      E_SYSTEM                                                        A system error has occurred.
 386         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 387         */
 388         AudioChannelType GetOptimizedChannelType(void) const;
 389
 390         /**
 391         *       Gets the optimized sample rate of the audio input device.
 392         *
 393         *   @since              2.0
 394         *
 395         *       @return         The sample rate in hertz (Hz)
 396         *       @exception      E_SUCCESS                                               The method is successful.
 397         *       @exception      E_SYSTEM                                                        A system error has occurred.
 398         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 399         */
 400         int GetOptimizedSampleRate(void) const;
 401
 402
 403 private:
 404         /**
 405          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 406          *
 407          *      @since          2.0
 408          */
 409         AudioIn(const AudioIn& rhs);
 410
 411         /**
 412          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 413          *
 414          *       @since         2.0
 415          */
 416         AudioIn& operator =(const AudioIn& rhs);
 417
 418         friend class _AudioInImpl;
 419         class _AudioInImpl* __pAudioInImpl;
 420 };
 421
 422 }} // Tizen::Media
 423
 424 #endif