spiritMP3Dec.h

00001 /*
00002   ******************************************************************************
00003   * @file    spiritMP3Dec.h
00004   * @author  MCD Application Team
00005   * @brief   This file is header for spiritMP3Dec MP3 decoder library.
00006   ******************************************************************************
00007   * Portions COPYRIGHT 2017 STMicroelectronics
00008   * Portions SPIRIT Audio Engine Copyright (c) 1995-2009, SPIRIT
00009   *
00010   * Redistribution and use in source and binary forms, with or without 
00011   * modification, are permitted, provided that the following conditions are met:
00012   *
00013   * 1. Redistribution of source code must retain the above copyright notice, 
00014   *    this list of conditions and the following disclaimer.
00015   * 2. Redistributions in binary form must reproduce the above copyright notice,
00016   *    this list of conditions and the following disclaimer in the documentation
00017   *    and/or other materials provided with the distribution.
00018   * 3. Neither the name of STMicroelectronics nor the names of other 
00019   *    contributors to this software may be used to endorse or promote products 
00020   *    derived from this software without specific written permission.
00021   * 4. This software, including modifications and/or derivative works of this 
00022   *    software, must execute solely and exclusively on microcontroller based on 
00023   *    ARM Cortex®-M3 and/or ARM Cortex®-M4 cores or microprocessor devices 
00024   *    manufactured by or for STMicroelectronics.
00025   * 5. Redistribution and use of this software other than as permitted under 
00026   *    this license is void and will automatically terminate your rights under 
00027   *    this license. 
00028   *
00029   * THIS SOFTWARE IS PROVIDED BY STMICROELECTRONICS AND CONTRIBUTORS "AS IS" 
00030   * AND ANY EXPRESS, IMPLIED OR STATUTORY WARRANTIES, INCLUDING, BUT NOT 
00031   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
00032   * PARTICULAR PURPOSE AND NON-INFRINGEMENT OF THIRD PARTY INTELLECTUAL PROPERTY
00033   * RIGHTS ARE DISCLAIMED TO THE FULLEST EXTENT PERMITTED BY LAW. IN NO EVENT 
00034   * SHALL STMICROELECTRONICS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00035   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00036   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
00037   * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
00038   * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
00039   * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00040   * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00041   *
00042   ******************************************************************************
00043   */
00044 
00045 #ifndef __SPIRITMP3DEC_H__
00046 #define __SPIRITMP3DEC_H__
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 
00053 /**
00054     Informational structure to provide information about MP3 stream.
00055 */
00056 typedef struct
00057 {
00058     unsigned int nLayer;                         /* MPEG Audio Layer (1-3). Zero indicates that structure is not valid */
00059     unsigned int nSampleRateHz;                  /* Sample rate, Hz */
00060     unsigned int nBitrateKbps;                   /* Current bit rate, kilobit per seconds (0 for free-format stream) */
00061     unsigned int nChannels;                      /* Number of channels (1 or 2) */
00062     unsigned int IsGoodStream;                   /* Zero indicates that audio stream is not consistent */
00063     unsigned int anCutOffFrq576[2];              /* Cut-off frequencies for both channels (range 0-576), where 576 = Nyquist frequency */
00064     unsigned int nBitsReadAfterFrameHeader;      /* Number of bits, read after last frame header (for AV sync) */
00065     unsigned int nSamplesPerFrame;               /* Number of samples per audio frame (for AV sync) */
00066     unsigned int nSamplesLeftInFrame;            /* Number of samples, remaining in the internal buffer (for AV sync) */
00067 } TSpiritMP3Info;
00068 
00069 
00070 /**
00071     MP3 decoder object (persistent RAM).
00072 */
00073 typedef struct
00074 {
00075     int hidden[3086];                            /* Structure contents is hidden for demo version */
00076 } TSpiritMP3Decoder;
00077 
00078 
00079 /**
00080     Callback function type to supply decoder with input data.
00081     return number of MAU's read into buffer.
00082 */
00083 typedef unsigned int (fnSpiritMP3ReadCallback)(
00084     void * pMP3CompressedData,                   /* [OUT] Pointer to buffer to fill with coded MP3 data */
00085     unsigned int nMP3DataSizeInChars,            /* Buffer size in MAU's */
00086     void * token                                 /* Application-supplied token */
00087     );
00088 
00089 
00090 /**
00091 *   Application-supplied MDCT-domain processing function type.
00092 *   MDCT coefficients represented as float or int32 type, depending
00093 *   on build options.
00094 *   This function can be used for equalizer or pitch-shifter
00095 */
00096 typedef void (fnSpiritMP3ProcessCallback)(
00097     void * mdct_samples,                /* [IN/OUT] MDCT coefficients  */
00098     int isShort,                        /* Flag: 1 if short frame */
00099     int ch,                             /* Channel number (0 or 1). */
00100     void * token                        /* Application-supplied token */
00101     );
00102 
00103 /**
00104 *  Decoder initialization function
00105 */
00106 void SpiritMP3DecoderInit(
00107     TSpiritMP3Decoder *pDecoder,                 /* Decoder structure */
00108     fnSpiritMP3ReadCallback* pCallbackFn,        /* Data reading callback function */
00109     fnSpiritMP3ProcessCallback *pProcessFn,      /* Data processing callback function */
00110     void * token                                 /* Optional parameter for callback function */
00111     );
00112 
00113 
00114 /**
00115     Decoding function
00116     return number of audio samples decoded.
00117     NOTE: function always produce stereo data (1 sample = 32 bit = 2ch*16 bit).
00118 */
00119 unsigned int SpiritMP3Decode (
00120     TSpiritMP3Decoder *pDecoder,                 /* Decoder structure */
00121     short *pPCMSamples,                          /* [OUT] Output PCM buffer */
00122     unsigned int nSamplesRequired,               /* Number of samples to decode (1 sample = 32 bit = 2ch*16 bit) */
00123     TSpiritMP3Info * pMP3Info                    /* [OUT, opt] Optional informational structure */
00124     );
00125 
00126 
00127 /**
00128 *   Return sizeof(TSpiritMP3Decoder)
00129 */
00130 int SpiritMP3DecoderGetPersistentSize(void);
00131 
00132 #ifdef __cplusplus
00133 }
00134 #endif
00135 
00136 #endif