mpg123 version 1.13.0 头文件inc定义

;
;◎ ◎ mpg123.h->mpg123.inc  use to asm By G-Spider @2011
;
; Begin of file mpg123.h
;
;  libmpg123:MPEG Audio Decoder library (version 1.13.0)
;
;  copyright 1995-2010 by the mpg123 project - free software under the terms of the LGPL 2.1
;  see COPYING and AUTHORS files in distribution or http://mpg123.org
;
; * file mpg123.h The header file for the libmpg123 MPEG Audio decoder
;  A macro to check at compile time which set of API functions to expect.
;    This should be incremented at least each time a new symbol is added to the header.
MPG123_API_VERSION EQU 29
;
; * Function to initialise the mpg123 library.
;  * This function is not thread-safe. Call it exactly once per process,before any other (possibly threaded) work with the library.
;  *
;  * return MPG123_OK if successful,otherwise an error number.
;  
mpg123_init  PROTO C

; * Function to close down the mpg123 library.
;  * This function is not thread-safe. Call it exactly once per process,before any other (possibly threaded) work with the library.

mpg123_exit  PROTO C

; * Create a handle with optional choice of decoder (named by a string,see mpg123_decoders() or mpg123_supported_decoders()).
;  *  and optional retrieval of an error code to feed to mpg123_plain_strerror().
;  *  Optional means:Any of or both the parameters may be NULL.
;  *
;  *  return Non-NULL pointer when successful.
;   
mpg123_new  PROTO C  :DWORD,:DWORD

; * Delete handle,mh is either a valid mpg123 handle or NULL.

mpg123_delete         PROTO C  :DWORD 

; * Enumeration of the parameters types that it is possible to set/get.
MPG123_VERBOSE  EQU 0; *< set verbosity value for enabling messages to stderr,>= 0 makes sense (integer)
MPG123_FLAGS  EQU 1; *< set all flags,p.ex val = MPG123_GAPLESS|MPG123_MONO_MIX (integer)
MPG123_ADD_FLAGS EQU 2; *< add some flags (integer)
MPG123_FORCE_RATE EQU 3; *< when value > 0,force output rate to that value (integer)
MPG123_DOWN_SAMPLE EQU 4; *< 0=native rate,1=half rate,2=quarter rate (integer)
MPG123_RVA  EQU 5; *< one of the RVA choices above (integer)
MPG123_DOWNSPEED EQU 6; *< play a frame N times (integer)
MPG123_UPSPEED  EQU 7; *< play every Nth frame (integer)
MPG123_START_FRAME EQU 8; *< start with this frame (skip frames before that,integer)
MPG123_DECODE_FRAMES EQU 9; *< decode only this number of frames (integer)
MPG123_ICY_INTERVAL EQU 10; *< stream contains ICY metadata with this interval (integer)
MPG123_OUTSCALE  EQU 11; *< the scale for output samples (amplitude - integer or float according to mpg123 output format,normally integer)
MPG123_TIMEOUT  EQU 12; *< timeout for reading from a stream (not supported on win32,integer)
MPG123_REMOVE_FLAGS EQU 13; *< remove some flags (inverse of MPG123_ADD_FLAGS,integer)
MPG123_RESYNC_LIMIT EQU 14; *< Try resync on frame parsing for that many bytes or until end of stream (<0 ... integer).
MPG123_INDEX_SIZE EQU 15; *< Set the frame index size (if supported). Values <0 mean that the index is allowed to grow dynamically in these steps (in positive direction,of course)
MPG123_PREFRAMES EQU 16; *< Decode/ignore that many frames in advance for layer 3.

; * Flag bits for MPG123_FLAGS,use the usual binary or to combine.
MPG123_FORCE_MONO EQU 7   ; *<0111 Force some mono mode:This is a test bitmask for seeing if any mono forcing is active.
MPG123_MONO_LEFT EQU 1   ; *<0001 Force playback of left channel only. 
MPG123_MONO_RIGHT EQU 2   ; *<0010 Force playback of right channel only.
MPG123_MONO_MIX  EQU 4   ; *<0100 Force playback of mixed mono.
MPG123_FORCE_STEREO EQU 8   ; *<1000 Force stereo output. 
MPG123_FORCE_8BIT EQU 16  ; *<00010000 Force 8bit formats.   
MPG123_QUIET  EQU 32  ; *<00100000 Suppress any printouts (overrules verbose).
MPG123_GAPLESS  EQU 64  ; *<01000000 Enable gapless decoding (default on if libmpg123 has support).                          
MPG123_NO_RESYNC EQU 128 ; *<10000000 Disable resync stream after error.
MPG123_SEEKBUFFER EQU 256 ; *<000100000000 Enable small buffer on non-seekable streams to allow some peek-ahead (for better MPEG sync).
MPG123_FUZZY  EQU 512 ; *<001000000000 Enable fuzzy seeks (guessing byte offsets or using approximate seek points from Xing TOC)
MPG123_FORCE_FLOAT EQU 1024; *<010000000000 Force floating point output (32 or 64 bits depends on mpg123 internal precision).
MPG123_PLAIN_ID3TEXT EQU 2048; *<100000000000 Do not translate ID3 text data to UTF-8. ID3 strings will contain the raw text data,with the first byte containing the ID3 encoding code.
MPG123_IGNORE_STREAMLENGTH EQU 4096; *<1000000000000 Ignore any stream length information contained in the stream,which can be contained in a 'TLEN' frame of an ID3v2 tag or a Xing tag
MPG123_SKIP_ID3V2 EQU 8192t;*<10000000000000 Do not parse ID3v2 tags,just skip them.

; * choices for MPG123_RVA  
MPG123_RVA_OFF  EQU 0; *< RVA disabled (default).
MPG123_RVA_MIX  EQU 1; *< Use mix/track/radio gain.
MPG123_RVA_ALBUM EQU 2; *< Use album/audiophile gain
MPG123_RVA_MAX  EQU 2; *< The maximum RVA code,may increase in future.

