Mercurial > SDL_sound_CoreAudio

comparison decoders/libmpg123/mpg123.h @ 562:7e08477b0fc1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
MP3 decoder upgrade work. Ripped out SMPEG and mpglib support, replaced it with "mpg123.c" and libmpg123. libmpg123 is a much better version of mpglib, so it should solve all the problems about MP3's not seeking, or most modern MP3's not playing at all, etc. Since you no longer have to make a tradeoff with SMPEG for features, and SMPEG is basically rotting, I removed it from the project. There is still work to be done with libmpg123...there are MMX, 3DNow, SSE, Altivec, etc decoders which we don't have enabled at the moment, and the build system could use some work to make this compile more cleanly, etc. Still: huge win.
author Ryan C. Gordon <icculus@icculus.org>
date Fri, 30 Jan 2009 02:44:47 -0500
parents
children
comparison
equal deleted inserted replaced
561:f2985e08589c 562:7e08477b0fc1
1 /*
2 libmpg123: MPEG Audio Decoder library (version @PACKAGE_VERSION@)
3
4 copyright 1995-2008 by the mpg123 project - free software under the terms of the LGPL 2.1
5 see COPYING and AUTHORS files in distribution or http://mpg123.org
6 */
7
8 #ifndef MPG123_LIB_H
9 #define MPG123_LIB_H
10
11 /** \file mpg123.h The header file for the libmpg123 MPEG Audio decoder */
12
13 /* These aren't actually in use... seems to work without using libtool. */
14 #ifdef BUILD_MPG123_DLL
15 /* The dll exports. */
16 #define EXPORT __declspec(dllexport)
17 #else
18 #ifdef LINK_MPG123_DLL
19 /* The exe imports. */
20 #define EXPORT __declspec(dllimport)
21 #else
22 /* Nothing on normal/UNIX builds */
23 #define EXPORT
24 #endif
25 #endif
26
27 #ifndef MPG123_NO_CONFIGURE /* Enable use of this file without configure. */
28 @INCLUDE_STDLIB_H@
29 @INCLUDE_SYS_TYPE_H@
30
31 #if @LARGEFILE_SWITCH@ /* If we need trickery for large file support. */
32
33 /* Check for compiling programs agains this libmpg123. */
34 #if (defined _FILE_OFFSET_BITS) && (_FILE_OFFSET_BITS+0 == @LARGEFILE_BITS@)
35 /* ...all is fine, having enabled large file support and also the correct sort of which. */
36 #else
37 #error "Mismatch in large file setup! Enable/disable large file support appropriately to use libmpg123."
38 #endif
39
40 /* Redefine names of functions dealing with file and file offsets
41 ...everything handling off_t, for example, which can be 32 or 64 bits. */
42
43 #define mpg123_open mpg123_open@LARGEFILE_SUFFIX@
44 #define mpg123_open_fd mpg123_open_fd@LARGEFILE_SUFFIX@
45 #define mpg123_decode_frame mpg123_decode_frame@LARGEFILE_SUFFIX@
46 #define mpg123_tell mpg123_tell@LARGEFILE_SUFFIX@
47 #define mpg123_tellframe mpg123_tellframe@LARGEFILE_SUFFIX@
48 #define mpg123_tell_stream mpg123_tell_stream@LARGEFILE_SUFFIX@
49 #define mpg123_seek mpg123_seek@LARGEFILE_SUFFIX@
50 #define mpg123_feedseek mpg123_feedseek@LARGEFILE_SUFFIX@
51 #define mpg123_seek_frame mpg123_seek_frame@LARGEFILE_SUFFIX@
52 #define mpg123_timeframe mpg123_timeframe@LARGEFILE_SUFFIX@
53 #define mpg123_index mpg123_index@LARGEFILE_SUFFIX@
54 #define mpg123_position mpg123_position@LARGEFILE_SUFFIX@
55 #define mpg123_length mpg123_length@LARGEFILE_SUFFIX@
56 #define mpg123_set_filesize mpg123_set_filesize@LARGEFILE_SUFFIX@
57
58 #endif /* LARGEFILE_SWITCH */
59
60 #endif /* MPG123_NO_CONFIGURE */
61
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65
66 /** \defgroup mpg123_init mpg123 library and handle setup
67 *
68 * Functions to initialise and shutdown the mpg123 library and handles.
69 * The parameters of handles have workable defaults, you only have to tune them when you want to tune something;-)
70 * Tip: Use a RVA setting...
71 *
72 * @{
73 */
74
75 /** Opaque structure for the libmpg123 decoder handle. */
76 struct mpg123_handle_struct;
77
78 /** Opaque structure for the libmpg123 decoder handle.
79 * Most functions take a pointer to a mpg123_handle as first argument and operate on its data in an object-oriented manner.
80 */
81 typedef struct mpg123_handle_struct mpg123_handle;
82
83 /** Function to initialise the mpg123 library.
84 * This function is not thread-safe. Call it exactly once per process, before any other (possibly threaded) work with the library.
85 *
86 * \return MPG123_OK if successful, otherwise an error number.
87 */
88 EXPORT int mpg123_init(void);
89
90 /** Function to close down the mpg123 library.
91 * This function is not thread-safe. Call it exactly once per process, before any other (possibly threaded) work with the library. */
92 EXPORT void mpg123_exit(void);
93
94 /** Create a handle with optional choice of decoder (named by a string, see mpg123_decoders() or mpg123_supported_decoders()).
95 * and optional retrieval of an error code to feed to mpg123_plain_strerror().
96 * Optional means: Any of or both the parameters may be NULL.
97 *
98 * \return Non-NULL pointer when successful.
99 */
100 EXPORT mpg123_handle *mpg123_new(const char* decoder, int *error);
101
102 /** Delete handle, mh is either a valid mpg123 handle or NULL. */
103 EXPORT void mpg123_delete(mpg123_handle *mh);
104
105 /** Enumeration of the parameters types that it is possible to set/get. */
106 enum mpg123_parms
107 {
108 MPG123_VERBOSE, /**< set verbosity value for enabling messages to stderr, >= 0 makes sense (integer) */
109 MPG123_FLAGS, /**< set all flags, p.ex val = MPG123_GAPLESS|MPG123_MONO_MIX (integer) */
110 MPG123_ADD_FLAGS, /**< add some flags (integer) */
111 MPG123_FORCE_RATE, /**< when value > 0, force output rate to that value (integer) */
112 MPG123_DOWN_SAMPLE, /**< 0=native rate, 1=half rate, 2=quarter rate (integer) */
113 MPG123_RVA, /**< one of the RVA choices above (integer) */
114 MPG123_DOWNSPEED, /**< play a frame N times (integer) */
115 MPG123_UPSPEED, /**< play every Nth frame (integer) */
116 MPG123_START_FRAME, /**< start with this frame (skip frames before that, integer) */
117 MPG123_DECODE_FRAMES, /**< decode only this number of frames (integer) */
118 MPG123_ICY_INTERVAL, /**< stream contains ICY metadata with this interval (integer) */
119 MPG123_OUTSCALE, /**< the scale for output samples (amplitude - integer or float according to mpg123 output format, normally integer) */
120 MPG123_TIMEOUT, /**< timeout for reading from a stream (not supported on win32, integer) */
121 MPG123_REMOVE_FLAGS, /**< remove some flags (inverse of MPG123_ADD_FLAGS, integer) */
122 MPG123_RESYNC_LIMIT, /**< Try resync on frame parsing for that many bytes or until end of stream (<0 ... integer). */
123 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. */
124 };
125
126 /** Flag bits for MPG123_FLAGS, use the usual binary or to combine. */
127 enum mpg123_param_flags
128 {
129 MPG123_FORCE_MONO = 0x7 /**< 0111 Force some mono mode: This is a test bitmask for seeing if any mono forcing is active. */
130 ,MPG123_MONO_LEFT = 0x1 /**< 0001 Force playback of left channel only. */
131 ,MPG123_MONO_RIGHT = 0x2 /**< 0010 Force playback of right channel only. */
132 ,MPG123_MONO_MIX = 0x4 /**< 0100 Force playback of mixed mono. */
133 ,MPG123_FORCE_STEREO = 0x8 /**< 1000 Force stereo output. */
134 ,MPG123_FORCE_8BIT = 0x10 /**< 00010000 Force 8bit formats. */
135 ,MPG123_QUIET = 0x20 /**< 00100000 Suppress any printouts (overrules verbose). */
136 ,MPG123_GAPLESS = 0x40 /**< 01000000 Enable gapless decoding (default on if libmpg123 has support). */
137 ,MPG123_NO_RESYNC = 0x80 /**< 10000000 Disable resync stream after error. */
138 ,MPG123_SEEKBUFFER = 0x100 /**< 000100000000 Enable small buffer on non-seekable streams to allow some peek-ahead (for better MPEG sync). */
139 ,MPG123_FUZZY = 0x200 /**< 001000000000 Enable fuzzy seeks (guessing byte offsets or using approximate seek points from Xing TOC) */
140 };
141
142 /** choices for MPG123_RVA */
143 enum mpg123_param_rva
144 {
145 MPG123_RVA_OFF = 0 /**< RVA disabled (default). */
146 ,MPG123_RVA_MIX = 1 /**< Use mix/track/radio gain. */
147 ,MPG123_RVA_ALBUM = 2 /**< Use album/audiophile gain */
148 ,MPG123_RVA_MAX = MPG123_RVA_ALBUM /**< The maximum RVA code, may increase in future. */
149 };
150
151 /* TODO: Assess the possibilities and troubles of changing parameters during playback. */
152
153 /** Set a specific parameter, for a specific mpg123_handle, using a parameter
154 * type key chosen from the mpg123_parms enumeration, to the specified value. */
155 EXPORT int mpg123_param(mpg123_handle *mh, enum mpg123_parms type, long value, double fvalue);
156
157 /** Get a specific parameter, for a specific mpg123_handle.
158 * See the mpg123_parms enumeration for a list of available parameters. */
159 EXPORT int mpg123_getparam(mpg123_handle *mh, enum mpg123_parms type, long *val, double *fval);
160
161 /* @} */
162
163
164 /** \defgroup mpg123_error mpg123 error handling
165 *
166 * Functions to get text version of the error numbers and an enumeration
167 * of the error codes returned by libmpg123.
168 *
169 * Most functions operating on a mpg123_handle simply return MPG123_OK on success and MPG123_ERR on failure (setting the internal error variable of the handle to the specific error code).
170 * Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE.
171 * The positive range of return values is used for "useful" values when appropriate.
172 *
173 * @{
174 */
175
176 /** Enumeration of the message and error codes and returned by libmpg123 functions. */
177 enum mpg123_errors
178 {
179 MPG123_DONE=-12, /**< Message: Track ended. */
180 MPG123_NEW_FORMAT=-11, /**< Message: Output format will be different on next call. */
181 MPG123_NEED_MORE=-10, /**< Message: For feed reader: "Feed me more!" */
182 MPG123_ERR=-1, /**< Generic Error */
183 MPG123_OK=0, /**< Success */
184 MPG123_BAD_OUTFORMAT, /**< Unable to set up output format! */
185 MPG123_BAD_CHANNEL, /**< Invalid channel number specified. */
186 MPG123_BAD_RATE, /**< Invalid sample rate specified. */
187 MPG123_ERR_16TO8TABLE, /**< Unable to allocate memory for 16 to 8 converter table! */
188 MPG123_BAD_PARAM, /**< Bad parameter id! */
189 MPG123_BAD_BUFFER, /**< Bad buffer given -- invalid pointer or too small size. */
190 MPG123_OUT_OF_MEM, /**< Out of memory -- some malloc() failed. */
191 MPG123_NOT_INITIALIZED, /**< You didn't initialize the library! */
192 MPG123_BAD_DECODER, /**< Invalid decoder choice. */
193 MPG123_BAD_HANDLE, /**< Invalid mpg123 handle. */
194 MPG123_NO_BUFFERS, /**< Unable to initialize frame buffers (out of memory?). */
195 MPG123_BAD_RVA, /**< Invalid RVA mode. */
196 MPG123_NO_GAPLESS, /**< This build doesn't support gapless decoding. */
197 MPG123_NO_SPACE, /**< Not enough buffer space. */
198 MPG123_BAD_TYPES, /**< Incompatible numeric data types. */
199 MPG123_BAD_BAND, /**< Bad equalizer band. */
200 MPG123_ERR_NULL, /**< Null pointer given where valid storage address needed. */
201 MPG123_ERR_READER, /**< Error reading the stream. */
202 MPG123_NO_SEEK_FROM_END,/**< Cannot seek from end (end is not known). */
203 MPG123_BAD_WHENCE, /**< Invalid 'whence' for seek function.*/
204 MPG123_NO_TIMEOUT, /**< Build does not support stream timeouts. */
205 MPG123_BAD_FILE, /**< File access error. */
206 MPG123_NO_SEEK, /**< Seek not supported by stream. */
207 MPG123_NO_READER, /**< No stream opened. */
208 MPG123_BAD_PARS, /**< Bad parameter handle. */
209 MPG123_BAD_INDEX_PAR, /**< Bad parameters to mpg123_index() */
210 MPG123_OUT_OF_SYNC, /**< Lost track in bytestream and did not try to resync. */
211 MPG123_RESYNC_FAIL, /**< Resync failed to find valid MPEG data. */
212 MPG123_NO_8BIT, /**< No 8bit encoding possible. */
213 MPG123_BAD_ALIGN, /**< Stack aligmnent error */
214 MPG123_NULL_BUFFER, /**< NULL input buffer with non-zero size... */
215 MPG123_NO_RELSEEK, /**< Relative seek not possible (screwed up file offset) */
216 MPG123_NULL_POINTER, /**< You gave a null pointer somewhere where you shouldn't have. */
217 MPG123_BAD_KEY, /**< Bad key value given. */
218 MPG123_NO_INDEX, /**< No frame index in this build. */
219 MPG123_INDEX_FAIL /**< Something with frame index went wrong. */
220 };
221
222 /** Return a string describing that error errcode means. */
223 EXPORT const char* mpg123_plain_strerror(int errcode);
224
225 /** Give string describing what error has occured in the context of handle mh.
226 * When a function operating on an mpg123 handle returns MPG123_ERR, you should check for the actual reason via
227 * char *errmsg = mpg123_strerror(mh)
228 * This function will catch mh == NULL and return the message for MPG123_BAD_HANDLE. */
229 EXPORT const char* mpg123_strerror(mpg123_handle *mh);
230
231 /** Return the plain errcode intead of a string. */
232 EXPORT int mpg123_errcode(mpg123_handle *mh);
233
234 /*@}*/
235
236
237 /** \defgroup mpg123_decoder mpg123 decoder selection
238 *
239 * Functions to list and select the available decoders.
240 * Perhaps the most prominent feature of mpg123: You have several (optimized) decoders to choose from (on x86 and PPC (MacOS) systems, that is).
241 *
242 * @{
243 */
244
245 /** Return a NULL-terminated array of generally available decoder names (plain 8bit ASCII). */
246 EXPORT char **mpg123_decoders();
247
248 /** Return a NULL-terminated array of the decoders supported by the CPU (plain 8bit ASCII). */
249 EXPORT char **mpg123_supported_decoders();
250
251 /** Set the chosen decoder to 'decoder_name' */
252 EXPORT int mpg123_decoder(mpg123_handle *mh, const char* decoder_name);
253
254 /*@}*/
255
256
257 /** \defgroup mpg123_output mpg123 output audio format
258 *
259 * Functions to get and select the format of the decoded audio.
260 *
261 * @{
262 */
263
264 /** 16 or 8 bits, signed or unsigned... all flags fit into 15 bits and are designed to have meaningful binary AND/OR.
265 * Adding float and 32bit int definitions for experimental fun. Only 32bit (and possibly 64bit) float is
266 * somewhat there with a dedicated library build. */
267 enum mpg123_enc_enum
268 {
269 MPG123_ENC_8 = 0x00f /**< 0000 0000 1111 Some 8 bit integer encoding. */
270 ,MPG123_ENC_16 = 0x040 /**< 0000 0100 0000 Some 16 bit integer encoding. */
271 ,MPG123_ENC_32 = 0x100 /**< 0001 0000 0000 Some 32 bit integer encoding. */
272 ,MPG123_ENC_SIGNED = 0x080 /**< 0000 1000 0000 Some signed integer encoding. */
273 ,MPG123_ENC_FLOAT = 0x800 /**< 1110 0000 0000 Some float encoding. */
274 ,MPG123_ENC_SIGNED_16 = (MPG123_ENC_16|MPG123_ENC_SIGNED|0x10) /**< 0000 1101 0000 signed 16 bit */
275 ,MPG123_ENC_UNSIGNED_16 = (MPG123_ENC_16|0x20) /**< 0000 0110 0000 unsigned 16 bit*/
276 ,MPG123_ENC_UNSIGNED_8 = 0x01 /**< 0000 0000 0001 unsigned 8 bit*/
277 ,MPG123_ENC_SIGNED_8 = (MPG123_ENC_SIGNED|0x02) /**< 0000 1000 0010 signed 8 bit*/
278 ,MPG123_ENC_ULAW_8 = 0x04 /**< 0000 0000 0100 ulaw 8 bit*/
279 ,MPG123_ENC_ALAW_8 = 0x08 /**< 0000 0000 1000 alaw 8 bit */
280 ,MPG123_ENC_SIGNED_32 = MPG123_ENC_32|MPG123_ENC_SIGNED|0x10 /**< 0001 1001 0000 signed 32 bit */
281 ,MPG123_ENC_UNSIGNED_32 = MPG123_ENC_32|0x20 /**< 0001 0010 0000 unsigned 32 bit */
282 ,MPG123_ENC_FLOAT_32 = 0x200 /**< 0010 0000 0000 32bit float */
283 ,MPG123_ENC_FLOAT_64 = 0x400 /**< 0100 0000 0000 64bit float */
284 ,MPG123_ENC_ANY = ( MPG123_ENC_SIGNED_16 | MPG123_ENC_UNSIGNED_16 | MPG123_ENC_UNSIGNED_8
285 | MPG123_ENC_SIGNED_8 | MPG123_ENC_ULAW_8 | MPG123_ENC_ALAW_8
286 | MPG123_ENC_FLOAT_32 | MPG123_ENC_FLOAT_64 ) /**< any encoding */
287 };
288
289 /** They can be combined into one number (3) to indicate mono and stereo... */
290 enum mpg123_channelcount
291 {
292 MPG123_MONO = 1
293 ,MPG123_STEREO = 2
294 };
295
296 /** An array of supported standard sample rates
297 * These are possible native sample rates of MPEG audio files.
298 * You can still force mpg123 to resample to a different one, but by default you will only get audio in one of these samplings.
299 * \param list Store a pointer to the sample rates array there.
300 * \param number Store the number of sample rates there. */
301 EXPORT void mpg123_rates(const long **list, size_t *number);
302
303 /** An array of supported audio encodings.
304 * An audio encoding is one of the fully qualified members of mpg123_enc_enum (MPG123_ENC_SIGNED_16, not MPG123_SIGNED).
305 * \param list Store a pointer to the encodings array there.
306 * \param number Store the number of encodings there. */
307 EXPORT void mpg123_encodings(const int **list, size_t *number);
308
309 /** Configure a mpg123 handle to accept no output format at all,
310 * use before specifying supported formats with mpg123_format */
311 EXPORT int mpg123_format_none(mpg123_handle *mh);
312
313 /** Configure mpg123 handle to accept all formats
314 * (also any custom rate you may set) -- this is default. */
315 EXPORT int mpg123_format_all(mpg123_handle *mh);
316
317 /** Set the audio format support of a mpg123_handle in detail:
318 * \param mh audio decoder handle
319 * \param rate The sample rate value (in Hertz).
320 * \param channels A combination of MPG123_STEREO and MPG123_MONO.
321 * \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.
322 * \return MPG123_OK on success, MPG123_ERR if there was an error. */
323 EXPORT int mpg123_format(mpg123_handle *mh, long rate, int channels, int encodings);
324
325 /** Check to see if a specific format at a specific rate is supported
326 * by mpg123_handle.
327 * \return 0 for no support (that includes invalid parameters), MPG123_STEREO,
328 * MPG123_MONO or MPG123_STEREO|MPG123_MONO. */
329 EXPORT int mpg123_format_support(mpg123_handle *mh, long rate, int encoding);
330
331 /** Get the current output format written to the addresses givenr. */
332 EXPORT int mpg123_getformat(mpg123_handle *mh, long *rate, int *channels, int *encoding);
333
334 /*@}*/
335
336
337 /** \defgroup mpg123_input mpg123 file input and decoding
338 *
339 * Functions for input bitstream and decoding operations.
340 *
341 * @{
342 */
343
344 /* reading samples / triggering decoding, possible return values: */
345 /** Enumeration of the error codes returned by libmpg123 functions. */
346
347 /** Open and prepare to decode the specified file by filesystem path.
348 * This does not open HTTP urls; libmpg123 contains no networking code.
349 * If you want to decode internet streams, use mpg123_open_fd() or mpg123_open_feed().
350 */
351 EXPORT int mpg123_open(mpg123_handle *mh, const char *path);
352
353 /** Use an already opened file descriptor as the bitstream input
354 * mpg123_close() will _not_ close the file descriptor.
355 */
356 EXPORT int mpg123_open_fd(mpg123_handle *mh, int fd);
357
358 /** Open a new bitstream and prepare for direct feeding
359 * This works together with mpg123_decode(); you are responsible for reading and feeding the input bitstream.
360 */
361 EXPORT int mpg123_open_feed(mpg123_handle *mh);
362
363 /** Closes the source, if libmpg123 opened it. */
364 EXPORT int mpg123_close(mpg123_handle *mh);
365
366 /** Read from stream and decode up to outmemsize bytes.
367 * \param outmemory address of output buffer to write to
368 * \param outmemsize maximum number of bytes to write
369 * \param done address to store the number of actually decoded bytes to
370 * \return error/message code (watch out for MPG123_DONE and friends!) */
371 EXPORT int mpg123_read(mpg123_handle *mh, unsigned char *outmemory, size_t outmemsize, size_t *done);
372
373 /** Feed data for a stream that has been opened with mpg123_open_feed().
374 * It's give and take: You provide the bytestream, mpg123 gives you the decoded samples.
375 * \param in input buffer
376 * \param size number of input bytes
377 * \return error/message code. */
378 EXPORT int mpg123_feed(mpg123_handle *mh, const unsigned char *in, size_t size);
379
380 /** Decode MPEG Audio from inmemory to outmemory.
381 * This is very close to a drop-in replacement for old mpglib.
382 * When you give zero-sized output buffer the input will be parsed until
383 * decoded data is available. This enables you to get MPG123_NEW_FORMAT (and query it)
384 * without taking decoded data.
385 * Think of this function being the union of mpg123_read() and mpg123_feed() (which it actually is, sort of;-).
386 * You can actually always decide if you want those specialized functions in separate steps or one call this one here.
387 * \param inmemory input buffer
388 * \param inmemsize number of input bytes
389 * \param outmemory output buffer
390 * \param outmemsize maximum number of output bytes
391 * \param done address to store the number of actually decoded bytes to
392 * \return error/message code (watch out especially for MPG123_NEED_MORE)
393 */
394 EXPORT int mpg123_decode(mpg123_handle *mh, const unsigned char *inmemory, size_t inmemsize,
395 unsigned char *outmemory, size_t outmemsize, size_t *done);
396
397 /** Decode next MPEG frame to internal buffer
398 * or read a frame and return after setting a new format.
399 * \param num current frame offset gets stored there
400 * \param audio This pointer is set to the internal buffer to read the decoded audio from.
401 * \param bytes number of output bytes ready in the buffer
402 */
403 EXPORT int mpg123_decode_frame(mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes);
404
405 /*@}*/
406
407
408 /** \defgroup mpg123_seek mpg123 position and seeking
409 *
410 * Functions querying and manipulating position in the decoded audio bitstream.
411 * The position is measured in decoded audio samples, or MPEG frame offset for the specific functions.
412 * If gapless code is in effect, the positions are adjusted to compensate the skipped padding/delay - meaning, you should not care about that at all and just use the position defined for the samples you get out of the decoder;-)
413 * The general usage is modelled after stdlib's ftell() and fseek().
414 * Especially, the whence parameter for the seek functions has the same meaning as the one for fseek() and needs the same constants from stdlib.h:
415 * - SEEK_SET: set position to (or near to) specified offset
416 * - SEEK_CUR: change position by offset from now
417 * - SEEK_END: set position to offset from end
418 *
419 * Note that sample-accurate seek only works when gapless support has been enabled at compile time; seek is frame-accurate otherwise.
420 * Also, seeking is not guaranteed to work for all streams (underlying stream may not support it).
421 *
422 * @{
423 */
424
425 /** Returns the current position in samples.
426 * On the next read, you'd get that sample. */
427 EXPORT off_t mpg123_tell(mpg123_handle *mh);
428
429 /** Returns the frame number that the next read will give you data from. */
430 EXPORT off_t mpg123_tellframe(mpg123_handle *mh);
431
432 /** Returns the current byte offset in the input stream. */
433 EXPORT off_t mpg123_tell_stream(mpg123_handle *mh);
434
435 /** Seek to a desired sample offset.
436 * Set whence to SEEK_SET, SEEK_CUR or SEEK_END.
437 * \return The resulting offset >= 0 or error/message code */
438 EXPORT off_t mpg123_seek(mpg123_handle *mh, off_t sampleoff, int whence);
439
440 /** Seek to a desired sample offset in data feeding mode.
441 * This just prepares things to be right only if you ensure that the next chunk of input data will be from input_offset byte position.
442 * \param input_offset The position it expects to be at the
443 * next time data is fed to mpg123_decode().
444 * \return The resulting offset >= 0 or error/message code */
445 EXPORT off_t mpg123_feedseek(mpg123_handle *mh, off_t sampleoff, int whence, off_t *input_offset);
446
447 /** Seek to a desired MPEG frame index.
448 * Set whence to SEEK_SET, SEEK_CUR or SEEK_END.
449 * \return The resulting offset >= 0 or error/message code */
450 EXPORT off_t mpg123_seek_frame(mpg123_handle *mh, off_t frameoff, int whence);
451
452 /** Return a MPEG frame offset corresponding to an offset in seconds.
453 * 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.
454 * \return frame offset >= 0 or error/message code */
455 EXPORT off_t mpg123_timeframe(mpg123_handle *mh, double sec);
456
457 /** Give access to the frame index table that is managed for seeking.
458 * You are asked not to modify the values... unless you are really aware of what you are doing.
459 * \param offsets pointer to the index array
460 * \param step one index byte offset advances this many MPEG frames
461 * \param fill number of recorded index offsets; size of the array */
462 EXPORT int mpg123_index(mpg123_handle *mh, off_t **offsets, off_t *step, size_t *fill);
463
464 /** Get information about current and remaining frames/seconds.
465 * WARNING: This function is there because of special usage by standalone mpg123 and may be removed in the final version of libmpg123!
466 * You provide an offset (in frames) from now and a number of output bytes
467 * served by libmpg123 but not yet played. You get the projected current frame
468 * and seconds, as well as the remaining frames/seconds. This does _not_ care
469 * about skipped samples due to gapless playback. */
470 EXPORT int mpg123_position( mpg123_handle *mh, off_t frame_offset,
471 off_t buffered_bytes, off_t *current_frame,
472 off_t *frames_left, double *current_seconds,
473 double *seconds_left);
474
475 /*@}*/
476
477
478 /** \defgroup mpg123_voleq mpg123 volume and equalizer
479 *
480 * @{
481 */
482
483 enum mpg123_channels
484 {
485 MPG123_LEFT=0x1 /**< The Left Channel. */
486 ,MPG123_RIGHT=0x2 /**< The Right Channel. */
487 ,MPG123_LR=0x3 /**< Both left and right channel; same as MPG123_LEFT|MPG123_RIGHT */
488 };
489
490 /** Set the 32 Band Audio Equalizer settings.
491 * \param channel Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both.
492 * \param band The equaliser band to change (from 0 to 31)
493 * \param val The (linear) adjustment factor. */
494 EXPORT int mpg123_eq(mpg123_handle *mh, enum mpg123_channels channel, int band, double val);
495
496 /** Get the 32 Band Audio Equalizer settings.
497 * \param channel Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for (arithmetic mean of) both.
498 * \param band The equaliser band to change (from 0 to 31)
499 * \return The (linear) adjustment factor. */
500 EXPORT double mpg123_geteq(mpg123_handle *mh, enum mpg123_channels channel, int band);
501
502 /** Reset the 32 Band Audio Equalizer settings to flat */
503 EXPORT int mpg123_reset_eq(mpg123_handle *mh);
504
505 /** Set the absolute output volume including the RVA setting,
506 * vol<0 just applies (a possibly changed) RVA setting. */
507 EXPORT int mpg123_volume(mpg123_handle *mh, double vol);
508
509 /** Adjust output volume including the RVA setting by chosen amount */
510 EXPORT int mpg123_volume_change(mpg123_handle *mh, double change);
511
512 /** Return current volume setting, the actual value due to RVA, and the RVA
513 * adjustment itself. It's all as double float value to abstract the sample
514 * format. The volume values are linear factors / amplitudes (not percent)
515 * and the RVA value is in decibels. */
516 EXPORT int mpg123_getvolume(mpg123_handle *mh, double *base, double *really, double *rva_db);
517
518 /* TODO: Set some preamp in addition / to replace internal RVA handling? */
519
520 /*@}*/
521
522
523 /** \defgroup mpg123_status mpg123 status and information
524 *
525 * @{
526 */
527
528 /** Enumeration of the mode types of Variable Bitrate */
529 enum mpg123_vbr {
530 MPG123_CBR=0, /**< Constant Bitrate Mode (default) */
531 MPG123_VBR, /**< Variable Bitrate Mode */
532 MPG123_ABR /**< Average Bitrate Mode */
533 };
534
535 /** Enumeration of the MPEG Versions */
536 enum mpg123_version {
537 MPG123_1_0=0, /**< MPEG Version 1.0 */
538 MPG123_2_0, /**< MPEG Version 2.0 */
539 MPG123_2_5 /**< MPEG Version 2.5 */
540 };
541
542
543 /** Enumeration of the MPEG Audio mode.
544 * Only the mono mode has 1 channel, the others have 2 channels. */
545 enum mpg123_mode {
546 MPG123_M_STEREO=0, /**< Standard Stereo. */
547 MPG123_M_JOINT, /**< Joint Stereo. */
548 MPG123_M_DUAL, /**< Dual Channel. */
549 MPG123_M_MONO /**< Single Channel. */
550 };
551
552
553 /** Enumeration of the MPEG Audio flag bits */
554 enum mpg123_flags {
555 MPG123_CRC=0x1, /**< The bitstream is error protected using 16-bit CRC. */
556 MPG123_COPYRIGHT=0x2, /**< The bitstream is copyrighted. */
557 MPG123_PRIVATE=0x4, /**< The private bit has been set. */
558 MPG123_ORIGINAL=0x8 /**< The bitstream is an original, not a copy. */
559 };
560
561 /** Data structure for storing information about a frame of MPEG Audio */
562 struct mpg123_frameinfo
563 {
564 enum mpg123_version version; /**< The MPEG version (1.0/2.0/2.5). */
565 int layer; /**< The MPEG Audio Layer (MP1/MP2/MP3). */
566 long rate; /**< The sampling rate in Hz. */
567 enum mpg123_mode mode; /**< The audio mode (Mono, Stereo, Joint-stero, Dual Channel). */
568 int mode_ext; /**< The mode extension bit flag. */
569 int framesize; /**< The size of the frame (in bytes). */
570 enum mpg123_flags flags; /**< MPEG Audio flag bits. */
571 int emphasis; /**< The emphasis type. */
572 int bitrate; /**< Bitrate of the frame (kbps). */
573 int abr_rate; /**< The target average bitrate. */
574 enum mpg123_vbr vbr; /**< The VBR mode. */
575 };
576
577 /** Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo structure. */
578 EXPORT int mpg123_info(mpg123_handle *mh, struct mpg123_frameinfo *mi);
579
580 /** Get the safe output buffer size for all cases (when you want to replace the internal buffer) */
581 EXPORT size_t mpg123_safe_buffer();
582
583 /** Make a full parsing scan of each frame in the file. ID3 tags are found. An accurate length
584 * value is stored. Seek index will be filled. A seek back to current position
585 * is performed. At all, this function refuses work when stream is
586 * not seekable.
587 * \return MPG123_OK or MPG123_ERR.
588 */
589 EXPORT int mpg123_scan(mpg123_handle *mh);
590
591 /** Return, if possible, the full (expected) length of current track in samples.
592 * \return length >= 0 or MPG123_ERR if there is no length guess possible. */
593 EXPORT off_t mpg123_length(mpg123_handle *mh);
594
595 /** Override the value for file size in bytes.
596 * Useful for getting sensible track length values in feed mode or for HTTP streams.
597 * \return MPG123_OK or MPG123_ERR */
598 EXPORT int mpg123_set_filesize(mpg123_handle *mh, off_t size);
599
600 /** Returns the time (seconds) per frame; <0 is error. */
601 EXPORT double mpg123_tpf(mpg123_handle *mh);
602
603 /** Get and reset the clip count. */
604 EXPORT long mpg123_clip(mpg123_handle *mh);
605
606
607 /** The key values for state information from mpg123_getstate(). */
608 enum mpg123_state
609 {
610 MPG123_ACCURATE = 1 /**< Query if positons are currently accurate (integer value, 0 if false, 1 if true) */
611 };
612
613 /** Get various current decoder/stream state information.
614 * \param key the key to identify the information to give.
615 * \param val the address to return (long) integer values to
616 * \param fval the address to return floating point values to
617 * \return MPG123_OK or MPG123_ERR for success
618 */
619 EXPORT int mpg123_getstate(mpg123_handle *mh, enum mpg123_state key, long *val, double *fval);
620
621 /*@}*/
622
623
624 /** \defgroup mpg123_metadata mpg123 metadata handling
625 *
626 * Functions to retrieve the metadata from MPEG Audio files and streams.
627 * Also includes string handling functions.
628 *
629 * @{
630 */
631
632 /** Data structure for storing strings in a safer way than a standard C-String.
633 * Can also hold a number of null-terminated strings. */
634 typedef struct
635 {
636 char* p; /**< pointer to the string data */
637 size_t size; /**< raw number of bytes allocated */
638 size_t fill; /**< number of used bytes (including closing zero byte) */
639 } mpg123_string;
640
641 /** Create and allocate memory for a new mpg123_string */
642 EXPORT void mpg123_init_string(mpg123_string* sb);
643
644 /** Free-up mempory for an existing mpg123_string */
645 EXPORT void mpg123_free_string(mpg123_string* sb);
646
647 /** Change the size of a mpg123_string
648 * \return 0 on error, 1 on success */
649 EXPORT int mpg123_resize_string(mpg123_string* sb, size_t news);
650
651 /** Increase size of a mpg123_string if necessary (it may stay larger).
652 * Note that the functions for adding and setting in current libmpg123 use this instead of mpg123_resize_string().
653 * That way, you can preallocate memory and safely work afterwards with pieces.
654 * \return 0 on error, 1 on success */
655 EXPORT int mpg123_grow_string(mpg123_string* sb, size_t news);
656
657 /** Copy the contents of one mpg123_string string to another.
658 * \return 0 on error, 1 on success */
659 EXPORT int mpg123_copy_string(mpg123_string* from, mpg123_string* to);
660
661 /** Append a C-String to an mpg123_string
662 * \return 0 on error, 1 on success */
663 EXPORT int mpg123_add_string(mpg123_string* sb, const char* stuff);
664
665 /** Append a C-substring to an mpg123 string
666 * \return 0 on error, 1 on success
667 * \param from offset to copy from
668 * \param count number of characters to copy (a null-byte is always appended) */
669 EXPORT int mpg123_add_substring(mpg123_string *sb, const char *stuff, size_t from, size_t count);
670
671 /** Set the conents of a mpg123_string to a C-string
672 * \return 0 on error, 1 on success */
673 EXPORT int mpg123_set_string(mpg123_string* sb, const char* stuff);
674
675 /** Set the contents of a mpg123_string to a C-substring
676 * \return 0 on error, 1 on success
677 * \param from offset to copy from
678 * \param count number of characters to copy (a null-byte is always appended) */
679 EXPORT int mpg123_set_substring(mpg123_string *sb, const char *stuff, size_t from, size_t count);
680
681
682 /** Sub data structure for ID3v2, for storing various text fields (including comments).
683 * This is for ID3v2 COMM, TXXX and all the other text fields.
684 * Only COMM and TXXX have a description, only COMM has a language.
685 * You should consult the ID3v2 specification for the use of the various text fields ("frames" in ID3v2 documentation, I use "fields" here to separate from MPEG frames). */
686 typedef struct
687 {
688 char lang[3]; /**< Three-letter language code (not terminated). */
689 char id[4]; /**< The ID3v2 text field id, like TALB, TPE2, ... (4 characters, no string termination). */
690 mpg123_string description; /**< Empty for the generic comment... */
691 mpg123_string text; /**< ... */
692 } mpg123_text;
693
694 /** Data structure for storing IDV3v2 tags.
695 * This structure is not a direct binary mapping with the file contents.
696 * The ID3v2 text frames are allowed to contain multiple strings.
697 * So check for null bytes until you reach the mpg123_string fill.
698 * All text is encoded in UTF-8. */
699 typedef struct
700 {
701 unsigned char version; /**< 3 or 4 for ID3v2.3 or ID3v2.4. */
702 mpg123_string *title; /**< Title string (pointer into text_list). */
703 mpg123_string *artist; /**< Artist string (pointer into text_list). */
704 mpg123_string *album; /**< Album string (pointer into text_list). */
705 mpg123_string *year; /**< The year as a string (pointer into text_list). */
706 mpg123_string *genre; /**< Genre String (pointer into text_list). The genre string(s) may very well need postprocessing, esp. for ID3v2.3. */
707 mpg123_string *comment; /**< Pointer to last encountered comment text with empty description. */
708 /* Encountered ID3v2 fields are appended to these lists.
709 There can be multiple occurences, the pointers above always point to the last encountered data. */
710 mpg123_text *comment_list; /**< Array of comments. */
711 size_t comments; /**< Number of comments. */
712 mpg123_text *text; /**< Array of ID3v2 text fields */
713 size_t texts; /**< Numer of text fields. */
714 mpg123_text *extra; /**< The array of extra (TXXX) fields. */
715 size_t extras; /**< Number of extra text (TXXX) fields. */
716 } mpg123_id3v2;
717
718 /** Data structure for ID3v1 tags (the last 128 bytes of a file).
719 * Don't take anything for granted (like string termination)!
720 * Also note the change ID3v1.1 did: comment[28] = 0; comment[19] = track_number
721 * It is your task to support ID3v1 only or ID3v1.1 ...*/
722 typedef struct
723 {
724 char tag[3]; /**< Always the string "TAG", the classic intro. */
725 char title[30]; /**< Title string. */
726 char artist[30]; /**< Artist string. */
727 char album[30]; /**< Album string. */
728 char year[4]; /**< Year string. */
729 char comment[30]; /**< Comment string. */
730 unsigned char genre; /**< Genre index. */
731 } mpg123_id3v1;
732
733 #define MPG123_ID3 0x3 /**< 0011 There is some ID3 info. Also matches 0010 or NEW_ID3. */
734 #define MPG123_NEW_ID3 0x1 /**< 0001 There is ID3 info that changed since last call to mpg123_id3. */
735 #define MPG123_ICY 0xc /**< 1100 There is some ICY info. Also matches 0100 or NEW_ICY.*/
736 #define MPG123_NEW_ICY 0x4 /**< 0100 There is ICY info that changed since last call to mpg123_icy. */
737
738 /** Query if there is (new) meta info, be it ID3 or ICY (or something new in future).
739 The check function returns a combination of flags. */
740 EXPORT int mpg123_meta_check(mpg123_handle *mh); /* On error (no valid handle) just 0 is returned. */
741
742 /** Point v1 and v2 to existing data structures wich may change on any next read/decode function call.
743 * v1 and/or v2 can be set to NULL when there is no corresponding data.
744 * \return Return value is MPG123_OK or MPG123_ERR, */
745 EXPORT int mpg123_id3(mpg123_handle *mh, mpg123_id3v1 **v1, mpg123_id3v2 **v2);
746
747 /** Point icy_meta to existing data structure wich may change on any next read/decode function call.
748 * \return Return value is MPG123_OK or MPG123_ERR, */
749 EXPORT int mpg123_icy(mpg123_handle *mh, char **icy_meta); /* same for ICY meta string */
750
751 /** Decode from windows-1252 (the encoding ICY metainfo used) to UTF-8.
752 * \param icy_text The input data in ICY encoding
753 * \return pointer to newly allocated buffer with UTF-8 data (You free() it!) */
754 EXPORT char* mpg123_icy2utf8(const char* icy_text);
755
756
757 /* @} */
758
759
760 /** \defgroup mpg123_advpar mpg123 advanced parameter API
761 *
762 * Direct access to a parameter set without full handle around it.
763 * Possible uses:
764 * - Influence behaviour of library _during_ initialization of handle (MPG123_VERBOSE).
765 * - Use one set of parameters for multiple handles.
766 *
767 * The functions for handling mpg123_pars (mpg123_par() and mpg123_fmt()
768 * family) directly return a fully qualified mpg123 error code, the ones
769 * operating on full handles normally MPG123_OK or MPG123_ERR, storing the
770 * specific error code itseld inside the handle.
771 *
772 * @{
773 */
774
775 /** Opaque structure for the libmpg123 decoder parameters. */
776 struct mpg123_pars_struct;
777
778 /** Opaque structure for the libmpg123 decoder parameters. */
779 typedef struct mpg123_pars_struct mpg123_pars;
780
781 /** Create a handle with preset parameters. */
782 EXPORT mpg123_handle *mpg123_parnew(mpg123_pars *mp, const char* decoder, int *error);
783
784 /** Allocate memory for and return a pointer to a new mpg123_pars */
785 EXPORT mpg123_pars *mpg123_new_pars(int *error);
786
787 /** Delete and free up memory used by a mpg123_pars data structure */
788 EXPORT void mpg123_delete_pars(mpg123_pars* mp);
789
790 /** Configure mpg123 parameters to accept no output format at all,
791 * use before specifying supported formats with mpg123_format */
792 EXPORT int mpg123_fmt_none(mpg123_pars *mp);
793
794 /** Configure mpg123 parameters to accept all formats
795 * (also any custom rate you may set) -- this is default. */
796 EXPORT int mpg123_fmt_all(mpg123_pars *mp);
797
798 /** Set the audio format support of a mpg123_pars in detail:
799 \param rate The sample rate value (in Hertz).
800 \param channels A combination of MPG123_STEREO and MPG123_MONO.
801 \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).
802 \return 0 on success, -1 if there was an error. /
803 */
804 EXPORT int mpg123_fmt(mpg123_pars *mh, long rate, int channels, int encodings); /* 0 is good, -1 is error */
805
806 /** Check to see if a specific format at a specific rate is supported
807 * by mpg123_pars.
808 * \return 0 for no support (that includes invalid parameters), MPG123_STEREO,
809 * MPG123_MONO or MPG123_STEREO|MPG123_MONO. */
810 EXPORT int mpg123_fmt_support(mpg123_pars *mh, long rate, int encoding);
811
812 /** Set a specific parameter, for a specific mpg123_pars, using a parameter
813 * type key chosen from the mpg123_parms enumeration, to the specified value. */
814 EXPORT int mpg123_par(mpg123_pars *mp, enum mpg123_parms type, long value, double fvalue);
815
816 /** Get a specific parameter, for a specific mpg123_pars.
817 * See the mpg123_parms enumeration for a list of available parameters. */
818 EXPORT int mpg123_getpar(mpg123_pars *mp, enum mpg123_parms type, long *val, double *fval);
819
820 /* @} */
821
822
823 /** \defgroup mpg123_lowio mpg123 low level I/O
824 * 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...
825 *
826 * @{ */
827
828 /** Replace default internal buffer with user-supplied buffer.
829 * Instead of working on it's own private buffer, mpg123 will directly use the one you provide for storing decoded audio. */
830 EXPORT int mpg123_replace_buffer(mpg123_handle *mh, unsigned char *data, size_t size);
831
832 /** The max size of one frame's decoded output with current settings.
833 * Use that to determine an appropriate minimum buffer size for decoding one frame. */
834 EXPORT size_t mpg123_outblock(mpg123_handle *mh);
835
836 /** Replace low-level stream access functions; read and lseek as known in POSIX.
837 * You can use this to make any fancy file opening/closing yourself,
838 * using open_fd to set the file descriptor for your read/lseek (doesn't need to be a "real" file descriptor...).
839 * Setting a function to NULL means that the default internal read is
840 * used (active from next mpg123_open call on). */
841 EXPORT int mpg123_replace_reader( mpg123_handle *mh,
842 ssize_t (*r_read) (int, void *, size_t),
843 off_t (*r_lseek)(int, off_t, int) );
844
845 /* @} */
846
847
848 #ifdef __cplusplus
849 }
850 #endif
851
852 #endif