inc/FMediaAudioFrame.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                        FMediaAudioFrame.h
  20  * @brief                       This is the header file for the %AudioFrame class.
  21  *
  22  * This header file contains the declarations of the %AudioFrame class.
  23  */
  24
  25 #ifndef _FMEDIA_AUDIO_FRAME_H_
  26 #define _FMEDIA_AUDIO_FRAME_H_
  27
  28 #include <FBase.h>
  29 #include <FMediaAudioTypes.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33
  34 /**
  35  * @class       AudioFrame
  36  * @brief       This class has the audio frame data.
  37  *
  38  * @since               2.1
  39  *
  40  * @final       This class is not intended for extension.
  41  *
  42  * The %AudioFrame class has the audio frame data.
  43  * The frame has several plane components. @n
  44  * This object is delivered to the application by IAudioStreamFilter::ProcessAudioStream() when the audio file is streaming.
  45  *
  46  * The following example demonstrates how to use the %AudioFrame class.
  47  *
  48  * @code
  49  * #include <FBase.h>
  50  * #include <FMedia.h>
  51  * #include <FApp.h>
  52  *
  53  * using namespace Tizen::Media;
  54  *
  55  * class AudioFrameSample
  56  *     : public Tizen::Media::IAudioRecorderEventListener
  57  *     , public Tizen::Media::IAudioStreamFilter
  58  * {
  59  * public:
  60  *     AudioFrameSample(void);
  61  *     result Start(void);
  62  *     void Stop(void);
  63  *
  64  * protected:
  65  *     virtual void OnAudioRecorderStopped(result r) {}
  66  *     virtual void OnAudioRecorderCanceled(result r) {}
  67  *     virtual void OnAudioRecorderPaused(result r) {}
  68  *     virtual void OnAudioRecorderStarted(result r) {}
  69  *     virtual void OnAudioRecorderEndReached(RecordingEndCondition endCondition) {}
  70  *     virtual void OnAudioRecorderClosed(result r) {}
  71  *     virtual void OnAudioRecorderErrorOccurred(RecorderErrorReason r) {}
  72  *     virtual void ProcessAudioStream(AudioFrame &frame);
  73  *
  74  * private:
  75  *     AudioRecorder __recorder;
  76  * };
  77  *
  78  * AudioFrameSample::AudioFrameSample(void)
  79  * {
  80  * }
  81  *
  82  * result
  83  * AudioFrameSample::Start(void)
  84  * {
  85  *     result r = E_SUCCESS;
  86  *     String destFilePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.amr";
  87  *
  88  *     r = __recorder.Construct(*this);
  89  *     if (IsFailed(r))
  90  *     {
  91  *         return r;
  92  *     }
  93  *
  94  *     r = __recorder.CreateAudioFile(destFilePath, true);
  95  *     if (IsFailed(r))
  96  *     {
  97  *         return r;
  98  *     }
  99  *
 100  *     r = __recorder.AddAudioStreamListener(*this);
 101  *     if (IsFailed(r))
 102  *     {
 103  *         return r;
 104  *     }
 105  *
 106  *     r = __recorder.Record();
 107  *     if (IsFailed(r))
 108  *     {
 109  *         return r;
 110  *     }
 111  *
 112  *     return E_SUCCESS;
 113  *  }
 114  *
 115  * void
 116  * AudioFrameSample::Stop(void)
 117  * {
 118  *     __recorder.Stop();
 119  *     __recorder.Close();
 120  * }
 121  *
 122  * void
 123  * AudioFrameSample::ProcessAudioStream(AudioFrame &frame)
 124  * {
 125  *   // Manipulates the audio frame data
 126  *   // Gets a peak value from the audio frame.
 127  *   // This code supports only signed 16-bits sample format.
 128  *   if (frame.GetPlaneCount() < 1 || frame.GetSampleType() != AUDIO_TYPE_PCM_S16_LE)
 129  *   {
 130  *      return;
 131  *   }
 132  *   short* pSampleData = (short*)(frame.GetPlaneData(0)->GetPointer())
 133  *   int minPeakValue = 0;
 134  *   int maxPeakValue = 0;
 135  *   int sampleCount = frame.GetPlaneData(0)->GetCapacity() / 2;
 136  *   for (int i = 0; i<sampleCount; i++)
 137  *   {
 138  *        if (pSampleData[i] < minPeakValue)
 139  *        {
 140  *            minPeakValue = pSampleData[i];
 141  *        }
 142  *        if (pSampleData[i] > maxPeakValue)
 143  *        {
 144  *            maxPeakValue = pSampleData[i];
 145  *        }
 146  *   }
 147  * }
 148  *
 149  * @endcode
 150  *
 151  *
 152  */
 153 class _OSP_EXPORT_ AudioFrame
 154         : public Tizen::Base::Object
 155 {
 156 public:
 157
 158         /**
 159          *
 160          * Gets the plane count that a frame data has.
 161          *
 162          *
 163          * @return       The plane count
 164          *
 165          */
 166         int GetPlaneCount(void) const;
 167
 168         /**
 169          *
 170          * Gets the type of an audio channel.
 171          *
 172          *
 173          * @return       The audio channel
 174          *
 175          */
 176         AudioChannelType GetChannelType(void) const;
 177
 178         /**
 179          *
 180          * Gets the audio sample type.
 181          *
 182          *
 183          * @return       The audio sample type
 184          *
 185          */
 186         AudioSampleType GetSampleType(void) const;
 187
 188         /**
 189          *
 190          * Gets the audio sampling rate.
 191          *
 192          *
 193          * @return       The audio sampling rate in Hertz (Hz)
 194          *
 195          */
 196         int GetSamplingRate(void) const;
 197
 198         /**
 199          *
 200          * Gets the plane data at the specified @c index from a frame.
 201          *
 202          *
 203          * @return       The plane data, @n
 204          *               else @c null if an error has occurred
 205          * @param[in]   index                           The index at which the value is read
 206          * @exception   E_SUCCESS                                       The method is successful.
 207          * @exception   E_OUT_OF_RANGE                          The specified @c index is out of range.
 208          * @remarks
 209          *                      - The @c index should be less than the plane count.
 210          *              - The buffer in Tizen::Base::ByteBuffer is shared with the %AudioFrame instance.
 211          *                      - The specific error code can be accessed using the GetLastResult() method.
 212          */
 213         Tizen::Base::ByteBuffer* GetPlaneData(int index) const;
 214
 215 private:
 216
 217         /**
 218          * This is the default constructor for this class.
 219          *
 220          * @remarks     The object is not fully constructed after this constructor is called. For full construction,
 221          *                      the Construct() method must be called right after calling this constructor.
 222          */
 223         AudioFrame(void);
 224
 225         /**
 226          * This is the destructor for this class. @n
 227          * All allocated resources are deallocated by this method. This polymorphic destructor should be overridden if required.
 228          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 229          *
 230          */
 231         virtual ~AudioFrame(void);
 232
 233         /**
 234          * Constructs an instance of this class. @n
 235          *
 236          *
 237          * @return          An error code
 238          * @exception   E_SUCCESS       The method is successful.
 239          *
 240          */
 241         result Construct(void);
 242
 243         /**
 244           * This is the copy constructor for this class.
 245           *
 246           *
 247           * @remarks        The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 248           */
 249         AudioFrame(const AudioFrame& rhs);
 250
 251         /**
 252           * This is the copy assignment operator for this class.
 253           *
 254           *
 255           * @remarks        The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 256           *
 257           */
 258         AudioFrame& operator =(const AudioFrame& rhs);
 259
 260         friend class _AudioStreamCoordinator;
 261         friend class _AudioFrameImpl;
 262         class _AudioFrameImpl* __pImpl;
 263 };
 264
 265 }}// Tizen::Media
 266
 267 #endif