;  TODO:Assess the possibilities and troubles of changing parameters during playback.
; * Set a specific parameter,for a specific DWORD,using a parameter
;  *  type key chosen from the mpg123_parms enumeration,to the specified value.
mpg123_param    PROTO C  :DWORD,:DWORD,:DWORD,:REAL8

; * Get a specific parameter,for a specific DWORD.
;  *  See the mpg123_parms enumeration for a list of available parameters.
mpg123_getparam PROTO C  :DWORD,:DWORD,:DWORD,:DWORD

; * Feature set available for query with mpg123_feature.
MPG123_FEATURE_ABI_UTF8OPEN EQU 0; *< mpg123 expects path names to be given in UTF-8 encoding instead of plain native.
MPG123_FEATURE_OUTPUT_8BIT EQU 1; *< 8bit output  
MPG123_FEATURE_OUTPUT_16BIT EQU 2; *< 16bit output 
MPG123_FEATURE_OUTPUT_32BIT EQU 3; *< 32bit output 
MPG123_FEATURE_INDEX  EQU 4; *< support for building a frame index for accurate seeking
MPG123_FEATURE_PARSE_ID3V2 EQU 5; *< id3v2 parsing
MPG123_FEATURE_DECODE_LAYER1 EQU 6; *< mpeg layer-1 decoder enabled
MPG123_FEATURE_DECODE_LAYER2 EQU 7; *< mpeg layer-2 decoder enabled
MPG123_FEATURE_DECODE_LAYER3 EQU 8; *< mpeg layer-3 decoder enabled
MPG123_FEATURE_DECODE_ACCURATE EQU 9; *< accurate decoder rounding  
MPG123_FEATURE_DECODE_DOWNSAMPLE EQU    10; *< downsample (sample omit)    
MPG123_FEATURE_DECODE_NTOM EQU 11; *< flexible rate decoding      
MPG123_FEATURE_PARSE_ICY EQU 12; *< ICY support                 
MPG123_FEATURE_TIMEOUT_READ EQU 13; *< Reader with timeout (network).

; * Query libmpg123 feature,1 for success,0 for unimplemented functions.
mpg123_feature PROTO C :DWORD
 
; * defgroup mpg123_error mpg123 error handling
;  *
;  * Functions to get text version of the error numbers and an enumeration
;  * of the error codes returned by libmpg123.
;  *
;  * Most functions operating on a DWORD simply return MPG123_OK on success and MPG123_ERR on failure (setting the internal error variable of the handle to the specific error code).
;  * Decoding/seek functions may also return message codes MPG123_DONE,MPG123_NEW_FORMAT and MPG123_NEED_MORE (please read up on these on how to react!).
;  * The positive range of return values is used for "useful" values when appropriate.
;  *
; 
; * Enumeration of the message and error codes and returned by libmpg123 functions.
MPG123_DONE         EQU -12; *< Message:Track ended. Stop decoding.
MPG123_NEW_FORMAT EQU -11; *< Message:Output format will be different on next call.
MPG123_NEED_MORE EQU -10; *< Message:For feed reader:"Feed me more!" (call mpg123_feed() or mpg123_decode() with some new input data).
MPG123_ERR  EQU -1; *< Generic Error
MPG123_OK  EQU 0; *< Success
MPG123_BAD_OUTFORMAT EQU 1; *< Unable to set up output format!
MPG123_BAD_CHANNEL EQU 2; *< Invalid channel number specified.
MPG123_BAD_RATE  EQU 3; *< Invalid sample rate specified. 
MPG123_ERR_16TO8TABLE EQU 4; *< Unable to allocate memory for 16 to 8 converter table!
MPG123_BAD_PARAM EQU 5; *< Bad parameter id!
MPG123_BAD_BUFFER EQU 6; *< Bad buffer given -- invalid pointer or too small size.
MPG123_OUT_OF_MEM EQU 7; *< Out of memory -- some malloc() failed.
MPG123_NOT_INITIALIZED EQU 8; *< You didn't initialize the library!
MPG123_BAD_DECODER EQU 9; *< Invalid decoder choice.
MPG123_BAD_HANDLE EQU 10; *< Invalid mpg123 handle.
MPG123_NO_BUFFERS EQU 11; *< Unable to initialize frame buffers (out of memory?).
MPG123_BAD_RVA  EQU 12; *< Invalid RVA mode.
MPG123_NO_GAPLESS EQU 13; *< This build doesn't support gapless decoding.
MPG123_NO_SPACE  EQU 14; *< Not enough buffer space.
MPG123_BAD_TYPES EQU 15; *< Incompatible numeric data types.
MPG123_BAD_BAND  EQU 16; *< Bad equalizer band.
MPG123_ERR_NULL  EQU 17; *< Null pointer given where valid storage address needed.
MPG123_ERR_READER EQU 18; *< Error reading the stream.
MPG123_NO_SEEK_FROM_END EQU 19; *< Cannot seek from end (end is not known).
MPG123_BAD_WHENCE EQU 20; *< Invalid 'whence' for seek function.
MPG123_NO_TIMEOUT EQU 21; *< Build does not support stream timeouts.
MPG123_BAD_FILE  EQU 22; *< File access error.
MPG123_NO_SEEK  EQU 23; *< Seek not supported by stream.
MPG123_NO_READER EQU 24; *< No stream opened.
MPG123_BAD_PARS  EQU 25; *< Bad parameter handle.
MPG123_BAD_INDEX_PAR EQU 26; *< Bad parameters to mpg123_index() and mpg123_set_index()
MPG123_OUT_OF_SYNC EQU 27; *< Lost track in bytestream and did not try to resync.
MPG123_RESYNC_FAIL EQU 28; *< Resync failed to find valid MPEG data.
MPG123_NO_8BIT  EQU 29; *< No 8bit encoding possible.
MPG123_BAD_ALIGN EQU 30; *< Stack aligmnent error
MPG123_NULL_BUFFER EQU 31; *< NULL input buffer with non-zero size...
MPG123_NO_RELSEEK EQU 32; *< Relative seek not possible (screwed up file offset)
MPG123_NULL_POINTER EQU 33; *< You gave a null pointer somewhere where you shouldn't have.
MPG123_BAD_KEY  EQU 34; *< Bad key value given.
MPG123_NO_INDEX  EQU 35; *< No frame index in this build.
MPG123_INDEX_FAIL EQU 36; *< Something with frame index went wrong.
MPG123_BAD_DECODER_SETUP EQU 37; *< Something prevents a proper decoder setup
MPG123_MISSING_FEATURE EQU 38; *< This feature has not been built into libmpg123.
MPG123_BAD_VALUE EQU 39; *< A bad value has been given,somewhere.
MPG123_LSEEK_FAILED EQU 40; *< Low-level seek failed.
MPG123_BAD_CUSTOM_IO EQU 41; *< Custom I/O not prepared.
MPG123_LFS_OVERFLOW EQU 42; *< Offset value overflow during translation of large file API calls -- your client program cannot handle that large file.

