annotate decoders/libmpg123/mpg123.h @ 577:af33b35a55c1

Minor cleanups. Ready to release.
author Eric Wing <ewing . public |-at-| gmail . com>
date Sat, 23 Oct 2010 22:35:38 -0700
parents 7e08477b0fc1
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