out123.h

Go to the documentation of this file.

/*
    out123: audio output interface
 
    copyright 1995-2016 by the mpg123 project,
    free software under the terms of the LGPL 2.1
 
    see COPYING and AUTHORS files in distribution or http://mpg123.org
    initially written as audio.h by Michael Hipp, reworked into out123 API
    by Thomas Orgis
*/
 
#ifndef _OUT123_H_
#define _OUT123_H_
 
#define OUT123_API_VERSION 5
#define OUT123_PATCHLEVEL  1
 
/* We only need size_t definition. */
#include <stddef.h>
 
/* Common audio encoding specification, including a macro for getting
 *  size of encoded samples in bytes. Said macro is still hardcoded
 *  into out123_encsize(). Relying on this one may help an old program
 *  know sizes of encodings added to fmt123.h later on.
 *  If you don't care, just use the macro.
 */
#include "fmt123.h"
 
#ifndef MPG123_EXPORT
#ifdef BUILD_MPG123_DLL
/* The dll exports. */
#define MPG123_EXPORT __declspec(dllexport)
#else
#ifdef LINK_MPG123_DLL
/* The exe imports. */
#define MPG123_EXPORT __declspec(dllimport)
#else
/* Nothing on normal/UNIX builds */
#define MPG123_EXPORT
#endif
#endif
#endif
 
/* Earlier versions of libout123 put enums into public API calls,
 * thich is not exactly safe. There are ABI rules, but you can use
 * compiler switches to change the sizes of enums. It is safer not
 * to have them in API calls. Thus, the default is to remap calls and
 * structs to variants that use plain ints. Define MPG123_ENUM_API to
 * prevent that remapping.
 *
 * You might want to define this to increase the chance of your binary
 * working with an older version of the library. But if that is your goal,
 * you should better build with an older version to begin with.
 */
#ifndef MPG123_ENUM_API
 
#define out123_param    out123_param2
#define out123_getparam out123_getparam2
 
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct out123_struct;
typedef struct out123_struct out123_handle;
 
MPG123_EXPORT
const char *out123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch);
 
MPG123_EXPORT
unsigned int out123_libversion(unsigned int *patch);
 
enum out123_parms
{
    OUT123_FLAGS = 1 
,   OUT123_PRELOAD 
,   OUT123_GAIN    
,   OUT123_VERBOSE 
,   OUT123_DEVICEBUFFER 
,   OUT123_PROPFLAGS 
,   OUT123_NAME 
,   OUT123_BINDIR 
,   OUT123_ADD_FLAGS 
,   OUT123_REMOVE_FLAGS 
};
 
enum out123_flags
{
    OUT123_HEADPHONES       = 0x01 
,   OUT123_INTERNAL_SPEAKER = 0x02 
,   OUT123_LINE_OUT         = 0x04 
,   OUT123_QUIET            = 0x08 
,   OUT123_KEEP_PLAYING     = 0x10 
,   OUT123_MUTE             = 0x20 
};
 
enum out123_propflags
{
    OUT123_PROP_LIVE = 0x01 
,   OUT123_PROP_PERSISTENT = 0x02 
};
 
MPG123_EXPORT
out123_handle *out123_new(void);
 
MPG123_EXPORT
void out123_del(out123_handle *ao);
 
MPG123_EXPORT void out123_free(void *ptr);
 
enum out123_error
{
    OUT123_ERR = -1 
,   OUT123_OK  = 0  
,   OUT123_DOOM 
,   OUT123_BAD_DRIVER_NAME 
,   OUT123_BAD_DRIVER 
,   OUT123_NO_DRIVER 
,   OUT123_NOT_LIVE 
,   OUT123_DEV_PLAY 
,   OUT123_DEV_OPEN 
,   OUT123_BUFFER_ERROR 
,   OUT123_MODULE_ERROR 
,   OUT123_ARG_ERROR 
,   OUT123_BAD_PARAM 
,   OUT123_SET_RO_PARAM 
,   OUT123_BAD_HANDLE 
,   OUT123_NOT_SUPPORTED 
,   OUT123_DEV_ENUMERATE 
,   OUT123_ERRCOUNT 
};
 