; * Return a string describing that error errcode means.
mpg123_plain_strerror PROTO C :DWORD

; * Give string describing what error has occured in the context of handle mh.
;  *  When a function operating on an mpg123 handle returns MPG123_ERR,you should check for the actual reason via
;  *  char *errmsg = mpg123_strerror(mh)
;  *  This function will catch mh == NULL and return the message for MPG123_BAD_HANDLE.
mpg123_strerror  PROTO C :DWORD

; * Return the plain errcode intead of a string.  
mpg123_errcode  PROTO C :DWORD

; * defgroup mpg123_decoder mpg123 decoder selection
;  *
;  * Functions to list and select the available decoders.
;  * Perhaps the most prominent feature of mpg123:You have several (optimized) decoders to choose from (on x86 and PPC (MacOS) systems,that is).
;  *
; 
; * Return a NULL-terminated array of generally available decoder names (plain 8bit ASCII).
mpg123_decoders  PROTO C

; * Return a NULL-terminated array of the decoders supported by the CPU (plain 8bit ASCII).
mpg123_supported_decoders PROTO C

; * Set the chosen decoder to 'decoder_name'
mpg123_decoder  PROTO C :DWORD,:DWORD

; * Get the currently active decoder engine name.
;     The active decoder engine can vary depening on output constraints,
;     mostly non-resampling,integer output is accelerated via 3DNow & Co. but for other modes a fallback engine kicks in.
;     Note that this can return a decoder that is ony active in the hidden and not available as decoder choice from the outside.
;     return The decoder name or NULL on error.
mpg123_current_decoder PROTO C :DWORD

