inc/FMediaAudioOut.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                        FMediaAudioOut.h
  20  * @brief                       This is the header file for the %AudioOut class.
  21  *
  22  * This header file contains the declarations of the %AudioOut class.
  23  */
  24
  25 #ifndef _FMEDIA_AUDIO_OUT_H_
  26 #define _FMEDIA_AUDIO_OUT_H_
  27
  28 #include <FBaseByteBuffer.h>
  29 #include <FMediaAudioTypes.h>
  30 #include <FMediaAudioManagerTypes.h>
  31 #include <FMediaIAudioOutEventListener.h>
  32
  33 namespace Tizen { namespace Media
  34 {
  35
  36 /**
  37  * @class               AudioOut
  38  * @brief               This class plays raw audio data.
  39  *
  40  * @since               2.0
  41  *
  42  * @remarks
  43  * The maximum number of %AudioOut instances is limited by Media::MediaCapability class. This number is a system wide count so that the application must not be able to construct more instances than the maximum number permitted.
  44  *
  45  * The %AudioOut class plays raw audio data and provides methods for:
  46  * - Playing PCM data in various audio sample types
  47  * - Controlling volume
  48  *
  49  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/playing_pcm_audio.htm">Playing PCM Audio</a>.
  50  *
  51  * The following example demonstrates how to use the %AudioOut class.
  52  *
  53  *
  54  * @code
  55  * #include <FBase.h>
  56  * #include <FIo.h>
  57  * #include <FApp.h>
  58  * #include <FMedia.h>
  59  *
  60  * using namespace Tizen::Base;
  61  * using namespace Tizen::Io;
  62  * using namespace Tizen::Media;
  63  *
  64  * #define MAX_BUFFER_COUNT     3
  65  *
  66  * class AudioOutSample
  67  *       : public Tizen::Media::IAudioOutEventListener
  68  * {
  69  * public:
  70  *       result Start(void);
  71  *       void Stop(void);
  72  *
  73  * protected:
  74  *       virtual void OnAudioOutBufferEndReached(Tizen::Media::AudioOut& src);
  75  *       virtual void OnAudioOutErrorOccurred(Tizen::Media::AudioOut& src, result r) {}
  76  *       virtual void OnAudioOutInterrupted(Tizen::Media::AudioOut& src) {}
  77  *       virtual void OnAudioOutReleased(Tizen::Media::AudioOut& src) {}
  78  *       virtual void OnAudioOutAudioFocusChanged(Tizen::Media::AudioOut& src) {}
  79  *
  80  * private:
  81  *       AudioOut __audioOut;
  82  *       File __file;
  83  *       ByteBuffer __buffer[MAX_BUFFER_COUNT];
  84  *       int __bufIndex;
  85  * };
  86  *
  87  * result
  88  * AudioOutSample::Start(void)
  89  * {
  90  *       FileAttributes attr;
  91  *       String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.pcm";
  92  *       result r;
  93  *       int minBufferSize;
  94  *
  95  *       // Opens the input file
  96  *       __file.Construct(filePath, L"rb");
  97  *
  98  *       // Constructs the AudioOut instance with a listener
  99  *       r = __audioOut.Construct(*this);
 100  *       if (IsFailed(r))
 101  *       {
 102  *               return r;
 103  *       }
 104  *
 105  *       // Prepares the AudioOut instance
 106  *       // Considers the input data as signed 16-bit, stereo, 44100 Hz PCM data
 107  *       __audioOut.Prepare(AUDIO_TYPE_PCM_S16_LE, AUDIO_CHANNEL_TYPE_STEREO, 44100);
 108  *       minBufferSize = __audioOut.GetMinBufferSize();
 109  *
 110  *       // Constructs the pcm buffer and enqueue the buffer to the __audioOut
 111  *       for (int i = 0; i < MAX_BUFFER_COUNT; i++)
 112  *       {
 113  *               __buffer[i].Construct(minBufferSize);
 114  *               __file.Read(__buffer[i]);
 115  *               __audioOut.WriteBuffer(__buffer[i]);
 116  *       }
 117  *       __bufIndex = 0;
 118  *
 119  *       // Starts playing
 120  *       r = __audioOut.Start();
 121  *       if (IsFailed(r))
 122  *       {
 123  *               return r;
 124  *       }
 125  *
 126  *       return E_SUCCESS;
 127  * }
 128  *
 129  * void
 130  * AudioOutSample::Stop(void)
 131  * {
 132  *       __audioOut.Stop();
 133  *       __audioOut.Unprepare();
 134  * }
 135  *
 136  * void
 137  * AudioOutSample::OnAudioOutBufferEndReached(Tizen::Media::AudioOut& src)
 138  * {
 139  *       result r = E_SUCCESS;
 140  *
 141  *       r = __file.Read(__buffer[__bufIndex % MAX_BUFFER_COUNT]);
 142  *       if (IsFailed(r))
 143  *       {
 144  *               // Handles end of file event
 145  *
 146  *               return;
 147  *       }
 148  *
 149  *       src.WriteBuffer(__buffer[__bufIndex % MAX_BUFFER_COUNT]);
 150  *       __bufIndex++;
 151  * }
 152  *
 153  *
 154  * @endcode
 155  */
 156
 157 class _OSP_EXPORT_ AudioOut
 158         : public Tizen::Base::Object
 159 {
 160 public:
 161         /**
 162          * 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.
 163          *
 164          * @since               2.0
 165          *
 166          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 167          * @see                 Construct()
 168          */
 169         AudioOut(void);
 170
 171         /**
 172          * This destructor overrides Tizen::Base::Object::~Object().
 173          * All allocated resources are released by this method.
 174          * This method must be called in the same thread as the Construct() method.
 175          *
 176          * @since               2.0
 177          *
 178          * @see                 Construct()
 179          */
 180         virtual ~AudioOut(void);
 181
 182 public:
 183         /**
 184         * Initializes this instance of %AudioOut with the specified listener.
 185         *
 186         * @since                2.0
 187         *
 188         * @return               An error code
 189         * @param[in]    listener                                                                                        An instance of IAudioOutEventListener
 190         * @exception    E_SUCCESS                                                                               The method is successful.
 191         * @exception    E_SYSTEM                                                                                        A system error has occurred.
 192         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 193         * @exception    E_RESOURCE_UNAVAILABLE          The AudioOut's resources are unavailable.
 194         */
 195         result Construct(IAudioOutEventListener& listener);
 196
 197         /**
 198         * Prepares an audio output device with the defined settings.
 199         *
 200         * @since                2.0
 201         *
 202         * @return               An error code
 203         * @param[in]    audioSampleType                                 The type of the audio sample
 204         * @param[in]    audioChannelType                                        The type of the audio channel
 205         * @param[in]    audioSampleRate                                 The audio sample rate in hertz (Hz)
 206         * @exception    E_SUCCESS                                                                       The method is successful.
 207         * @exception    E_INVALID_STATE                                 This instance is in an invalid state for this method.
 208         * @exception    E_SYSTEM                                                                                A system error has occurred.
 209         * @exception    E_INVALID_ARG                                                   A specified input parameter is invalid.
 210         * @exception    E_UNSUPPORTED_FORMAT            The specified audio sample type is not supported.
 211         * @see                  Unprepare()
 212         */
 213         result Prepare(AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
 214
 215         /**
 216         * Prepares an audio output device with the defined settings with the audio stream type.
 217         *
 218         * @since                2.0
 219         *
 220         * @return               An error code
 221         * @param[in]    audioStreamType                                 The type of the audio stream
 222         * @param[in]    audioSampleType                                 The type of the audio sample
 223         * @param[in]    audioChannelType                                        The type of the audio channel
 224         * @param[in]    audioSampleRate                                 The audio sample rate in hertz (Hz)
 225         * @exception    E_SUCCESS                                                               The method is successful.
 226         * @exception    E_INVALID_STATE                                 This instance is in an invalid state for this method.
 227         * @exception   E_DEVICE_FAILED                          The device failed with unknown reason.
 228         * @exception    E_INVALID_ARG                                           A specified input parameter is invalid.
 229         * @exception    E_UNSUPPORTED_FORMAT            The specified audio sample type is not supported.
 230         * @see                  Unprepare()
 231         */
 232         result Prepare(AudioStreamType audioStreamType, AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
 233
 234         /**
 235         * Closes the audio output device.
 236         *
 237         * @since                2.0
 238         *
 239         * @return               An error code
 240         * @exception    E_SUCCESS                                               The method is successful.
 241         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 242         * @exception    E_SYSTEM                                                        A system error has occurred.
 243         * @see                  Prepare()
 244         */
 245         result Unprepare(void);
 246
 247         /**
 248         * Writes into the data buffer containing the audio data to be played to this audio output device. @n
 249         * When the end of the buffer is reached, the application gets the notification through %IAudioOutEventListener.
 250         *
 251         * @since                2.0
 252         *
 253         * @return               An error code
 254         * @param[in]    userData                                                        A pointer of the buffer containing the PCM data block
 255         * @exception    E_SUCCESS                                               The method is successful.
 256         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 257         * @exception    E_SYSTEM                                                        A system error has occurred.
 258         * @exception    E_INVALID_ARG                           The specified input parameter is invalid.
 259         * @exception    E_OVERFLOW                                              The specified input instance has overflowed.
 260         * @see                  Start(), IAudioOutEventListener::OnAudioOutBufferEndReached()
 261         */
 262         result WriteBuffer(const Tizen::Base::ByteBuffer& userData);
 263
 264         /**
 265         * Starts the specified audio output device.
 266         *
 267         * @since                2.0
 268         *
 269         * @return               An error code
 270         * @exception    E_SUCCESS                                               The method is successful.
 271         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 272         * @exception    E_DEVICE_BUSY                           The device cannot be approached because of other operations.
 273         * @exception    E_SYSTEM                                                        A system error has occurred.
 274         * @see                  Stop()
 275         */
 276         result Start(void);
 277
 278         /**
 279         * Stops or pauses the playing of the audio output device. @n
 280         * The current position of the playback is stored internally and the playback will restart from this position
 281         * when Start() is called again.
 282         *
 283         * @since                2.0
 284         *
 285         * @return               An error code
 286         * @exception    E_SUCCESS                                               The method is successful.
 287         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 288         * @exception    E_SYSTEM                                                        A system error has occurred.
 289         * @remarks              Use Start() to resume the playback from the current playback position.
 290         * @see                  Start(), IAudioOutEventListener::OnAudioOutBufferEndReached()
 291         */
 292         result Stop(void);
 293
 294         /**
 295         * Resets the audio output device. @n
 296         * All pending and current data buffers in the queue are removed immediately without any notification. The
 297         * state is changed to AUDIOOUT_STATE_PREPARED.
 298         *
 299         * @since                2.0
 300         *
 301         * @return               An error code
 302         * @exception    E_SUCCESS                                               The method is successful.
 303         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 304         * @exception    E_SYSTEM                                                        A system error has occurred.
 305         */
 306         result Reset(void);
 307
 308         /**
 309         * Gets the state of the current audio output device.
 310         *
 311         * @since                2.0
 312         *
 313         * @return               The state of current audio output
 314         * @exception    E_SUCCESS                                               The method is successful.
 315         * @exception    E_SYSTEM                                                        A system error has occurred.
 316         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 317         */
 318         AudioOutState GetState(void) const;
 319
 320         /**
 321         * Gets the maximum size of buffer that can be used with WriteBuffer(). @n
 322         * This maximum value is set by Prepare() and reset to @c 0 by Unprepare().
 323         *
 324         * @since                2.0
 325         *
 326         * @return               The maximum size of buffer, @n
 327         *                               else @c -1 if an error occurs
 328         * @exception    E_SUCCESS                                               The method is successful.
 329         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 330         * @exception    E_SYSTEM                                                        A system error has occurred.
 331         * @remarks              The return value is available after calling the Prepare() method.
 332         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 333         */
 334         int GetMaxBufferSize(void) const;
 335
 336         /**
 337         * Gets the minimum size of buffer that can be used with WriteBuffer(). @n
 338         * This minimum value is set by Prepare() and reset to @c 0 by Unprepare().
 339         *
 340         * @since                2.0
 341         *
 342         * @return               The minimum size of buffer, @n
 343         *                               else @c -1 if an error occurs
 344         * @exception    E_SUCCESS                                               The method is successful.
 345         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 346         * @exception    E_SYSTEM                                                        A system error has occurred.
 347         * @remarks              The return value is available after calling the Prepare() method.
 348         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 349         */
 350         int GetMinBufferSize(void) const;
 351
 352         /**
 353         * Gets the optimized sample type of the audio output device.
 354         *
 355         * @since                2.0
 356         *
 357         * @return               The audio encoding type
 358         * @exception    E_SUCCESS                                               The method is successful.
 359         * @exception    E_SYSTEM                                                        A system error has occurred.
 360         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 361         */
 362         AudioSampleType GetOptimizedSampleType(void) const;
 363
 364         /**
 365         * Gets the optimized channel type of the audio output device.
 366         *
 367         * @since                2.0
 368         *
 369         * @return               The audio channel type
 370         * @exception    E_SUCCESS                                               The method is successful.
 371         * @exception    E_SYSTEM                                                        A system error has occurred.
 372         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 373         */
 374         AudioChannelType GetOptimizedChannelType(void) const;
 375
 376         /**
 377         * Gets the optimized sample rate of the audio output device.
 378         *
 379         * @since                2.0
 380         *
 381         * @return               The sample rate in hertz (Hz)
 382         * @exception    E_SUCCESS                                               The method is successful.
 383         * @exception    E_SYSTEM                                                        A system error has occurred.
 384         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 385         */
 386         int GetOptimizedSampleRate(void) const;
 387
 388         /**
 389         * Sets the volume level of the audio output device.
 390         *
 391         * @since                2.0
 392         *
 393         * @return               An error code
 394         * @param[in]    volume                          The new value for volume @n
 395         *                                                                       The range of this parameter is from @c 0 to @c 100 and it is proportional to the current media sound volume level in setting.
 396         * @exception    E_SUCCESS                                               The method is successful.
 397         * @exception    E_OUT_OF_RANGE                  The specified volume is out of range.
 398         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 399         * @remarks              This method must be called after Prepare().
 400         * @see                  GetVolume()
 401         */
 402         result SetVolume(int volume);
 403
 404         /**
 405         * Gets the current volume level of this audio output.
 406         *
 407         * @since                2.0
 408         *
 409         * @return               The current volume level, @n
 410         *                               else @c -1 if an error occurs @n
 411         *                               This return value ranges from @c 0 to @c 100.
 412         * @exception    E_SUCCESS                                               The method is successful.
 413         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 414         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 415         * @remarks              This method must be called after calling the Prepare() method.
 416         * @see                  SetVolume()
 417         */
 418         int GetVolume(void) const;
 419
 420 private:
 421         /**
 422          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 423          *
 424          * @since               2.0
 425          */
 426         AudioOut(const AudioOut& rhs);
 427
 428         /**
 429          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 430          *
 431          * @since               2.0
 432          */
 433         AudioOut& operator =(const AudioOut& rhs);
 434
 435         friend class _AudioOutImpl;
 436         class _AudioOutImpl* __pAudioOutImpl;
 437 };
 438
 439 }} // Tizen::Media
 440
 441 #endif