/* DecMPA - simple MPEG Audio decoding library. Copyright (C) 2002 Hauke Duden This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA For more information look at the file License.txt in this package. email: hazard_hd@users.sourceforge.net */ #ifndef _DECMPA_H_ #define _DECMPA_H_ /**\file Specifies the DecMPA API.*/ #ifndef DECMPA_VERSION /**DecMPA API version number.*/ #define DECMPA_VERSION 1 #endif #if defined(_WINDOWS) || defined(_WIN32) #ifndef CALLBACK #include #endif #define DECMPA_CC CALLBACK #else #define DECMPA_CC #endif /**\def DECMPA_CC Macro for the calling convention used by DecMPA functions.*/ /**\defgroup GroupFunctions Functions*/ /**\defgroup GroupResults Result Codes Description of the result codes that are returned by most DecMPA functions. Codes of the form DECMPA_ERROR_*** represent errors and are all negative. The other result codes, all >=0, indicate different degrees of success.*/ /**\defgroup GroupParamIDs Configuations Parameters Description of the possible parameters that can be defined using #DecMPA_SetParam. */ /**\defgroup GroupParamValues Configuration Parameter Values Description of the value constants that can be assigned to some configuration parameters.*/ /**\defgroup GroupStructs Structures*/ /**\addtogroup GroupStructs*/ /*@{*/ /**This structure contains pointers to the functions that are used to read the MP3 data during DecMPA_Decode.*/ typedef struct { /**Pointer to the function that is used to read data. If this pointer is NULL, DecMPA will read from stdin and ignore the other callback functions. @param pContext context pointer that was passed to #DecMPA_CreateUsingCallbacks @param pBuffer buffer that the data should be stored into @param nBytes number of bytes to read @return the number of bytes read or -1 if an error occurred. If the returned value is less than nBytes it is assumed that the end of the data stream was reached. \note the function that the pointer points to should have the calling convention DECMPA_CC, i.e. it should be defined as: \code long DECMPA_CC MyReadFuncName(void* pContext,void* pBuffer,long nBytes); \endcode*/ long (DECMPA_CC* Read)(void* pContext,void* pBuffer,long nBytes); /**Pointer to function that seeks to the specified data stream position. This function pointer should be set to NULL if seeking is not supported. @param pContext context pointer that was passed to #DecMPA_CreateUsingCallbacks @param DestPos destination position, in bytes. @return nonzero if successful, 0 otherwise. \note the function that the pointer points to should have the calling convention DECMPA_CC, i.e. it should be defined as: \code int DECMPA_CC MySeekFuncName(void* pContext,long DestPos); \endcode*/ int (DECMPA_CC* Seek)(void* pContext,long DestPos); /**Pointer to a function that returns the length of the data stream. This function pointer can be set to NULL if the length cannot be determined. Alternatively the function can return -1, @param pContext context pointer that was passed to #DecMPA_CreateUsingCallbacks @return the length, in bytes. -1 if unknown. \note the function that the pointer points to should have the calling convention DECMPA_CC, i.e. it should be defined as: \code long DECMPA_CC MyGetLengthFuncName(void* pContext); \endcode*/ long (DECMPA_CC* GetLength)(void* pContext); /**Pointer to a function that returns the current position in the data stream. This function pointer can only be NULL if Read is also NULL. @param pContext context pointer that was passed to #DecMPA_CreateUsingCallbacks @return the current position, in bytes or -1 if an error occurred. \note the function that the pointer points to should have the calling convention DECMPA_CC, i.e. it should be defined as: \code long DECMPA_CC MyGetPositionFuncName(void* pContext); \endcode*/ long (DECMPA_CC* GetPosition)(void* pContext); } DecMPA_Callbacks; /**This structure provides information extracted from an MPEG Audio header.*/ typedef struct { /**The original header data.*/ unsigned char aRawData[4]; /**Protection*/ int bProtection; /**Layer*/ int nLayer; /**Version*/ int nVersion; /**Padding*/ int bPadding; /**Frequency index*/ int nFrequencyIndex; /**Frequency in Hz*/ int nFrequency; /**Bitrate index*/ int nBitRateIndex; /**Extended mode*/ int nExtendedMode; /**Mode*/ int nMode; /**Input stereo*/ int bInputStereo; /**MPEG 2.5*/ int bMPEG25; /**Frame size in bytes*/ int nFrameSize; /**Number of decoded samples per frame. If the data is stereo, a sample consists of one value for the left channel and one for the right.*/ int nDecodedSamplesPerFrame; /**Bitrate in Kbps.*/ int nBitRateKbps; } DecMPA_MPEGHeader; /**DecMPA_OutputFormat objects are used to specify the format of the decoded audio data that is returned by DecMPA_Decode.*/ typedef struct { /**Specifies the type of the data. Can be either DECMPA_OUTPUT_INT16 or DECMPA_OUTPUT_FLOAT*/ int nType; /**Specifies the frequency of the data.*/ int nFrequency; /**Specifies the number of channels. Can be 1 for mono or 2 for stereo.*/ int nChannels; } DecMPA_OutputFormat; /*@}*/ /**\addtogroup GroupResults*/ /*@{*/ /**The operation has been successfully completed.*/ #define DECMPA_OK 0 /**The end of the stream was reached and there is no more data to decode.*/ #define DECMPA_END 1 /**An invalid parameter was passed to a function.*/ #define DECMPA_ERROR_PARAM (-1) /**The operation is not supported.*/ #define DECMPA_ERROR_UNSUPPORTED (-2) /**There is not enough free memory.*/ #define DECMPA_ERROR_MEMORY (-3) /**An internal error occurred in the decoding routines.*/ #define DECMPA_ERROR_INTERNAL (-4) /**Indicates an error during decoding, which usually means that the input data is invalid or corrupted.*/ #define DECMPA_ERROR_DECODE (-5) /**An error occurred during the reading of new data.*/ #define DECMPA_ERROR_READ (-6) /**An error occurred when it was tried to seek to a different position in the data stream.*/ #define DECMPA_ERROR_SEEK (-7) /**An error occurred when opening a file.*/ #define DECMPA_ERROR_OPENFILE (-8) /**The decoder is in the wrong state to perform the specified function.*/ #define DECMPA_ERROR_WRONGSTATE (-9) /**The requested resource is not available*/ #define DECMPA_ERROR_NOTAVAILABLE (-10) /**The version of the DecMPA library that is used is incompatible:*/ #define DECMPA_ERROR_INCOMPATIBLEVERSION (-11) /*@}*/ /**\addtogroup GroupParamIDs*/ /*@{*/ /**Specifies the format DecMPA will use to output the decoded audio samples. Can be either #DECMPA_OUTPUT_INT16 or #DECMPA_OUTPUT_FLOAT. Default value: #DECMPA_OUTPUT_INT16.*/ #define DECMPA_PARAM_OUTPUT 0 /**Specifies wether the decoder should load a leading ID3v2 tag and make it available through #DecMPA_GetID3v2Data. Can be either #DECMPA_YES or #DECMPA_NO. Default value: #DECMPA_NO.*/ #define DECMPA_PARAM_PROVIDEID3V2 1 /*@}*/ /**Constant indicating the number of definable parameters.*/ #define DECMPA_PARAMCOUNT 2 /**\addtogroup GroupParamValues*/ /*@{*/ /**\defgroup GroupParamGeneric Generic values*/ /*@{*/ /**Indicates that the specified function is activated.*/ #define DECMPA_YES 1 /**Indicates that the specified function is not activated.*/ #define DECMPA_NO 0 /*@}*/ /**\defgroup GroupParamOutput DECMPA_PARAM_OUTPUT values*/ /*@{*/ /**Indicates that the audio samples are signed 16 bit integers (one per channel). -32768 is the minimum and 32767 is the maximum value. \note As of version 0.3.0 DecMPA uses integers internally. That means that #DECMPA_OUTPUT_INT16 is a little faster than #DECMPA_OUTPUT_FLOAT because the latter requires an additional conversion.*/ #define DECMPA_OUTPUT_INT16 0 /**Indicates that the audio samples are floats (one per channel). -1.0 is the minimum and 1.0 is the maximum value. \note As of version 0.3.0 DecMPA uses integers internally. That means that #DECMPA_OUTPUT_INT16 is a little faster than #DECMPA_OUTPUT_FLOAT because the latter requires an additional conversion.*/ #define DECMPA_OUTPUT_FLOAT 1 /*@}*/ /*@}*/ /**\addtogroup GroupFunctions*/ /*@{*/ /**Creates a new decoder that obtains its input data from a file. If you want to provide the input data in some other customized way, use #DecMPA_CreateUsingCallbacks instead. After the decoder is created, additional parameters can be configured with #DecMPA_SetParam. @param ppDecoder pointer to a void* variable that receives the address of the decoder object. @param sFilePath path of the file to open @param APIVersion version number of the DecMPA API. You should always pass the constant #DECMPA_VERSION for this parameter. @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_CreateUsingFile(void** ppDecoder,const char* sFilePath,int APIVersion); /**Creates a new decoder that obtains its input data using callback functions. After the decoder is created, additional parameters can be configured with #DecMPA_SetParam. @param ppDecoder pointer to a void* variable that receives the address of the decoder object. @param pCallbacks structure containing pointers to the callback functions that are used to retrieve the MPEG Audio data. @param pCallbackContext a pointer that is simply passed to the callback functions. It has no meaning to the decoder and is only meant to be used to pass arbitrary data to the callback functions. @param APIVersion version number of the DecMPA API. You should always pass the constant #DECMPA_VERSION for this parameter. @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_CreateUsingCallbacks(void** ppDecoder,const DecMPA_Callbacks* pCallbacks,void* pCallbackContext,int APIVersion); /**Sets additional DecMPA parameters. Calling this function is completely optional - if you don't call it or only call it for some parameters, the remaining parameters will simply keep their default values. This function should only be called directly after the decoder was created, before calling any of the other functions. Otherwise DecMPA_SetParam may return #DECMPA_ERROR_WRONGSTATE. @param pDecoder the decoder object @param ID ID of the parameter to set. See \ref GroupParamIDs. @param Value the new value for the specified parameter. Which values are possible depends of the parameter. @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_SetParam(void* pDecoder,int ID,long Value); /**Returns the current value of a DecMPA parameter. @param pDecoder the decoder object @param ID ID of the parameter. See \ref GroupParamIDs. @return the current value of the specified parameter. @see #DecMPA_SetParam */ long DECMPA_CC DecMPA_GetParam(void* pDecoder,int ID); /**Decodes some data and stores it in the supplied buffer. The buffer is not necessarily completely filled. Always check the value stored in pBytesDecoded to find out how much data has been decoded. The format of the data (frequency and number of channels) can be obtained by calling #DecMPA_GetOutputFormat after DecMPA_Decode. The format may change from one call of DecMPA_Decode to the next. Wether the format has changed can be checked using #DecMPA_OutputFormatChanged. @param pDecoder the decoder object @param pBuffer pointer to a buffer that receives the decoded data. @param nBufferBytes size of the buffer, in bytes @param pBytesDecoded pointer to a variable that receives the number of bytes that were stored in the buffer. @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_Decode(void* pDecoder,void* pBuffer,long nBufferBytes,long* pBytesDecoded); /**This is a special version of #DecMPA_Decode that does not actually decode any MPEG Audio data, but only decodes the header information. This function is a lot faster than #DecMPA_Decode and can be used to make a quick run through the file and obtain accurate information about its properties, like the exact duration or decoded file size. The function behaves in all ways like #DecMPA_Decode, except that it does not return any data. In particular, the output format and mpeg audio header information returned by #DecMPA_GetOutputFormat and #DecMPA_GetMPEGHeader will be properly updated, just as #DecMPA_Decode does. @param pDecoder the decoder object @param pDecodedBytes pointer to a variable that receives the decoded size (in bytes) of the current MPEG audio frame. If #DecMPA_Decode was called before and some parts of the current frame have already been read, the size of the remaining data is returned @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_DecodeNoData(void* pDecoder,long* pDecodedBytes); /**Changes the decoding position to the specified time, relative to the beginning of the data stream. If #DecMPA_CreateUsingCallbacks was used to create the decoder and no Seek callback function has been specified, seeking is not supported and #DECMPA_ERROR_UNSUPPORTED is returned. @param pDecoder the decoder object @param Millis the target time, in milliseconds @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_SeekToTime(void* pDecoder,long Millis); /**Retrieves the current decoding time. The decoding time corresponds to the time that it takes to play the data that has been decoded up to now. @param pDecoder the decoder object @param pTime pointer to a variable that receives the time, in milliseconds. @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_GetTime(void* pDecoder,long* pTime); /**Retrieves the time that it takes to play back the whole data stream. If the duration is not known -1 is returned. \note The duration is an estimation that can be slightly wrong for some files but is pretty accurate for the wide majority of files. If you need a 100% accurate duration value, there is really no other way than to read through the whole file with #DecMPA_Decode or #DecMPA_DecodeNoData and add up the \c DecodedBytes values that are returned by those functions. Note that if you only make this pass through the file to get the duration, i.e. you do not need decoded audio data, you can use #DecMPA_DecodeNoData which is a lot faster than #DecMPA_Decode. @param pDecoder the decoder object @param pDuration pointer to a variable that receives the duration, in milliseconds. @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_GetDuration(void* pDecoder,long* pDuration); /**Retrieves the format of the data that was returned by the last call to DecMPA_Decode. The nType member of DecMPA_OutputFormat never changes and its value is defined by the #DECMPA_PARAM_OUTPUT parameter that can be set using #DecMPA_SetParam. If the value has not been explicitly changed using #DecMPA_SetParam it will be #DECMPA_OUTPUT_INT16, indicating 16 bit signed samples. The remaining fields of the structure may change after calls to #DecMPA_Decode or #DecMPA_DecodeNoData. @param pDecoder the decoder object @param pFormat pointer to a DecMPA_OutputFormat object that is filled with the format data @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_GetOutputFormat(void* pDecoder,DecMPA_OutputFormat* pFormat); /**Checks wether the output format has changed during the last call to DecMPA_Decode. @return nonzero if the format has changed, zero otherwise.*/ int DECMPA_CC DecMPA_OutputFormatChanged(void* pDecoder); /**Retrieve mpeg header of the data that was returned by the last call to DecMPA_Decode. This function is only supplied for information purposes. @param pDecoder the decoder object @param pHeader pointer to a DecMPA_MPEGHeader object that received the data. @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_GetMPEGHeader(void* pDecoder,DecMPA_MPEGHeader* pHeader); /**Returns the file's ID3v2 tag, if it has one. If the file has no ID3v2 tag, #DECMPA_ERROR_NOTAVAILABLE is returned. This function will always return #DECMPA_ERROR_NOTAVAILABLE if the decoder parameter #DECMPA_PARAM_PROVIDEID3V2 has not been set to #DECMPA_YES with #DecMPA_SetParam. \note There are other libraries that can be used to parse the returned data, one of them being id3lib. It can be found at http://id3lib.sourceforge.net/ . @param pDecoder the decoder object @param ppData pointer to a pointer variable that will receive the address of the ID3v2 data. The memory that contains the data will remain valid until the decoder is destroyed. @param pDataSize pointer to a variable that will receive the size of the ID3v2 data, in bytes. @return a DecMPA result code (see \ref GroupResults).*/ int DECMPA_CC DecMPA_GetID3v2Data(void* pDecoder,unsigned char** ppData,long* pDataSize); /**Destroys a decoder. @param pDecoder decoder object.*/ void DECMPA_CC DecMPA_Destroy(void* pDecoder); /**Returns the version number of the DecMPA API used by the library.*/ int DECMPA_CC DecMPA_GetVersion(void); /*@}*/ #endif