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