# API documentation for libmpg123, libout123, and libsyn123

Note: This API doc is automatically generated from the current development version that you can get via Subversion or as a daily snapshot from http://mpg123.org/snapshot. There may be differences (additions) compared to the latest stable release. See NEWS.libmpg123, NEWS.libout123, NEWS.libsyn123, and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for the lib*123 family is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).
out123.h
Go to the documentation of this file.
1 /*
2 out123: audio output interface
3
4 copyright 1995-2016 by the mpg123 project,
5 free software under the terms of the LGPL 2.1
6
7 see COPYING and AUTHORS files in distribution or http://mpg123.org
8 initially written as audio.h by Michael Hipp, reworked into out123 API
9 by Thomas Orgis
10 */
11
12 #ifndef _OUT123_H_
13 #define _OUT123_H_
14
21 #define OUT123_API_VERSION 5
22
23 #define OUT123_PATCHLEVEL 2
24
25 /* We only need size_t definition. */
26 #include <stddef.h>
27
28 /* Common audio encoding specification, including a macro for getting
29 * size of encoded samples in bytes. Said macro is still hardcoded
30 * into out123_encsize(). Relying on this one may help an old program
31 * know sizes of encodings added to fmt123.h later on.
32 * If you don't care, just use the macro.
33 */
34 #include "fmt123.h"
35
36 #ifndef MPG123_EXPORT
37
44 #ifdef BUILD_MPG123_DLL
45 /* The dll exports. */
46 #define MPG123_EXPORT __declspec(dllexport)
47 #else
48 #ifdef LINK_MPG123_DLL
49 /* The exe imports. */
50 #define MPG123_EXPORT __declspec(dllimport)
51 #else
52 /* Nothing on normal/UNIX builds */
53 #define MPG123_EXPORT
54 #endif
55 #endif
56 #endif
57
58 /* Earlier versions of libout123 put enums into public API calls,
59 * thich is not exactly safe. There are ABI rules, but you can use
60 * compiler switches to change the sizes of enums. It is safer not
61 * to have them in API calls. Thus, the default is to remap calls and
62 * structs to variants that use plain ints. Define MPG123_ENUM_API to
63 * prevent that remapping.
64 *
65 * You might want to define this to increase the chance of your binary
66 * working with an older version of the library. But if that is your goal,
67 * you should better build with an older version to begin with.
68 */
69 #ifndef MPG123_ENUM_API
70
71 #define out123_param out123_param2
72 #define out123_getparam out123_getparam2
73
74 #endif
75
76 #ifdef __cplusplus
77 extern "C" {
78 #endif
79
117 struct out123_struct;
119 typedef struct out123_struct out123_handle;
120
128 MPG123_EXPORT
129 const char *out123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch);
130
135 MPG123_EXPORT
136 unsigned int out123_libversion(unsigned int *patch);
137
139 enum out123_parms
140 {
141 OUT123_FLAGS = 1
142 , OUT123_PRELOAD
143 , OUT123_GAIN
144 , OUT123_VERBOSE
145 , OUT123_DEVICEBUFFER
153 , OUT123_PROPFLAGS
154 , OUT123_NAME
158 , OUT123_BINDIR
163 , OUT123_ADD_FLAGS
164 , OUT123_REMOVE_FLAGS
165 };
166
168 enum out123_flags
169 {
170 OUT123_HEADPHONES = 0x01
171 , OUT123_INTERNAL_SPEAKER = 0x02
172 , OUT123_LINE_OUT = 0x04
173 , OUT123_QUIET = 0x08
174 , OUT123_KEEP_PLAYING = 0x10
184 , OUT123_MUTE = 0x20
185 };
186
188 enum out123_propflags
189 {
190 OUT123_PROP_LIVE = 0x01
194 , OUT123_PROP_PERSISTENT = 0x02
198 };
199
205 MPG123_EXPORT
206 out123_handle *out123_new(void);
207
211 MPG123_EXPORT
212 void out123_del(out123_handle *ao);
213
219 MPG123_EXPORT void out123_free(void *ptr);
220
227 enum out123_error
228 {
229 OUT123_ERR = -1
230 , OUT123_OK = 0
231 , OUT123_DOOM
232 , OUT123_BAD_DRIVER_NAME
233 , OUT123_BAD_DRIVER
234 , OUT123_NO_DRIVER
235 , OUT123_NOT_LIVE
236 , OUT123_DEV_PLAY
237 , OUT123_DEV_OPEN
238 , OUT123_BUFFER_ERROR
241 , OUT123_MODULE_ERROR
242 , OUT123_ARG_ERROR
243 , OUT123_BAD_PARAM
244 , OUT123_SET_RO_PARAM
245 , OUT123_BAD_HANDLE
246 , OUT123_NOT_SUPPORTED
247 , OUT123_DEV_ENUMERATE
248 , OUT123_ERRCOUNT
249 };
250
256 MPG123_EXPORT
257 const char* out123_strerror(out123_handle *ao);
258
265 MPG123_EXPORT
266 int out123_errcode(out123_handle *ao);
267
272 MPG123_EXPORT
273 const char* out123_plain_strerror(int errcode);
274
306 MPG123_EXPORT
307 int out123_set_buffer(out123_handle *ao, size_t buffer_bytes);
308
309 #ifdef MPG123_ENUM_API
310
327 MPG123_EXPORT
328 int out123_param( out123_handle *ao, enum out123_parms code
329 , long value, double fvalue, const char *svalue );
330 #endif
331
349 MPG123_EXPORT
350 int out123_param2( out123_handle *ao, int code
351 , long value, double fvalue, const char *svalue );
352
353
355 #define out123_param_int(ao, code, value) \
356 out123_param((ao), (code), (value), 0., NULL)
357
358 #define out123_param_float(ao, code, value) \
359 out123_param((ao), (code), 0, (value), NULL)
360
361 #define out123_param_string(ao, code, value) \
362 out123_param((ao), (code), 0, 0., (value))
363
364 #ifdef MPG123_ENUM_API
365
378 MPG123_EXPORT
379 int out123_getparam( out123_handle *ao, enum out123_parms code
380 , long *ret_value, double *ret_fvalue, char* *ret_svalue );
381 #endif
382
396 MPG123_EXPORT
397 int out123_getparam2( out123_handle *ao, int code
398 , long *ret_value, double *ret_fvalue, char* *ret_svalue );
399
401 #define out123_getparam_int(ao, code, value) \
402 out123_getparam((ao), (code), (value), NULL, NULL)
403
404 #define out123_getparam_float(ao, code, value) \
405 out123_getparam((ao), (code), NULL, (value), NULL)
406
407 #define out123_getparam_string(ao, code, value) \
408 out123_getparam((ao), (code), NULL, NULL, (value))
409
415 MPG123_EXPORT
416 int out123_param_from(out123_handle *ao, out123_handle* from_ao);
417
434 MPG123_EXPORT
435 int out123_drivers(out123_handle *ao, char ***names, char ***descr);
436
465 MPG123_EXPORT
466 int out123_devices( out123_handle *ao, const char *driver
467 , char ***names, char ***descr, char **active_driver );
468
480 MPG123_EXPORT
481 void out123_stringlists_free(char **name, char **descr, int count);
482
483
496 MPG123_EXPORT
497 int out123_open(out123_handle *ao, const char* driver, const char* device);
498
510 MPG123_EXPORT
511 int out123_driver_info(out123_handle *ao, char **driver, char **device);
512
521 MPG123_EXPORT
522 void out123_close(out123_handle *ao);
523
541 MPG123_EXPORT
542 int out123_encodings(out123_handle *ao, long rate, int channels);
543
547 MPG123_EXPORT int out123_encsize(int encoding);
548
577 MPG123_EXPORT
578 int out123_formats( out123_handle *ao, const long *rates, int ratecount
579 , int minchannels, int maxchannels
580 , struct mpg123_fmt **fmtlist );
581
587 MPG123_EXPORT
588 int out123_enc_list(int **enclist);
589
594 MPG123_EXPORT
595 int out123_enc_byname(const char *name);
596
601 MPG123_EXPORT
602 const char* out123_enc_name(int encoding);
603
608 MPG123_EXPORT
609 const char* out123_enc_longname(int encoding);
610
623 MPG123_EXPORT
624 int out123_start( out123_handle *ao
625 , long rate, int channels, int encoding );
626
634 MPG123_EXPORT
635 void out123_pause(out123_handle *ao);
636
647 MPG123_EXPORT
648 void out123_continue(out123_handle *ao);
649
656 MPG123_EXPORT
657 void out123_stop(out123_handle *ao);
658
675 MPG123_EXPORT
676 size_t out123_play( out123_handle *ao
677 , void *buffer, size_t bytes );
678
688 MPG123_EXPORT
689 void out123_drop(out123_handle *ao);
690
698 MPG123_EXPORT
699 void out123_drain(out123_handle *ao);
700
718 MPG123_EXPORT
719 void out123_ndrain(out123_handle *ao, size_t bytes);
720
727 MPG123_EXPORT
728 size_t out123_buffered(out123_handle *ao);
729
740 MPG123_EXPORT
741 int out123_getformat( out123_handle *ao
742 , long *rate, int *channels, int *encoding, int *framesize );
743
746 #ifdef __cplusplus
747 }
748 #endif
749
750 #endif
751
OUT123_REMOVE_FLAGS
@ OUT123_REMOVE_FLAGS
Definition: out123.h:164
out123_drivers
MPG123_EXPORT int out123_drivers(out123_handle *ao, char ***names, char ***descr)
out123_getparam2
MPG123_EXPORT int out123_getparam2(out123_handle *ao, int code, long *ret_value, double *ret_fvalue, char **ret_svalue)
OUT123_DEV_ENUMERATE
@ OUT123_DEV_ENUMERATE
Definition: out123.h:247
fmt123.h
OUT123_BINDIR
@ OUT123_BINDIR
Definition: out123.h:158
OUT123_SET_RO_PARAM
@ OUT123_SET_RO_PARAM
Definition: out123.h:244
OUT123_DOOM
@ OUT123_DOOM
Definition: out123.h:231
out123_enc_name
const MPG123_EXPORT char * out123_enc_name(int encoding)
out123_set_buffer
MPG123_EXPORT int out123_set_buffer(out123_handle *ao, size_t buffer_bytes)
out123_plain_strerror
const MPG123_EXPORT char * out123_plain_strerror(int errcode)
out123_driver_info
MPG123_EXPORT int out123_driver_info(out123_handle *ao, char **driver, char **device)
out123_devices
MPG123_EXPORT int out123_devices(out123_handle *ao, const char *driver, char ***names, char ***descr, char **active_driver)
out123_buffered
MPG123_EXPORT size_t out123_buffered(out123_handle *ao)
OUT123_BAD_DRIVER
@ OUT123_BAD_DRIVER
Definition: out123.h:233
OUT123_BAD_PARAM
@ OUT123_BAD_PARAM
Definition: out123.h:243
out123_getformat
MPG123_EXPORT int out123_getformat(out123_handle *ao, long *rate, int *channels, int *encoding, int *framesize)
OUT123_BAD_HANDLE
@ OUT123_BAD_HANDLE
Definition: out123.h:245
OUT123_QUIET
@ OUT123_QUIET
Definition: out123.h:173
OUT123_ARG_ERROR
@ OUT123_ARG_ERROR
Definition: out123.h:242
OUT123_DEVICEBUFFER
@ OUT123_DEVICEBUFFER
Definition: out123.h:145
OUT123_KEEP_PLAYING
@ OUT123_KEEP_PLAYING
Definition: out123.h:174
OUT123_OK
@ OUT123_OK
Definition: out123.h:230
mpg123_fmt
Definition: fmt123.h:147
out123_distversion
const MPG123_EXPORT char * out123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch)
out123_enc_byname
MPG123_EXPORT int out123_enc_byname(const char *name)
OUT123_NO_DRIVER
@ OUT123_NO_DRIVER
Definition: out123.h:234
out123_ndrain
MPG123_EXPORT void out123_ndrain(out123_handle *ao, size_t bytes)
out123_param
MPG123_EXPORT int out123_param(out123_handle *ao, enum out123_parms code, long value, double fvalue, const char *svalue)
out123_start
MPG123_EXPORT int out123_start(out123_handle *ao, long rate, int channels, int encoding)
out123_pause
MPG123_EXPORT void out123_pause(out123_handle *ao)
OUT123_NOT_SUPPORTED
@ OUT123_NOT_SUPPORTED
Definition: out123.h:246
out123_libversion
MPG123_EXPORT unsigned int out123_libversion(unsigned int *patch)
out123_close
MPG123_EXPORT void out123_close(out123_handle *ao)
out123_continue
MPG123_EXPORT void out123_continue(out123_handle *ao)
OUT123_HEADPHONES
@ OUT123_HEADPHONES
Definition: out123.h:170
out123_flags
out123_flags
Definition: out123.h:168
out123_param_from
MPG123_EXPORT int out123_param_from(out123_handle *ao, out123_handle *from_ao)
out123_getparam
MPG123_EXPORT int out123_getparam(out123_handle *ao, enum out123_parms code, long *ret_value, double *ret_fvalue, char **ret_svalue)
out123_encsize
MPG123_EXPORT int out123_encsize(int encoding)
out123_handle
struct out123_struct out123_handle
Definition: out123.h:119
out123_enc_list
MPG123_EXPORT int out123_enc_list(int **enclist)
out123_strerror
const MPG123_EXPORT char * out123_strerror(out123_handle *ao)
out123_new
MPG123_EXPORT out123_handle * out123_new(void)
out123_stringlists_free
MPG123_EXPORT void out123_stringlists_free(char **name, char **descr, int count)
OUT123_NOT_LIVE
@ OUT123_NOT_LIVE
Definition: out123.h:235
out123_error
out123_error
Definition: out123.h:227
OUT123_MODULE_ERROR
@ OUT123_MODULE_ERROR
Definition: out123.h:241
OUT123_FLAGS
@ OUT123_FLAGS
Definition: out123.h:141
out123_play
MPG123_EXPORT size_t out123_play(out123_handle *ao, void *buffer, size_t bytes)
out123_open
MPG123_EXPORT int out123_open(out123_handle *ao, const char *driver, const char *device)
OUT123_PROP_LIVE
@ OUT123_PROP_LIVE
Definition: out123.h:190
MPG123_EXPORT
#define MPG123_EXPORT
Definition: out123.h:53
OUT123_NAME
@ OUT123_NAME
Definition: out123.h:154
OUT123_MUTE
@ OUT123_MUTE
Definition: out123.h:184
OUT123_BAD_DRIVER_NAME
@ OUT123_BAD_DRIVER_NAME
Definition: out123.h:232
OUT123_PRELOAD
@ OUT123_PRELOAD
Definition: out123.h:142
out123_enc_longname
const MPG123_EXPORT char * out123_enc_longname(int encoding)
out123_encodings
MPG123_EXPORT int out123_encodings(out123_handle *ao, long rate, int channels)
OUT123_DEV_PLAY
@ OUT123_DEV_PLAY
Definition: out123.h:236
out123_parms
out123_parms
Definition: out123.h:139
out123_drop
MPG123_EXPORT void out123_drop(out123_handle *ao)
out123_del
MPG123_EXPORT void out123_del(out123_handle *ao)
OUT123_ERRCOUNT
@ OUT123_ERRCOUNT
Definition: out123.h:248
OUT123_ERR
@ OUT123_ERR
Definition: out123.h:229
OUT123_GAIN
@ OUT123_GAIN
Definition: out123.h:143
OUT123_INTERNAL_SPEAKER
@ OUT123_INTERNAL_SPEAKER
Definition: out123.h:171
out123_formats
MPG123_EXPORT int out123_formats(out123_handle *ao, const long *rates, int ratecount, int minchannels, int maxchannels, struct mpg123_fmt **fmtlist)
out123_free
MPG123_EXPORT void out123_free(void *ptr)
OUT123_DEV_OPEN
@ OUT123_DEV_OPEN
Definition: out123.h:237
out123_errcode
MPG123_EXPORT int out123_errcode(out123_handle *ao)
OUT123_PROP_PERSISTENT
@ OUT123_PROP_PERSISTENT
Definition: out123.h:194
OUT123_LINE_OUT
@ OUT123_LINE_OUT
Definition: out123.h:172
OUT123_PROPFLAGS
@ OUT123_PROPFLAGS
Definition: out123.h:153
out123_stop
MPG123_EXPORT void out123_stop(out123_handle *ao)
OUT123_BUFFER_ERROR
@ OUT123_BUFFER_ERROR
Definition: out123.h:238
out123_propflags
out123_propflags
Definition: out123.h:188
out123_drain
MPG123_EXPORT void out123_drain(out123_handle *ao)
OUT123_VERBOSE
@ OUT123_VERBOSE
Definition: out123.h:144
out123_param2
MPG123_EXPORT int out123_param2(out123_handle *ao, int code, long value, double fvalue, const char *svalue)
OUT123_ADD_FLAGS
@ OUT123_ADD_FLAGS
Definition: out123.h:163