; * defgroup mpg123_output mpg123 output audio format
;  *
;  * Functions to get and select the format of the decoded audio.
;  *
; 
; * An enum over all sample types possibly known to mpg123.
;  *  The values are designed as bit flags to allow bitmasking for encoding families.
;  *
;  *  Note that (your build of) libmpg123 does not necessarily support all these.
;  *  Usually,you can expect the 8bit encodings and signed 16 bit.
;  *  Also 32bit float will be usual beginning with mpg123-1.7.0 .
;  *  What you should bear in mind is that (SSE,etc) optimized routines may be absent
;  *  for some formats. We do have SSE for 16,32 bit and float,though.
;  *  24 bit integer is done via postprocessing of 32 bit output -- just cutting
;  *  the last byte,no rounding,even. If you want better,do it yourself.
;  *
;  *  All formats are in native byte order. If you need different endinaness,you
;  *  can simply postprocess the output buffers (libmpg123 wouldn't do anything else).
;  *  mpg123_encsize() can be helpful there.
; 
MPG123_ENC_8         EQU 15      ; *<      0000 0000 1111 Some 8 bit  integer encoding.
MPG123_ENC_16         EQU 64      ; *<      0000 0100 0000 Some 16 bit integer encoding.
MPG123_ENC_24         EQU 16384   ; *< 0100 0000 0000 0000 Some 24 bit integer encoding.
MPG123_ENC_32         EQU 256     ; *<      0001 0000 0000 Some 32 bit integer encoding.
MPG123_ENC_SIGNED EQU 128     ; *<      0000 1000 0000 Some signed integer encoding.
MPG123_ENC_FLOAT EQU 3584    ; *<      1110 0000 0000 Some float encoding.
MPG123_ENC_SIGNED_16 EQU 208     ; *<           1101 0000 signed 16 bit
MPG123_ENC_UNSIGNED_16 EQU 96      ; *<           0110 0000 unsigned 16 bit
MPG123_ENC_UNSIGNED_8 EQU 1       ; *<           0000 0001 unsigned 8 bit
MPG123_ENC_SIGNED_8 EQU 130     ; *<           1000 0010 signed 8 bit
MPG123_ENC_ULAW_8 EQU 4       ; *<           0000 0100 ulaw 8 bit
MPG123_ENC_ALAW_8 EQU 8       ; *<           0000 1000 alaw 8 bit
MPG123_ENC_SIGNED_32 EQU 4480    ; *< 0001 0001 1000 0000 signed 32 bit
MPG123_ENC_UNSIGNED_32 EQU 8448    ; *< 0010 0001 0000 0000 unsigned 32 bit
MPG123_ENC_SIGNED_24 EQU 20608   ; *< 0101 0000 1000 0000 signed 24 bit
MPG123_ENC_UNSIGNED_24 EQU 24576   ; *< 0110 0000 0000 0000 unsigned 24 bit
MPG123_ENC_FLOAT_32 EQU 512     ; *<      0010 0000 0000 32bit float
MPG123_ENC_FLOAT_64 EQU 1024    ; *<      0100 0000 0000 64bit float
MPG123_ENC_ANY  EQU 30719   ; *< Any encoding on the list.

; * They can be combined into one number (3) to indicate mono and stereo...
;//enum mpg123_channelcount
MPG123_MONO  EQU 1
MPG123_STEREO  EQU 2

; * An array of supported standard sample rates
;  *  These are possible native sample rates of MPEG audio files.
;  *  You can still force mpg123 to resample to a different one,but by default you will only get audio in one of these samplings.
;  *  param list Store a pointer to the sample rates array there.
;  *  param number Store the number of sample rates there.
mpg123_rates  PROTO C : DWORD,:DWORD

; * An array of supported audio encodings.
;  *  An audio encoding is one of the fully qualified members of mpg123_enc_enum (MPG123_ENC_SIGNED_16,not MPG123_SIGNED).
;  *  param list Store a pointer to the encodings array there.
;  *  param number Store the number of encodings there.
mpg123_encodings PROTO C : DWORD,:DWORD

; * Return the size (in bytes) of one mono sample of the named encoding.
;  * param encoding The encoding value to analyze.
;  * return positive size of encoding in bytes,0 on invalid encoding. 
mpg123_encsize  PROTO C :DWORD

; * Configure a mpg123 handle to accept no output format at all,
;  *  use before specifying supported formats with mpg123_format
mpg123_format_none PROTO C :DWORD

; * Configure mpg123 handle to accept all formats
;  *  (also any custom rate you may set) -- this is default.
mpg123_format_all PROTO C :DWORD

; * Set the audio format support of a DWORD in detail:
;  *  param mh audio decoder handle
;  *  param rate The sample rate value (in Hertz).
;  *  param channels A combination of MPG123_STEREO and MPG123_MONO.
;  *  param encodings A combination of accepted encodings for rate and channels,p.ex MPG123_ENC_SIGNED16 | MPG123_ENC_ULAW_8 (or 0 for no support).
;  *  Please note that some encodings may not be supported in the library build and thus will be ignored here.
;  *  return MPG123_OK on success,MPG123_ERR if there was an error.
mpg123_format  PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * Check to see if a specific format at a specific rate is supported
;  *  by DWORD.
;  *  return 0 for no support (that includes invalid parameters),MPG123_STEREO,
;  *          MPG123_MONO or MPG123_STEREO|MPG123_MONO.
mpg123_format_support PROTO C :DWORD,:DWORD,:DWORD

; * Get the current output format written to the addresses givenr.
mpg123_getformat PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * defgroup mpg123_input mpg123 file input and decoding
;  *
;  * Functions for input bitstream and decoding operations.
;  * Decoding/seek functions may also return message codes MPG123_DONE,MPG123_NEW_FORMAT and MPG123_NEED_MORE (please read up on these on how to react!).
; 
;  reading samples / triggering decoding,possible return values:
; * Enumeration of the error codes returned by libmpg123 functions.
; * Open and prepare to decode the specified file by filesystem path.
;  *  This does not open HTTP urls; libmpg123 contains no networking code.
;  *  If you want to decode internet streams,use mpg123_open_fd() or mpg123_open_feed().
;   
mpg123_open  PROTO C  :DWORD,:DWORD

; * Use an already opened file descriptor as the bitstream input
;  *  mpg123_close() will _not_ close the file descriptor.
; 
mpg123_open_fd  PROTO C  

; * Use an opaque handle as bitstream input. This works only with the
;  *  replaced I/O from mpg123_replace_reader_handle()!
;  *  mpg123_close() will call the cleanup callback for your handle (if you gave one).
; 
mpg123_open_handle PROTO C :DWORD,:DWORD

; * Open a new bitstream and prepare for direct feeding
;  *  This works together with mpg123_decode(); you are responsible for reading and feeding the input bitstream.
; 
mpg123_open_feed PROTO C :DWORD

; * Closes the source,if libmpg123 opened it.
mpg123_close  PROTO C :DWORD

; * Read from stream and decode up to outmemsize bytes.
;  *  param outmemory address of output buffer to write to
;  *  param outmemsize maximum number of bytes to write
;  *  param done address to store the number of actually decoded bytes to
;  *  return error/message code (watch out for MPG123_DONE and friends!)
mpg123_read  PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * Feed data for a stream that has been opened with mpg123_open_feed().
;  *  It's give and take:You provide the bytestream,mpg123 gives you the decoded samples.
;  *  param in input buffer
;  *  param size number of input bytes
;  *  return error/message code.
mpg123_feed  PROTO C :DWORD,:DWORD,:DWORD

; * Decode MPEG Audio from inmemory to outmemory.
;  *  This is very close to a drop-in replacement for old mpglib.
;  *  When you give zero-sized output buffer the input will be parsed until
;  *  decoded data is available. This enables you to get MPG123_NEW_FORMAT (and query it)
;  *  without taking decoded data.
;  *  Think of this function being the union of mpg123_read() and mpg123_feed() (which it actually is,sort of;-).
;  *  You can actually always decide if you want those specialized functions in separate steps or one call this one here.
;  *  param inmemory input buffer
;  *  param inmemsize number of input bytes
;  *  param outmemory output buffer
;  *  param outmemsize maximum number of output bytes
;  *  param done address to store the number of actually decoded bytes to
;  *  return error/message code (watch out especially for MPG123_NEED_MORE)
; 
mpg123_decode  PROTO C :DWORD,:DWORD,:DWORD,:DWORD,:DWORD,:DWORD

; * Decode next MPEG frame to internal buffer
;  *  or read a frame and return after setting a new format.
;  *  param num current frame offset gets stored there
;  *  param audio This pointer is set to the internal buffer to read the decoded audio from.
;  *  param bytes number of output bytes ready in the buffer
; 
mpg123_decode_frame PROTO C :DWORD,:DWORD,: DWORD,:DWORD

; * Decode current MPEG frame to internal buffer.
;  * Warning:This is experimental API that might change in future releases!
;  * Please watch mpg123 development closely when using it.
;  *  param num last frame offset gets stored there
;  *  param audio this pointer is set to the internal buffer to read the decoded audio from.
;  *  param bytes number of output bytes ready in the buffer
; 
mpg123_framebyframe_decode PROTO C :DWORD,:DWORD,: DWORD,:DWORD

; * Find,read and parse the next mp3 frame
;  * Warning:This is experimental API that might change in future releases!
;  * Please watch mpg123 development closely when using it.
; 
mpg123_framebyframe_next PROTO C :DWORD

; * defgroup mpg123_seek mpg123 position and seeking
;  *
;  * Functions querying and manipulating position in the decoded audio bitstream.
;  * The position is measured in decoded audio samples,or MPEG frame offset for the specific functions.
;  * If gapless code is in effect,the positions are adjusted to compensate the skipped padding/delay
;    - meaning,you should not care about that at all and just use the position defined for the samples you get out of the decoder;-)
;  * The general usage is modelled after stdlib's ftell() and fseek().
;  * Especially,the whence parameter for the seek functions has the same meaning as the one for fseek() and needs the same constants from stdlib.h:
;  * - SEEK_SET:set position to (or near to) specified offset
;  * - SEEK_CUR:change position by offset from now
;  * - SEEK_END:set position to offset from end
;  *
;  * Note that sample-accurate seek only works when gapless support has been enabled at compile time; seek is frame-accurate otherwise.
;  * Also,really sample-accurate seeking (meaning that you get the identical sample value after seeking compared to plain decoding up to the position)
;  * is only guaranteed when you do not mess with the position code by using MPG123_UPSPEED,MPG123_DOWNSPEED or MPG123_START_FRAME.
;  * The first two mainly should cause trouble with NtoM resampling,but in any case with these options in effect,
;  * you have to keep in mind that the sample offset is not the same as counting the samples you get from decoding since mpg123 counts the skipped samples,
;  * too (or the samples played twice only once)!
;  * Short:When you care about the sample position,don't mess with those parameters;-)
;  * Also,seeking is not guaranteed to work for all streams (underlying stream may not support it).
;  *
; 
; * Returns the current position in samples.
;  *  On the next read,you'd get that sample.
mpg123_tell  PROTO C :DWORD

