1 /* 2 libmpg123: MPEG Audio Decoder library (version 1.26.2) 3 4 copyright 1995-2015 by the mpg123 project 5 free software under the terms of the LGPL 2.1 6 see COPYING and AUTHORS files in distribution or http://mpg123.org 7 */ 8 9 #ifndef MPG123_LIB_H 10 #define MPG123_LIB_H 11 12 #include <fmt123.h> 13 14 /** \file mpg123.h The header file for the libmpg123 MPEG Audio decoder */ 15 16 /** A macro to check at compile time which set of API functions to expect. 17 * This should be incremented at least each time a new symbol is added 18 * to the header. 19 */ 20 #define MPG123_API_VERSION 45 21 22 #ifndef MPG123_EXPORT 23 /** Defines needed for MS Visual Studio(tm) DLL builds. 24 * Every public function must be prefixed with MPG123_EXPORT. When building 25 * the DLL ensure to define BUILD_MPG123_DLL. This makes the function accessible 26 * for clients and includes it in the import library which is created together 27 * with the DLL. When consuming the DLL ensure to define LINK_MPG123_DLL which 28 * imports the functions from the DLL. 29 */ 30 #ifdef BUILD_MPG123_DLL 31 /* The dll exports. */ 32 #define MPG123_EXPORT __declspec(dllexport) 33 #else 34 #ifdef LINK_MPG123_DLL 35 /* The exe imports. */ 36 #define MPG123_EXPORT __declspec(dllimport) 37 #else 38 /* Nothing on normal/UNIX builds */ 39 #define MPG123_EXPORT 40 #endif 41 #endif 42 #endif 43 44 #ifndef __REACTOS__ 45 /* This is for Visual Studio, so this header works as distributed in the binary downloads */ 46 #if defined(_MSC_VER) && !defined(MPG123_DEF_SSIZE_T) 47 #define MPG123_DEF_SSIZE_T 48 #include <stddef.h> 49 typedef ptrdiff_t ssize_t; 50 #endif 51 #endif /* __REACTOS__ */ 52 53 #ifndef MPG123_NO_CONFIGURE /* Enable use of this file without configure. */ 54 #include <stdlib.h> 55 #include <sys/types.h> 56 57 #ifdef __REACTOS__ 58 #ifndef ssize_t 59 typedef long ssize_t; 60 #endif 61 #endif /* __REACTOS__ */ 62 63 /* Simplified large file handling. 64 I used to have a check here that prevents building for a library with conflicting large file setup 65 (application that uses 32 bit offsets with library that uses 64 bits). 66 While that was perfectly fine in an environment where there is one incarnation of the library, 67 it hurt GNU/Linux and Solaris systems with multilib where the distribution fails to provide the 68 correct header matching the 32 bit library (where large files need explicit support) or 69 the 64 bit library (where there is no distinction). 70 71 New approach: When the app defines _FILE_OFFSET_BITS, it wants non-default large file support, 72 and thus functions with added suffix (mpg123_open_64). 73 Any mismatch will be caught at link time because of the _FILE_OFFSET_BITS setting used when 74 building libmpg123. Plus, there's dual mode large file support in mpg123 since 1.12 now. 75 Link failure is not the expected outcome of any half-sane usage anymore. 76 77 More complication: What about client code defining _LARGEFILE64_SOURCE? It might want direct access to the _64 functions, along with the ones without suffix. Well, that's possible now via defining MPG123_NO_LARGENAME and MPG123_LARGESUFFIX, respectively, for disabling or enforcing the suffix names. 78 */ 79 80 /* 81 Now, the renaming of large file aware functions. 82 By default, it appends underscore _FILE_OFFSET_BITS (so, mpg123_seek_64 for mpg123_seek), if _FILE_OFFSET_BITS is defined. You can force a different suffix via MPG123_LARGESUFFIX (that must include the underscore), or you can just disable the whole mess by defining MPG123_NO_LARGENAME. 83 */ 84 #if (!defined MPG123_NO_LARGENAME) && ((defined _FILE_OFFSET_BITS) || (defined MPG123_LARGESUFFIX)) 85 86 /* Need some trickery to concatenate the value(s) of the given macro(s). */ 87 #define MPG123_MACROCAT_REALLY(a, b) a ## b 88 #define MPG123_MACROCAT(a, b) MPG123_MACROCAT_REALLY(a, b) 89 #ifndef MPG123_LARGESUFFIX 90 #define MPG123_LARGESUFFIX MPG123_MACROCAT(_, _FILE_OFFSET_BITS) 91 #endif 92 #define MPG123_LARGENAME(func) MPG123_MACROCAT(func, MPG123_LARGESUFFIX) 93 94 #define mpg123_open_fixed MPG123_LARGENAME(mpg123_open_fixed) 95 #define mpg123_open MPG123_LARGENAME(mpg123_open) 96 #define mpg123_open_fd MPG123_LARGENAME(mpg123_open_fd) 97 #define mpg123_open_handle MPG123_LARGENAME(mpg123_open_handle) 98 #define mpg123_framebyframe_decode MPG123_LARGENAME(mpg123_framebyframe_decode) 99 #define mpg123_decode_frame MPG123_LARGENAME(mpg123_decode_frame) 100 #define mpg123_tell MPG123_LARGENAME(mpg123_tell) 101 #define mpg123_tellframe MPG123_LARGENAME(mpg123_tellframe) 102 #define mpg123_tell_stream MPG123_LARGENAME(mpg123_tell_stream) 103 #define mpg123_seek MPG123_LARGENAME(mpg123_seek) 104 #define mpg123_feedseek MPG123_LARGENAME(mpg123_feedseek) 105 #define mpg123_seek_frame MPG123_LARGENAME(mpg123_seek_frame) 106 #define mpg123_timeframe MPG123_LARGENAME(mpg123_timeframe) 107 #define mpg123_index MPG123_LARGENAME(mpg123_index) 108 #define mpg123_set_index MPG123_LARGENAME(mpg123_set_index) 109 #define mpg123_position MPG123_LARGENAME(mpg123_position) 110 #define mpg123_length MPG123_LARGENAME(mpg123_length) 111 #define mpg123_framelength MPG123_LARGENAME(mpg123_framelength) 112 #define mpg123_set_filesize MPG123_LARGENAME(mpg123_set_filesize) 113 #define mpg123_replace_reader MPG123_LARGENAME(mpg123_replace_reader) 114 #define mpg123_replace_reader_handle MPG123_LARGENAME(mpg123_replace_reader_handle) 115 #define mpg123_framepos MPG123_LARGENAME(mpg123_framepos) 116 117 #endif /* largefile hackery */ 118 119 #endif /* MPG123_NO_CONFIGURE */ 120 121 #ifdef __cplusplus 122 extern "C" { 123 #endif 124 125 /** \defgroup mpg123_init mpg123 library and handle setup 126 * 127 * Functions to initialise and shutdown the mpg123 library and handles. 128 * The parameters of handles have workable defaults, you only have to tune them when you want to tune something;-) 129 * Tip: Use a RVA setting... 130 * 131 * @{ 132 */ 133 134 /** Opaque structure for the libmpg123 decoder handle. */ 135 struct mpg123_handle_struct; 136 137 /** Opaque structure for the libmpg123 decoder handle. 138 * Most functions take a pointer to a mpg123_handle as first argument and operate on its data in an object-oriented manner. 139 */ 140 typedef struct mpg123_handle_struct mpg123_handle; 141 142 /** Function to initialise the mpg123 library. 143 * This should be called once in a non-parallel context. It is not explicitly 144 * thread-safe, but repeated/concurrent calls still _should_ be safe as static 145 * tables are filled with the same values anyway. 146 * 147 * \return MPG123_OK if successful, otherwise an error number. 148 */ 149 MPG123_EXPORT int mpg123_init(void); 150 151 /** Superfluous Function to close down the mpg123 library. 152 * This was created with the thought that there sometime will be cleanup code 153 * to be run after library use. This never materialized. You can forget about 154 * this function and it is only here for old programs that do call it. 155 */ 156 MPG123_EXPORT void mpg123_exit(void); 157 158 /** Create a handle with optional choice of decoder (named by a string, see mpg123_decoders() or mpg123_supported_decoders()). 159 * and optional retrieval of an error code to feed to mpg123_plain_strerror(). 160 * Optional means: Any of or both the parameters may be NULL. 161 * 162 * \param decoder optional choice of decoder variant (NULL for default) 163 * \param error optional address to store error codes 164 * \return Non-NULL pointer to fresh handle when successful. 165 */ 166 MPG123_EXPORT mpg123_handle *mpg123_new(const char* decoder, int *error); 167 168 /** Delete handle, mh is either a valid mpg123 handle or NULL. 169 * \param mh handle 170 */ 171 MPG123_EXPORT void mpg123_delete(mpg123_handle *mh); 172 173 /** Free plain memory allocated within libmpg123. 174 * This is for library users that are not sure to use the same underlying 175 * memory allocator as libmpg123. It is just a wrapper over free() in 176 * the underlying C library. 177 */ 178 MPG123_EXPORT void mpg123_free(void *ptr); 179 180 /** Enumeration of the parameters types that it is possible to set/get. */ 181 enum mpg123_parms 182 { 183 MPG123_VERBOSE = 0, /**< set verbosity value for enabling messages to stderr, >= 0 makes sense (integer) */ 184 MPG123_FLAGS, /**< set all flags, p.ex val = MPG123_GAPLESS|MPG123_MONO_MIX (integer) */ 185 MPG123_ADD_FLAGS, /**< add some flags (integer) */ 186 MPG123_FORCE_RATE, /**< when value > 0, force output rate to that value (integer) */ 187 MPG123_DOWN_SAMPLE, /**< 0=native rate, 1=half rate, 2=quarter rate (integer) */ 188 MPG123_RVA, /**< one of the RVA choices above (integer) */ 189 MPG123_DOWNSPEED, /**< play a frame N times (integer) */ 190 MPG123_UPSPEED, /**< play every Nth frame (integer) */ 191 MPG123_START_FRAME, /**< start with this frame (skip frames before that, integer) */ 192 MPG123_DECODE_FRAMES, /**< decode only this number of frames (integer) */ 193 MPG123_ICY_INTERVAL, /**< Stream contains ICY metadata with this interval (integer). 194 Make sure to set this _before_ opening a stream.*/ 195 MPG123_OUTSCALE, /**< the scale for output samples (amplitude - integer or float according to mpg123 output format, normally integer) */ 196 MPG123_TIMEOUT, /**< timeout for reading from a stream (not supported on win32, integer) */ 197 MPG123_REMOVE_FLAGS, /**< remove some flags (inverse of MPG123_ADD_FLAGS, integer) */ 198 MPG123_RESYNC_LIMIT, /**< Try resync on frame parsing for that many bytes or until end of stream (<0 ... integer). This can enlarge the limit for skipping junk on beginning, too (but not reduce it). */ 199 MPG123_INDEX_SIZE /**< 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) -- Use this when you really want a full index with every individual frame. */ 200 ,MPG123_PREFRAMES /**< Decode/ignore that many frames in advance for layer 3. This is needed to fill bit reservoir after seeking, for example (but also at least one frame in advance is needed to have all "normal" data for layer 3). Give a positive integer value, please.*/ 201 ,MPG123_FEEDPOOL /**< For feeder mode, keep that many buffers in a pool to avoid frequent malloc/free. The pool is allocated on mpg123_open_feed(). If you change this parameter afterwards, you can trigger growth and shrinkage during decoding. The default value could change any time. If you care about this, then set it. (integer) */ 202 ,MPG123_FEEDBUFFER /**< Minimal size of one internal feeder buffer, again, the default value is subject to change. (integer) */ 203 ,MPG123_FREEFORMAT_SIZE /**< Tell the parser a free-format frame size to 204 * avoid read-ahead to get it. A value of -1 (default) means that the parser 205 * will determine it. The parameter value is applied during decoder setup 206 * for a freshly opened stream only. 207 */ 208 }; 209 210 /** Flag bits for MPG123_FLAGS, use the usual binary or to combine. */ 211 enum mpg123_param_flags 212 { 213 MPG123_FORCE_MONO = 0x7 /**< 0111 Force some mono mode: This is a test bitmask for seeing if any mono forcing is active. */ 214 ,MPG123_MONO_LEFT = 0x1 /**< 0001 Force playback of left channel only. */ 215 ,MPG123_MONO_RIGHT = 0x2 /**< 0010 Force playback of right channel only. */ 216 ,MPG123_MONO_MIX = 0x4 /**< 0100 Force playback of mixed mono. */ 217 ,MPG123_FORCE_STEREO = 0x8 /**< 1000 Force stereo output. */ 218 ,MPG123_FORCE_8BIT = 0x10 /**< 00010000 Force 8bit formats. */ 219 ,MPG123_QUIET = 0x20 /**< 00100000 Suppress any printouts (overrules verbose). */ 220 ,MPG123_GAPLESS = 0x40 /**< 01000000 Enable gapless decoding (default on if libmpg123 has support). */ 221 ,MPG123_NO_RESYNC = 0x80 /**< 10000000 Disable resync stream after error. */ 222 ,MPG123_SEEKBUFFER = 0x100 /**< 000100000000 Enable small buffer on non-seekable streams to allow some peek-ahead (for better MPEG sync). */ 223 ,MPG123_FUZZY = 0x200 /**< 001000000000 Enable fuzzy seeks (guessing byte offsets or using approximate seek points from Xing TOC) */ 224 ,MPG123_FORCE_FLOAT = 0x400 /**< 010000000000 Force floating point output (32 or 64 bits depends on mpg123 internal precision). */ 225 ,MPG123_PLAIN_ID3TEXT = 0x800 /**< 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. */ 226 ,MPG123_IGNORE_STREAMLENGTH = 0x1000 /**< 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 */ 227 ,MPG123_SKIP_ID3V2 = 0x2000 /**< 10 0000 0000 0000 Do not parse ID3v2 tags, just skip them. */ 228 ,MPG123_IGNORE_INFOFRAME = 0x4000 /**< 100 0000 0000 0000 Do not parse the LAME/Xing info frame, treat it as normal MPEG data. */ 229 ,MPG123_AUTO_RESAMPLE = 0x8000 /**< 1000 0000 0000 0000 Allow automatic internal resampling of any kind (default on if supported). Especially when going lowlevel with replacing output buffer, you might want to unset this flag. Setting MPG123_DOWNSAMPLE or MPG123_FORCE_RATE will override this. */ 230 ,MPG123_PICTURE = 0x10000 /**< 17th bit: Enable storage of pictures from tags (ID3v2 APIC). */ 231 ,MPG123_NO_PEEK_END = 0x20000 /**< 18th bit: Do not seek to the end of 232 * the stream in order to probe 233 * the stream length and search for the id3v1 field. This also means 234 * the file size is unknown unless set using mpg123_set_filesize() and 235 * the stream is assumed as non-seekable unless overridden. 236 */ 237 ,MPG123_FORCE_SEEKABLE = 0x40000 /**< 19th bit: Force the stream to be seekable. */ 238 ,MPG123_STORE_RAW_ID3 = 0x80000 /**< store raw ID3 data (even if skipping) */ 239 ,MPG123_FORCE_ENDIAN = 0x100000 /**< Enforce endianess of output samples. 240 * This is not reflected in the format codes. If this flag is set along with 241 * MPG123_BIG_ENDIAN, MPG123_ENC_SIGNED16 means s16be, without 242 * MPG123_BIG_ENDIAN, it means s16le. Normal operation without 243 * MPG123_FORCE_ENDIAN produces output in native byte order. 244 */ 245 ,MPG123_BIG_ENDIAN = 0x200000 /**< Choose big endian instead of little. */ 246 ,MPG123_NO_READAHEAD = 0x400000 /**< Disable read-ahead in parser. If 247 * you know you provide full frames to the feeder API, this enables 248 * decoder output from the first one on, instead of having to wait for 249 * the next frame to confirm that the stream is healthy. It also disables 250 * free format support unless you provide a frame size using 251 * MPG123_FREEFORMAT_SIZE. 252 */ 253 ,MPG123_FLOAT_FALLBACK = 0x800000 /**< Consider floating point output encoding only after 254 * trying other (possibly downsampled) rates and encodings first. This is to 255 * support efficient playback where floating point output is only configured for 256 * an external resampler, bypassing that resampler when the desired rate can 257 * be produced directly. This is enabled by default to be closer to older versions 258 * of libmpg123 which did not enable float automatically at all. If disabled, 259 * float is considered after the 16 bit default and higher-bit integer encodings 260 * for any rate. */ 261 ,MPG123_NO_FRANKENSTEIN = 0x1000000 /**< Disable support for Frankenstein streams 262 * (different MPEG streams stiched together). Do not accept serious change of MPEG 263 * header inside a single stream. With this flag, the audio output format cannot 264 * change during decoding unless you open a new stream. This also stops decoding 265 * after an announced end of stream (Info header contained a number of frames 266 * and this number has been reached). This makes your MP3 files behave more like 267 * ordinary media files with defined structure, rather than stream dumps with 268 * some sugar. */ 269 }; 270 271 /** choices for MPG123_RVA */ 272 enum mpg123_param_rva 273 { 274 MPG123_RVA_OFF = 0 /**< RVA disabled (default). */ 275 ,MPG123_RVA_MIX = 1 /**< Use mix/track/radio gain. */ 276 ,MPG123_RVA_ALBUM = 2 /**< Use album/audiophile gain */ 277 ,MPG123_RVA_MAX = MPG123_RVA_ALBUM /**< The maximum RVA code, may increase in future. */ 278 }; 279 280 /** Set a specific parameter, for a specific mpg123_handle, using a parameter 281 * type key chosen from the mpg123_parms enumeration, to the specified value. 282 * \param mh handle 283 * \param type parameter choice 284 * \param value integer value 285 * \param fvalue floating point value 286 * \return MPG123_OK on success 287 */ 288 MPG123_EXPORT int mpg123_param( mpg123_handle *mh 289 , enum mpg123_parms type, long value, double fvalue ); 290 291 /** Get a specific parameter, for a specific mpg123_handle. 292 * See the mpg123_parms enumeration for a list of available parameters. 293 * \param mh handle 294 * \param type parameter choice 295 * \param value integer value return address 296 * \param fvalue floating point value return address 297 * \return MPG123_OK on success 298 */ 299 MPG123_EXPORT int mpg123_getparam( mpg123_handle *mh 300 , enum mpg123_parms type, long *value, double *fvalue ); 301 302 /** Feature set available for query with mpg123_feature. */ 303 enum mpg123_feature_set 304 { 305 MPG123_FEATURE_ABI_UTF8OPEN = 0 /**< mpg123 expects path names to be given in UTF-8 encoding instead of plain native. */ 306 ,MPG123_FEATURE_OUTPUT_8BIT /**< 8bit output */ 307 ,MPG123_FEATURE_OUTPUT_16BIT /**< 16bit output */ 308 ,MPG123_FEATURE_OUTPUT_32BIT /**< 32bit output */ 309 ,MPG123_FEATURE_INDEX /**< support for building a frame index for accurate seeking */ 310 ,MPG123_FEATURE_PARSE_ID3V2 /**< id3v2 parsing */ 311 ,MPG123_FEATURE_DECODE_LAYER1 /**< mpeg layer-1 decoder enabled */ 312 ,MPG123_FEATURE_DECODE_LAYER2 /**< mpeg layer-2 decoder enabled */ 313 ,MPG123_FEATURE_DECODE_LAYER3 /**< mpeg layer-3 decoder enabled */ 314 ,MPG123_FEATURE_DECODE_ACCURATE /**< accurate decoder rounding */ 315 ,MPG123_FEATURE_DECODE_DOWNSAMPLE /**< downsample (sample omit) */ 316 ,MPG123_FEATURE_DECODE_NTOM /**< flexible rate decoding */ 317 ,MPG123_FEATURE_PARSE_ICY /**< ICY support */ 318 ,MPG123_FEATURE_TIMEOUT_READ /**< Reader with timeout (network). */ 319 ,MPG123_FEATURE_EQUALIZER /**< tunable equalizer */ 320 ,MPG123_FEATURE_MOREINFO /**< more info extraction (for frame analyzer) */ 321 ,MPG123_FEATURE_OUTPUT_FLOAT32 /**< 32 bit float output */ 322 ,MPG123_FEATURE_OUTPUT_FLOAT64 /**< 64 bit float output (usually never) */ 323 }; 324 325 /** Query libmpg123 features. 326 * \param key feature selection 327 * \return 1 for success, 0 for unimplemented functions 328 */ 329 MPG123_EXPORT int mpg123_feature(const enum mpg123_feature_set key); 330 331 /** Query libmpg123 features with better ABI compatibility 332 * 333 * This is the same as mpg123_feature(), but this time not using 334 * the enum as argument. Compilers don't have to agree on the size of 335 * enums and hence they are not safe in public API. 336 * 337 * \param key feature selection 338 * \return 1 for success, 0 for unimplemented functions 339 */ 340 MPG123_EXPORT int mpg123_feature2(int key); 341 342 /* @} */ 343 344 345 /** \defgroup mpg123_error mpg123 error handling 346 * 347 * Functions to get text version of the error numbers and an enumeration 348 * of the error codes returned by libmpg123. 349 * 350 * Most functions operating on a mpg123_handle simply return MPG123_OK (0) 351 * on success and MPG123_ERR (-1) on failure, setting the internal error 352 * variable of the handle to the specific error code. If there was not a valid 353 * (non-NULL) handle provided to a function operating on one, MPG123_BAD_HANDLE 354 * may be returned if this can not be confused with a valid positive return 355 * value. 356 * Meaning: A function expected to return positive integers on success will 357 * always indicate error or a special condition by returning a negative one. 358 * 359 * Decoding/seek functions may also return message codes MPG123_DONE, 360 * MPG123_NEW_FORMAT and MPG123_NEED_MORE (all negative, see below on how to 361 * react). Note that calls to those can be nested, so generally watch out 362 * for these codes after initial handle setup. 363 * Especially any function that needs information about the current stream 364 * to work will try to at least parse the beginning if that did not happen 365 * yet. 366 * 367 * On a function that is supposed to return MPG123_OK on success and 368 * MPG123_ERR on failure, make sure you check for != MPG123_OK, not 369 * == MPG123_ERR, as the error code could get more specific in future, 370 * or there is just a special message from a decoding routine as indicated 371 * above. 372 * 373 * @{ 374 */ 375 376 /** Enumeration of the message and error codes and returned by libmpg123 functions. */ 377 enum mpg123_errors 378 { 379 MPG123_DONE=-12, /**< Message: Track ended. Stop decoding. */ 380 MPG123_NEW_FORMAT=-11, /**< Message: Output format will be different on next call. Note that some libmpg123 versions between 1.4.3 and 1.8.0 insist on you calling mpg123_getformat() after getting this message code. Newer verisons behave like advertised: You have the chance to call mpg123_getformat(), but you can also just continue decoding and get your data. */ 381 MPG123_NEED_MORE=-10, /**< Message: For feed reader: "Feed me more!" (call mpg123_feed() or mpg123_decode() with some new input data). */ 382 MPG123_ERR=-1, /**< Generic Error */ 383 MPG123_OK=0, /**< Success */ 384 MPG123_BAD_OUTFORMAT, /**< Unable to set up output format! */ 385 MPG123_BAD_CHANNEL, /**< Invalid channel number specified. */ 386 MPG123_BAD_RATE, /**< Invalid sample rate specified. */ 387 MPG123_ERR_16TO8TABLE, /**< Unable to allocate memory for 16 to 8 converter table! */ 388 MPG123_BAD_PARAM, /**< Bad parameter id! */ 389 MPG123_BAD_BUFFER, /**< Bad buffer given -- invalid pointer or too small size. */ 390 MPG123_OUT_OF_MEM, /**< Out of memory -- some malloc() failed. */ 391 MPG123_NOT_INITIALIZED, /**< You didn't initialize the library! */ 392 MPG123_BAD_DECODER, /**< Invalid decoder choice. */ 393 MPG123_BAD_HANDLE, /**< Invalid mpg123 handle. */ 394 MPG123_NO_BUFFERS, /**< Unable to initialize frame buffers (out of memory?). */ 395 MPG123_BAD_RVA, /**< Invalid RVA mode. */ 396 MPG123_NO_GAPLESS, /**< This build doesn't support gapless decoding. */ 397 MPG123_NO_SPACE, /**< Not enough buffer space. */ 398 MPG123_BAD_TYPES, /**< Incompatible numeric data types. */ 399 MPG123_BAD_BAND, /**< Bad equalizer band. */ 400 MPG123_ERR_NULL, /**< Null pointer given where valid storage address needed. */ 401 MPG123_ERR_READER, /**< Error reading the stream. */ 402 MPG123_NO_SEEK_FROM_END,/**< Cannot seek from end (end is not known). */ 403 MPG123_BAD_WHENCE, /**< Invalid 'whence' for seek function.*/ 404 MPG123_NO_TIMEOUT, /**< Build does not support stream timeouts. */ 405 MPG123_BAD_FILE, /**< File access error. */ 406 MPG123_NO_SEEK, /**< Seek not supported by stream. */ 407 MPG123_NO_READER, /**< No stream opened. */ 408 MPG123_BAD_PARS, /**< Bad parameter handle. */ 409 MPG123_BAD_INDEX_PAR, /**< Bad parameters to mpg123_index() and mpg123_set_index() */ 410 MPG123_OUT_OF_SYNC, /**< Lost track in bytestream and did not try to resync. */ 411 MPG123_RESYNC_FAIL, /**< Resync failed to find valid MPEG data. */ 412 MPG123_NO_8BIT, /**< No 8bit encoding possible. */ 413 MPG123_BAD_ALIGN, /**< Stack aligmnent error */ 414 MPG123_NULL_BUFFER, /**< NULL input buffer with non-zero size... */ 415 MPG123_NO_RELSEEK, /**< Relative seek not possible (screwed up file offset) */ 416 MPG123_NULL_POINTER, /**< You gave a null pointer somewhere where you shouldn't have. */ 417 MPG123_BAD_KEY, /**< Bad key value given. */ 418 MPG123_NO_INDEX, /**< No frame index in this build. */ 419 MPG123_INDEX_FAIL, /**< Something with frame index went wrong. */ 420 MPG123_BAD_DECODER_SETUP, /**< Something prevents a proper decoder setup */ 421 MPG123_MISSING_FEATURE /**< This feature has not been built into libmpg123. */ 422 ,MPG123_BAD_VALUE /**< A bad value has been given, somewhere. */ 423 ,MPG123_LSEEK_FAILED /**< Low-level seek failed. */ 424 ,MPG123_BAD_CUSTOM_IO /**< Custom I/O not prepared. */ 425 ,MPG123_LFS_OVERFLOW /**< Offset value overflow during translation of large file API calls -- your client program cannot handle that large file. */ 426 ,MPG123_INT_OVERFLOW /**< Some integer overflow. */ 427 }; 428 429 /** Look up error strings given integer code. 430 * \param errcode integer error code 431 * \return string describing what that error error code means 432 */ 433 MPG123_EXPORT const char* mpg123_plain_strerror(int errcode); 434 435 /** Give string describing what error has occured in the context of handle mh. 436 * When a function operating on an mpg123 handle returns MPG123_ERR, you should check for the actual reason via 437 * char *errmsg = mpg123_strerror(mh) 438 * This function will catch mh == NULL and return the message for MPG123_BAD_HANDLE. 439 * \param mh handle 440 * \return error message 441 */ 442 MPG123_EXPORT const char* mpg123_strerror(mpg123_handle *mh); 443 444 /** Return the plain errcode intead of a string. 445 * \param mh handle 446 * \return error code recorded in handle or MPG123_BAD_HANDLE 447 */ 448 MPG123_EXPORT int mpg123_errcode(mpg123_handle *mh); 449 450 /*@}*/ 451 452 453 /** \defgroup mpg123_decoder mpg123 decoder selection 454 * 455 * Functions to list and select the available decoders. 456 * Perhaps the most prominent feature of mpg123: You have several (optimized) decoders to choose from (on x86 and PPC (MacOS) systems, that is). 457 * 458 * @{ 459 */ 460 461 /** Get available decoder list. 462 * \return NULL-terminated array of generally available decoder names (plain 8bit ASCII) 463 */ 464 MPG123_EXPORT const char **mpg123_decoders(void); 465 466 /** Get supported decoder list. 467 * \return NULL-terminated array of the decoders supported by the CPU (plain 8bit ASCII) 468 */ 469 MPG123_EXPORT const char **mpg123_supported_decoders(void); 470 471 /** Set the active decoder. 472 * \param mh handle 473 * \param decoder_name name of decoder 474 * \return MPG123_OK on success 475 */ 476 MPG123_EXPORT int mpg123_decoder(mpg123_handle *mh, const char* decoder_name); 477 478 /** Get the currently active decoder name. 479 * The active decoder engine can vary depening on output constraints, 480 * mostly non-resampling, integer output is accelerated via 3DNow & Co. but for 481 * other modes a fallback engine kicks in. 482 * Note that this can return a decoder that is only active in the hidden and not 483 * available as decoder choice from the outside. 484 * \param mh handle 485 * \return The decoder name or NULL on error. 486 */ 487 MPG123_EXPORT const char* mpg123_current_decoder(mpg123_handle *mh); 488 489 /*@}*/ 490 491 492 /** \defgroup mpg123_output mpg123 output audio format 493 * 494 * Functions to get and select the format of the decoded audio. 495 * 496 * Before you dive in, please be warned that you might get confused by this. 497 * This seems to happen a lot, therefore I am trying to explain in advance. 498 * If you do feel confused and just want to decode your normal MPEG audio files that 499 * don't alter properties in the middle, just use mpg123_open_fixed() with a fixed encoding 500 * and channel count and forget about a matrix of audio formats. If you want to get funky, 501 * read ahead ... 502 * 503 * The mpg123 library decides what output format to use when encountering the first frame in a stream, or actually any frame that is still valid but differs from the frames before in the prompted output format. At such a deciding point, an internal table of allowed encodings, sampling rates and channel setups is consulted. According to this table, an output format is chosen and the decoding engine set up accordingly (including optimized routines for different output formats). This might seem unusual but it just follows from the non-existence of "MPEG audio files" with defined overall properties. There are streams, streams are concatenations of (semi) independent frames. We store streams on disk and call them "MPEG audio files", but that does not change their nature as the decoder is concerned (the LAME/Xing header for gapless decoding makes things interesting again). 504 * 505 * To get to the point: What you do with mpg123_format() and friends is to fill the internal table of allowed formats before it is used. That includes removing support for some formats or adding your forced sample rate (see MPG123_FORCE_RATE) that will be used with the crude internal resampler. Also keep in mind that the sample encoding is just a question of choice -- the MPEG frames do only indicate their native sampling rate and channel count. If you want to decode to integer or float samples, 8 or 16 bit ... that is your decision. In a "clean" world, libmpg123 would always decode to 32 bit float and let you handle any sample conversion. But there are optimized routines that work faster by directly decoding to the desired encoding / accuracy. We prefer efficiency over conceptual tidyness. 506 * 507 * People often start out thinking that mpg123_format() should change the actual decoding format on the fly. That is wrong. It only has effect on the next natural change of output format, when libmpg123 will consult its format table again. To make life easier, you might want to call mpg123_format_none() before any thing else and then just allow one desired encoding and a limited set of sample rates / channel choices that you actually intend to deal with. You can force libmpg123 to decode everything to 44100 KHz, stereo, 16 bit integer ... it will duplicate mono channels and even do resampling if needed (unless that feature is disabled in the build, same with some encodings). But I have to stress that the resampling of libmpg123 is very crude and doesn't even contain any kind of "proper" interpolation. 508 * 509 * In any case, watch out for MPG123_NEW_FORMAT as return message from decoding routines and call mpg123_getformat() to get the currently active output format. 510 * 511 * @{ 512 */ 513 514 /** They can be combined into one number (3) to indicate mono and stereo... */ 515 enum mpg123_channelcount 516 { 517 MPG123_MONO = 1 /**< mono */ 518 ,MPG123_STEREO = 2 /**< stereo */ 519 }; 520 521 /** An array of supported standard sample rates 522 * These are possible native sample rates of MPEG audio files. 523 * You can still force mpg123 to resample to a different one, but by 524 * default you will only get audio in one of these samplings. 525 * This list is in ascending order. 526 * \param list Store a pointer to the sample rates array there. 527 * \param number Store the number of sample rates there. */ 528 MPG123_EXPORT void mpg123_rates(const long **list, size_t *number); 529 530 /** An array of supported audio encodings. 531 * An audio encoding is one of the fully qualified members of mpg123_enc_enum (MPG123_ENC_SIGNED_16, not MPG123_SIGNED). 532 * \param list Store a pointer to the encodings array there. 533 * \param number Store the number of encodings there. */ 534 MPG123_EXPORT void mpg123_encodings(const int **list, size_t *number); 535 536 /** Return the size (in bytes) of one mono sample of the named encoding. 537 * \param encoding The encoding value to analyze. 538 * \return positive size of encoding in bytes, 0 on invalid encoding. */ 539 MPG123_EXPORT int mpg123_encsize(int encoding); 540 541 /** Configure a mpg123 handle to accept no output format at all, 542 * use before specifying supported formats with mpg123_format 543 * \param mh handle 544 * \return MPG123_OK on success 545 */ 546 MPG123_EXPORT int mpg123_format_none(mpg123_handle *mh); 547 548 /** Configure mpg123 handle to accept all formats 549 * (also any custom rate you may set) -- this is default. 550 * \param mh handle 551 * \return MPG123_OK on success 552 */ 553 MPG123_EXPORT int mpg123_format_all(mpg123_handle *mh); 554 555 /** Set the audio format support of a mpg123_handle in detail: 556 * \param mh handle 557 * \param rate The sample rate value (in Hertz). 558 * \param channels A combination of MPG123_STEREO and MPG123_MONO. 559 * \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. 560 * \return MPG123_OK on success, MPG123_ERR if there was an error. */ 561 MPG123_EXPORT int mpg123_format( mpg123_handle *mh 562 , long rate, int channels, int encodings ); 563 564 /** Set the audio format support of a mpg123_handle in detail: 565 * \param mh handle 566 * \param rate The sample rate value (in Hertz). Special value 0 means 567 * all rates (the reason for this variant of mpg123_format()). 568 * \param channels A combination of MPG123_STEREO and MPG123_MONO. 569 * \param encodings A combination of accepted encodings for rate and channels, 570 * p.ex MPG123_ENC_SIGNED16 | MPG123_ENC_ULAW_8 (or 0 for no support). 571 * Please note that some encodings may not be supported in the library build 572 * and thus will be ignored here. 573 * \return MPG123_OK on success, MPG123_ERR if there was an error. */ 574 MPG123_EXPORT int mpg123_format2( mpg123_handle *mh 575 , long rate, int channels, int encodings ); 576 577 /** Check to see if a specific format at a specific rate is supported 578 * by mpg123_handle. 579 * \param mh handle 580 * \param rate sampling rate 581 * \param encoding encoding 582 * \return 0 for no support (that includes invalid parameters), MPG123_STEREO, 583 * MPG123_MONO or MPG123_STEREO|MPG123_MONO. */ 584 MPG123_EXPORT int mpg123_format_support( mpg123_handle *mh 585 , long rate, int encoding ); 586 587 /** Get the current output format written to the addresses given. 588 * If the stream is freshly loaded, this will try to parse enough 589 * of it to give you the format to come. This clears the flag that 590 * would otherwise make the first decoding call return 591 * MPG123_NEW_FORMAT. 592 * \param mh handle 593 * \param rate sampling rate return address 594 * \param channels channel count return address 595 * \param encoding encoding return address 596 * \return MPG123_OK on success 597 */ 598 MPG123_EXPORT int mpg123_getformat( mpg123_handle *mh 599 , long *rate, int *channels, int *encoding ); 600 601 /** Get the current output format written to the addresses given. 602 * This differs from plain mpg123_getformat() in that you can choose 603 * _not_ to clear the flag that would trigger the next decoding call 604 * to return MPG123_NEW_FORMAT in case of a new format arriving. 605 * \param mh handle 606 * \param rate sampling rate return address 607 * \param channels channel count return address 608 * \param encoding encoding return address 609 * \param clear_flag if true, clear internal format flag 610 * \return MPG123_OK on success 611 */ 612 MPG123_EXPORT int mpg123_getformat2( mpg123_handle *mh 613 , long *rate, int *channels, int *encoding, int clear_flag ); 614 615 /*@}*/ 616 617 618 /** \defgroup mpg123_input mpg123 file input and decoding 619 * 620 * Functions for input bitstream and decoding operations. 621 * 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!). 622 * @{ 623 */ 624 625 /** Open a simple MPEG file with fixed properties. 626 * 627 * This function shall simplify the common use case of a plain MPEG 628 * file on disk that you want to decode, with one fixed sample 629 * rate and channel count, and usually a length defined by a Lame/Info/Xing 630 * tag. It will: 631 * 632 * - set the MPG123_NO_FRANKENSTEIN flag 633 * - set up format support according to given parameters, 634 * - open the file, 635 * - query audio format, 636 * - fix the audio format support table to ensure the format stays the same, 637 * - call mpg123_scan() if there is no header frame to tell the track length. 638 * 639 * From that on, you can call mpg123_getformat() for querying the sample 640 * rate (and channel count in case you allowed both) and mpg123_length() 641 * to get a pretty safe number for the duration. 642 * Only the sample rate is left open as that indeed is a fixed property of 643 * MPEG files. You could set MPG123_FORCE_RATE beforehand, but that may trigger 644 * low-quality resampling in the decoder, only do so if in dire need. 645 * The library will convert mono files to stereo for you, and vice versa. 646 * If any constraint cannot be satisified (most likely because of a non-default 647 * build of libmpg123), you get MPG123_ERR returned and can query the detailed 648 * cause from the handle. Only on MPG123_OK there will an open file that you 649 * then close using mpg123_close(), or implicitly on mpg123_delete() or the next 650 * call to open another file. 651 * 652 * So, for your usual CD rip collection, you could use 653 * 654 * mpg123_open_fixed(mh, path, MPG123_STEREO, MPG123_ENC_SIGNED_16) 655 * 656 * and be happy calling mpg123_getformat() to verify 44100 Hz rate, then just 657 * playing away with mpg123_read(). The occasional mono file, or MP2 file, 658 * will also be decoded without you really noticing. Just the speed could be 659 * wrong if you do not care about sample rate at all. 660 * \param mh handle 661 * \param path filesystem path 662 * \param channels allowed channel count, either 1 (MPG123_MONO) or 663 * 2 (MPG123_STEREO), or bitwise or of them, but then you're halfway back to 664 * calling mpg123_format() again;-) 665 * \param encoding a definite encoding from enum mpg123_enc_enum 666 * or a bitmask like for mpg123_format(), defeating the purpose somewhat 667 */ 668 MPG123_EXPORT int mpg123_open_fixed(mpg123_handle *mh, const char *path 669 , int channels, int encoding); 670 671 /** Open and prepare to decode the specified file by filesystem path. 672 * This does not open HTTP urls; libmpg123 contains no networking code. 673 * If you want to decode internet streams, use mpg123_open_fd() or mpg123_open_feed(). 674 * \param mh handle 675 * \param path filesystem path 676 * \return MPG123_OK on success 677 */ 678 MPG123_EXPORT int mpg123_open(mpg123_handle *mh, const char *path); 679 680 /** Use an already opened file descriptor as the bitstream input 681 * mpg123_close() will _not_ close the file descriptor. 682 * \param mh handle 683 * \param fd file descriptor 684 * \return MPG123_OK on success 685 */ 686 MPG123_EXPORT int mpg123_open_fd(mpg123_handle *mh, int fd); 687 688 /** Use an opaque handle as bitstream input. This works only with the 689 * replaced I/O from mpg123_replace_reader_handle()! 690 * mpg123_close() will call the cleanup callback for your handle (if you gave one). 691 * \param mh handle 692 * \param iohandle your handle 693 * \return MPG123_OK on success 694 */ 695 MPG123_EXPORT int mpg123_open_handle(mpg123_handle *mh, void *iohandle); 696 697 /** Open a new bitstream and prepare for direct feeding 698 * This works together with mpg123_decode(); you are responsible for reading and feeding the input bitstream. 699 * Also, you are expected to handle ICY metadata extraction yourself. This 700 * input method does not handle MPG123_ICY_INTERVAL. It does parse ID3 frames, though. 701 * \param mh handle 702 * \return MPG123_OK on success 703 */ 704 MPG123_EXPORT int mpg123_open_feed(mpg123_handle *mh); 705 706 /** Closes the source, if libmpg123 opened it. 707 * \param mh handle 708 * \return MPG123_OK on success 709 */ 710 MPG123_EXPORT int mpg123_close(mpg123_handle *mh); 711 712 /** Read from stream and decode up to outmemsize bytes. 713 * 714 * Note: The type of outmemory changed to a void pointer in mpg123 1.26.0 715 * (API version 45). 716 * 717 * \param mh handle 718 * \param outmemory address of output buffer to write to 719 * \param outmemsize maximum number of bytes to write 720 * \param done address to store the number of actually decoded bytes to 721 * \return MPG123_OK or error/message code 722 */ 723 MPG123_EXPORT int mpg123_read(mpg123_handle *mh 724 , void *outmemory, size_t outmemsize, size_t *done ); 725 726 /** Feed data for a stream that has been opened with mpg123_open_feed(). 727 * It's give and take: You provide the bytestream, mpg123 gives you the decoded samples. 728 * \param mh handle 729 * \param in input buffer 730 * \param size number of input bytes 731 * \return MPG123_OK or error/message code. 732 */ 733 MPG123_EXPORT int mpg123_feed( mpg123_handle *mh 734 , const unsigned char *in, size_t size ); 735 736 /** Decode MPEG Audio from inmemory to outmemory. 737 * This is very close to a drop-in replacement for old mpglib. 738 * When you give zero-sized output buffer the input will be parsed until 739 * decoded data is available. This enables you to get MPG123_NEW_FORMAT (and query it) 740 * without taking decoded data. 741 * Think of this function being the union of mpg123_read() and mpg123_feed() (which it actually is, sort of;-). 742 * You can actually always decide if you want those specialized functions in separate steps or one call this one here. 743 * 744 * Note: The type of outmemory changed to a void pointer in mpg123 1.26.0 745 * (API version 45). 746 * 747 * \param mh handle 748 * \param inmemory input buffer 749 * \param inmemsize number of input bytes 750 * \param outmemory output buffer 751 * \param outmemsize maximum number of output bytes 752 * \param done address to store the number of actually decoded bytes to 753 * \return error/message code (watch out especially for MPG123_NEED_MORE) 754 */ 755 MPG123_EXPORT int mpg123_decode( mpg123_handle *mh 756 , const unsigned char *inmemory, size_t inmemsize 757 , void *outmemory, size_t outmemsize, size_t *done ); 758 759 /** Decode next MPEG frame to internal buffer 760 * or read a frame and return after setting a new format. 761 * \param mh handle 762 * \param num current frame offset gets stored there 763 * \param audio This pointer is set to the internal buffer to read the decoded audio from. 764 * \param bytes number of output bytes ready in the buffer 765 * \return MPG123_OK or error/message code 766 */ 767 MPG123_EXPORT int mpg123_decode_frame( mpg123_handle *mh 768 , off_t *num, unsigned char **audio, size_t *bytes ); 769 770 /** Decode current MPEG frame to internal buffer. 771 * Warning: This is experimental API that might change in future releases! 772 * Please watch mpg123 development closely when using it. 773 * \param mh handle 774 * \param num last frame offset gets stored there 775 * \param audio this pointer is set to the internal buffer to read the decoded audio from. 776 * \param bytes number of output bytes ready in the buffer 777 * \return MPG123_OK or error/message code 778 */ 779 MPG123_EXPORT int mpg123_framebyframe_decode( mpg123_handle *mh 780 , off_t *num, unsigned char **audio, size_t *bytes ); 781 782 /** Find, read and parse the next mp3 frame 783 * Warning: This is experimental API that might change in future releases! 784 * Please watch mpg123 development closely when using it. 785 * \param mh handle 786 * \return MPG123_OK or error/message code 787 */ 788 MPG123_EXPORT int mpg123_framebyframe_next(mpg123_handle *mh); 789 790 /** Get access to the raw input data for the last parsed frame. 791 * This gives you a direct look (and write access) to the frame body data. 792 * Together with the raw header, you can reconstruct the whole raw MPEG stream without junk and meta data, or play games by actually modifying the frame body data before decoding this frame (mpg123_framebyframe_decode()). 793 * A more sane use would be to use this for CRC checking (see mpg123_info() and MPG123_CRC), the first two bytes of the body make up the CRC16 checksum, if present. 794 * You can provide NULL for a parameter pointer when you are not interested in the value. 795 * 796 * \param mh handle 797 * \param header the 4-byte MPEG header 798 * \param bodydata pointer to the frame body stored in the handle (without the header) 799 * \param bodybytes size of frame body in bytes (without the header) 800 * \return MPG123_OK if there was a yet un-decoded frame to get the 801 * data from, MPG123_BAD_HANDLE or MPG123_ERR otherwise (without further 802 * explanation, the error state of the mpg123_handle is not modified by 803 * this function). 804 */ 805 MPG123_EXPORT int mpg123_framedata( mpg123_handle *mh 806 , unsigned long *header, unsigned char **bodydata, size_t *bodybytes ); 807 808 /** Get the input position (byte offset in stream) of the last parsed frame. 809 * This can be used for external seek index building, for example. 810 * It just returns the internally stored offset, regardless of validity -- 811 * you ensure that a valid frame has been parsed before! 812 * \param mh handle 813 * \return byte offset in stream 814 */ 815 MPG123_EXPORT off_t mpg123_framepos(mpg123_handle *mh); 816 817 /*@}*/ 818 819 820 /** \defgroup mpg123_seek mpg123 position and seeking 821 * 822 * Functions querying and manipulating position in the decoded audio bitstream. 823 * The position is measured in decoded audio samples, or MPEG frame offset for the specific functions. 824 * 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;-) 825 * The general usage is modelled after stdlib's ftell() and fseek(). 826 * 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: 827 * - SEEK_SET: set position to (or near to) specified offset 828 * - SEEK_CUR: change position by offset from now 829 * - SEEK_END: set position to offset from end 830 * 831 * Note that sample-accurate seek only works when gapless support has been enabled at compile time; seek is frame-accurate otherwise. 832 * 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)! 833 * Short: When you care about the sample position, don't mess with those parameters;-) 834 * Also, seeking is not guaranteed to work for all streams (underlying stream may not support it). 835 * And yet another caveat: If the stream is concatenated out of differing pieces (Frankenstein stream), seeking may suffer, too. 836 * 837 * @{ 838 */ 839 840 /** Returns the current position in samples. 841 * On the next successful read, you'd get that sample. 842 * \param mh handle 843 * \return sample offset or MPG123_ERR (null handle) 844 */ 845 MPG123_EXPORT off_t mpg123_tell(mpg123_handle *mh); 846 847 /** Returns the frame number that the next read will give you data from. 848 * \param mh handle 849 * \return frame offset or MPG123_ERR (null handle) 850 */ 851 MPG123_EXPORT off_t mpg123_tellframe(mpg123_handle *mh); 852 853 /** Returns the current byte offset in the input stream. 854 * \param mh handle 855 * \return byte offset or MPG123_ERR (null handle) 856 */ 857 MPG123_EXPORT off_t mpg123_tell_stream(mpg123_handle *mh); 858 859 /** Seek to a desired sample offset. 860 * Usage is modelled afer the standard lseek(). 861 * \param mh handle 862 * \param sampleoff offset in PCM samples 863 * \param whence one of SEEK_SET, SEEK_CUR or SEEK_END 864 * \return The resulting offset >= 0 or error/message code 865 */ 866 MPG123_EXPORT off_t mpg123_seek( mpg123_handle *mh 867 , off_t sampleoff, int whence ); 868 869 /** Seek to a desired sample offset in data feeding mode. 870 * 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. 871 * \param mh handle 872 * \param sampleoff offset in PCM samples 873 * \param whence one of SEEK_SET, SEEK_CUR or SEEK_END 874 * \param input_offset The position it expects to be at the 875 * next time data is fed to mpg123_decode(). 876 * \return The resulting offset >= 0 or error/message code */ 877 MPG123_EXPORT off_t mpg123_feedseek( mpg123_handle *mh 878 , off_t sampleoff, int whence, off_t *input_offset ); 879 880 /** Seek to a desired MPEG frame offset. 881 * Usage is modelled afer the standard lseek(). 882 * \param mh handle 883 * \param frameoff offset in MPEG frames 884 * \param whence one of SEEK_SET, SEEK_CUR or SEEK_END 885 * \return The resulting offset >= 0 or error/message code */ 886 MPG123_EXPORT off_t mpg123_seek_frame( mpg123_handle *mh 887 , off_t frameoff, int whence ); 888 889 /** Return a MPEG frame offset corresponding to an offset in seconds. 890 * 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. 891 * \return frame offset >= 0 or error/message code */ 892 MPG123_EXPORT off_t mpg123_timeframe(mpg123_handle *mh, double sec); 893 894 /** Give access to the frame index table that is managed for seeking. 895 * You are asked not to modify the values... Use mpg123_set_index to set the 896 * seek index 897 * \param mh handle 898 * \param offsets pointer to the index array 899 * \param step one index byte offset advances this many MPEG frames 900 * \param fill number of recorded index offsets; size of the array 901 * \return MPG123_OK on success 902 */ 903 MPG123_EXPORT int mpg123_index( mpg123_handle *mh 904 , off_t **offsets, off_t *step, size_t *fill ); 905 906 /** Set the frame index table 907 * Setting offsets to NULL and fill > 0 will allocate fill entries. Setting offsets 908 * to NULL and fill to 0 will clear the index and free the allocated memory used by the index. 909 * \param mh handle 910 * \param offsets pointer to the index array 911 * \param step one index byte offset advances this many MPEG frames 912 * \param fill number of recorded index offsets; size of the array 913 * \return MPG123_OK on success 914 */ 915 MPG123_EXPORT int mpg123_set_index( mpg123_handle *mh 916 , off_t *offsets, off_t step, size_t fill ); 917 918 /** An old crutch to keep old mpg123 binaries happy. 919 * WARNING: This function is there only to avoid runtime linking errors with 920 * standalone mpg123 before version 1.23.0 (if you strangely update the 921 * library but not the end-user program) and actually is broken 922 * for various cases (p.ex. 24 bit output). Do never use. It might eventually 923 * be purged from the library. 924 */ 925 MPG123_EXPORT int mpg123_position( mpg123_handle *mh, off_t frame_offset, off_t buffered_bytes, off_t *current_frame, off_t *frames_left, double *current_seconds, double *seconds_left); 926 927 /*@}*/ 928 929 930 /** \defgroup mpg123_voleq mpg123 volume and equalizer 931 * 932 * @{ 933 */ 934 935 /** another channel enumeration, for left/right choice */ 936 enum mpg123_channels 937 { 938 MPG123_LEFT=0x1 /**< The Left Channel. */ 939 ,MPG123_RIGHT=0x2 /**< The Right Channel. */ 940 ,MPG123_LR=0x3 /**< Both left and right channel; same as MPG123_LEFT|MPG123_RIGHT */ 941 }; 942 943 /** Set the 32 Band Audio Equalizer settings. 944 * \param mh handle 945 * \param channel Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both. 946 * \param band The equaliser band to change (from 0 to 31) 947 * \param val The (linear) adjustment factor. 948 * \return MPG123_OK on success 949 */ 950 MPG123_EXPORT int mpg123_eq( mpg123_handle *mh 951 , enum mpg123_channels channel, int band, double val ); 952 953 /** Get the 32 Band Audio Equalizer settings. 954 * \param mh handle 955 * \param channel Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for (arithmetic mean of) both. 956 * \param band The equaliser band to change (from 0 to 31) 957 * \return The (linear) adjustment factor (zero for pad parameters) */ 958 MPG123_EXPORT double mpg123_geteq(mpg123_handle *mh 959 , enum mpg123_channels channel, int band); 960 961 /** Reset the 32 Band Audio Equalizer settings to flat 962 * \param mh handle 963 * \return MPG123_OK on success 964 */ 965 MPG123_EXPORT int mpg123_reset_eq(mpg123_handle *mh); 966 967 /** Set the absolute output volume including the RVA setting, 968 * vol<0 just applies (a possibly changed) RVA setting. 969 * \param mh handle 970 * \param vol volume value (linear factor) 971 * \return MPG123_OK on success 972 */ 973 MPG123_EXPORT int mpg123_volume(mpg123_handle *mh, double vol); 974 975 /** Adjust output volume including the RVA setting by chosen amount 976 * \param mh handle 977 * \param change volume value (linear factor increment) 978 * \return MPG123_OK on success 979 */ 980 MPG123_EXPORT int mpg123_volume_change(mpg123_handle *mh, double change); 981 982 /** Return current volume setting, the actual value due to RVA, and the RVA 983 * adjustment itself. It's all as double float value to abstract the sample 984 * format. The volume values are linear factors / amplitudes (not percent) 985 * and the RVA value is in decibels. 986 * \param mh handle 987 * \param base return address for base volume (linear factor) 988 * \param really return address for actual volume (linear factor) 989 * \param rva_db return address for RVA value (decibels) 990 * \return MPG123_OK on success 991 */ 992 MPG123_EXPORT int mpg123_getvolume(mpg123_handle *mh, double *base, double *really, double *rva_db); 993 994 /* TODO: Set some preamp in addition / to replace internal RVA handling? */ 995 996 /*@}*/ 997 998 999 /** \defgroup mpg123_status mpg123 status and information 1000 * 1001 * @{ 1002 */ 1003 1004 /** Enumeration of the mode types of Variable Bitrate */ 1005 enum mpg123_vbr { 1006 MPG123_CBR=0, /**< Constant Bitrate Mode (default) */ 1007 MPG123_VBR, /**< Variable Bitrate Mode */ 1008 MPG123_ABR /**< Average Bitrate Mode */ 1009 }; 1010 1011 /** Enumeration of the MPEG Versions */ 1012 enum mpg123_version { 1013 MPG123_1_0=0, /**< MPEG Version 1.0 */ 1014 MPG123_2_0, /**< MPEG Version 2.0 */ 1015 MPG123_2_5 /**< MPEG Version 2.5 */ 1016 }; 1017 1018 1019 /** Enumeration of the MPEG Audio mode. 1020 * Only the mono mode has 1 channel, the others have 2 channels. */ 1021 enum mpg123_mode { 1022 MPG123_M_STEREO=0, /**< Standard Stereo. */ 1023 MPG123_M_JOINT, /**< Joint Stereo. */ 1024 MPG123_M_DUAL, /**< Dual Channel. */ 1025 MPG123_M_MONO /**< Single Channel. */ 1026 }; 1027 1028 1029 /** Enumeration of the MPEG Audio flag bits */ 1030 enum mpg123_flags { 1031 MPG123_CRC=0x1, /**< The bitstream is error protected using 16-bit CRC. */ 1032 MPG123_COPYRIGHT=0x2, /**< The bitstream is copyrighted. */ 1033 MPG123_PRIVATE=0x4, /**< The private bit has been set. */ 1034 MPG123_ORIGINAL=0x8 /**< The bitstream is an original, not a copy. */ 1035 }; 1036 1037 /** Data structure for storing information about a frame of MPEG Audio */ 1038 struct mpg123_frameinfo 1039 { 1040 enum mpg123_version version; /**< The MPEG version (1.0/2.0/2.5). */ 1041 int layer; /**< The MPEG Audio Layer (MP1/MP2/MP3). */ 1042 long rate; /**< The sampling rate in Hz. */ 1043 enum mpg123_mode mode; /**< The audio mode (Mono, Stereo, Joint-stero, Dual Channel). */ 1044 int mode_ext; /**< The mode extension bit flag. */ 1045 int framesize; /**< The size of the frame (in bytes, including header). */ 1046 enum mpg123_flags flags; /**< 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. */ 1047 int emphasis; /**< The emphasis type. */ 1048 int bitrate; /**< Bitrate of the frame (kbps). */ 1049 int abr_rate; /**< The target average bitrate. */ 1050 enum mpg123_vbr vbr; /**< The VBR mode. */ 1051 }; 1052 1053 /** Data structure for even more detailed information out of the decoder, 1054 * for MPEG layer III only. 1055 * This was added to support the frame analyzer by the Lame project and 1056 * just follows what was used there before. You know what the fields mean 1057 * if you want use this structure. */ 1058 struct mpg123_moreinfo 1059 { 1060 double xr[2][2][576]; 1061 double sfb[2][2][22]; /* [2][2][SBMAX_l] */ 1062 double sfb_s[2][2][3*13]; /* [2][2][3*SBMAX_s] */ 1063 int qss[2][2]; 1064 int big_values[2][2]; 1065 int sub_gain[2][2][3]; 1066 int scalefac_scale[2][2]; 1067 int preflag[2][2]; 1068 int blocktype[2][2]; 1069 int mixed[2][2]; 1070 int mainbits[2][2]; 1071 int sfbits[2][2]; 1072 int scfsi[2]; 1073 int maindata; 1074 int padding; 1075 }; 1076 1077 /** Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo structure. 1078 * \param mh handle 1079 * \param mi address of existing frameinfo structure to write to 1080 * \return MPG123_OK on success 1081 */ 1082 MPG123_EXPORT int mpg123_info(mpg123_handle *mh, struct mpg123_frameinfo *mi); 1083 1084 /** Trigger collection of additional decoder information while decoding. 1085 * \param mh handle 1086 * \param mi pointer to data storage (NULL to disable collection) 1087 * \return MPG123_OK if the collection was enabled/disabled as desired, MPG123_ERR 1088 * otherwise (e.g. if the feature is disabled) 1089 */ 1090 MPG123_EXPORT int mpg123_set_moreinfo( mpg123_handle *mh 1091 , struct mpg123_moreinfo *mi ); 1092 1093 /** Get the safe output buffer size for all cases 1094 * (when you want to replace the internal buffer) 1095 * \return safe buffer size 1096 */ 1097 MPG123_EXPORT size_t mpg123_safe_buffer(void); 1098 1099 /** Make a full parsing scan of each frame in the file. ID3 tags are found. An 1100 * accurate length value is stored. Seek index will be filled. A seek back to 1101 * current position is performed. At all, this function refuses work when 1102 * stream is not seekable. 1103 * \param mh handle 1104 * \return MPG123_OK on success 1105 */ 1106 MPG123_EXPORT int mpg123_scan(mpg123_handle *mh); 1107 1108 /** Return, if possible, the full (expected) length of current track in 1109 * MPEG frames. 1110 * \param mh handle 1111 * \return length >= 0 or MPG123_ERR if there is no length guess possible. 1112 */ 1113 MPG123_EXPORT off_t mpg123_framelength(mpg123_handle *mh); 1114 1115 /** Return, if possible, the full (expected) length of current 1116 * track in samples (PCM frames). 1117 * 1118 * This relies either on an Info frame at the beginning or a previous 1119 * call to mpg123_scan() to get the real number of MPEG frames in a 1120 * file. It will guess based on file size if neither Info frame nor 1121 * scan data are present. In any case, there is no guarantee that the 1122 * decoder will not give you more data, for example in case the open 1123 * file gets appended to during decoding. 1124 * \param mh handle 1125 * \return length >= 0 or MPG123_ERR if there is no length guess possible. 1126 */ 1127 MPG123_EXPORT off_t mpg123_length(mpg123_handle *mh); 1128 1129 /** Override the value for file size in bytes. 1130 * Useful for getting sensible track length values in feed mode or for HTTP streams. 1131 * \param mh handle 1132 * \param size file size in bytes 1133 * \return MPG123_OK on success 1134 */ 1135 MPG123_EXPORT int mpg123_set_filesize(mpg123_handle *mh, off_t size); 1136 1137 /** Get MPEG frame duration in seconds. 1138 * \param mh handle 1139 * \return frame duration in seconds, <0 on error 1140 */ 1141 MPG123_EXPORT double mpg123_tpf(mpg123_handle *mh); 1142 1143 /** Get MPEG frame duration in samples. 1144 * \param mh handle 1145 * \return samples per frame for the most recently parsed frame; <0 on errors 1146 */ 1147 MPG123_EXPORT int mpg123_spf(mpg123_handle *mh); 1148 1149 /** Get and reset the clip count. 1150 * \param mh handle 1151 * \return count of clipped samples 1152 */ 1153 MPG123_EXPORT long mpg123_clip(mpg123_handle *mh); 1154 1155 1156 /** The key values for state information from mpg123_getstate(). */ 1157 enum mpg123_state 1158 { 1159 MPG123_ACCURATE = 1 /**< Query if positons are currently accurate (integer value, 0 if false, 1 if true). */ 1160 ,MPG123_BUFFERFILL /**< Get fill of internal (feed) input buffer as integer byte count returned as long and as double. An error is returned on integer overflow while converting to (signed) long, but the returned floating point value shold still be fine. */ 1161 ,MPG123_FRANKENSTEIN /**< Stream consists of carelessly stitched together files. Seeking may yield unexpected results (also with MPG123_ACCURATE, it may be confused). */ 1162 ,MPG123_FRESH_DECODER /**< Decoder structure has been updated, possibly indicating changed stream (integer value, 0 if false, 1 if true). Flag is cleared after retrieval. */ 1163 ,MPG123_ENC_DELAY /** Encoder delay read from Info tag (layer III, -1 if unknown). */ 1164 ,MPG123_ENC_PADDING /** Encoder padding read from Info tag (layer III, -1 if unknown). */ 1165 ,MPG123_DEC_DELAY /** Decoder delay (for layer III only, -1 otherwise). */ 1166 }; 1167 1168 /** Get various current decoder/stream state information. 1169 * \param mh handle 1170 * \param key the key to identify the information to give. 1171 * \param val the address to return (long) integer values to 1172 * \param fval the address to return floating point values to 1173 * \return MPG123_OK on success 1174 */ 1175 MPG123_EXPORT int mpg123_getstate( mpg123_handle *mh 1176 , enum mpg123_state key, long *val, double *fval ); 1177 1178 /*@}*/ 1179 1180 1181 /** \defgroup mpg123_metadata mpg123 metadata handling 1182 * 1183 * Functions to retrieve the metadata from MPEG Audio files and streams. 1184 * Also includes string handling functions. 1185 * 1186 * @{ 1187 */ 1188 1189 /** Data structure for storing strings in a safer way than a standard C-String. 1190 * Can also hold a number of null-terminated strings. */ 1191 typedef struct 1192 { 1193 char* p; /**< pointer to the string data */ 1194 size_t size; /**< raw number of bytes allocated */ 1195 size_t fill; /**< number of used bytes (including closing zero byte) */ 1196 } mpg123_string; 1197 1198 /** Allocate and intialize a new string. 1199 * \param val optional initial string value (can be NULL) 1200 */ 1201 MPG123_EXPORT mpg123_string* mpg123_new_string(const char* val); 1202 1203 /** Free memory of contents and the string structure itself. 1204 * \param sb string handle 1205 */ 1206 MPG123_EXPORT void mpg123_delete_string(mpg123_string* sb); 1207 1208 /** Initialize an existing mpg123_string structure to {NULL, 0, 0}. 1209 * If you hand in a NULL pointer here, your program should crash. The other 1210 * string functions are more forgiving, but this one here is too basic. 1211 * \param sb string handle (address of existing structure on your side) 1212 */ 1213 MPG123_EXPORT void mpg123_init_string(mpg123_string* sb); 1214 1215 /** Free-up memory of the contents of an mpg123_string (not the struct itself). 1216 * This also calls mpg123_init_string() and hence is safe to be called 1217 * repeatedly. 1218 * \param sb string handle 1219 */ 1220 MPG123_EXPORT void mpg123_free_string(mpg123_string* sb); 1221 1222 /** Change the size of a mpg123_string 1223 * \param sb string handle 1224 * \param news new size in bytes 1225 * \return 0 on error, 1 on success 1226 */ 1227 MPG123_EXPORT int mpg123_resize_string(mpg123_string* sb, size_t news); 1228 1229 /** Increase size of a mpg123_string if necessary (it may stay larger). 1230 * Note that the functions for adding and setting in current libmpg123 1231 * use this instead of mpg123_resize_string(). 1232 * That way, you can preallocate memory and safely work afterwards with 1233 * pieces. 1234 * \param sb string handle 1235 * \param news new minimum size 1236 * \return 0 on error, 1 on success 1237 */ 1238 MPG123_EXPORT int mpg123_grow_string(mpg123_string* sb, size_t news); 1239 1240 /** Copy the contents of one mpg123_string string to another. 1241 * Yes the order of arguments is reversed compated to memcpy(). 1242 * \param from string handle 1243 * \param to string handle 1244 * \return 0 on error, 1 on success 1245 */ 1246 MPG123_EXPORT int mpg123_copy_string(mpg123_string* from, mpg123_string* to); 1247 1248 /** Move the contents of one mpg123_string string to another. 1249 * This frees any memory associated with the target and moves over the 1250 * pointers from the source, leaving the source without content after 1251 * that. The only possible error is that you hand in NULL pointers. 1252 * If you handed in a valid source, its contents will be gone, even if 1253 * there was no target to move to. If you hand in a valid target, its 1254 * original contents will also always be gone, to be replaced with the 1255 * source's contents if there was some. 1256 * \param from source string handle 1257 * \param to target string handle 1258 * \return 0 on error, 1 on success 1259 */ 1260 MPG123_EXPORT int mpg123_move_string(mpg123_string* from, mpg123_string* to); 1261 1262 /** Append a C-String to an mpg123_string 1263 * \param sb string handle 1264 * \param stuff to append 1265 * \return 0 on error, 1 on success 1266 */ 1267 MPG123_EXPORT int mpg123_add_string(mpg123_string* sb, const char* stuff); 1268 1269 /** Append a C-substring to an mpg123 string 1270 * \param sb string handle 1271 * \param stuff content to copy 1272 * \param from offset to copy from 1273 * \param count number of characters to copy (a null-byte is always appended) 1274 * \return 0 on error, 1 on success 1275 */ 1276 MPG123_EXPORT int mpg123_add_substring( mpg123_string *sb 1277 , const char *stuff, size_t from, size_t count ); 1278 1279 /** Set the content of a mpg123_string to a C-string 1280 * \param sb string handle 1281 * \param stuff content to copy 1282 * \return 0 on error, 1 on success 1283 */ 1284 MPG123_EXPORT int mpg123_set_string(mpg123_string* sb, const char* stuff); 1285 1286 /** Set the content of a mpg123_string to a C-substring 1287 * \param sb string handle 1288 * \param stuff the future content 1289 * \param from offset to copy from 1290 * \param count number of characters to copy (a null-byte is always appended) 1291 * \return 0 on error, 1 on success 1292 */ 1293 MPG123_EXPORT int mpg123_set_substring( mpg123_string *sb 1294 , const char *stuff, size_t from, size_t count ); 1295 1296 /** Count characters in a mpg123 string (non-null bytes or Unicode points). 1297 * This function is of limited use, as it does just count code points 1298 * encoded in an UTF-8 string, only loosely related to the count of visible 1299 * characters. Get your full Unicode handling support elsewhere. 1300 * \param sb string handle 1301 * \param utf8 a flag to tell if the string is in utf8 encoding 1302 * \return character count 1303 */ 1304 MPG123_EXPORT size_t mpg123_strlen(mpg123_string *sb, int utf8); 1305 1306 /** Remove trailing \\r and \\n, if present. 1307 * \param sb string handle 1308 * \return 0 on error, 1 on success 1309 */ 1310 MPG123_EXPORT int mpg123_chomp_string(mpg123_string *sb); 1311 1312 /** Determine if two strings contain the same data. 1313 * This only returns 1 if both given handles are non-NULL and 1314 * if they are filled with the same bytes. 1315 * \param a first string handle 1316 * \param b second string handle 1317 * \return 0 for different strings, 1 for identical 1318 */ 1319 MPG123_EXPORT int mpg123_same_string(mpg123_string *a, mpg123_string *b); 1320 1321 /** The mpg123 text encodings. This contains encodings we encounter in ID3 tags or ICY meta info. */ 1322 enum mpg123_text_encoding 1323 { 1324 mpg123_text_unknown = 0 /**< Unkown encoding... mpg123_id3_encoding can return that on invalid codes. */ 1325 ,mpg123_text_utf8 = 1 /**< UTF-8 */ 1326 ,mpg123_text_latin1 = 2 /**< ISO-8859-1. Note that sometimes latin1 in ID3 is abused for totally different encodings. */ 1327 ,mpg123_text_icy = 3 /**< ICY metadata encoding, usually CP-1252 but we take it as UTF-8 if it qualifies as such. */ 1328 ,mpg123_text_cp1252 = 4 /**< Really CP-1252 without any guessing. */ 1329 ,mpg123_text_utf16 = 5 /**< Some UTF-16 encoding. The last of a set of leading BOMs (byte order mark) rules. 1330 * When there is no BOM, big endian ordering is used. Note that UCS-2 qualifies as UTF-8 when 1331 * you don't mess with the reserved code points. If you want to decode little endian data 1332 * without BOM you need to prepend 0xff 0xfe yourself. */ 1333 ,mpg123_text_utf16bom = 6 /**< Just an alias for UTF-16, ID3v2 has this as distinct code. */ 1334 ,mpg123_text_utf16be = 7 /**< Another alias for UTF16 from ID3v2. Note, that, because of the mess that is reality, 1335 * BOMs are used if encountered. There really is not much distinction between the UTF16 types for mpg123 1336 * One exception: Since this is seen in ID3v2 tags, leading null bytes are skipped for all other UTF16 1337 * types (we expect a BOM before real data there), not so for utf16be!*/ 1338 ,mpg123_text_max = 7 /**< Placeholder for the maximum encoding value. */ 1339 }; 1340 1341 /** The encoding byte values from ID3v2. */ 1342 enum mpg123_id3_enc 1343 { 1344 mpg123_id3_latin1 = 0 /**< Note: This sometimes can mean anything in practice... */ 1345 ,mpg123_id3_utf16bom = 1 /**< UTF16, UCS-2 ... it's all the same for practical purposes. */ 1346 ,mpg123_id3_utf16be = 2 /**< Big-endian UTF-16, BOM see note for mpg123_text_utf16be. */ 1347 ,mpg123_id3_utf8 = 3 /**< Our lovely overly ASCII-compatible 8 byte encoding for the world. */ 1348 ,mpg123_id3_enc_max = 3 /**< Placeholder to check valid range of encoding byte. */ 1349 }; 1350 1351 /** Convert ID3 encoding byte to mpg123 encoding index. 1352 * \param id3_enc_byte the ID3 encoding code 1353 * \return the mpg123 encoding index 1354 */ 1355 1356 MPG123_EXPORT enum mpg123_text_encoding mpg123_enc_from_id3(unsigned char id3_enc_byte); 1357 1358 /** Store text data in string, after converting to UTF-8 from indicated encoding 1359 * 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). 1360 * Also, you might want to take a bit of care with preparing the data; for example, strip leading zeroes (I have seen that). 1361 * \param sb target string 1362 * \param enc mpg123 text encoding value 1363 * \param source source buffer with plain unsigned bytes (you might need to cast from signed char) 1364 * \param source_size number of bytes in the source buffer 1365 * \return 0 on error, 1 on success (on error, mpg123_free_string is called on sb) 1366 */ 1367 MPG123_EXPORT int mpg123_store_utf8(mpg123_string *sb, enum mpg123_text_encoding enc, const unsigned char *source, size_t source_size); 1368 1369 /** Sub data structure for ID3v2, for storing various text fields (including comments). 1370 * This is for ID3v2 COMM, TXXX and all the other text fields. 1371 * Only COMM, TXXX and USLT may have a description, only COMM and USLT 1372 * have a language. 1373 * You should consult the ID3v2 specification for the use of the various text fields 1374 * ("frames" in ID3v2 documentation, I use "fields" here to separate from MPEG frames). */ 1375 typedef struct 1376 { 1377 char lang[3]; /**< Three-letter language code (not terminated). */ 1378 char id[4]; /**< The ID3v2 text field id, like TALB, TPE2, ... (4 characters, no string termination). */ 1379 mpg123_string description; /**< Empty for the generic comment... */ 1380 mpg123_string text; /**< ... */ 1381 } mpg123_text; 1382 1383 /** The picture type values from ID3v2. */ 1384 enum mpg123_id3_pic_type 1385 { 1386 mpg123_id3_pic_other = 0 /**< see ID3v2 docs */ 1387 ,mpg123_id3_pic_icon = 1 /**< see ID3v2 docs */ 1388 ,mpg123_id3_pic_other_icon = 2 /**< see ID3v2 docs */ 1389 ,mpg123_id3_pic_front_cover = 3 /**< see ID3v2 docs */ 1390 ,mpg123_id3_pic_back_cover = 4 /**< see ID3v2 docs */ 1391 ,mpg123_id3_pic_leaflet = 5 /**< see ID3v2 docs */ 1392 ,mpg123_id3_pic_media = 6 /**< see ID3v2 docs */ 1393 ,mpg123_id3_pic_lead = 7 /**< see ID3v2 docs */ 1394 ,mpg123_id3_pic_artist = 8 /**< see ID3v2 docs */ 1395 ,mpg123_id3_pic_conductor = 9 /**< see ID3v2 docs */ 1396 ,mpg123_id3_pic_orchestra = 10 /**< see ID3v2 docs */ 1397 ,mpg123_id3_pic_composer = 11 /**< see ID3v2 docs */ 1398 ,mpg123_id3_pic_lyricist = 12 /**< see ID3v2 docs */ 1399 ,mpg123_id3_pic_location = 13 /**< see ID3v2 docs */ 1400 ,mpg123_id3_pic_recording = 14 /**< see ID3v2 docs */ 1401 ,mpg123_id3_pic_performance = 15 /**< see ID3v2 docs */ 1402 ,mpg123_id3_pic_video = 16 /**< see ID3v2 docs */ 1403 ,mpg123_id3_pic_fish = 17 /**< see ID3v2 docs */ 1404 ,mpg123_id3_pic_illustration = 18 /**< see ID3v2 docs */ 1405 ,mpg123_id3_pic_artist_logo = 19 /**< see ID3v2 docs */ 1406 ,mpg123_id3_pic_publisher_logo = 20 /**< see ID3v2 docs */ 1407 }; 1408 1409 /** Sub data structure for ID3v2, for storing picture data including comment. 1410 * This is for the ID3v2 APIC field. You should consult the ID3v2 specification 1411 * for the use of the APIC field ("frames" in ID3v2 documentation, I use "fields" 1412 * here to separate from MPEG frames). */ 1413 typedef struct 1414 { 1415 char type; /**< mpg123_id3_pic_type value */ 1416 mpg123_string description; /**< description string */ 1417 mpg123_string mime_type; /**< MIME type */ 1418 size_t size; /**< size in bytes */ 1419 unsigned char* data; /**< pointer to the image data */ 1420 } mpg123_picture; 1421 1422 /** Data structure for storing IDV3v2 tags. 1423 * This structure is not a direct binary mapping with the file contents. 1424 * The ID3v2 text frames are allowed to contain multiple strings. 1425 * So check for null bytes until you reach the mpg123_string fill. 1426 * All text is encoded in UTF-8. */ 1427 typedef struct 1428 { 1429 unsigned char version; /**< 3 or 4 for ID3v2.3 or ID3v2.4. */ 1430 mpg123_string *title; /**< Title string (pointer into text_list). */ 1431 mpg123_string *artist; /**< Artist string (pointer into text_list). */ 1432 mpg123_string *album; /**< Album string (pointer into text_list). */ 1433 mpg123_string *year; /**< The year as a string (pointer into text_list). */ 1434 mpg123_string *genre; /**< Genre String (pointer into text_list). The genre string(s) may very well need postprocessing, esp. for ID3v2.3. */ 1435 mpg123_string *comment; /**< Pointer to last encountered comment text with empty description. */ 1436 /* Encountered ID3v2 fields are appended to these lists. 1437 There can be multiple occurences, the pointers above always point to the last encountered data. */ 1438 mpg123_text *comment_list; /**< Array of comments. */ 1439 size_t comments; /**< Number of comments. */ 1440 mpg123_text *text; /**< Array of ID3v2 text fields (including USLT) */ 1441 size_t texts; /**< Numer of text fields. */ 1442 mpg123_text *extra; /**< The array of extra (TXXX) fields. */ 1443 size_t extras; /**< Number of extra text (TXXX) fields. */ 1444 mpg123_picture *picture; /**< Array of ID3v2 pictures fields (APIC). 1445 Only populated if MPG123_PICTURE flag is set! */ 1446 size_t pictures; /**< Number of picture (APIC) fields. */ 1447 } mpg123_id3v2; 1448 1449 /** Data structure for ID3v1 tags (the last 128 bytes of a file). 1450 * Don't take anything for granted (like string termination)! 1451 * Also note the change ID3v1.1 did: comment[28] = 0; comment[29] = track_number 1452 * It is your task to support ID3v1 only or ID3v1.1 ...*/ 1453 typedef struct 1454 { 1455 char tag[3]; /**< Always the string "TAG", the classic intro. */ 1456 char title[30]; /**< Title string. */ 1457 char artist[30]; /**< Artist string. */ 1458 char album[30]; /**< Album string. */ 1459 char year[4]; /**< Year string. */ 1460 char comment[30]; /**< Comment string. */ 1461 unsigned char genre; /**< Genre index. */ 1462 } mpg123_id3v1; 1463 1464 #define MPG123_ID3 0x3 /**< 0011 There is some ID3 info. Also matches 0010 or NEW_ID3. */ 1465 #define MPG123_NEW_ID3 0x1 /**< 0001 There is ID3 info that changed since last call to mpg123_id3. */ 1466 #define MPG123_ICY 0xc /**< 1100 There is some ICY info. Also matches 0100 or NEW_ICY.*/ 1467 #define MPG123_NEW_ICY 0x4 /**< 0100 There is ICY info that changed since last call to mpg123_icy. */ 1468 1469 /** Query if there is (new) meta info, be it ID3 or ICY (or something new in future). 1470 * \param mh handle 1471 * \return combination of flags, 0 on error (same as "nothing new") 1472 */ 1473 MPG123_EXPORT int mpg123_meta_check(mpg123_handle *mh); 1474 1475 /** Clean up meta data storage (ID3v2 and ICY), freeing memory. 1476 * \param mh handle 1477 */ 1478 MPG123_EXPORT void mpg123_meta_free(mpg123_handle *mh); 1479 1480 /** Point v1 and v2 to existing data structures wich may change on any next read/decode function call. 1481 * v1 and/or v2 can be set to NULL when there is no corresponding data. 1482 * \return MPG123_OK on success 1483 */ 1484 MPG123_EXPORT int mpg123_id3( mpg123_handle *mh 1485 , mpg123_id3v1 **v1, mpg123_id3v2 **v2 ); 1486 1487 /** Return pointers to and size of stored raw ID3 data if storage has 1488 * been configured with MPG123_RAW_ID3 and stream parsing passed the 1489 * metadata already. Null value with zero size is a possibility! 1490 * The storage can change at any next API call. 1491 * \param v1 address to store pointer to v1 tag 1492 * \param v1_size size of v1 data in bytes 1493 * \param v2 address to store pointer to v2 tag 1494 * \param v2_size size of v2 data in bytes 1495 * \return MPG123_OK or MPG123_ERR. Only on MPG123_OK the output 1496 * values are set. 1497 */ 1498 MPG123_EXPORT int mpg123_id3_raw( mpg123_handle *mh 1499 , unsigned char **v1, size_t *v1_size 1500 , unsigned char **v2, size_t *v2_size ); 1501 1502 /** Point icy_meta to existing data structure wich may change on any next read/decode function call. 1503 * \param mh handle 1504 * \param icy_meta return address for ICY meta string (set to NULL if nothing there) 1505 * \return MPG123_OK on success 1506 */ 1507 MPG123_EXPORT int mpg123_icy(mpg123_handle *mh, char **icy_meta); 1508 1509 /** Decode from windows-1252 (the encoding ICY metainfo used) to UTF-8. 1510 * Note that this is very similar to mpg123_store_utf8(&sb, mpg123_text_icy, icy_text, strlen(icy_text+1)) . 1511 * \param icy_text The input data in ICY encoding 1512 * \return pointer to newly allocated buffer with UTF-8 data (You free() it!) */ 1513 MPG123_EXPORT char* mpg123_icy2utf8(const char* icy_text); 1514 1515 1516 /* @} */ 1517 1518 1519 /** \defgroup mpg123_advpar mpg123 advanced parameter API 1520 * 1521 * Direct access to a parameter set without full handle around it. 1522 * Possible uses: 1523 * - Influence behaviour of library _during_ initialization of handle (MPG123_VERBOSE). 1524 * - Use one set of parameters for multiple handles. 1525 * 1526 * The functions for handling mpg123_pars (mpg123_par() and mpg123_fmt() 1527 * family) directly return a fully qualified mpg123 error code, the ones 1528 * operating on full handles normally MPG123_OK or MPG123_ERR, storing the 1529 * specific error code itseld inside the handle. 1530 * 1531 * @{ 1532 */ 1533 1534 /** Opaque structure for the libmpg123 decoder parameters. */ 1535 struct mpg123_pars_struct; 1536 1537 /** Opaque structure for the libmpg123 decoder parameters. */ 1538 typedef struct mpg123_pars_struct mpg123_pars; 1539 1540 /** Create a handle with preset parameters. 1541 * \param mp parameter handle 1542 * \param decoder decoder choice 1543 * \param error error code return address 1544 * \return mpg123 handle 1545 */ 1546 MPG123_EXPORT mpg123_handle *mpg123_parnew( mpg123_pars *mp 1547 , const char* decoder, int *error ); 1548 1549 /** Allocate memory for and return a pointer to a new mpg123_pars 1550 * \param error error code return address 1551 * \return new parameter handle 1552 */ 1553 MPG123_EXPORT mpg123_pars *mpg123_new_pars(int *error); 1554 1555 /** Delete and free up memory used by a mpg123_pars data structure 1556 * \param mp parameter handle 1557 */ 1558 MPG123_EXPORT void mpg123_delete_pars(mpg123_pars* mp); 1559 1560 /** Configure mpg123 parameters to accept no output format at all, 1561 * use before specifying supported formats with mpg123_format 1562 * \param mp parameter handle 1563 * \return MPG123_OK on success 1564 */ 1565 MPG123_EXPORT int mpg123_fmt_none(mpg123_pars *mp); 1566 1567 /** Configure mpg123 parameters to accept all formats 1568 * (also any custom rate you may set) -- this is default. 1569 * \param mp parameter handle 1570 * \return MPG123_OK on success 1571 */ 1572 MPG123_EXPORT int mpg123_fmt_all(mpg123_pars *mp); 1573 1574 /** Set the audio format support of a mpg123_pars in detail: 1575 * \param mp parameter handle 1576 * \param rate The sample rate value (in Hertz). 1577 * \param channels A combination of MPG123_STEREO and MPG123_MONO. 1578 * \param encodings A combination of accepted encodings for rate and channels, 1579 * p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no 1580 * support). 1581 * \return MPG123_OK on success 1582 */ 1583 MPG123_EXPORT int mpg123_fmt(mpg123_pars *mp 1584 , long rate, int channels, int encodings); 1585 1586 /** Set the audio format support of a mpg123_pars in detail: 1587 * \param mp parameter handle 1588 * \param rate The sample rate value (in Hertz). Special value 0 means 1589 * all rates (reason for this variant of mpg123_fmt). 1590 * \param channels A combination of MPG123_STEREO and MPG123_MONO. 1591 * \param encodings A combination of accepted encodings for rate and channels, 1592 * p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no 1593 * support). 1594 * \return MPG123_OK on success 1595 */ 1596 MPG123_EXPORT int mpg123_fmt2(mpg123_pars *mp 1597 , long rate, int channels, int encodings); 1598 1599 /** Check to see if a specific format at a specific rate is supported 1600 * by mpg123_pars. 1601 * \param mp parameter handle 1602 * \param rate sampling rate 1603 * \param encoding encoding 1604 * \return 0 for no support (that includes invalid parameters), MPG123_STEREO, 1605 * MPG123_MONO or MPG123_STEREO|MPG123_MONO. */ 1606 MPG123_EXPORT int mpg123_fmt_support(mpg123_pars *mp, long rate, int encoding); 1607 1608 /** Set a specific parameter, for a specific mpg123_pars, using a parameter 1609 * type key chosen from the mpg123_parms enumeration, to the specified value. 1610 * \param mp parameter handle 1611 * \param type parameter choice 1612 * \param value integer value 1613 * \param fvalue floating point value 1614 * \return MPG123_OK on success 1615 */ 1616 MPG123_EXPORT int mpg123_par( mpg123_pars *mp 1617 , enum mpg123_parms type, long value, double fvalue ); 1618 1619 /** Get a specific parameter, for a specific mpg123_pars. 1620 * See the mpg123_parms enumeration for a list of available parameters. 1621 * \param mp parameter handle 1622 * \param type parameter choice 1623 * \param value integer value return address 1624 * \param fvalue floating point value return address 1625 * \return MPG123_OK on success 1626 */ 1627 MPG123_EXPORT int mpg123_getpar( mpg123_pars *mp 1628 , enum mpg123_parms type, long *value, double *fvalue); 1629 1630 /* @} */ 1631 1632 1633 /** \defgroup mpg123_lowio mpg123 low level I/O 1634 * 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... 1635 * 1636 * @{ */ 1637 1638 /** Replace default internal buffer with user-supplied buffer. 1639 * Instead of working on it's own private buffer, mpg123 will directly use the one you provide for storing decoded audio. 1640 * Note that the required buffer size could be bigger than expected from output 1641 * encoding if libmpg123 has to convert from primary decoder output (p.ex. 32 bit 1642 * storage for 24 bit output). 1643 * 1644 * Note: The type of data changed to a void pointer in mpg123 1.26.0 1645 * (API version 45). 1646 * 1647 * \param mh handle 1648 * \param data pointer to user buffer 1649 * \param size of buffer in bytes 1650 * \return MPG123_OK on success 1651 */ 1652 MPG123_EXPORT int mpg123_replace_buffer(mpg123_handle *mh 1653 , void *data, size_t size); 1654 1655 /** The max size of one frame's decoded output with current settings. 1656 * Use that to determine an appropriate minimum buffer size for decoding one frame. 1657 * \param mh handle 1658 * \return maximum decoded data size in bytes 1659 */ 1660 MPG123_EXPORT size_t mpg123_outblock(mpg123_handle *mh); 1661 1662 /** Replace low-level stream access functions; read and lseek as known in POSIX. 1663 * You can use this to make any fancy file opening/closing yourself, 1664 * using mpg123_open_fd() to set the file descriptor for your read/lseek 1665 * (doesn't need to be a "real" file descriptor...). 1666 * Setting a function to NULL means that the default internal read is 1667 * used (active from next mpg123_open call on). 1668 * Note: As it would be troublesome to mess with this while having a file open, 1669 * this implies mpg123_close(). 1670 * \param mh handle 1671 * \param r_read callback for reading (behaviour like POSIX read) 1672 * \param r_lseek callback for seeking (like POSIX lseek) 1673 * \return MPG123_OK on success 1674 */ 1675 MPG123_EXPORT int mpg123_replace_reader( mpg123_handle *mh 1676 , ssize_t (*r_read) (int, void *, size_t) 1677 , off_t (*r_lseek)(int, off_t, int) 1678 ); 1679 1680 /** Replace I/O functions with your own ones operating on some kind of 1681 * handle instead of integer descriptors. 1682 * The handle is a void pointer, so you can pass any data you want... 1683 * mpg123_open_handle() is the call you make to use the I/O defined here. 1684 * There is no fallback to internal read/seek here. 1685 * Note: As it would be troublesome to mess with this while having a file open, 1686 * this mpg123_close() is implied here. 1687 * \param mh handle 1688 * \param r_read callback for reading (behaviour like POSIX read) 1689 * \param r_lseek callback for seeking (like POSIX lseek) 1690 * \param cleanup A callback to clean up an I/O handle on mpg123_close, 1691 * can be NULL for none (you take care of cleaning your handles). 1692 * \return MPG123_OK on success 1693 */ 1694 MPG123_EXPORT int mpg123_replace_reader_handle( mpg123_handle *mh 1695 , ssize_t (*r_read) (void *, void *, size_t) 1696 , off_t (*r_lseek)(void *, off_t, int) 1697 , void (*cleanup)(void*) ); 1698 1699 /* @} */ 1700 1701 #ifdef __cplusplus 1702 } 1703 #endif 1704 1705 #endif 1706