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 stream is coming.
  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  *   // manipulate audio frmae data.
 126  *   // Get 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 peakValue = 0;
 134  *   int sampleCount = frame.GetPlaneSize(0) / 2;
 135  *   for (int i = 0; i<sampleCount; i++)
 136  *   {
 137  *        if (pSampleData[i] >peakValue)
 138  *            peakValue = pSampleData[i];
 139  *   }
 140  * }
 141  *
 142  * @endcode
 143  *
 144  *
 145  */
 146 class _OSP_EXPORT_ AudioFrame
 147         : public Tizen::Base::Object
 148 {
 149 public:
 150
 151         /**
 152          *
 153          * Gets the plane count which the frame data has.
 154          *
 155          *
 156          * @return       The plane count
 157          *
 158          */
 159         int GetPlaneCount(void) const;
 160
 161         /**
 162          *
 163          * Gets the audio channel.
 164          *
 165          *
 166          * @return       The audio channel
 167          *
 168          */
 169         AudioChannelType GetChannelType(void) const;
 170
 171         /**
 172          *
 173          * Gets the audio sample type.
 174          *
 175          *
 176          * @return       The audio sample type
 177          *
 178          */
 179         AudioSampleType GetSampleType(void) const;
 180
 181         /**
 182          *
 183          * Gets the audio sampling rate.
 184          *
 185          *
 186          * @return       The audio sampling rate in hertz (Hz)
 187          *
 188          */
 189         int GetSamplingRate(void) const;
 190
 191         /**
 192          *
 193          * Gets the plane data at the specified index from the frame.
 194          *
 195          *
 196          * @return       The plane data, @n
 197          *               else @null if an error occurred
 198          * @param[in]   index                           The index at which the value is read
 199          * @exception   E_SUCCESS                                       The method is successful.
 200          * @exception   E_OUT_OF_RANGE                          The specified index is out of range.
 201          * @remarks     The index should be less than the plane count. @n
 202          *          The buufer in ByteBuffer is shared with @c AudioFrame instance. @n
 203          *                      The specific error code can be accessed using the GetLastResult() method.
 204          */
 205         Tizen::Base::ByteBuffer* GetPlaneData(int index) const;
 206
 207 private:
 208
 209         /**
 210          * This is the default constructor for this class.
 211          *
 212          * @remarks     The object is not fully constructed after this constructor is called. For full construction,
 213          *                      the Construct() method must be called right after calling this constructor.
 214          */
 215         AudioFrame(void);
 216
 217         /**
 218          * This is the destructor for this class. @n
 219          * All allocated resources are deallocated by this method. This polymorphic destructor should be overridden if required.
 220          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 221          *
 222          */
 223         virtual ~AudioFrame(void);
 224
 225         /**
 226          * Constructs the instance of this class. @n
 227          *
 228          *
 229          * @return          An error code
 230          * @exception   E_SUCCESS       The method is successful.
 231          *
 232          */
 233         result Construct(void);
 234
 235         /**
 236           * This is the copy constructor for this class.
 237           *
 238           *
 239           * @remarks        The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 240           */
 241         AudioFrame(const AudioFrame& rhs);
 242
 243         /**
 244           * This is the copy assignment operator for this class.
 245           *
 246           *
 247           * @remarks        The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 248           *
 249           */
 250         AudioFrame& operator =(const AudioFrame& rhs);
 251
 252         friend class _AudioStreamCoordinator;
 253         friend class _AudioFrameImpl;
 254         class _AudioFrameImpl* __pImpl;
 255 };
 256
 257 }}// Tizen::Media
 258
 259 #endif