; * Returns the frame number that the next read will give you data from.
mpg123_tellframe PROTO C :DWORD

; * Returns the current byte offset in the input stream.
mpg123_tell_stream PROTO C :DWORD

; * Seek to a desired sample offset.
;  *  Set whence to SEEK_SET,SEEK_CUR or SEEK_END.
;  *  return The resulting offset >= 0 or error/message code
mpg123_seek  PROTO C :DWORD,:DWORD,:DWORD

; * Seek to a desired sample offset in data feeding mode.
;  *  This just prepares things to be right only if you ensure that the next chunk of input data will be from input_offset byte position.
;  *  param input_offset The position it expects to be at the
;  *                      next time data is fed to mpg123_decode().
;  *  return The resulting offset >= 0 or error/message code
mpg123_feedseek  PROTO C  :DWORD,:DWORD,:DWORD,:DWORD

; * Seek to a desired MPEG frame index.
;  *  Set whence to SEEK_SET,SEEK_CUR or SEEK_END.
;  *  return The resulting offset >= 0 or error/message code
mpg123_seek_frame PROTO C :DWORD,:DWORD,:DWORD

; * Return a MPEG frame offset corresponding to an offset in seconds.
;  *  This assumes that the samples per frame do not change in the file/stream,which is a good assumption for any sane file/stream only.
;  *  return frame offset >= 0 or error/message code
mpg123_timeframe PROTO C :DWORD,:REAL8
; * Give access to the frame index table that is managed for seeking.
;  *  You are asked not to modify the values... Use mpg123_set_index to set the
;  *  seek index
;  *  param offsets pointer to the index array
;  *  param step one index byte offset advances this many MPEG frames
;  *  param fill number of recorded index offsets; size of the array
mpg123_index  PROTO C :DWORD,: DWORD,:DWORD,:DWORD

; * Set the frame index table
;  *  Setting offsets to NULL and fill > 0 will allocate fill entries. Setting offsets
;  *  to NULL and fill to 0 will clear the index and free the allocated memory used by the index.
;  *  param offsets pointer to the index array
;  *  param step    one index byte offset advances this many MPEG frames
;  *  param fill    number of recorded index offsets; size of the array
mpg123_set_index PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * Get information about current and remaining frames/seconds.
;  *  WARNING:This function is there because of special usage by standalone mpg123 and may be removed in the final version of libmpg123!
;  *  You provide an offset (in frames) from now and a number of output bytes
;  *  served by libmpg123 but not yet played. You get the projected current frame
;  *  and seconds,as well as the remaining frames/seconds. This does _not_ care
;  *  about skipped samples due to gapless playback.
mpg123_position  PROTO C :DWORD,:DWORD,:DWORD,:DWORD,:DWORD,:DWORD,:DWORD

; * defgroup mpg123_voleq mpg123 volume and equalizer
;  *
;//enum mpg123_channels 
MPG123_LEFT  EQU 1; *< The Left Channel.
MPG123_RIGHT  EQU 2; *< The Right Channel.
MPG123_LR  EQU 3; *< Both left and right channel; same as MPG123_LEFT|MPG123_RIGHT

; * Set the 32 Band Audio Equalizer settings.
;  *  param channel Can be MPG123_LEFT,MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both.
;  *  param band The equaliser band to change (from 0 to 31)
;  *  param val The (linear) adjustment factor.
mpg123_eq  PROTO C :DWORD,:DWORD,:DWORD,:REAL8

; * Get the 32 Band Audio Equalizer settings.
;  *  param channel Can be MPG123_LEFT,MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for (arithmetic mean of) both.
;  *  param band The equaliser band to change (from 0 to 31)
;  *  return The (linear) adjustment factor.
mpg123_geteq  PROTO C :DWORD,:DWORD,:DWORD

; * Reset the 32 Band Audio Equalizer settings to flat
mpg123_reset_eq  PROTO C :DWORD

; * Set the absolute output volume including the RVA setting,
;  *  vol<0 just applies (a possibly changed) RVA setting.
mpg123_volume  PROTO C :DWORD,:REAL8

; * Adjust output volume including the RVA setting by chosen amount
mpg123_volume_change PROTO C :DWORD,:REAL8

; * Return current volume setting,the actual value due to RVA,and the RVA
;  *  adjustment itself. It's all as double float value to abstract the sample
;  *  format. The volume values are linear factors / amplitudes (not percent)
;  *  and the RVA value is in decibels.
mpg123_getvolume PROTO C :DWORD,:DWORD,:DWORD,:DWORD