MPG123_EXPORT
const char* out123_strerror(out123_handle *ao);
 
MPG123_EXPORT
int out123_errcode(out123_handle *ao);
 
MPG123_EXPORT
const char* out123_plain_strerror(int errcode);
 
MPG123_EXPORT
int out123_set_buffer(out123_handle *ao, size_t buffer_bytes);
 
#ifdef MPG123_ENUM_API
MPG123_EXPORT
int out123_param( out123_handle *ao, enum out123_parms code
,                 long value, double fvalue, const char *svalue );
#endif
 
MPG123_EXPORT
int out123_param2( out123_handle *ao, int code
,                 long value, double fvalue, const char *svalue );
 
 
#define out123_param_int(ao, code, value) \
    out123_param((ao), (code), (value), 0., NULL)
#define out123_param_float(ao, code, value) \
    out123_param((ao), (code), 0, (value), NULL)
#define out123_param_string(ao, code, value) \
    out123_param((ao), (code), 0, 0., (value))
 
#ifdef MPG123_ENUM_API
MPG123_EXPORT
int out123_getparam( out123_handle *ao, enum out123_parms code
,                    long *ret_value, double *ret_fvalue, char* *ret_svalue );
#endif
 
MPG123_EXPORT
int out123_getparam2( out123_handle *ao, int code
,                    long *ret_value, double *ret_fvalue, char* *ret_svalue );
 
#define out123_getparam_int(ao, code, value) \
    out123_getparam((ao), (code), (value), NULL, NULL)
#define out123_getparam_float(ao, code, value) \
    out123_getparam((ao), (code), NULL, (value), NULL)
#define out123_getparam_string(ao, code, value) \
    out123_getparam((ao), (code), NULL, NULL, (value))
 
MPG123_EXPORT
int out123_param_from(out123_handle *ao, out123_handle* from_ao);
 
MPG123_EXPORT
int out123_drivers(out123_handle *ao, char ***names, char ***descr);
 
MPG123_EXPORT
int out123_devices( out123_handle *ao, const char *driver
,   char ***names, char ***descr, char **active_driver );
 
MPG123_EXPORT
void out123_stringlists_free(char **name, char **descr, int count);
 
 
MPG123_EXPORT
int out123_open(out123_handle *ao, const char* driver, const char* device);
 
MPG123_EXPORT
int out123_driver_info(out123_handle *ao, char **driver, char **device);
 
MPG123_EXPORT
void out123_close(out123_handle *ao);
 
MPG123_EXPORT
int out123_encodings(out123_handle *ao, long rate, int channels);
 
MPG123_EXPORT int out123_encsize(int encoding);
 
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_enc_list(int **enclist);
 
MPG123_EXPORT
int out123_enc_byname(const char *name);
 
MPG123_EXPORT
const char* out123_enc_name(int encoding);
 
MPG123_EXPORT
const char* out123_enc_longname(int encoding);
 
MPG123_EXPORT
int out123_start( out123_handle *ao
,                 long rate, int channels, int encoding );
 
MPG123_EXPORT
void out123_pause(out123_handle *ao);
 
MPG123_EXPORT
void out123_continue(out123_handle *ao);
 
MPG123_EXPORT
void out123_stop(out123_handle *ao);
 
MPG123_EXPORT
size_t out123_play( out123_handle *ao
                  , void *buffer, size_t bytes );
 
MPG123_EXPORT
void out123_drop(out123_handle *ao);
 
MPG123_EXPORT
void out123_drain(out123_handle *ao);
 
MPG123_EXPORT
void out123_ndrain(out123_handle *ao, size_t bytes);
 
MPG123_EXPORT
size_t out123_buffered(out123_handle *ao);
 
MPG123_EXPORT
int out123_getformat( out123_handle *ao
,   long *rate, int *channels, int *encoding, int *framesize );
 
#ifdef __cplusplus
}
#endif
 
#endif