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
23 #define OUT123_PATCHLEVEL 1
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
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 
129 const char *out123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch);
130 
136 unsigned int out123_libversion(unsigned int *patch);
137 
140 {
141  OUT123_FLAGS = 1
165 };
166 
169 {
170  OUT123_HEADPHONES = 0x01
173 , OUT123_QUIET = 0x08
184 , OUT123_MUTE = 0x20
185 };
186 
189 {
190  OUT123_PROP_LIVE = 0x01
198 };
199 
207 
213 
219 MPG123_EXPORT void out123_free(void *ptr);
220 
228 {
229  OUT123_ERR = -1
230 , OUT123_OK = 0
249 };
250 
258 
267 
273 const char* out123_plain_strerror(int errcode);
274 
307 int out123_set_buffer(out123_handle *ao, size_t buffer_bytes);
308 
309 #ifdef MPG123_ENUM_API
329 , long value, double fvalue, const char *svalue );
330 #endif
331 
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)
358 #define out123_param_float(ao, code, value) \
359  out123_param((ao), (code), 0, (value), NULL)
361 #define out123_param_string(ao, code, value) \
362  out123_param((ao), (code), 0, 0., (value))
363 
364 #ifdef MPG123_ENUM_API
380 , long *ret_value, double *ret_fvalue, char* *ret_svalue );
381 #endif
382 
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)
404 #define out123_getparam_float(ao, code, value) \
405  out123_getparam((ao), (code), NULL, (value), NULL)
407 #define out123_getparam_string(ao, code, value) \
408  out123_getparam((ao), (code), NULL, NULL, (value))
409 
417 
435 int out123_drivers(out123_handle *ao, char ***names, char ***descr);
436 
466 int out123_devices( out123_handle *ao, const char *driver
467 , char ***names, char ***descr, char **active_driver );
468 
481 void out123_stringlists_free(char **name, char **descr, int count);
482 
483 
497 int out123_open(out123_handle *ao, const char* driver, const char* device);
498 
511 int out123_driver_info(out123_handle *ao, char **driver, char **device);
512 
523 
542 int out123_encodings(out123_handle *ao, long rate, int channels);
543 
547 MPG123_EXPORT int out123_encsize(int encoding);
548 
578 int out123_formats( out123_handle *ao, const long *rates, int ratecount
579  , int minchannels, int maxchannels
580  , struct mpg123_fmt **fmtlist );
581 
588 int out123_enc_list(int **enclist);
589 
595 int out123_enc_byname(const char *name);
596 
602 const char* out123_enc_name(int encoding);
603 
609 const char* out123_enc_longname(int encoding);
610 
625 , long rate, int channels, int encoding );
626 
636 
649 
658 
677  , void *buffer, size_t bytes );
678 
690 
700 
719 void out123_ndrain(out123_handle *ao, size_t bytes);
720 
729 
742 , long *rate, int *channels, int *encoding, int *framesize );
743 
746 #ifdef __cplusplus
747 }
748 #endif
749 
750 #endif
751 
MPG123_EXPORT void out123_close(out123_handle *ao)
MPG123_EXPORT void out123_stop(out123_handle *ao)
MPG123_EXPORT const char * out123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch)
MPG123_EXPORT void out123_drop(out123_handle *ao)
MPG123_EXPORT int out123_set_buffer(out123_handle *ao, size_t buffer_bytes)
MPG123_EXPORT int out123_open(out123_handle *ao, const char *driver, const char *device)
MPG123_EXPORT void out123_free(void *ptr)
MPG123_EXPORT int out123_enc_byname(const char *name)
MPG123_EXPORT void out123_ndrain(out123_handle *ao, size_t bytes)
MPG123_EXPORT int out123_driver_info(out123_handle *ao, char **driver, char **device)
MPG123_EXPORT const char * out123_plain_strerror(int errcode)
MPG123_EXPORT out123_handle * out123_new(void)
MPG123_EXPORT void out123_continue(out123_handle *ao)
MPG123_EXPORT int out123_formats(out123_handle *ao, const long *rates, int ratecount, int minchannels, int maxchannels, struct mpg123_fmt **fmtlist)
MPG123_EXPORT int out123_devices(out123_handle *ao, const char *driver, char ***names, char ***descr, char **active_driver)
MPG123_EXPORT int out123_getparam2(out123_handle *ao, int code, long *ret_value, double *ret_fvalue, char **ret_svalue)
MPG123_EXPORT int out123_encsize(int encoding)
MPG123_EXPORT int out123_param_from(out123_handle *ao, out123_handle *from_ao)
MPG123_EXPORT const char * out123_enc_name(int encoding)
out123_propflags
Definition: out123.h:189
out123_error
Definition: out123.h:228
MPG123_EXPORT int out123_enc_list(int **enclist)
struct out123_struct out123_handle
Definition: out123.h:119
MPG123_EXPORT int out123_param(out123_handle *ao, enum out123_parms code, long value, double fvalue, const char *svalue)
MPG123_EXPORT void out123_drain(out123_handle *ao)
MPG123_EXPORT int out123_param2(out123_handle *ao, int code, long value, double fvalue, const char *svalue)
MPG123_EXPORT unsigned int out123_libversion(unsigned int *patch)
out123_flags
Definition: out123.h:169
MPG123_EXPORT void out123_del(out123_handle *ao)
MPG123_EXPORT int out123_errcode(out123_handle *ao)
out123_parms
Definition: out123.h:140
MPG123_EXPORT int out123_start(out123_handle *ao, long rate, int channels, int encoding)
MPG123_EXPORT int out123_getformat(out123_handle *ao, long *rate, int *channels, int *encoding, int *framesize)
MPG123_EXPORT int out123_drivers(out123_handle *ao, char ***names, char ***descr)
MPG123_EXPORT size_t out123_play(out123_handle *ao, void *buffer, size_t bytes)
MPG123_EXPORT size_t out123_buffered(out123_handle *ao)
MPG123_EXPORT int out123_encodings(out123_handle *ao, long rate, int channels)
MPG123_EXPORT const char * out123_enc_longname(int encoding)
MPG123_EXPORT int out123_getparam(out123_handle *ao, enum out123_parms code, long *ret_value, double *ret_fvalue, char **ret_svalue)
MPG123_EXPORT void out123_stringlists_free(char **name, char **descr, int count)
MPG123_EXPORT void out123_pause(out123_handle *ao)
MPG123_EXPORT const char * out123_strerror(out123_handle *ao)
@ OUT123_PROP_LIVE
Definition: out123.h:190
@ OUT123_PROP_PERSISTENT
Definition: out123.h:194
@ OUT123_NOT_LIVE
Definition: out123.h:235
@ OUT123_BAD_DRIVER_NAME
Definition: out123.h:232
@ OUT123_ERR
Definition: out123.h:229
@ OUT123_NO_DRIVER
Definition: out123.h:234
@ OUT123_ARG_ERROR
Definition: out123.h:242
@ OUT123_NOT_SUPPORTED
Definition: out123.h:246
@ OUT123_OK
Definition: out123.h:230
@ OUT123_DOOM
Definition: out123.h:231
@ OUT123_DEV_PLAY
Definition: out123.h:236
@ OUT123_BAD_DRIVER
Definition: out123.h:233
@ OUT123_SET_RO_PARAM
Definition: out123.h:244
@ OUT123_DEV_ENUMERATE
Definition: out123.h:247
@ OUT123_BAD_PARAM
Definition: out123.h:243
@ OUT123_ERRCOUNT
Definition: out123.h:248
@ OUT123_BAD_HANDLE
Definition: out123.h:245
@ OUT123_BUFFER_ERROR
Definition: out123.h:238
@ OUT123_DEV_OPEN
Definition: out123.h:237
@ OUT123_MODULE_ERROR
Definition: out123.h:241
@ OUT123_QUIET
Definition: out123.h:173
@ OUT123_HEADPHONES
Definition: out123.h:170
@ OUT123_LINE_OUT
Definition: out123.h:172
@ OUT123_INTERNAL_SPEAKER
Definition: out123.h:171
@ OUT123_MUTE
Definition: out123.h:184
@ OUT123_KEEP_PLAYING
Definition: out123.h:174
@ OUT123_REMOVE_FLAGS
Definition: out123.h:164
@ OUT123_BINDIR
Definition: out123.h:158
@ OUT123_PROPFLAGS
Definition: out123.h:153
@ OUT123_PRELOAD
Definition: out123.h:142
@ OUT123_NAME
Definition: out123.h:154
@ OUT123_GAIN
Definition: out123.h:143
@ OUT123_DEVICEBUFFER
Definition: out123.h:145
@ OUT123_VERBOSE
Definition: out123.h:144
@ OUT123_FLAGS
Definition: out123.h:141
@ OUT123_ADD_FLAGS
Definition: out123.h:163
#define MPG123_EXPORT
Definition: out123.h:53
Hopefully valid HTML! Valid CSS!