;  TODO:Set some preamp in addition / to replace internal RVA handling?
; * defgroup mpg123_status mpg123 status and information
;  *
; 
; * Enumeration of the mode types of Variable Bitrate
MPG123_CBR  EQU 0; *< Constant Bitrate Mode (default)
MPG123_VBR  EQU 1; *< Variable Bitrate Mode
MPG123_ABR  EQU 2; *< Average Bitrate Mode

; * Enumeration of the MPEG Versions
MPG123_1_0  EQU 0; *< MPEG Version 1.0
MPG123_2_0  EQU 1; *< MPEG Version 2.0
MPG123_2_5  EQU 2; *< MPEG Version 2.5

; * Enumeration of the MPEG Audio mode.
;  *  Only the mono mode has 1 channel,the others have 2 channels.
MPG123_M_STEREO  EQU 0; *< Standard Stereo.
MPG123_M_JOINT  EQU 1; *< Joint Stereo.
MPG123_M_DUAL  EQU 2; *< Dual Channel.
MPG123_M_MONO  EQU 3; *< Single Channel.

; * Enumeration of the MPEG Audio flag bits
MPG123_CRC  EQU 1; *< The bitstream is error protected using 16-bit CRC.
MPG123_COPYRIGHT EQU 2; *< The bitstream is copyrighted.
MPG123_PRIVATE  EQU 4; *< The private bit has been set.
MPG123_ORIGINAL  EQU 8; *< The bitstream is an original,not a copy.

; * Data structure for storing information about a frame of MPEG Audio
; *< The MPEG version (1.0/2.0/2.5).
; *< The MPEG Audio Layer (MP1/MP2/MP3).
; *< The sampling rate in Hz.
; *< The audio mode (Mono,Stereo,Joint-stero,Dual Channel).
; *< The mode extension bit flag.
; *< The size of the frame (in bytes).
; *< MPEG Audio flag bits. Just now I realize that it should be declared as int,not enum. It's a bitwise combination of the enum values.
; *< The emphasis type.
; *< Bitrate of the frame (kbps).
; *< The target average bitrate.
; *< The VBR mode.
mpg123_frameinfo STRUCT
        version  DWORD ?
        layer  DWORD ?
        rate  DWORD ?
        mode  DWORD ?
        mode_ext DWORD ?
        framesize DWORD ?
        flags  DWORD ?
        emphasis DWORD ?
        bitrate  DWORD ?
        abr_rate DWORD ?
        vbr  DWORD ?
mpg123_frameinfo ENDS

; * Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo structure.
mpg123_info  PROTO C :DWORD,:DWORD

; * Get the safe output buffer size for all cases (when you want to replace the internal buffer)
mpg123_safe_buffer PROTO C

; * Make a full parsing scan of each frame in the file. ID3 tags are found. An accurate length
;  *  value is stored. Seek index will be filled. A seek back to current position
;  *  is performed. At all,this function refuses work when stream is
;  *  not seekable.
;  *  return MPG123_OK or MPG123_ERR.
; 
mpg123_scan  PROTO C :DWORD

; * Return,if possible,the full (expected) length of current track in samples.
;   * return length >= 0 or MPG123_ERR if there is no length guess possible.
mpg123_length  PROTO C :DWORD

; * Override the value for file size in bytes.
;   * Useful for getting sensible track length values in feed mode or for HTTP streams.
;   * return MPG123_OK or MPG123_ERR
mpg123_set_filesize PROTO C :DWORD,:DWORD

; * Returns the time (seconds) per frame; <0 is error.
mpg123_tpf  PROTO C :DWORD

; * Get and reset the clip count.
mpg123_clip  PROTO C :DWORD

; * The key values for state information from mpg123_getstate().
;//enum mpg123_state
MPG123_ACCURATE  EQU 1; *< Query if positons are currently accurate (integer value,0 if false,1 if true)

; * Get various current decoder/stream state information.
;  *  param key the key to identify the information to give.
;  *  param val the address to return (long) integer values to
;  *  param fval the address to return floating point values to
;  *  return MPG123_OK or MPG123_ERR for success
; 
mpg123_getstate  PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * defgroup mpg123_metadata mpg123 metadata handling
;  *
;  * Functions to retrieve the metadata from MPEG Audio files and streams.
;  * Also includes string handling functions.
;  *
; 
; * Data structure for storing strings in a safer way than a standard C-String.
;  *  Can also hold a number of null-terminated strings.
; *< pointer to the string data
; *< raw number of bytes allocated
; *< number of used bytes (including closing zero byte)
mpg123_string         STRUCT
        p  DWORD ?
        _size  DWORD ?
        fill  DWORD ?
mpg123_string  ENDS

; * Create and allocate memory for a new mpg123_string
mpg123_init_string PROTO C :DWORD

; * Free-up mempory for an existing mpg123_string
mpg123_free_string PROTO C :DWORD

; * Change the size of a mpg123_string
;  *  return 0 on error,1 on success 
mpg123_resize_string PROTO C :DWORD,:DWORD

; * Increase size of a mpg123_string if necessary (it may stay larger).
;  *  Note that the functions for adding and setting in current libmpg123 use this instead of mpg123_resize_string().
;  *  That way,you can preallocate memory and safely work afterwards with pieces.
;  *  return 0 on error,1 on success
mpg123_grow_string PROTO C :DWORD,:DWORD

; * Copy the contents of one mpg123_string string to another.
;  *  return 0 on error,1 on success
mpg123_copy_string PROTO C :DWORD,:DWORD

; * Append a C-String to an mpg123_string
;  *  return 0 on error,1 on success
mpg123_add_string PROTO C :DWORD,:DWORD

; * Append a C-substring to an mpg123 string
;  *  return 0 on error,1 on success
;  *  param from offset to copy from
;  *  param count number of characters to copy (a null-byte is always appended)
mpg123_add_substring PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * Set the conents of a mpg123_string to a C-string
;  *  return 0 on error,1 on success
mpg123_set_string PROTO C :DWORD,:DWORD

