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          */
 170         AudioIn(void);
 171
 172         /**
 173          *      This destructor overrides Tizen::Base::Object::~Object().
 174          *      All allocated resources are deallocated with this method. @n
 175          *      This method must be called in the same thread as the Construct() method.
 176          *
 177          *  @since              2.0
 178          *
 179          *      @see            Construct()
 180          */
 181         virtual ~AudioIn(void);
 182
 183         /**
 184         *       Initializes this instance of %AudioIn with the specified IAudioInEventListener. @n
 185         *       The %Construct() method creates an instance of %AudioIn in the subsystem.
 186         *
 187         *   @since              2.0
 188         *
 189         *       @return         An error code
 190         *       @param[in]      listener                                        An instance of IAudioInEventListener
 191         *       @exception      E_SUCCESS                                       The method is successful.
 192         *       @exception      E_DEVICE_BUSY                           The device cannot be approached because of other operations.
 193         *       @exception      E_UNSUPPORTED_OPERATION         This operation is not supported.
 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         * @endif
 222         */
 223         result Prepare(AudioInputDevice audioInputDevice, AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
 224
 225         /**
 226         *       Prepares the specified audio input device with the application-defined settings. @n
 227         *   When the caller finishes using the audio input device, the resources must be released by calling the Unprepare() method.
 228         *
 229         *   @since              2.0
 230         *
 231         *       @return         An error code
 232         *       @param[in]      audioSampleType                                         The type of audio sample
 233         *       @param[in]      audioChannelType                                                The audio channel type
 234         *       @param[in]      audioSampleRate                                         The audio sample rate in Hertz (Hz)
 235         *       @exception      E_SUCCESS                                                                       The method is successful.
 236         *  @exception  E_DEVICE_FAILED                                          The device failed with unknown reason.
 237         *       @exception      E_INVALID_ARG                                                   A specified input parameter is invalid.
 238         *       @exception      E_UNSUPPORTED_FORMAT                    The specified audio sample type is not supported.
 239         */
 240         result Prepare(AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
 241
 242         /**
 243         *       Stops the usage of the input device and releases the allocated resources during the execution of the Prepare() method. @n
 244         *   Resources allocated during %Prepare() are released.
 245         *
 246         *   @since              2.0
 247         *
 248         *       @return         An error code
 249         *       @exception      E_SUCCESS                                               The method is successful.
 250         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 251         *       @exception      E_SYSTEM                                                        A system error has occurred.
 252         */
 253         result Unprepare(void);
 254
 255         /**
 256         *       Adds an input buffer to the specified audio input device. @n
 257         *       When the buffer is filled, the %AudioIn class returns the buffer to the caller
 258         *       by invoking IAudioInEventListener::OnAudioInBufferIsFilled().
 259         *
 260         *   @since              2.0
 261         *
 262         *       @return                 An error code
 263         *       @param[in]      pByteBuffer                                                             A pointer to the buffer
 264         *       @exception      E_SUCCESS                                                                       The method is successful.
 265         *       @exception      E_INVALID_ARG                                                   The input parameter is invalid.
 266         *       @exception      E_INVALID_STATE                                 This instance is in an invalid state for this method.
 267         *       @exception      E_SYSTEM                                                                                A system error has occurred.
 268         *       @exception      E_OUT_OF_MEMORY                                 The memory is insufficient.
 269         *       @remarks        The data size of @c pByteBuffer must be the same as every call of this method.
 270         *       @see            Start()
 271         *       @see            IAudioInEventListener::OnAudioInBufferIsFilled()
 272         */
 273         result AddBuffer(const Tizen::Base::ByteBuffer* pByteBuffer);
 274
 275         /**
 276         *       Starts reading the audio data from an audio input device and fills the data into the buffer.
 277         *
 278         *   @since              2.0
 279         *
 280         *       @return                 An error code
 281         *       @exception      E_SUCCESS                                                       The method is successful.
 282         *       @exception      E_INVALID_STATE                 This instance is in an invalid state for this method.
 283         *       @exception      E_DEVICE_BUSY                                   The device cannot be approached because of other operations.
 284         *       @exception      E_SYSTEM                                                                A system error has occurred.
 285         *       @remarks        Several buffers must be added to the queue with AddBuffer() before calling this method.
 286         *       @see            Stop()
 287     *   @see        IAudioInEventListener::OnAudioInBufferIsFilled()
 288         */
 289         result Start(void);
 290
 291         /**
 292         *       Stops using the audio input device. @n
 293         *       All pending and current buffers that are filled with audio data
 294         *   at the time of calling the %Stop() method, are returned to the listener.
 295         *       Use Start() to start capturing audio input data again.
 296         *
 297         *   @since              2.0
 298         *
 299         *       @return                 An error code
 300         *       @exception      E_SUCCESS                                               The method is successful.
 301         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 302         *       @exception      E_SYSTEM                                                        A system error has occurred.
 303         *   @see            IAudioInEventListener::OnAudioInBufferIsFilled()
 304         */
 305         result Stop(void);
 306
 307         /**
 308         *       Resets using the audio input device without returning buffers to the caller. @n
 309         *       All pending and current buffers are released immediately without any notifications.
 310         *       The state is changed to @c AUDIOIN_STATE_PREPARED.
 311         *
 312         *   @since              2.0
 313         *
 314         *       @return                 An error code
 315         *       @exception      E_SUCCESS                                               The method is successful.
 316         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 317         *       @exception      E_SYSTEM                                                        A system error has occurred.
 318         */
 319         result Reset(void);
 320
 321         /**
 322         *       Gets the current state of this instance.
 323         *
 324         *   @since              2.0
 325         *
 326         *       @return                 The state of this instance
 327         *       @exception      E_SUCCESS                                               The method is successful.
 328         *       @exception      E_SYSTEM                                                        A system error has occurred.
 329         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 330         */
 331         AudioInState GetState(void) const;
 332
 333         /**
 334         *       Gets the maximum size of the buffer that can be used with AddBuffer(). @n
 335         *       This maximum value is set by Prepare() and reset to @c 0 by Unprepare().
 336         *
 337         *   @since              2.0
 338         *
 339         *       @return                 The maximum size of the buffer in bytes, @n
 340         *                               else @c -1 if an error occurs
 341         *       @exception      E_SUCCESS                                               The method is successful.
 342         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 343         *       @exception      E_SYSTEM                                                        A system error has occurred.
 344         *       @remarks        The return value is available after calling the Prepare() method.
 345         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 346         */
 347         int GetMaxBufferSize(void) const;
 348
 349         /**
 350         *       Gets the minimum size of the buffer that can be used with AddBuffer(). @n
 351         *       This minimum value is set by Prepare() and reset to @c 0 by Unprepare().
 352         *
 353         *   @since              2.0
 354         *
 355         *       @return                 The minimum size of the buffer in bytes, @n
 356         *                               else @c -1 if an error occurs
 357         *       @exception      E_SUCCESS                                               The method is successful.
 358         *       @exception      E_INVALID_STATE         This instance is in an invalid state for this method.
 359         *       @exception      E_SYSTEM                                                        A system error has occurred.
 360         *       @remarks        The return value is available after calling the Prepare() method.
 361         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 362         */
 363         int GetMinBufferSize(void) const;
 364
 365         /**
 366         *       Gets the optimized sample type of the audio input device.
 367         *
 368         *   @since              2.0
 369         *
 370         *       @return                 The audio encoding type
 371         *       @exception      E_SUCCESS                                               The method is successful.
 372         *       @exception      E_SYSTEM                                                        A system error has occurred.
 373         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 374         */
 375         AudioSampleType GetOptimizedSampleType(void) const;
 376
 377         /**
 378         *       Gets the optimized channel type of the audio input device.
 379         *
 380         *   @since              2.0
 381         *
 382         *       @return         The audio channel type
 383         *       @exception      E_SUCCESS                                               The method is successful.
 384         *       @exception      E_SYSTEM                                                        A system error has occurred.
 385         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 386         */
 387         AudioChannelType GetOptimizedChannelType(void) const;
 388
 389         /**
 390         *       Gets the optimized sample rate of the audio input device.
 391         *
 392         *   @since              2.0
 393         *
 394         *       @return         The sample rate in Hertz (Hz)
 395         *       @exception      E_SUCCESS                                               The method is successful.
 396         *       @exception      E_SYSTEM                                                        A system error has occurred.
 397         *       @remarks        The specific error code can be accessed using the GetLastResult() method.
 398         */
 399         int GetOptimizedSampleRate(void) const;
 400
 401
 402 private:
 403         /**
 404          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 405          *
 406          *      @since          2.0
 407          */
 408         AudioIn(const AudioIn& rhs);
 409
 410         /**
 411          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 412          *
 413          *       @since         2.0
 414          */
 415         AudioIn& operator =(const AudioIn& rhs);
 416
 417         friend class _AudioInImpl;
 418         class _AudioInImpl* __pAudioInImpl;
 419 };
 420
 421 }} // Tizen::Media
 422
 423 #endif