Debian Codegraph @

src/include/out123.h

raw
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
15 /** \file out123.h The header file for the libout123 audio output facility. */
16
17 /** A macro to check at compile time which set of API functions to expect.
18 * This must be incremented at least each time a new symbol is added
19 * to the header.
20 */
21 #define OUT123_API_VERSION 5
22 /** library patch level at client build time */
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 /** Defines needed for MS Visual Studio(tm) DLL builds.
38 * Every public function must be prefixed with MPG123_EXPORT. When building
39 * the DLL ensure to define BUILD_MPG123_DLL. This makes the function accessible
40 * for clients and includes it in the import library which is created together
41 * with the DLL. When consuming the DLL ensure to define LINK_MPG123_DLL which
42 * imports the functions from the DLL.
43 */
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
80 /** \defgroup out123_api out123 library API
81 * This is out123, a library focused on continuous playback of audio streams
82 * via various platform-specific output methods. It glosses over details of
83 * the native APIs to give an interface close to simply writing data to a
84 * file. There might be the option to tune details like buffer (period) sizes
85 * and the number of them on the device side in future, but the focus of the
86 * library is to ease the use case of just getting that raw audio data out
87 * there, without interruptions.
88 *
89 * The basic idea is to create a handle with out123_new() and open a certain
90 * output device (using a certain driver module, possibly build-time defaults)
91 * with out123_open(). Now, you can query the output device for supported
92 * encodings for given rate and channel count with out123_get_encodings() and
93 * decide what to use for actually starting playback with out123_start().
94 *
95 * Then, you just need to provide (interleaved pcm) data for playback with
96 * out123_play(), which will block when the device's buffers are full. You get
97 * your timing from that (instead of callbacks). If your program does the
98 * production of the audio data just a little bit faster than the playback,
99 * causing out123_play() to block ever so briefly, you're fine.
100 *
101 * You stop playback with out123_stop(), or just close the device and driver
102 * via out123_close(), or even just decide to drop it all and do out123_del()
103 * right away when you're done.
104 *
105 * There are other functions for specific needs, but the basic idea should be
106 * covered by the above.
107 *
108 * Note that the driver modules that bind to the operating system API for
109 * output might impose restrictions on what you can safely do regarding your
110 * out123_handle and multiple threads or processes. You should be on the safe
111 * side ensuring that you confine usage of a handle to a single thread instead
112 * of passing it around.
113 @{
114 */
115
116 /** Opaque structure for the libout123 handle. */
117 struct out123_struct;
118 /** Typedef shortcut as preferrend name for the handle type. */
119 typedef struct out123_struct out123_handle;
120
121 /** Get version of the mpg123 distribution this library build came with.
122 * (optional means non-NULL)
123 * \param major optional address to store major version number
124 * \param minor optional address to store minor version number
125 * \param patch optional address to store patchlevel version number
126 * \return full version string (like "1.2.3-beta4 (experimental)")
127 */
128 MPG123_EXPORT
129 const char *out123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch);
130
131 /** Get API version of library build.
132 * \param patch optional address to store patchlevel
133 * \return API version of library
134 */
135 MPG123_EXPORT
136 unsigned int out123_libversion(unsigned int *patch);
137
138 /** Enumeration of codes for the parameters that it is possible to set/get. */
139 enum out123_parms
140 {
141 OUT123_FLAGS = 1 /**< integer, various flags, see enum #out123_flags */
142 , OUT123_PRELOAD /**< float, fraction of buffer to fill before playback */
143 , OUT123_GAIN /**< integer, output device gain (module-specific) */
144 , OUT123_VERBOSE /**< integer, verbosity to stderr, >= 0 */
145 , OUT123_DEVICEBUFFER /**<
146 * float, length of device buffer in seconds;
147 * This might be ignored, might have only a loose relation to actual
148 * buffer sizes and latency, depending on output driver. Try to tune
149 * this before opening a device if you want to influcence latency or reduce
150 * dropouts. Value <= 0 uses some default, usually favouring stable playback
151 * over low latency. Values above 0.5 are probably too much.
152 */
153 , OUT123_PROPFLAGS /**< integer, query driver/device property flags (r/o) */
154 , OUT123_NAME /**< string, name of this instance (NULL restores default);
155 * The value returned by out123_getparam() might be different if the audio
156 * backend changed it (to be unique among clients, p.ex.).
157 * TODO: The name provided here is used as prefix in diagnostic messages. */
158 , OUT123_BINDIR /**< string, path to a program binary directory to use
159 * as starting point in the search for the output module directory
160 * (e.g. ../lib/mpg123 or ./plugins). The environment variable MPG123_MODDIR
161 * is always tried first and the in-built installation path last.
162 */
163 , OUT123_ADD_FLAGS /**< enable given flags */
164 , OUT123_REMOVE_FLAGS /**< disable diven flags */
165 };
166
167 /** Flags to tune out123 behaviour */
168 enum out123_flags
169 {
170 OUT123_HEADPHONES = 0x01 /**< output to headphones (if supported) */
171 , OUT123_INTERNAL_SPEAKER = 0x02 /**< output to speaker (if supported) */
172 , OUT123_LINE_OUT = 0x04 /**< output to line out (if supported) */
173 , OUT123_QUIET = 0x08 /**< no printouts to standard error */
174 , OUT123_KEEP_PLAYING = 0x10 /**<
175 * When this is set (default), playback continues in a loop when the device
176 * does not consume all given data at once. This happens when encountering
177 * signals (like SIGSTOP, SIGCONT) that cause interruption of the underlying
178 * functions.
179 * Note that this flag is meaningless when the optional buffer is employed,
180 * There, your program will always block until the buffer completely took
181 * over the data given to it via out123_play(), unless a communication error
182 * arises.
183 */
184 , OUT123_MUTE = 0x20 /**< software mute (play silent audio) */
185 };
186
187 /** Read-only output driver/device property flags (OUT123_PROPFLAGS). */
188 enum out123_propflags
189 {
190 OUT123_PROP_LIVE = 0x01 /**< This is a live output, meaning that
191 * special care might be needed for pauses in playback (p.ex. stream
192 * of silence instead of interruption), as opposed to files on disk.
193 */
194 , OUT123_PROP_PERSISTENT = 0x02 /**< This (live) output does not need
195 * special care for pauses (continues with silence itself),
196 * out123_pause() does nothing to the device.
197 */
198 };
199
200 /** Create a new output handle.
201 * This only allocates and initializes memory, so the only possible
202 * error condition is running out of memory.
203 * \return pointer to new handle or NULL on error
204 */
205 MPG123_EXPORT
206 out123_handle *out123_new(void);
207
208 /** Delete output handle.
209 * This implies out123_close().
210 */
211 MPG123_EXPORT
212 void out123_del(out123_handle *ao);
213
214 /** Free plain memory allocated within libout123.
215 * This is for library users that are not sure to use the same underlying
216 * memory allocator as libout123. It is just a wrapper over free() in
217 * the underlying C library.
218 */
219 MPG123_EXPORT void out123_free(void *ptr);
220
221 /** Error code enumeration
222 * API calls return a useful (positve) value or zero (OUT123_OK) on simple
223 * success. A negative value (-1 == OUT123_ERR) usually indicates that some
224 * error occured. Which one, that can be queried using out123_errcode()
225 * and friends.
226 */
227 enum out123_error
228 {
229 OUT123_ERR = -1 /**< generic alias for verbosity, always == -1 */
230 , OUT123_OK = 0 /**< just a name for zero, not going to change */
231 , OUT123_DOOM /**< dazzled, out of memory */
232 , OUT123_BAD_DRIVER_NAME /**< bad driver name given */
233 , OUT123_BAD_DRIVER /**< unspecified issue loading a driver */
234 , OUT123_NO_DRIVER /**< no driver loaded */
235 , OUT123_NOT_LIVE /**< no active audio device */
236 , OUT123_DEV_PLAY /**< some device playback error */
237 , OUT123_DEV_OPEN /**< error opening device */
238 , OUT123_BUFFER_ERROR /**<
239 * Some (really unexpected) error in buffer infrastructure.
240 */
241 , OUT123_MODULE_ERROR /**< basic failure in module loading */
242 , OUT123_ARG_ERROR /**< some bad function arguments supplied */
243 , OUT123_BAD_PARAM /**< unknown parameter code */
244 , OUT123_SET_RO_PARAM /**< attempt to set read-only parameter */
245 , OUT123_BAD_HANDLE /**< bad handle pointer (NULL, usually) */
246 , OUT123_NOT_SUPPORTED /**< some requested operation is not supported (right now) */
247 , OUT123_DEV_ENUMERATE /**< device enumeration itself failed */
248 , OUT123_ERRCOUNT /**< placeholder for shaping arrays */
249 };
250
251 /** Get string representation of last encountered error in the
252 * context of given handle.
253 * \param ao handle
254 * \return error string
255 */
256 MPG123_EXPORT
257 const char* out123_strerror(out123_handle *ao);
258
259 /** Get the plain errcode intead of a string.
260 * Note that this used to return OUT123_ERR instead of
261 * OUT123_BAD_HANDLE in case of ao==NULL before mpg123-1.23.5 .
262 * \param ao handle
263 * \return error code recorded in handle or OUT123_BAD_HANDLE
264 */
265 MPG123_EXPORT
266 int out123_errcode(out123_handle *ao);
267
268 /** Return the error string for a given error code.
269 * \param errcode the integer error code
270 * \return error string
271 */
272 MPG123_EXPORT
273 const char* out123_plain_strerror(int errcode);
274
275 /** Set a desired output buffer size.
276 * This starts a separate process that handles the audio output, decoupling
277 * the latter from the main process with a memory buffer and saving you the
278 * burden to ensure sparing CPU cycles for actual playback.
279 * This is for applicatons that prefer continuous playback over small latency.
280 * In other words: The kind of applications that out123 is designed for.
281 * This routine always kills off any currently active audio output module /
282 * device, even if you just disable the buffer when there is no buffer.
283 *
284 * Keep this in mind for memory-constrainted systems: Activating the
285 * buffer causes a fork of the calling process, doubling the virtual memory
286 * use. Depending on your operating system kernel's behaviour regarding
287 * memory overcommit, it might be wise to call out123_set_buffer() very
288 * early in your program before allocating lots of memory.
289 *
290 * There _might_ be a change to threads in future, but for now this is
291 * classic fork with shared memory, working without any threading library.
292 * If your platform or build does not support that, you will always get an
293 * error on trying to set up a non-zero buffer (but the API call will be
294 * present).
295 *
296 * Also, if you do intend to use this from a multithreaded program, think
297 * twice and make sure that your setup is happy with forking full-blown
298 * processes off threaded programs. Probably you are better off spawning a
299 * buffer thread yourself.
300 *
301 * \param ao handle
302 * \param buffer_bytes size (bytes) of a memory buffer for decoded audio,
303 * a value of zero disables the buffer.
304 * \return 0 on success, OUT123_ERR on error
305 */
306 MPG123_EXPORT
307 int out123_set_buffer(out123_handle *ao, size_t buffer_bytes);
308
309 #ifdef MPG123_ENUM_API
310 /** Set a parameter on a out123_handle.
311 *
312 * Note that this name is mapped to out123_param2() instead unless
313 * MPG123_ENUM_API is defined.
314 *
315 * The parameters usually only change what happens on next out123_open, not
316 * incfluencing running operation. There are macros To ease the API a bit:
317 * You can call out123_param_int(ao, code, value) for integer (long) values,
318 * same with out123_param_float() and out123_param_string().
319 *
320 * \param ao handle
321 * \param code parameter code
322 * \param value input value for integer parameters
323 * \param fvalue input value for floating point parameters
324 * \param svalue input value for string parameters (contens are copied)
325 * \return 0 on success, OUT123_ERR on error.
326 */
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
332 /** Set a parameter on a out123_handle. No enum.
333 *
334 * This is actually called instead of out123_param()
335 * unless MPG123_ENUM_API is defined.
336 *
337 * The parameters usually only change what happens on next out123_open, not
338 * incfluencing running operation. There are macros To ease the API a bit:
339 * You can call out123_param_int(ao, code, value) for integer (long) values,
340 * same with out123_param_float() and out123_param_string().
341 *
342 * \param ao handle
343 * \param code parameter code (from enum #out123_parms)
344 * \param value input value for integer parameters
345 * \param fvalue input value for floating point parameters
346 * \param svalue input value for string parameters (contens are copied)
347 * \return 0 on success, OUT123_ERR on error.
348 */
349 MPG123_EXPORT
350 int out123_param2( out123_handle *ao, int code
351 , long value, double fvalue, const char *svalue );
352
353
354 /** Shortcut for out123_param() to set an integer parameter. */
355 #define out123_param_int(ao, code, value) \
356 out123_param((ao), (code), (value), 0., NULL)
357 /** Shortcut for out123_param() to set a float parameter. */
358 #define out123_param_float(ao, code, value) \
359 out123_param((ao), (code), 0, (value), NULL)
360 /** Shortcut for out123_param() to set an string parameter. */
361 #define out123_param_string(ao, code, value) \
362 out123_param((ao), (code), 0, 0., (value))
363
364 #ifdef MPG123_ENUM_API
365 /** Get a parameter from an out123_handle.
366 *
367 * Note that this name is mapped to out123_param2() instead unless
368 * MPG123_ENUM_API is defined.
369 *
370 * \param ao handle
371 * \param code parameter code
372 * \param ret_value output address for integer parameters
373 * \param ret_fvalue output address for floating point parameters
374 * \param ret_svalue output address for string parameters (pointer to
375 * internal memory, so no messing around, please)
376 * \return 0 on success, OUT123_ERR on error (bad parameter name or bad handle).
377 */
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
383 /** Get a parameter from an out123_handle. No enum.
384 *
385 * This is actually called instead of out123_getparam()
386 * unless MPG123_ENUM_API is defined.
387 *
388 * \param ao handle
389 * \param code parameter code (from enum #out123_parms)
390 * \param ret_value output address for integer parameters
391 * \param ret_fvalue output address for floating point parameters
392 * \param ret_svalue output address for string parameters (pointer to
393 * internal memory, so no messing around, please)
394 * \return 0 on success, OUT123_ERR on error (bad parameter name or bad handle).
395 */
396 MPG123_EXPORT
397 int out123_getparam2( out123_handle *ao, int code
398 , long *ret_value, double *ret_fvalue, char* *ret_svalue );
399
400 /** Shortcut for out123_getparam() to get an integer parameter. */
401 #define out123_getparam_int(ao, code, value) \
402 out123_getparam((ao), (code), (value), NULL, NULL)
403 /** Shortcut for out123_getparam() to get a float parameter. */
404 #define out123_getparam_float(ao, code, value) \
405 out123_getparam((ao), (code), NULL, (value), NULL)
406 /** Shortcut for out123_getparam() to get a string parameter. */
407 #define out123_getparam_string(ao, code, value) \
408 out123_getparam((ao), (code), NULL, NULL, (value))
409
410 /** Copy parameters from another out123_handle.
411 * \param ao handle
412 * \param from_ao the handle to copy parameters from
413 * \return 0 in success, -1 on error
414 */
415 MPG123_EXPORT
416 int out123_param_from(out123_handle *ao, out123_handle* from_ao);
417
418 /** Get list of driver modules reachable in system in C argv-style format.
419 *
420 * The client is responsible for freeing the memory of both the individual
421 * strings and the lists themselves. There is out123_stringlists_free()
422 * to assist.
423 *
424 * A module that is not loadable because of missing libraries is simply
425 * skipped. You will get stderr messages about that unless OUT123_QUIET was
426 * was set, though. Failure to open the module directory is a serious error,
427 * resulting in negative return value.
428 *
429 * \param ao handle
430 * \param names address for storing list of names
431 * \param descr address for storing list of descriptions
432 * \return number of drivers found, -1 on error
433 */
434 MPG123_EXPORT
435 int out123_drivers(out123_handle *ao, char ***names, char ***descr);
436
437 /** Get a list of available output devices for a given driver.
438 *
439 * If the driver supports enumeration, you can get a listing of possible
440 * output devices. If this list is exhaustive, depends on the driver.
441 * Note that this implies out123_close(). When you have a device already
442 * open, you don't need to look for one anymore. If you really do, just
443 * create another handle.
444 *
445 * Your provided pointers are only used for non-negative return values.
446 * In this case, you are responsible for freeing the associated memory of
447 * the strings and the lists themselves. The format of the lists is an
448 * array of char pointers, with the returned count just like the usual
449 * C argv and argc. There is out123_stringlists_free() to assist.
450 *
451 * Note: Calling this on a handle with a configured buffer process will
452 * yield #OUT123_NOT_SUPPORTED.
453 *
454 * \param ao handle
455 * \param driver driver name or comma-separated list of names
456 * to try, just like for out123_open(), possibly NULL for some default
457 * \param names address for storing list of names
458 * \param descr address for storing list of descriptions
459 * \param active_driver address for storing a copy of the actually active
460 * driver name (in case you gave a list or NULL as driver), can be NULL
461 * if not interesting
462 * \return count of devices or #OUT123_ERR if some error was encountered,
463 * possibly just #OUT123_NOT_SUPPORTED if the driver lacks enumeration support
464 */
465 MPG123_EXPORT
466 int out123_devices( out123_handle *ao, const char *driver
467 , char ***names, char ***descr, char **active_driver );
468
469 /** Helper to free string list memory.
470 *
471 * This aids in freeing the memory allocated by out123_devices() and
472 * out123_drivers().
473 *
474 * Any of the given lists can be NULL and nothing will happen to it.
475 *
476 * \param name first string list
477 * \param descr second string list
478 * \param count count of strings
479 */
480 MPG123_EXPORT
481 void out123_stringlists_free(char **name, char **descr, int count);
482
483
484 /** Open an output device with a certain driver
485 * Note: Opening means that the driver code is loaded and the desired
486 * device name recorded, possibly tested for availability or tentatively
487 * opened. After out123_open(), you can ask for supported encodings
488 * and then really open the device for playback with out123_start().
489 * \param ao handle
490 * \param driver (comma-separated list of) output driver name(s to try),
491 * NULL for default
492 * \param device device name to open, NULL for default
493 * (stdout for file-based drivers)
494 * \return 0 on success, -1 on error.
495 */
496 MPG123_EXPORT
497 int out123_open(out123_handle *ao, const char* driver, const char* device);
498
499 /** Give info about currently loaded driver and device
500 * Any of the return addresses can be NULL if you are not interested in
501 * everything. You get pointers to internal storage. They are valid
502 * as long as the driver/device combination is opened.
503 * The device may be NULL indicating some unnamed default.
504 * TODO: Make the driver modules return names for such defaults.
505 * \param ao handle
506 * \param driver return address for driver name
507 * \param device return address for device name
508 * \return 0 on success, -1 on error (i.e. no driver loaded)
509 */
510 MPG123_EXPORT
511 int out123_driver_info(out123_handle *ao, char **driver, char **device);
512
513 /** Close the current output device and driver.
514 * This implies out123_drain() to ensure no data is lost.
515 * With a buffer, that might cause considerable delay during
516 * which your main application is blocked waiting.
517 * Call out123_drop() beforehand if you want to end things
518 * quickly.
519 * \param ao handle
520 */
521 MPG123_EXPORT
522 void out123_close(out123_handle *ao);
523
524 /** Get supported audio encodings for given rate and channel count,
525 * for the currently openend audio device.
526 * Usually, a wider range of rates is supported, but the number
527 * of sample encodings is limited, as is the number of channels.
528 * So you can call this with some standard rate and hope that the
529 * returned encodings work also for others, with the tested channel
530 * count.
531 * The return value of -1 on some encountered error conveniently also
532 * does not match any defined format (only 15 bits used for encodings,
533 * so this would even work with 16 bit integers).
534 * This implies out123_stop() to enter query mode.
535 * \param ao handle
536 * \param rate sampling rate
537 * \param channels number of channels
538 * \return supported encodings combined with bitwise or, to be checked
539 * against your favourite bitmask, -1 on error
540 */
541 MPG123_EXPORT
542 int out123_encodings(out123_handle *ao, long rate, int channels);
543
544 /** Return the size (in bytes) of one mono sample of the named encoding.
545 * \param encoding The encoding value to analyze.
546 * \return positive size of encoding in bytes, 0 on invalid encoding. */
547 MPG123_EXPORT int out123_encsize(int encoding);
548
549 /** Get list of supported formats for currently opened audio device.
550 * Given a list of sampling rates and minimal/maximal channel count,
551 * this quickly checks what formats are supported with these
552 * constraints. The first entry is always reserved for a default
553 * format for the output device. If there is no such default,
554 * all values of the format are -1.
555 * For each requested combination of rate and channels, a format entry is
556 * created, possible with encoding value 0 to indicate that this combination
557 * has been tested and rejected. So, when there is no basic error, the
558 * number of returned format entries should be
559 * (ratecount*(maxchannels-minchannels+1)+1)
560 * . But instead of forcing you to guess, this will be allocated by
561 * successful run.
562 * For the first entry, the encoding member is supposed to be a definite
563 * encoding, for the others it is a bitwise combination of all possible
564 * encodings.
565 * This function is more efficient than many calls to out123_encodings().
566 * \param ao handle
567 * \param rates pointer to an array of sampling rates, may be NULL for none
568 * \param ratecount number of provided sampling rates
569 * \param minchannels minimal channel count
570 * \param maxchannels maximal channel count
571 * \param fmtlist return address for array of supported formats
572 * the encoding field of each entry is a combination of all
573 * supported encodings at this rate and channel count;
574 * Memory shall be freed by user.
575 * \return number of returned format enries, -1 on error
576 */
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
582 /** Get list of encodings known to the library.
583 * You are responsible for freeing the allocated array.
584 * \param enclist return address for allocated array of encoding codes
585 * \return number of encodings, -1 on error
586 */
587 MPG123_EXPORT
588 int out123_enc_list(int **enclist);
589
590 /** Find encoding code by name.
591 * \param name short or long name to find encoding code for
592 * \return encoding if found (enum #mpg123_enc_enum), else 0
593 */
594 MPG123_EXPORT
595 int out123_enc_byname(const char *name);
596
597 /** Get name of encoding.
598 * \param encoding code (enum #mpg123_enc_enum)
599 * \return short name for valid encodings, NULL otherwise
600 */
601 MPG123_EXPORT
602 const char* out123_enc_name(int encoding);
603
604 /** Get long name of encoding.
605 * \param encoding code (enum #mpg123_enc_enum)
606 * \return long name for valid encodings, NULL otherwise
607 */
608 MPG123_EXPORT
609 const char* out123_enc_longname(int encoding);
610
611 /** Start playback with a certain output format
612 * It might be a good idea to have audio data handy to feed after this
613 * returns with success.
614 * Rationale for not taking a pointer to struct mpg123_fmt: This would
615 * always force you to deal with that type and needlessly enlarge the
616 * shortest possible program.
617 * \param ao handle
618 * \param encoding sample encoding (values matching libmpg123 API)
619 * \param channels number of channels (1 or 2, usually)
620 * \param rate sampling rate
621 * \return 0 on success, negative on error (bad format, usually)
622 */
623 MPG123_EXPORT
624 int out123_start( out123_handle *ao
625 , long rate, int channels, int encoding );
626
627 /** Pause playback
628 * Interrupt playback, holding any data in the optional buffer.
629 *
630 * This closes the audio device if it is a live sink, ready to be re-opened
631 * by out123_continue() or out123_play() with the existing parameters.
632 * \param ao handle
633 */
634 MPG123_EXPORT
635 void out123_pause(out123_handle *ao);
636
637 /** Continue playback
638 * The counterpart to out123_pause(). Announce to the driver that playback
639 * shall continue.
640 *
641 * Playback might not resume immediately if the optional buffer is configured
642 * to wait for a minimum fill and close to being empty. You can force playback
643 * of the last scrap with out123_drain(), or just by feeding more data with
644 * out123_play(), which will trigger out123_continue() for you, too.
645 * \param ao handle
646 */
647 MPG123_EXPORT
648 void out123_continue(out123_handle *ao);
649
650 /** Stop playback.
651 * This waits for pending audio data to drain to the speakers.
652 * You might want to call out123_drop() before stopping if you want
653 * to end things right away.
654 * \param ao handle
655 */
656 MPG123_EXPORT
657 void out123_stop(out123_handle *ao);
658
659 /** Hand over data for playback and wait in case audio device is busy.
660 * This survives non-fatal signals like SIGSTOP/SIGCONT and keeps on
661 * playing until the buffer is done with if the flag
662 * OUT123_KEEP_PLAYING ist set (default). So, per default, if
663 * you provided a byte count divisible by the PCM frame size, it is an
664 * error when less bytes than given are played.
665 * To be sure if an error occured, check out123_errcode().
666 * Also note that it is no accident that the buffer parameter is not marked
667 * as constant. Some output drivers might need to do things like swap
668 * byte order. This is done in-place instead of wasting memory on yet
669 * another copy. Software muting also overwrites the data.
670 * \param ao handle
671 * \param buffer pointer to raw audio data to be played
672 * \param bytes number of bytes to read from the buffer
673 * \return number of bytes played (might be less than given, even zero)
674 */
675 MPG123_EXPORT
676 size_t out123_play( out123_handle *ao
677 , void *buffer, size_t bytes );
678
679 /** Drop any buffered data, making next provided data play right away.
680 * This does not imply an actual pause in playback.
681 * You are expected to play something, unless you called out123_pause().
682 * Feel free to call out123_stop() afterwards instead for a quicker
683 * exit than the implied out123_drain().
684 * For live sinks, this may include dropping data from their buffers.
685 * For others (files), this only concerns data in the optional buffer.
686 * \param ao handle
687 */
688 MPG123_EXPORT
689 void out123_drop(out123_handle *ao);
690
691 /** Drain the output, waiting until all data went to the hardware.
692 * This does imply out123_continue() before and out123_pause()
693 * after draining.
694 * This might involve only the optional buffer process, or the
695 * buffers on the audio driver side, too.
696 * \param ao handle
697 */
698 MPG123_EXPORT
699 void out123_drain(out123_handle *ao);
700
701 /** Drain the output, but only partially up to the given number of
702 * bytes. This gives you the opportunity to do something while
703 * the optional buffer is writing remaining data instead of having
704 * one atomic API call for it all.
705 *
706 * It is wholly expected that the return value of out123_buffered()
707 * before and after calling this has a bigger difference than the
708 * provided limit, as the buffer is writing all the time in the
709 * background.
710 *
711 * This is just a plain out123_drain() if the optional buffer is not
712 * in use. Also triggers out123_continue(), but only out123_pause()
713 * if there is no buffered data anymore.
714 * \param ao handle
715 * \param bytes limit of buffered bytes to drain
716 * \return number of bytes drained from buffer
717 */
718 MPG123_EXPORT
719 void out123_ndrain(out123_handle *ao, size_t bytes);
720
721 /** Get an indication of how many bytes reside in the optional buffer.
722 * This might get extended to tell the number of bytes queued up in the
723 * audio backend, too.
724 * \param ao handle
725 * \return number of bytes in out123 library buffer
726 */
727 MPG123_EXPORT
728 size_t out123_buffered(out123_handle *ao);
729
730 /** Extract currently used audio format from handle.
731 * matching mpg123_getformat().
732 * Given return addresses may be NULL to indicate no interest.
733 * \param ao handle
734 * \param rate address for sample rate
735 * \param channels address for channel count
736 * \param encoding address for encoding
737 * \param framesize size of a full PCM frame (for convenience)
738 * \return 0 on success, -1 on error
739 */
740 MPG123_EXPORT
741 int out123_getformat( out123_handle *ao
742 , long *rate, int *channels, int *encoding, int *framesize );
743
744 /** @} */
745
746 #ifdef __cplusplus
747 }
748 #endif
749
750 #endif
751