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