annotate decoders/libmpg123/mpg123.h.in @ 562:7e08477b0fc1

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