; * Set the contents of a mpg123_string to a C-substring
;  *  return 0 on error,1 on success
;  *  param from offset to copy from
;  *  param count number of characters to copy (a null-byte is always appended)
mpg123_set_substring PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * Count characters in a mpg123 string (non-null bytes or UTF-8 characters).
;  *  return character count
;  *  param sb the string
;  *  param utf8 a flag to tell if the string is in utf8 encoding
;  *  Even with the fill property,the character count is not obvious as there could be multiple trailing null bytes.
;
mpg123_strlen  PROTO C :DWORD,:DWORD

; * The mpg123 text encodings. This contains encodings we encounter in ID3 tags or ICY meta info.
;//enum mpg123_text_encoding
mpg123_text_unknown EQU 0; *< Unkown encoding... mpg123_id3_encoding can return that on invalid codes.
mpg123_text_utf8 EQU 1; *< UTF-8
mpg123_text_latin1 EQU 2; *< ISO-8859-1. Note that sometimes latin1 in ID3 is abused for totally different encodings.
mpg123_text_icy  EQU 3; *< ICY metadata encoding,usually CP-1252 but we take it as UTF-8 if it qualifies as such.
mpg123_text_cp1252 EQU 4; *< Really CP-1252 without any guessing.
mpg123_text_utf16 EQU 5; *< Some UTF-16 encoding. The last of a set of leading BOMs (byte order mark) rules.
                                 ; *  When there is no BOM,big endian ordering is used. Note that UCS-2 qualifies as UTF-8 when
                                 ; *  you don't mess with the reserved code points. If you want to decode little endian data
                                 ; *  without BOM you need to prepend 0xff 0xfe yourself.
mpg123_text_utf16bom EQU 6; *< Just an alias for UTF-16,ID3v2 has this as distinct code.
mpg123_text_utf16be EQU 7; *< Another alias for UTF16 from ID3v2. Note,that,because of the mess that is reality,
                                 ; *  BOMs are used if encountered. There really is not much distinction between the UTF16 types for mpg123
                                 ; *  One exception:Since this is seen in ID3v2 tags,leading null bytes are skipped for all other UTF16
                                 ; *  types (we expect a BOM before real data there),not so for utf16be!

mpg123_text_max  EQU 7; *< Placeholder for the maximum encoding value.

; * The encoding byte values from ID3v2.
;//enum mpg123_id3_enc
mpg123_id3_latin1 EQU 0; *< Note:This sometimes can mean anything in practice...
mpg123_id3_utf16bom EQU 1; *< UTF16,UCS-2 ... it's all the same for practical purposes.
mpg123_id3_utf16be EQU 2; *< Big-endian UTF-16,BOM see note for mpg123_text_utf16be.
mpg123_id3_utf8  EQU 3; *< Our lovely overly ASCII-compatible 8 byte encoding for the world.
mpg123_id3_enc_max EQU 3; *< Placeholder to check valid range of encoding byte.

; * Convert ID3 encoding byte to mpg123 encoding index.
mpg123_enc_from_id3 PROTO C :BYTE

; * Store text data in string,after converting to UTF-8 from indicated encoding
;  *  return 0 on error,1 on success (on error,mpg123_free_string is called on sb)
;  *  param sb  target string
;  *  param enc mpg123 text encoding value
;  *  param source source buffer with plain unsigned bytes (you might need to cast from char *)
;  *  param source_size number of bytes in the source buffer
;  *
;  *  A prominent error can be that you provided an unknown encoding value,or this build of libmpg123 lacks support for certain encodings (ID3 or ICY stuff missing).
;  *  Also,you might want to take a bit of care with preparing the data; for example,strip leading zeroes (I have seen that).

mpg123_store_utf8 PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * Sub data structure for ID3v2,for storing various text fields (including comments).
;  *  This is for ID3v2 COMM,TXXX and all the other text fields.
;  *  Only COMM and TXXX have a description,only COMM and USLT have a language.
;  *  You should consult the ID3v2 specification for the use of the various text fields ("frames" in ID3v2 documentation,I use "fields" here to separate from MPEG frames).
; *< Three-letter language code (not terminated).
; *< The ID3v2 text field id,like TALB,TPE2,... (4 characters,no string termination).
; *< Empty for the generic comment...
; *< ...
mpg123_text STRUCT
        lang  BYTE 3 DUP (?)
        id  BYTE 4 DUP (?)
        description mpg123_string <>
        text  mpg123_string <>
mpg123_text ENDS

; * Data structure for storing IDV3v2 tags.
;  *  This structure is not a direct binary mapping with the file contents.
;  *  The ID3v2 text frames are allowed to contain multiple strings.
;  *  So check for null bytes until you reach the mpg123_string fill.
;  *  All text is encoded in UTF-8.
; *< 3 or 4 for ID3v2.3 or ID3v2.4.
; *< The array of extra (TXXX) fields.
; *< Number of extra text (TXXX) fields.
mpg123_id3v2  STRUCT
        version  DWORD ?
        _title  DWORD ?
        artist  DWORD ?
        album  DWORD ?
        year  DWORD ?
        genre  DWORD ?
        _comment DWORD ?
        comment_list DWORD ?
        comments DWORD ?
        text  DWORD ?
        texts  DWORD ?
        extra  DWORD ?
        extras  DWORD   ?
mpg123_id3v2  ENDS

; * Data structure for ID3v1 tags (the last 128 bytes of a file).
;  *  Don't take anything for granted (like string termination)!
;  *  Also note the change ID3v1.1 did:comment[28] = 0; comment[19] = track_number
;  *  It is your task to support ID3v1 only or ID3v1.1 ...
; *< Always the string "TAG",the classic intro.
; *< Title string. 
; *< Artist string.
; *< Album string.
; *< Year string.
; *< Comment string.
; *< Genre index.
mpg123_id3v1  STRUCT
        tag  BYTE 3  DUP (?)
        _title  BYTE 30 DUP (?)
        artist  BYTE 30 DUP (?)
        album  BYTE 30 DUP (?)
        year  BYTE 4  DUP (?)
        _comment BYTE 30 DUP (?)
        genre  BYTE ?
mpg123_id3v1  ENDS

