|
Packit |
c32a2d |
/*
|
|
Packit |
c32a2d |
out123: audio output interface
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
copyright 1995-2016 by the mpg123 project,
|
|
Packit |
c32a2d |
free software under the terms of the LGPL 2.1
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
see COPYING and AUTHORS files in distribution or http://mpg123.org
|
|
Packit |
c32a2d |
initially written as audio.h by Michael Hipp, reworked into out123 API
|
|
Packit |
c32a2d |
by Thomas Orgis
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
#ifndef _OUT123_H_
|
|
Packit |
c32a2d |
#define _OUT123_H_
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** \file out123.h The header file for the libout123 audio output facility. */
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/* We only need size_t definition. */
|
|
Packit |
c32a2d |
#include <stddef.h>
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/* Common audio encoding specification, including a macro for getting
|
|
Packit |
c32a2d |
* size of encodined samples in bytes. Said macro is still hardcoded
|
|
Packit |
c32a2d |
* into out123_encsize(). Relying on this one may help an old program
|
|
Packit |
c32a2d |
* know sizes of encodings added to fmt123.h later on.
|
|
Packit |
c32a2d |
* If you don't care, just use the macro.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
#include <fmt123.h>
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** A macro to check at compile time which set of API functions to expect.
|
|
Packit |
c32a2d |
* This should be incremented at least each time a new symbol is added
|
|
Packit |
c32a2d |
* to the header.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
#define OUT123_API_VERSION @OUTAPI_VERSION@
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
#ifndef MPG123_EXPORT
|
|
Packit |
c32a2d |
/** Defines needed for MS Visual Studio(tm) DLL builds.
|
|
Packit |
c32a2d |
* Every public function must be prefixed with MPG123_EXPORT. When building
|
|
Packit |
c32a2d |
* the DLL ensure to define BUILD_MPG123_DLL. This makes the function accessible
|
|
Packit |
c32a2d |
* for clients and includes it in the import library which is created together
|
|
Packit |
c32a2d |
* with the DLL. When consuming the DLL ensure to define LINK_MPG123_DLL which
|
|
Packit |
c32a2d |
* imports the functions from the DLL.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
#ifdef BUILD_MPG123_DLL
|
|
Packit |
c32a2d |
/* The dll exports. */
|
|
Packit |
c32a2d |
#define MPG123_EXPORT __declspec(dllexport)
|
|
Packit |
c32a2d |
#else
|
|
Packit |
c32a2d |
#ifdef LINK_MPG123_DLL
|
|
Packit |
c32a2d |
/* The exe imports. */
|
|
Packit |
c32a2d |
#define MPG123_EXPORT __declspec(dllimport)
|
|
Packit |
c32a2d |
#else
|
|
Packit |
c32a2d |
/* Nothing on normal/UNIX builds */
|
|
Packit |
c32a2d |
#define MPG123_EXPORT
|
|
Packit |
c32a2d |
#endif
|
|
Packit |
c32a2d |
#endif
|
|
Packit |
c32a2d |
#endif
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
#ifdef __cplusplus
|
|
Packit |
c32a2d |
extern "C" {
|
|
Packit |
c32a2d |
#endif
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** \defgroup out123_api out123 library API
|
|
Packit |
c32a2d |
* This is out123, a library focused on continuous playback of audio streams
|
|
Packit |
c32a2d |
* via various platform-specific output methods. It glosses over details of
|
|
Packit |
c32a2d |
* the native APIs to give an interface close to simply writing data to a
|
|
Packit |
c32a2d |
* file. There might be the option to tune details like buffer (period) sizes
|
|
Packit |
c32a2d |
* and the number of them on the device side in future, but the focus of the
|
|
Packit |
c32a2d |
* library is to ease the use case of just getting that raw audio data out
|
|
Packit |
c32a2d |
* there, without interruptions.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* The basic idea is to create a handle with out123_new() and open a certain
|
|
Packit |
c32a2d |
* output device (using a certain driver module, possibly build-time defaults)
|
|
Packit |
c32a2d |
* with out123_open(). Now, you can query the output device for supported
|
|
Packit |
c32a2d |
* encodings for given rate and channel count with out123_get_encodings() and
|
|
Packit |
c32a2d |
* decide what to use for actually starting playback with out123_start().
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* Then, you just need to provide (interleaved pcm) data for playback with
|
|
Packit |
c32a2d |
* out123_play(), which will block when the device's buffers are full. You get
|
|
Packit |
c32a2d |
* your timing from that (instead of callbacks). If your program does the
|
|
Packit |
c32a2d |
* production of the audio data just a little bit faster than the playback,
|
|
Packit |
c32a2d |
* causing out123_play() to block ever so briefly, you're fine.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* You stop playback with out123_stop(), or just close the device and driver
|
|
Packit |
c32a2d |
* via out123_close(), or even just decide to drop it all and do out123_del()
|
|
Packit |
c32a2d |
* right away when you're done.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* There are other functions for specific needs, but the basic idea should be
|
|
Packit |
c32a2d |
* covered by the above.
|
|
Packit |
c32a2d |
@{
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Opaque structure for the libout123 handle. */
|
|
Packit |
c32a2d |
struct out123_struct;
|
|
Packit |
c32a2d |
/** Typedef shortcut as preferrend name for the handle type. */
|
|
Packit |
c32a2d |
typedef struct out123_struct out123_handle;
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Enumeration of codes for the parameters that it is possible to set/get. */
|
|
Packit |
c32a2d |
enum out123_parms
|
|
Packit |
c32a2d |
{
|
|
Packit |
c32a2d |
OUT123_FLAGS = 1 /**< integer, various flags, see enum out123_flags */
|
|
Packit |
c32a2d |
, OUT123_PRELOAD /**< float, fraction of buffer to fill before playback */
|
|
Packit |
c32a2d |
, OUT123_GAIN /**< integer, output device gain (module-specific) */
|
|
Packit |
c32a2d |
, OUT123_VERBOSE /**< integer, verbosity to stderr, >= 0 */
|
|
Packit |
c32a2d |
, OUT123_DEVICEBUFFER /**<
|
|
Packit |
c32a2d |
* float, length of device buffer in seconds;
|
|
Packit |
c32a2d |
* This might be ignored, might have only a loose relation to actual
|
|
Packit |
c32a2d |
* buffer sizes and latency, depending on output driver. Try to tune
|
|
Packit |
c32a2d |
* this before opening a device if you want to influcence latency or reduce
|
|
Packit |
c32a2d |
* dropouts. Value <= 0 uses some default, usually favouring stable playback
|
|
Packit |
c32a2d |
* over low latency. Values above 0.5 are probably too much.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
, OUT123_PROPFLAGS /**< integer, query driver/device property flags (r/o) */
|
|
Packit |
c32a2d |
, OUT123_NAME /**< string, name of this instance (NULL restores default);
|
|
Packit |
c32a2d |
* The value returned by out123_getparam() might be different if the audio
|
|
Packit |
c32a2d |
* backend changed it (to be unique among clients, p.ex.).
|
|
Packit |
c32a2d |
* TODO: The name provided here is used as prefix in diagnostic messages. */
|
|
Packit |
c32a2d |
, OUT123_BINDIR /**< string, path to a program binary directory to use
|
|
Packit |
c32a2d |
* as starting point in the search for the output module directory
|
|
Packit |
c32a2d |
* (e.g. ../lib/mpg123 or ./plugins). The environment variable MPG123_MODDIR
|
|
Packit |
c32a2d |
* is always tried first and the in-built installation path last.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
};
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Flags to tune out123 behaviour */
|
|
Packit |
c32a2d |
enum out123_flags
|
|
Packit |
c32a2d |
{
|
|
Packit |
c32a2d |
OUT123_HEADPHONES = 0x01 /**< output to headphones (if supported) */
|
|
Packit |
c32a2d |
, OUT123_INTERNAL_SPEAKER = 0x02 /**< output to speaker (if supported) */
|
|
Packit |
c32a2d |
, OUT123_LINE_OUT = 0x04 /**< output to line out (if supported) */
|
|
Packit |
c32a2d |
, OUT123_QUIET = 0x08 /**< no printouts to standard error */
|
|
Packit |
c32a2d |
, OUT123_KEEP_PLAYING = 0x10 /**<
|
|
Packit |
c32a2d |
* When this is set (default), playback continues in a loop when the device
|
|
Packit |
c32a2d |
* does not consume all given data at once. This happens when encountering
|
|
Packit |
c32a2d |
* signals (like SIGSTOP, SIGCONT) that cause interruption of the underlying
|
|
Packit |
c32a2d |
* functions.
|
|
Packit |
c32a2d |
* Note that this flag is meaningless when the optional buffer is employed,
|
|
Packit |
c32a2d |
* There, your program will always block until the buffer completely took
|
|
Packit |
c32a2d |
* over the data given to it via out123_play(), unless a communication error
|
|
Packit |
c32a2d |
* arises.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
};
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Read-only output driver/device property flags (OUT123_PROPFLAGS). */
|
|
Packit |
c32a2d |
enum out123_propflags
|
|
Packit |
c32a2d |
{
|
|
Packit |
c32a2d |
OUT123_PROP_LIVE = 0x01 /**< This is a live output, meaning that
|
|
Packit |
c32a2d |
* special care might be needed for pauses in playback (p.ex. stream
|
|
Packit |
c32a2d |
* of silence instead of interruption), as opposed to files on disk.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
, OUT123_PROP_PERSISTENT = 0x02 /**< This (live) output does not need
|
|
Packit |
c32a2d |
* special care for pauses (continues with silence itself),
|
|
Packit |
c32a2d |
* out123_pause() does nothing to the device.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
};
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Create a new output handle.
|
|
Packit |
c32a2d |
* This only allocates and initializes memory, so the only possible
|
|
Packit |
c32a2d |
* error condition is running out of memory.
|
|
Packit |
c32a2d |
* \return pointer to new handle or NULL on error
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
out123_handle *out123_new(void);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Delete output handle.
|
|
Packit |
c32a2d |
* This implies out123_close().
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
void out123_del(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Error code enumeration
|
|
Packit |
c32a2d |
* API calls return a useful (positve) value or zero (OUT123_OK) on simple
|
|
Packit |
c32a2d |
* success. A negative value (-1 == OUT123_ERR) usually indicates that some
|
|
Packit |
c32a2d |
* error occured. Which one, that can be queried using out123_errcode()
|
|
Packit |
c32a2d |
* and friends.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
enum out123_error
|
|
Packit |
c32a2d |
{
|
|
Packit |
c32a2d |
OUT123_ERR = -1 /**< generic alias for verbosity, always == -1 */
|
|
Packit |
c32a2d |
, OUT123_OK = 0 /**< just a name for zero, not going to change */
|
|
Packit |
c32a2d |
, OUT123_DOOM /**< dazzled, out of memory */
|
|
Packit |
c32a2d |
, OUT123_BAD_DRIVER_NAME /**< bad driver name given */
|
|
Packit |
c32a2d |
, OUT123_BAD_DRIVER /**< unspecified issue loading a driver */
|
|
Packit |
c32a2d |
, OUT123_NO_DRIVER /**< no driver loaded */
|
|
Packit |
c32a2d |
, OUT123_NOT_LIVE /**< no active audio device */
|
|
Packit |
c32a2d |
, OUT123_DEV_PLAY /**< some device playback error */
|
|
Packit |
c32a2d |
, OUT123_DEV_OPEN /**< error opening device */
|
|
Packit |
c32a2d |
, OUT123_BUFFER_ERROR /**<
|
|
Packit |
c32a2d |
* Some (really unexpected) error in buffer infrastructure.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
, OUT123_MODULE_ERROR /**< basic failure in module loading */
|
|
Packit |
c32a2d |
, OUT123_ARG_ERROR /**< some bad function arguments supplied */
|
|
Packit |
c32a2d |
, OUT123_BAD_PARAM /**< unknown parameter code */
|
|
Packit |
c32a2d |
, OUT123_SET_RO_PARAM /**< attempt to set read-only parameter */
|
|
Packit |
c32a2d |
, OUT123_BAD_HANDLE /**< bad handle pointer (NULL, usually) */
|
|
Packit |
c32a2d |
, OUT123_ERRCOUNT /**< placeholder for shaping arrays */
|
|
Packit |
c32a2d |
};
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get string representation of last encountered error in the
|
|
Packit |
c32a2d |
* context of given handle.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \return error string
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
const char* out123_strerror(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get the plain errcode intead of a string.
|
|
Packit |
c32a2d |
* Note that this used to return OUT123_ERR instead of
|
|
Packit |
c32a2d |
* OUT123_BAD_HANDLE in case of ao==NULL before mpg123-1.23.5 .
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \return error code recorded in handle or OUT123_BAD_HANDLE
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_errcode(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Return the error string for a given error code.
|
|
Packit |
c32a2d |
* \param errcode the integer error code
|
|
Packit |
c32a2d |
* \return error string
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
const char* out123_plain_strerror(int errcode);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Set a desired output buffer size.
|
|
Packit |
c32a2d |
* This starts a separate process that handles the audio output, decoupling
|
|
Packit |
c32a2d |
* the latter from the main process with a memory buffer and saving you the
|
|
Packit |
c32a2d |
* burden to ensure sparing CPU cycles for actual playback.
|
|
Packit |
c32a2d |
* This is for applicatons that prefer continuous playback over small latency.
|
|
Packit |
c32a2d |
* In other words: The kind of applications that out123 is designed for.
|
|
Packit |
c32a2d |
* This routine always kills off any currently active audio output module /
|
|
Packit |
c32a2d |
* device, even if you just disable the buffer when there is no buffer.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* Keep this in mind for memory-constrainted systems: Activating the
|
|
Packit |
c32a2d |
* buffer causes a fork of the calling process, doubling the virtual memory
|
|
Packit |
c32a2d |
* use. Depending on your operating system kernel's behaviour regarding
|
|
Packit |
c32a2d |
* memory overcommit, it might be wise to call out123_set_buffer() very
|
|
Packit |
c32a2d |
* early in your program before allocating lots of memory.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* There _might_ be a change to threads in future, but for now this is
|
|
Packit |
c32a2d |
* classic fork with shared memory, working without any threading library.
|
|
Packit |
c32a2d |
* If your platform or build does not support that, you will always get an
|
|
Packit |
c32a2d |
* error on trying to set up a non-zero buffer (but the API call will be
|
|
Packit |
c32a2d |
* present).
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* Also, if you do intend to use this from a multithreaded program, think
|
|
Packit |
c32a2d |
* twice and make sure that your setup is happy with forking full-blown
|
|
Packit |
c32a2d |
* processes off threaded programs. Probably you are better off spawning a
|
|
Packit |
c32a2d |
* buffer thread yourself.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param buffer_bytes size (bytes) of a memory buffer for decoded audio,
|
|
Packit |
c32a2d |
* a value of zero disables the buffer.
|
|
Packit |
c32a2d |
* \return 0 on success, OUT123_ERR on error
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_set_buffer(out123_handle *ao, size_t buffer_bytes);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Set a specific parameter, for a specific out123_handle, using a parameter
|
|
Packit |
c32a2d |
* code chosen from the out123_parms enumeration, to the specified value.
|
|
Packit |
c32a2d |
* The parameters usually only change what happens on next out123_open, not
|
|
Packit |
c32a2d |
* incfluencing running operation.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param code parameter code
|
|
Packit |
c32a2d |
* \param value input value for integer parameters
|
|
Packit |
c32a2d |
* \param fvalue input value for floating point parameters
|
|
Packit |
c32a2d |
* \param svalue input value for string parameters (contens are copied)
|
|
Packit |
c32a2d |
* \return 0 on success, OUT123_ERR on error.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_param( out123_handle *ao, enum out123_parms code
|
|
Packit |
c32a2d |
, long value, double fvalue, const char *svalue );
|
|
Packit |
c32a2d |
#define out123_param_int(ao, code, value) \
|
|
Packit |
c32a2d |
out123_param((ao), (code), (value), 0., NULL)
|
|
Packit |
c32a2d |
#define out123_param_float(ao, code, value) \
|
|
Packit |
c32a2d |
out123_param((ao), (code), 0, (value), NULL)
|
|
Packit |
c32a2d |
#define out123_param_string(ao, code, value) \
|
|
Packit |
c32a2d |
out123_param((ao), (code), 0, 0., (value))
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get a specific parameter, for a specific out123_handle, using a parameter
|
|
Packit |
c32a2d |
* code chosen from the out123_parms enumeration, to the specified value.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param code parameter code
|
|
Packit |
c32a2d |
* \param ret_value output address for integer parameters
|
|
Packit |
c32a2d |
* \param ret_fvalue output address for floating point parameters
|
|
Packit |
c32a2d |
* \param ret_svalue output address for string parameters (pointer to
|
|
Packit |
c32a2d |
* internal memory, so no messing around, please)
|
|
Packit |
c32a2d |
* \return 0 on success, OUT123_ERR on error (bad parameter name or bad handle).
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_getparam( out123_handle *ao, enum out123_parms code
|
|
Packit |
c32a2d |
, long *ret_value, double *ret_fvalue, char* *ret_svalue );
|
|
Packit |
c32a2d |
#define out123_getparam_int(ao, code, value) \
|
|
Packit |
c32a2d |
out123_getparam((ao), (code), (value), NULL, NULL)
|
|
Packit |
c32a2d |
#define out123_getparam_float(ao, code, value) \
|
|
Packit |
c32a2d |
out123_getparam((ao), (code), NULL, (value), NULL)
|
|
Packit |
c32a2d |
#define out123_getparam_string(ao, code, value) \
|
|
Packit |
c32a2d |
out123_getparam((ao), (code), NULL, NULL, (value))
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Copy parameters from another out123_handle.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param from_ao the handle to copy parameters from
|
|
Packit |
c32a2d |
* \return 0 in success, -1 on error
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_param_from(out123_handle *ao, out123_handle* from_ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get list of driver modules reachable in system in C argv-style format.
|
|
Packit |
c32a2d |
* The client is responsible for freeing the memory of both the individual
|
|
Packit |
c32a2d |
* strings and the lists themselves.
|
|
Packit |
c32a2d |
* A module that is not loadable because of missing libraries is simply
|
|
Packit |
c32a2d |
* skipped. You will get stderr messages about that unless OUT123_QUIET was
|
|
Packit |
c32a2d |
* was set, though. Failure to open the module directory is a serious error,
|
|
Packit |
c32a2d |
* resulting in negative return value.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param names address for storing list of names
|
|
Packit |
c32a2d |
* \param descr address for storing list of descriptions
|
|
Packit |
c32a2d |
* \return number of drivers found, -1 on error
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_drivers(out123_handle *ao, char ***names, char ***descr);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Open an output device with a certain driver
|
|
Packit |
c32a2d |
* Note: Opening means that the driver code is loaded and the desired
|
|
Packit |
c32a2d |
* device name recorded, possibly tested for availability or tentatively
|
|
Packit |
c32a2d |
* opened. After out123_open(), you can ask for supported encodings
|
|
Packit |
c32a2d |
* and then really open the device for playback with out123_start().
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param driver (comma-separated list of) output driver name(s to try),
|
|
Packit |
c32a2d |
* NULL for default (stdout for file-based drivers)
|
|
Packit |
c32a2d |
* \param device device name to open, NULL for default
|
|
Packit |
c32a2d |
* \return 0 on success, -1 on error.
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_open(out123_handle *ao, const char* driver, const char* device);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Give info about currently loaded driver and device
|
|
Packit |
c32a2d |
* Any of the return addresses can be NULL if you are not interested in
|
|
Packit |
c32a2d |
* everything. You get pointers to internal storage. They are valid
|
|
Packit |
c32a2d |
* as long as the driver/device combination is opened.
|
|
Packit |
c32a2d |
* The device may be NULL indicating some unnamed default.
|
|
Packit |
c32a2d |
* TODO: Make the driver modules return names for such defaults.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param driver return address for driver name
|
|
Packit |
c32a2d |
* \param device return address for device name
|
|
Packit |
c32a2d |
* \return 0 on success, -1 on error (i.e. no driver loaded)
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_driver_info(out123_handle *ao, char **driver, char **device);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Close the current output device and driver.
|
|
Packit |
c32a2d |
* This implies out123_drain() to ensure no data is lost.
|
|
Packit |
c32a2d |
* With a buffer, that might cause considerable delay during
|
|
Packit |
c32a2d |
* which your main application is blocked waiting.
|
|
Packit |
c32a2d |
* Call out123_drop() beforehand if you want to end things
|
|
Packit |
c32a2d |
* quickly.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
void out123_close(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get supported audio encodings for given rate and channel count,
|
|
Packit |
c32a2d |
* for the currently openend audio device.
|
|
Packit |
c32a2d |
* TODO: Reopening the underlying audio device for each query
|
|
Packit |
c32a2d |
* is dumb, at least when dealing with JACK. It takes
|
|
Packit |
c32a2d |
* a long time and is just a waste. Reconsider that.
|
|
Packit |
c32a2d |
* Make sure that all output modules are fine with it, though!
|
|
Packit |
c32a2d |
* Usually, a wider range of rates is supported, but the number
|
|
Packit |
c32a2d |
* of sample encodings is limited, as is the number of channels.
|
|
Packit |
c32a2d |
* So you can call this with some standard rate and hope that the
|
|
Packit |
c32a2d |
* returned encodings work also for others, with the tested channel
|
|
Packit |
c32a2d |
* count.
|
|
Packit |
c32a2d |
* The return value of -1 on some encountered error conveniently also
|
|
Packit |
c32a2d |
* does not match any defined format (only 15 bits used for encodings,
|
|
Packit |
c32a2d |
* so this would even work with 16 bit integers).
|
|
Packit |
c32a2d |
* This implies out123_stop() to enter query mode.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param rate sampling rate
|
|
Packit |
c32a2d |
* \param channels number of channels
|
|
Packit |
c32a2d |
* \return supported encodings combined with bitwise or, to be checked
|
|
Packit |
c32a2d |
* against your favourite bitmask, -1 on error
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_encodings(out123_handle *ao, long rate, int channels);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Return the size (in bytes) of one mono sample of the named encoding.
|
|
Packit |
c32a2d |
* \param encoding The encoding value to analyze.
|
|
Packit |
c32a2d |
* \return positive size of encoding in bytes, 0 on invalid encoding. */
|
|
Packit |
c32a2d |
MPG123_EXPORT int out123_encsize(int encoding);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get list of supported formats for currently opened audio device.
|
|
Packit |
c32a2d |
* Given a list of sampling rates and minimal/maximal channel count,
|
|
Packit |
c32a2d |
* this quickly checks what formats are supported with these
|
|
Packit |
c32a2d |
* constraints. The first entry is always reserved for a default
|
|
Packit |
c32a2d |
* format for the output device. If there is no such default,
|
|
Packit |
c32a2d |
* all values of the format are -1.
|
|
Packit |
c32a2d |
* For each requested combination of rate and channels, a format entry is
|
|
Packit |
c32a2d |
* created, possible with encoding value 0 to indicate that this combination
|
|
Packit |
c32a2d |
* has been tested and rejected. So, when there is no basic error, the
|
|
Packit |
c32a2d |
* number of returned format entries should be
|
|
Packit |
c32a2d |
* (ratecount*(maxchannels-minchannels+1)+1)
|
|
Packit |
c32a2d |
* . But instead of forcing you to guess, this will be allocated by
|
|
Packit |
c32a2d |
* successful run.
|
|
Packit |
c32a2d |
* For the first entry, the encoding member is supposed to be a definite
|
|
Packit |
c32a2d |
* encoding, for the others it is a bitwise combination of all possible
|
|
Packit |
c32a2d |
* encodings.
|
|
Packit |
c32a2d |
* This function is more efficient than many calls to out123_encodings().
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param rates pointer to an array of sampling rates, may be NULL for none
|
|
Packit |
c32a2d |
* \param ratecount number of provided sampling rates
|
|
Packit |
c32a2d |
* \param minchannels minimal channel count
|
|
Packit |
c32a2d |
* \param maxchannels maximal channel count
|
|
Packit |
c32a2d |
* \param fmtlist return address for array of supported formats
|
|
Packit |
c32a2d |
* the encoding field of each entry is a combination of all
|
|
Packit |
c32a2d |
* supported encodings at this rate and channel count;
|
|
Packit |
c32a2d |
* Memory shall be freed by user.
|
|
Packit |
c32a2d |
* \return number of returned format enries, -1 on error
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_formats( out123_handle *ao, const long *rates, int ratecount
|
|
Packit |
c32a2d |
, int minchannels, int maxchannels
|
|
Packit |
c32a2d |
, struct mpg123_fmt **fmtlist );
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get list of encodings known to the library.
|
|
Packit |
c32a2d |
* You are responsible for freeing the allocated array.
|
|
Packit |
c32a2d |
* \param enclist return address for allocated array of encoding codes
|
|
Packit |
c32a2d |
* \return number of encodings, -1 on error
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_enc_list(int **enclist);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Find encoding code by name.
|
|
Packit |
c32a2d |
* \param name short or long name to find encoding code for
|
|
Packit |
c32a2d |
* \return encoding if found (enum mpg123_enc_enum), else 0
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_enc_byname(const char *name);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get name of encoding.
|
|
Packit |
c32a2d |
* \param encoding code (enum mpg123_enc_enum)
|
|
Packit |
c32a2d |
* \return short name for valid encodings, NULL otherwise
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
const char* out123_enc_name(int encoding);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get long name of encoding.
|
|
Packit |
c32a2d |
* \param encoding code (enum mpg123_enc_enum)
|
|
Packit |
c32a2d |
* \return long name for valid encodings, NULL otherwise
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
const char* out123_enc_longname(int encoding);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Start playback with a certain output format
|
|
Packit |
c32a2d |
* It might be a good idea to have audio data handy to feed after this
|
|
Packit |
c32a2d |
* returns with success.
|
|
Packit |
c32a2d |
* Rationale for not taking a pointer to struct mpg123_fmt: This would
|
|
Packit |
c32a2d |
* always force you to deal with that type and needlessly enlarge the
|
|
Packit |
c32a2d |
* shortest possible program.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param encoding sample encoding (values matching libmpg123 API)
|
|
Packit |
c32a2d |
* \param channels number of channels (1 or 2, usually)
|
|
Packit |
c32a2d |
* \param rate sampling rate
|
|
Packit |
c32a2d |
* \return 0 on success, negative on error (bad format, usually)
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_start( out123_handle *ao
|
|
Packit |
c32a2d |
, long rate, int channels, int encoding );
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Pause playback
|
|
Packit |
c32a2d |
* Interrupt playback, holding any data in the optional buffer.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* This closes the audio device if it is a live sink, ready to be re-opened
|
|
Packit |
c32a2d |
* by out123_continue() or out123_play() with the existing parameters.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
void out123_pause(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Continue playback
|
|
Packit |
c32a2d |
* The counterpart to out123_pause(). Announce to the driver that playback
|
|
Packit |
c32a2d |
* shall continue.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* Playback might not resume immediately if the optional buffer is configured
|
|
Packit |
c32a2d |
* to wait for a minimum fill and close to being empty. You can force playback
|
|
Packit |
c32a2d |
* of the last scrap with out123_drain(), or just by feeding more data with
|
|
Packit |
c32a2d |
* out123_play(), which will trigger out123_continue() for you, too.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
void out123_continue(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Stop playback.
|
|
Packit |
c32a2d |
* This waits for pending audio data to drain to the speakers.
|
|
Packit |
c32a2d |
* You might want to call out123_drop() before stopping if you want
|
|
Packit |
c32a2d |
* to end things right away.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
void out123_stop(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Hand over data for playback and wait in case audio device is busy.
|
|
Packit |
c32a2d |
* This survives non-fatal signals like SIGSTOP/SIGCONT and keeps on
|
|
Packit |
c32a2d |
* playing until the buffer is done with if the flag
|
|
Packit |
c32a2d |
* OUT123_KEEP_PLAYING ist set (default). So, per default, if
|
|
Packit |
c32a2d |
* you provided a byte count divisible by the PCM frame size, it is an
|
|
Packit |
c32a2d |
* error when less bytes than given are played.
|
|
Packit |
c32a2d |
* To be sure if an error occured, check out123_errcode().
|
|
Packit |
c32a2d |
* Also note that it is no accident that the buffer parameter is not marked
|
|
Packit |
c32a2d |
* as constant. Some output drivers might need to do things like swap
|
|
Packit |
c32a2d |
* byte order. This is done in-place instead of wasting memory on yet
|
|
Packit |
c32a2d |
* another copy.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param buffer pointer to raw audio data to be played
|
|
Packit |
c32a2d |
* \param bytes number of bytes to read from the buffer
|
|
Packit |
c32a2d |
* \return number of bytes played (might be less than given, even zero)
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
size_t out123_play( out123_handle *ao
|
|
Packit |
c32a2d |
, void *buffer, size_t bytes );
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Drop any buffered data, making next provided data play right away.
|
|
Packit |
c32a2d |
* This does not imply an actual pause in playback.
|
|
Packit |
c32a2d |
* You are expected to play something, unless you called out123_pause().
|
|
Packit |
c32a2d |
* Feel free to call out123_stop() afterwards instead for a quicker
|
|
Packit |
c32a2d |
* exit than the implied out123_drain().
|
|
Packit |
c32a2d |
* For live sinks, this may include dropping data from their buffers.
|
|
Packit |
c32a2d |
* For others (files), this only concerns data in the optional buffer.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
void out123_drop(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Drain the output, waiting until all data went to the hardware.
|
|
Packit |
c32a2d |
* This does imply out123_continue() before and out123_pause()
|
|
Packit |
c32a2d |
* after draining.
|
|
Packit |
c32a2d |
* This might involve only the optional buffer process, or the
|
|
Packit |
c32a2d |
* buffers on the audio driver side, too.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
void out123_drain(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Drain the output, but only partially up to the given number of
|
|
Packit |
c32a2d |
* bytes. This gives you the opportunity to do something while
|
|
Packit |
c32a2d |
* the optional buffer is writing remaining data instead of having
|
|
Packit |
c32a2d |
* one atomic API call for it all.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* It is wholly expected that the return value of out123_buffered()
|
|
Packit |
c32a2d |
* before and after calling this has a bigger difference than the
|
|
Packit |
c32a2d |
* provided limit, as the buffer is writing all the time in the
|
|
Packit |
c32a2d |
* background.
|
|
Packit |
c32a2d |
*
|
|
Packit |
c32a2d |
* This is just a plain out123_drain() if the optional buffer is not
|
|
Packit |
c32a2d |
* in use. Also triggers out123_continue(), but only out123_pause()
|
|
Packit |
c32a2d |
* if there is no buffered data anymore.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param bytes limit of buffered bytes to drain
|
|
Packit |
c32a2d |
* \return number of bytes drained from buffer
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
void out123_ndrain(out123_handle *ao, size_t bytes);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Get an indication of how many bytes reside in the optional buffer.
|
|
Packit |
c32a2d |
* This might get extended to tell the number of bytes queued up in the
|
|
Packit |
c32a2d |
* audio backend, too.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \return number of bytes in out123 library buffer
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
size_t out123_buffered(out123_handle *ao);
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/** Extract currently used audio format from handle.
|
|
Packit |
c32a2d |
* matching mpg123_getformat().
|
|
Packit |
c32a2d |
* Given return addresses may be NULL to indicate no interest.
|
|
Packit |
c32a2d |
* \param ao handle
|
|
Packit |
c32a2d |
* \param rate address for sample rate
|
|
Packit |
c32a2d |
* \param channels address for channel count
|
|
Packit |
c32a2d |
* \param encoding address for encoding
|
|
Packit |
c32a2d |
* \param framesize size of a full PCM frame (for convenience)
|
|
Packit |
c32a2d |
* \return 0 on success, -1 on error
|
|
Packit |
c32a2d |
*/
|
|
Packit |
c32a2d |
MPG123_EXPORT
|
|
Packit |
c32a2d |
int out123_getformat( out123_handle *ao
|
|
Packit |
c32a2d |
, long *rate, int *channels, int *encoding, int *framesize );
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
/* @} */
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
#ifdef __cplusplus
|
|
Packit |
c32a2d |
}
|
|
Packit |
c32a2d |
#endif
|
|
Packit |
c32a2d |
|
|
Packit |
c32a2d |
#endif
|
|
Packit |
c32a2d |
|