inc/FMediaAudioDecoder.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   FMediaAudioDecoder.h
  20  * @brief  This is the header file for the %AudioDecoder class.
  21  *
  22  * This header file contains the declarations of the %AudioDecoder class.
  23  */
  24
  25 #ifndef _FMEDIA_AUDIO_DECODER_H_
  26 #define _FMEDIA_AUDIO_DECODER_H_
  27
  28 #include <FBase.h>
  29 #include <FMediaAudioTypes.h>
  30 #include <FMediaTypes.h>
  31
  32 namespace Tizen { namespace Media
  33 {
  34
  35 /**
  36  * @class AudioDecoder
  37  * @brief This class decodes a compressed audio stream to a raw audio data.
  38  *
  39  * @since               2.0
  40  *
  41  * @remarks
  42  * Source data of AAC and AMR decoder must be raw compressed data without header.
  43  *
  44  *  The %AudioDecoder class decodes a compressed audio stream to a raw audio data.
  45  *  The audio decoding formats, such as CODEC_MP3, CODEC_AAC, and CODEC_AMR_NB, are supported.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_audio.htm">Encoding and Decoding Audio</a>.
  48  *
  49  * The following example demonstrates how to use the %AudioDecoder class in MP3 decoding.
  50  *
  51  *
  52  * @code
  53  *
  54  * #include <FBase.h>
  55  * #include <FIo.h>
  56  * #include <FApp.h>
  57  * #include <FMedia.h>
  58  *
  59  * using namespace Tizen::Base;
  60  * using namespace Tizen::Base::Collection;
  61  * using namespace Tizen::Io;
  62  * using namespace Tizen::Media;
  63  *
  64  * #define DST_BUF_SIZE   (1024*16)
  65  *
  66  * result
  67  * AudioDecoderSample(void)
  68  * {
  69  *       AudioDecoder dec;
  70  *       result r;
  71  *       ByteBuffer srcBuf, dstBuf;
  72  *       File srcFile;
  73  *       FileAttributes attr;
  74  *       int sampleRate;
  75  *       AudioChannelType channelType;
  76  *       AudioSampleType sampleType;
  77  *       String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp3";
  78  *
  79  *       // Loads src file into buffer
  80  *       File::GetAttributes(filePath, attr);
  81  *       srcBuf.Construct(attr.GetFileSize());
  82  *       srcFile.Construct(filePath, "rb");
  83  *       srcFile.Read(srcBuf);
  84  *       srcBuf.Flip();  // Sets the position of source buffer to zero
  85  *
  86  *       // Adds code that skips ID3 tag in srcBuf
  87  *
  88  *       dstBuf.Construct(DST_BUF_SIZE);
  89  *
  90  *       dec.Construct(CODEC_MP3);
  91  *       r = dec.Probe(srcBuf, sampleType, channelType, sampleRate);
  92  *       if (IsFailed(r))
  93  *       {
  94  *               return r;
  95  *       }
  96  *
  97  *       while (srcBuf.GetRemaining() > 0)
  98  *       {
  99  *               r = dec.Decode(srcBuf, dstBuf);
 100  *               if (IsFailed(r))
 101  *               {
 102  *                       break;
 103  *               }
 104  *
 105  *               // Adds code handling decoded data
 106  *
 107  *               dstBuf.Clear();
 108  *       }
 109  *
 110  *       return r;
 111  * }
 112  * @endcode
 113  */
 114
 115 class _OSP_EXPORT_ AudioDecoder
 116         : public Tizen::Base::Object
 117 {
 118 public:
 119         /**
 120          *      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.
 121          *
 122          *      @since          2.0
 123          *
 124          *      @remarks        After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 125          *      @see            Construct()
 126          */
 127         AudioDecoder(void);
 128
 129         /**
 130          *      This destructor overrides Tizen::Base::Object::~Object().
 131          *
 132          *      @since          2.0
 133          */
 134         virtual ~AudioDecoder(void);
 135
 136         /**
 137          *      Initializes this instance of %AudioDecoder with the specified parameters. @n
 138          *  The following example demonstrates how to use the %Construct() method as a simple decoder construction with optional parameters.
 139          *  @code
 140          *
 141          * result OpenAacDecoder(void)
 142          * {
 143          *       AudioDecoder dec;
 144          *       result r;
 145          *       HashMap option;
 146          *
 147          *       option.Construct();
 148          *       option.Add(*(new Integer(MEDIA_PROPERTY_AUDIO_CHANNEL_TYPE)), *(new Integer(AUDIO_CHANNEL_TYPE_STEREO)));
 149          *       option.Add(*(new Integer(MEDIA_PROPERTY_AUDIO_SAMPLE_RATE)), *(new Integer(44100)));
 150          *
 151          *       r = dec.Construct(CODEC_AAC, &option);
 152          *       if (IsFailed(r))
 153          *       {
 154          *              goto CATCH;
 155          *       }
 156          *
 157          *      return E_SUCCESS;
 158          * CATCH:
 159          *       return r;
 160          * }
 161          * @endcode
 162          *
 163          *      @since          2.0
 164          *
 165          *      @return         An error code
 166          *      @param[in]      type                            The codec type
 167          *      @param[in]      pOption                         The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_audio.htm#decoding_audio">optional parameters</a>
 168          *      @exception      E_SUCCESS                       The method is successful.
 169          *      @exception      E_UNSUPPORTED_CODEC The specified decoder is not supported.
 170          *      @exception      E_OUT_OF_RANGE          A specified input parameter has a value that is out of range.
 171          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 172          *      @exception      E_SYSTEM                        A system error has occurred.
 173          *      @remarks        The key type of the specified option is Tizen::Base::Integer, and the value type varies depending on the key type.
 174          */
 175         result Construct(CodecType type, const Tizen::Base::Collection::HashMap* pOption = null);
 176
 177         /**
 178          *
 179          *      Probes whether the audio data can be decoded.
 180          *
 181          *      @since          2.0
 182          *
 183          *      @return  An error code
 184          *      @param[in]      srcBuf                                  The source buffer that stores the compressed audio data
 185          *      @param[out]     sampleType                              The sample type of the decoded audio sample
 186          *      @param[out]     channelType                             The channel type of the decoded audio sample
 187          *      @param[out]     sampleRate                              The sample rate of the decoded audio sample
 188          *      @exception      E_SUCCESS                               The method is successful.
 189          *      @exception      E_INVALID_ARG                   A specified source buffer is invalid.
 190          *      @exception      E_UNSUPPORTED_FORMAT    The input data is not in a supported format.
 191          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient to decode the sample.
 192          *      @exception  E_SYSTEM                            A system error has occurred.
 193          *      @remarks        This method resets the internal state of an audio decoder.
 194          */
 195         result Probe(const Tizen::Base::ByteBuffer& srcBuf, AudioSampleType& sampleType, AudioChannelType& channelType, int& sampleRate);
 196
 197         /**
 198          *
 199          *      Decodes the audio data from the source buffer and stores the decoded data into a destination buffer. @n
 200          *      The %AudioDecoder class reads and decodes the audio data from the source buffer
 201          *      and it also writes the decoded audio data into the destination buffer. @n
 202          *  The position of the source buffer is moved to the end of the consumed data and the position of the destination buffer is moved to the end of the written data.
 203          *
 204          *      @since          2.0
 205          *
 206          *      @return  An error code
 207          *      @param[in]      srcBuf                  The source buffer that stores the compressed audio data
 208          *      @param[out]     dstBuf                  The destination buffer that stores the decoded audio data
 209          *      @exception      E_SUCCESS               The method is successful.
 210          *      @exception      E_INVALID_ARG                   A specified source or destination buffer is invalid.
 211          *      @exception      E_UNSUPPORTED_FORMAT    The input data is not in a supported format.
 212          *      @exception      E_OUT_OF_MEMORY                 The specified destination buffer is insufficient to store the decoded data.
 213          *      @exception  E_SYSTEM                            A system error has occurred.
 214          */
 215         result Decode(Tizen::Base::ByteBuffer& srcBuf, Tizen::Base::ByteBuffer& dstBuf);
 216
 217         /**
 218          *      Resets the internal state of the audio decoder to process a new audio stream.
 219          *
 220          *      @since          2.0
 221          *
 222          *      @return         An error code
 223          *      @exception      E_SUCCESS                       The method is successful.
 224          *      @exception      E_SYSTEM                        A system error has occurred.
 225          */
 226         result Reset(void);
 227
 228         /**
 229          *      Gets the specified property type value of this instance.
 230          *
 231          *      @since          2.0
 232          *
 233          *      @return          An error code
 234          *      @param[in]              key                                     The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_audio.htm#decoding_audio">key</a> for which the value is obtained
 235          *      @param[out]             value                   The obtained property value
 236          *      @exception      E_SUCCESS                               The method is successful.
 237          *      @exception      E_OBJ_NOT_FOUND                 The specified @c key is not found.
 238          *      @exception      E_INVALID_ARG                   The specified @c key is not supported.
 239          *      @exception      E_SYSTEM                                A system error has occurred.
 240          *      @remarks        The property whose value type is enum can be obtained using this method.
 241          */
 242         result GetValue(MediaPropertyType key, int& value) const;
 243
 244         /**
 245          *      Gets the supported properties of this instance.
 246          *
 247          *      @since          2.0
 248          *
 249          *      @return  A list of supported properties, @n
 250          *                              else @c null if no property is supported or if an exception occurs
 251          *      @exception      E_SUCCESS                               The method is successful.
 252          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 253          *      @exception      E_SYSTEM                                A system error has occurred.
 254          *      @exception      E_OBJ_NOT_FOUND                 This instance does not support any property.
 255          *      @remarks        The specific error code can be accessed using the GetLastResult() method. @n
 256          *                              The return value must be deleted.
 257          */
 258         Tizen::Base::Collection::IListT<MediaPropertyType>* GetSupportedPropertyListN(void) const;
 259
 260         /**
 261          *      Checks whether the specified property type is supported.
 262          *
 263          *      @since          2.0
 264          *
 265          *      @return  @c true if the property is supported, @n
 266          *                              else @c false
 267          *      @param[in]              key                             The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_audio.htm#decoding_audio">key</a> for which the value is obtained
 268          *      @exception      E_SUCCESS                   The method is successful.
 269          *      @exception      E_OBJ_NOT_FOUND         The specified @c key is not found.
 270          *      @exception      E_SYSTEM                        A system error has occurred.
 271          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
 272          */
 273         bool IsPropertySupported(MediaPropertyType key) const;
 274
 275         /**
 276         * Gets a list of the supported codecs.
 277         *
 278         * @since                2.0
 279         *
 280         * @return     A list of the codecs supported by the %AudioDecoder class, @n
 281         *             else @c null if an exception occurs
 282         * @exception  E_SUCCESS             The method is successful.
 283         * @exception  E_OUT_OF_MEMORY       The memory is insufficient.
 284         * @remarks    The specific error code can be accessed using the GetLastResult() method.
 285         * @remarks    The return value must be deleted by the caller.
 286         */
 287         static Tizen::Base::Collection::IListT<CodecType>* GetSupportedCodecListN(void);
 288
 289 private:
 290         /**
 291         *       The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 292         *
 293         *       @since          2.0
 294         *
 295         */
 296         AudioDecoder(const AudioDecoder& rhs);
 297         /**
 298         *       The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 299         *
 300         *       @since          2.0
 301         *
 302         */
 303         AudioDecoder& operator =(const AudioDecoder& rhs);
 304
 305         friend class _AudioDecoderImpl;
 306         class _AudioDecoderImpl* __pImpl;
 307 };
 308
 309 }} // Tizen::Media
 310
 311 #endif // _FMEDIA_AUDIODECODER_H_