MPG123_ID3  EQU 3h; *< 0011 There is some ID3 info. Also matches 0010 or NEW_ID3.
MPG123_NEW_ID3  EQU 1h; *< 0001 There is ID3 info that changed since last call to mpg123_id3.
MPG123_ICY  EQU    0ch; *< 1100 There is some ICY info. Also matches 0100 or NEW_ICY.
MPG123_NEW_ICY  EQU 4h; *< 0100 There is ICY info that changed since last call to mpg123_icy.

; * Query if there is (new) meta info,be it ID3 or ICY (or something new in future).
;    The check function returns a combination of flags.
mpg123_meta_check PROTO C :DWORD

;  On error (no valid handle) just 0 is returned.
; * Point v1 and v2 to existing data structures wich may change on any next read/decode function call.
;  *  v1 and/or v2 can be set to NULL when there is no corresponding data.
;  *  return Return value is MPG123_OK or MPG123_ERR,
mpg123_id3  PROTO C :DWORD,: DWORD,: DWORD

; * Point icy_meta to existing data structure wich may change on any next read/decode function call.
;  *  return Return value is MPG123_OK or MPG123_ERR,
mpg123_icy  PROTO C :DWORD,: DWORD

;  same for ICY meta string
; * Decode from windows-1252 (the encoding ICY metainfo used) to UTF-8.
;  *  Note that this is very similar to mpg123_store_utf8(&sb,mpg123_text_icy,icy_text,strlen(icy_text+1)) .
;  *  param icy_text The input data in ICY encoding
;  *  return pointer to newly allocated buffer with UTF-8 data (You free() it!)
mpg123_icy2utf8  PROTO C :DWORD

; * defgroup mpg123_advpar mpg123 advanced parameter API
;  *
;  *  Direct access to a parameter set without full handle around it.
;  * Possible uses:
;  *    - Influence behaviour of library _during_ initialization of handle (MPG123_VERBOSE).
;  *    - Use one set of parameters for multiple handles.
;  *
;  * The functions for handling mpg123_pars (mpg123_par() and mpg123_fmt()
;  *  family) directly return a fully qualified mpg123 error code,the ones
;  *  operating on full handles normally MPG123_OK or MPG123_ERR,storing the
;  *  specific error code itseld inside the handle.
;  *
; 
; * Opaque structure for the libmpg123 decoder parameters.
; * Opaque structure for the libmpg123 decoder parameters.

; * Create a handle with preset parameters.
mpg123_parnew  PROTO C :DWORD,:DWORD,:DWORD

; * Allocate memory for and return a pointer to a new mpg123_pars
mpg123_new_pars  PROTO C :DWORD

; * Delete and free up memory used by a mpg123_pars data structure
mpg123_delete_pars PROTO C :DWORD

; * Configure mpg123 parameters to accept no output format at all,
;  * use before specifying supported formats with mpg123_format
mpg123_fmt_none  PROTO C :DWORD

; * Configure mpg123 parameters to accept all formats
;  *  (also any custom rate you may set) -- this is default.
mpg123_fmt_all  PROTO C :DWORD

; * Set the audio format support of a mpg123_pars in detail:
;  param rate The sample rate value (in Hertz).
;  param channels A combination of MPG123_STEREO and MPG123_MONO.
;  param encodings A combination of accepted encodings for rate and channels,p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no support).
;  return 0 on success,-1 if there was an error. /
;
mpg123_fmt  PROTO C :DWORD,:DWORD,:DWORD,:DWORD

;  0 is good,-1 is error
; * Check to see if a specific format at a specific rate is supported
;  *  by mpg123_pars.
;  *  return 0 for no support (that includes invalid parameters),MPG123_STEREO,
;  *          MPG123_MONO or MPG123_STEREO|MPG123_MONO.
mpg123_fmt_support PROTO C :DWORD,:DWORD,:DWORD

; * Set a specific parameter,for a specific mpg123_pars,using a parameter
;  *  type key chosen from the mpg123_parms enumeration,to the specified value.
mpg123_par  PROTO C :DWORD,:DWORD,:DWORD,:REAL8

; * Get a specific parameter,for a specific mpg123_pars.
;  *  See the mpg123_parms enumeration for a list of available parameters.
mpg123_getpar  PROTO C :DWORD,:DWORD,:DWORD,:DWORD

; * defgroup mpg123_lowio mpg123 low level I/O
;   * You may want to do tricky stuff with I/O that does not work with mpg123's default file access or you want to make it decode into your own pocket...
;   *
; * Replace default internal buffer with user-supplied buffer.
;   * Instead of working on it's own private buffer,mpg123 will directly use the one you provide for storing decoded audio.
mpg123_replace_buffer PROTO C :DWORD,:DWORD,:DWORD

; * The max size of one frame's decoded output with current settings.
;  *  Use that to determine an appropriate minimum buffer size for decoding one frame.
mpg123_outblock  PROTO C :DWORD

; * Replace low-level stream access functions; read and lseek as known in POSIX.
;  *  You can use this to make any fancy file opening/closing yourself,
;  *  using mpg123_open_fd() to set the file descriptor for your read/lseek (doesn't need to be a "real" file descriptor...).
;  *  Setting a function to NULL means that the default internal read is
;  *  used (active from next mpg123_open call on).
;  *  Note:As it would be troublesome to mess with this while having a file open,
;  *  this implies mpg123_close().
mpg123_replace_reader PROTO C :DWORD,:DWORD,:DWORD

; * Replace I/O functions with your own ones operating on some kind of handle instead of integer descriptors.
;  *  The handle is a void pointer,so you can pass any data you want...
;  *  mpg123_open_handle() is the call you make to use the I/O defined here.
;  *  There is no fallback to internal read/seek here.
;  *  Note:As it would be troublesome to mess with this while having a file open,
;  *  this mpg123_close() is implied here.
;  *  param r_read The callback for reading (behaviour like posix read).
;  *  param r_lseek The callback for seeking (like posix lseek).
;  *  param cleanup A callback to clean up an I/O handle on mpg123_close,can be NULL for none (you take care of cleaning your handles).

mpg123_replace_reader_handle PROTO C :DWORD,:DWORD,:DWORD,:DWORD

;
; End of file mpg123.h