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. @n
 121          *      For full construction, the Construct() method must be called right after calling this constructor.
 122          *
 123          *      @since          2.0
 124          *
 125          */
 126         AudioDecoder(void);
 127
 128         /**
 129          *      This destructor overrides Tizen::Base::Object::~Object().
 130          *
 131          *      @since          2.0
 132          */
 133         virtual ~AudioDecoder(void);
 134
 135         /**
 136          *      Initializes this instance of %AudioDecoder with the specified parameters. @n
 137          *  The following example demonstrates how to use the %Construct() method as a simple decoder construction with optional parameters.
 138          *  @code
 139          *
 140          * result OpenAacDecoder(void)
 141          * {
 142          *       AudioDecoder dec;
 143          *       result r;
 144          *       HashMap option;
 145          *
 146          *       option.Construct();
 147          *       option.Add(*(new Integer(MEDIA_PROPERTY_AUDIO_CHANNEL_TYPE)), *(new Integer(AUDIO_CHANNEL_TYPE_STEREO)));
 148          *       option.Add(*(new Integer(MEDIA_PROPERTY_AUDIO_SAMPLE_RATE)), *(new Integer(44100)));
 149          *
 150          *       r = dec.Construct(CODEC_AAC, &option);
 151          *       if (IsFailed(r))
 152          *       {
 153          *              goto CATCH;
 154          *       }
 155          *
 156          *      return E_SUCCESS;
 157          * CATCH:
 158          *       return r;
 159          * }
 160          * @endcode
 161          *
 162          *      @since          2.0
 163          *
 164          *      @return         An error code
 165          *      @param[in]      type                            The codec type
 166          *      @param[in]      pOption                         The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_audio.htm#decoding_audio">optional parameters</a>
 167          *      @exception      E_SUCCESS                       The method is successful.
 168          *      @exception      E_UNSUPPORTED_CODEC The specified decoder is not supported.
 169          *      @exception      E_OUT_OF_RANGE          A specified input parameter has a value that is out of range.
 170          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 171          *      @exception      E_SYSTEM                        A system error has occurred.
 172          *      @remarks        The key type of the specified option is Tizen::Base::Integer, and the value type varies depending on the key type.
 173          */
 174         result Construct(CodecType type, const Tizen::Base::Collection::HashMap* pOption = null);
 175
 176         /**
 177          *
 178          *      Probes whether the audio data can be decoded.
 179          *
 180          *      @since          2.0
 181          *
 182          *      @return  An error code
 183          *      @param[in]      srcBuf                                  The source buffer that stores the compressed audio data
 184          *      @param[out]     sampleType                              The sample type of the decoded audio sample
 185          *      @param[out]     channelType                             The channel type of the decoded audio sample
 186          *      @param[out]     sampleRate                              The sample rate of the decoded audio sample
 187          *      @exception      E_SUCCESS                               The method is successful.
 188          *      @exception      E_INVALID_ARG                   A specified source buffer is invalid.
 189          *      @exception      E_UNSUPPORTED_FORMAT    The input data is not in a supported format.
 190          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient to decode the sample.
 191          *      @exception  E_SYSTEM                            A system error has occurred.
 192          *      @remarks        This method resets the internal state of an audio decoder.
 193          */
 194         result Probe(const Tizen::Base::ByteBuffer& srcBuf, AudioSampleType& sampleType, AudioChannelType& channelType, int& sampleRate);
 195
 196         /**
 197          *
 198          *      Decodes the audio data from the source buffer and stores the decoded data into a destination buffer. @n
 199          *      The %AudioDecoder class reads and decodes the audio data from the source buffer
 200          *      and it also writes the decoded audio data into the destination buffer. @n
 201          *  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.
 202          *
 203          *      @since          2.0
 204          *
 205          *      @return  An error code
 206          *      @param[in]      srcBuf                  The source buffer that stores the compressed audio data
 207          *      @param[out]     dstBuf                  The destination buffer that stores the decoded audio data
 208          *      @exception      E_SUCCESS               The method is successful.
 209          *      @exception      E_INVALID_ARG                   A specified source or destination buffer is invalid.
 210          *      @exception      E_UNSUPPORTED_FORMAT    The input data is not in a supported format.
 211          *      @exception      E_OUT_OF_MEMORY                 The specified destination buffer is insufficient to store the decoded data.
 212          *      @exception  E_SYSTEM                            A system error has occurred.
 213          */
 214         result Decode(Tizen::Base::ByteBuffer& srcBuf, Tizen::Base::ByteBuffer& dstBuf);
 215
 216         /**
 217          *      Resets the internal state of the audio decoder to process a new audio stream.
 218          *
 219          *      @since          2.0
 220          *
 221          *      @return         An error code
 222          *      @exception      E_SUCCESS                       The method is successful.
 223          *      @exception      E_SYSTEM                        A system error has occurred.
 224          */
 225         result Reset(void);
 226
 227         /**
 228          *      Gets the specified property type value of this instance.
 229          *
 230          *      @since          2.0
 231          *
 232          *      @return          An error code
 233          *      @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
 234          *      @param[out]             value                   The obtained property value
 235          *      @exception      E_SUCCESS                               The method is successful.
 236          *      @exception      E_OBJ_NOT_FOUND                 The specified @c key is not found.
 237          *      @exception      E_INVALID_ARG                   The specified @c key is not supported.
 238          *      @exception      E_SYSTEM                                A system error has occurred.
 239          *      @remarks        The property whose value type is enum can be obtained using this method.
 240          */
 241         result GetValue(MediaPropertyType key, int& value) const;
 242
 243         /**
 244          *      Gets the supported properties of this instance.
 245          *
 246          *      @since          2.0
 247          *
 248          *      @return  A list of supported properties, @n
 249          *                              else @c null if no property is supported or if an exception occurs
 250          *      @exception      E_SUCCESS                               The method is successful.
 251          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 252          *      @exception      E_SYSTEM                                A system error has occurred.
 253          *      @exception      E_OBJ_NOT_FOUND                 This instance does not support any property.
 254          *      @remarks
 255          *                              - The specific error code can be accessed using the GetLastResult() method.
 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
 285         *                       - The specific error code can be accessed using the GetLastResult() method.
 286         *                       - The return value must be deleted by the caller.
 287         */
 288         static Tizen::Base::Collection::IListT<CodecType>* GetSupportedCodecListN(void);
 289
 290 private:
 291         /**
 292         *       The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 293         *
 294         *       @since          2.0
 295         *
 296         */
 297         AudioDecoder(const AudioDecoder& rhs);
 298         /**
 299         *       The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 300         *
 301         *       @since          2.0
 302         *
 303         */
 304         AudioDecoder& operator =(const AudioDecoder& rhs);
 305
 306         friend class _AudioDecoderImpl;
 307         class _AudioDecoderImpl* __pImpl;
 308 };
 309
 310 }} // Tizen::Media
 311
 312 #endif // _FMEDIA_AUDIODECODER_H_