Debian Codegraph @

src/include/mpg123.h

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