mirror of
https://gitlab.freedesktop.org/pulseaudio/pulseaudio.git
synced 2025-11-04 13:29:59 -05:00
Big documentation update. Describe the client API in a more tutorial like
manner. git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@667 fefdeb5f-60dc-0310-8127-8f9354f1896f
This commit is contained in:
Pierre Ossman
parent
a74253606f
commit
a6ce5c4b1d
12 changed files with 757 additions and 52 deletions
|
|
@ -25,6 +25,40 @@
|
|||
#include <polyp/sample.h>
|
||||
#include <polyp/cdecl.h>
|
||||
|
||||
/** \page channelmap Channel maps
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* Channel maps provide a way to associate channels in a stream with a
|
||||
* speaker. This relieves applications of having to make sure their channel
|
||||
* order is identical to the final output.
|
||||
*
|
||||
* \section init_sec Initialisation
|
||||
*
|
||||
* A channel map consists of an array of \ref pa_channel_position values,
|
||||
* one for each channel. This array is stored together with a channel count
|
||||
* in a pa_channel_map structure.
|
||||
*
|
||||
* Before filling the structure, the application must initialise it using
|
||||
* pa_channel_map_init(). There are also a number of convenience functions
|
||||
* for standard channel mappings:
|
||||
*
|
||||
* \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
|
||||
* \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
|
||||
* \li pa_channel_map_init_auto() - Create a standard channel map for up to
|
||||
* six channels.
|
||||
*
|
||||
* \section conv_sec Convenience functions
|
||||
*
|
||||
* The library contains a number of convenience functions for dealing with
|
||||
* channel maps:
|
||||
*
|
||||
* \li pa_channel_map_valid() - Tests if a channel map is valid.
|
||||
* \li pa_channel_map_equal() - Tests if two channel maps are identical.
|
||||
* \li pa_channel_map_snprint() - Creates a textual description of a channel
|
||||
* map.
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* Constants and routines for channel mapping handling */
|
||||
|
||||
|
|
|
|||
|
|
@ -28,18 +28,116 @@
|
|||
#include <polyp/cdecl.h>
|
||||
#include <polyp/operation.h>
|
||||
|
||||
/** \page async Asynchronous API
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* The asynchronous API is the native interface to the polypaudio library.
|
||||
* It allows full access to all available functions. This also means that
|
||||
* it is rather complex and can take some time to fully master.
|
||||
*
|
||||
* \section mainloop_sec Main loop abstraction
|
||||
*
|
||||
* The API is based around an asynchronous event loop, or main loop,
|
||||
* abstraction. This abstraction contains three basic elements:
|
||||
*
|
||||
* \li Deferred events - Events that trigger each iteration of the main loop.
|
||||
* \li I/O events - Events that trigger on file descriptor activities.
|
||||
* \li Times events - Events that trigger after a fixed ammount of time.
|
||||
*
|
||||
* The abstraction is represented as a number of function pointers in the
|
||||
* pa_mainloop_api structure.
|
||||
*
|
||||
* To actually be able to use these functions, an actual implementation
|
||||
* be coupled to the abstraction. There are two of these shipped with
|
||||
* polypaudio, but any other can be used with a minimal ammount of work,
|
||||
* provided it supports the three basic events listed above.
|
||||
*
|
||||
* The implementations shipped with polypaudio are:
|
||||
*
|
||||
* \li \subpage mainloop - A minimal but fast implementation based on poll().
|
||||
* \li \subpage glib-mainloop - A wrapper around GLIB's main loop. Available
|
||||
* for both GLIB 1.2 and GLIB 2.x.
|
||||
*
|
||||
* UNIX signals may be hooked to a main loop using the functions from
|
||||
* \ref mainloop-signal.h. These rely only on the main loop abstraction
|
||||
* and can therefore be used with any of the implementations.
|
||||
*
|
||||
* \section refcnt_sec Reference counting
|
||||
*
|
||||
* Almost all objects in polypaudio are reference counted. What that means
|
||||
* is that you rarely malloc() or free() any objects. Instead you increase
|
||||
* and decrease their reference counts. Whenever an object's reference
|
||||
* count reaches zero, that object gets destroy and any resources it uses
|
||||
* get freed.
|
||||
*
|
||||
* The benefit of this design is that an application need not worry about
|
||||
* whether or not it needs to keep an object around in case the library is
|
||||
* using it internally. If it is, then it has made sure it has its own
|
||||
* reference to it.
|
||||
*
|
||||
* Whenever the library creates an object, it will have an initial
|
||||
* reference count of one. Most of the time, this single reference will be
|
||||
* sufficient for the application, so all required reference count
|
||||
* interaction will be a single call to the objects unref function.
|
||||
*
|
||||
* \section context_sec Context
|
||||
*
|
||||
* A context is the basic object for a connection to a polypaudio server.
|
||||
* It multiplexes commands, data streams and events through a single
|
||||
* channel.
|
||||
*
|
||||
* There is no need for more than one context per application, unless
|
||||
* connections to multiple servers is needed.
|
||||
*
|
||||
* \subsection ops_subsec Operations
|
||||
*
|
||||
* All operations on the context is performed asynchronously. I.e. the
|
||||
* client will not wait for the server to complete the request. To keep
|
||||
* track of all these in-flight operations, the application is given a
|
||||
* pa_operation object for each asynchronous operation.
|
||||
*
|
||||
* There are only two actions (besides reference counting) that can be
|
||||
* performed on a pa_operation: querying its state with
|
||||
* pa_operation_get_state() and aborting it with pa_operation_cancel().
|
||||
*
|
||||
* A pa_operation object is reference counted, so an application must
|
||||
* make sure to unreference it, even if it has no intention of using it.
|
||||
*
|
||||
* \subsection conn_subsec Connecting
|
||||
*
|
||||
* A context must be connected to a server before any operation can be
|
||||
* issued. Calling pa_context_connect() will initiate the connection
|
||||
* procedure. Unlike most asynchronous operations, connecting does not
|
||||
* result in a pa_operation object. Instead, the application should
|
||||
* register a callback using pa_context_set_state_callback().
|
||||
*
|
||||
* \subsection disc_subsec Disconnecting
|
||||
*
|
||||
* When the sound support is no longer needed, the connection needs to be
|
||||
* closed using pa_context_disconnect(). This is an immediate function that
|
||||
* works synchronously.
|
||||
*
|
||||
* Since the context object has references to other objects it must be
|
||||
* disconnected after use or there is a high risk of memory leaks. If the
|
||||
* connection has terminated by itself, then there is no need to explicitly
|
||||
* disconnect the context using pa_context_disconnect().
|
||||
*
|
||||
* \section Functions
|
||||
*
|
||||
* The sound server's functionality can be divided into a number of
|
||||
* subsections:
|
||||
*
|
||||
* \li \subpage streams
|
||||
* \li \subpage scache
|
||||
* \li \subpage introspect
|
||||
* \li \subpage subscribe
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* Connection contexts for asynchrononous communication with a
|
||||
* server. A pa_context object wraps a connection to a polypaudio
|
||||
* server using its native protocol. A context may be used to issue
|
||||
* commands on the server or to create playback or recording
|
||||
* streams. Multiple playback streams may be piped through a single
|
||||
* connection context. Operations on the contect involving
|
||||
* communication with the server are executed asynchronously: i.e. the
|
||||
* client function do not implicitely wait for completion of the
|
||||
* operation on the server. Instead the caller specifies a call back
|
||||
* function that is called when the operation is completed. Currently
|
||||
* running operations may be canceled using pa_operation_cancel(). */
|
||||
* server using its native protocol. */
|
||||
|
||||
/** \example pacat.c
|
||||
* A playback and recording tool using the asynchronous API */
|
||||
|
|
|
|||
|
|
@ -27,6 +27,17 @@
|
|||
#include <polyp/mainloop-api.h>
|
||||
#include <polyp/cdecl.h>
|
||||
|
||||
/** \page glib-mainloop GLIB main loop bindings
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* The GLIB main loop bindings are extremely easy to use. All that is
|
||||
* required is to create a pa_glib_mainloop object using
|
||||
* pa_glib_mainloop_new(). When the main loop abstraction is needed, it is
|
||||
* provided by pa_glib_mainloop_get_api().
|
||||
*
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* GLIB main loop support */
|
||||
|
||||
|
|
|
|||
|
|
@ -30,22 +30,176 @@
|
|||
#include <polyp/channelmap.h>
|
||||
#include <polyp/volume.h>
|
||||
|
||||
/** \page introspect Server query and control
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* Sometimes it is necessary to query and modify global settings in the
|
||||
* server. For this, Polypaudio has the introspection API. It can list sinks,
|
||||
* sources, samples and other aspects of the server. It can also modify the
|
||||
* attributes of the server that will affect operations on a global level,
|
||||
* and not just the application's context.
|
||||
*
|
||||
* \section query_sec Querying
|
||||
*
|
||||
* All querying is done through callbacks. This design is necessary to
|
||||
* maintain an asynchronous design. The client will request the information
|
||||
* and some time later, the server will respond with the desired data.
|
||||
*
|
||||
* Some objects can have multiple entries at the server. When requesting all
|
||||
* of these at once, the callback will be called multiple times, once for
|
||||
* each object. When the list has been exhausted, the callback will be called
|
||||
* without an information structure and the eol parameter set to a non-zero
|
||||
* value.
|
||||
*
|
||||
* Note that even if a single object is requested, and not the entire list,
|
||||
* the terminating call will still be made.
|
||||
*
|
||||
* If an error occurs, the callback will be called without and information
|
||||
* structure and eol set to zero.
|
||||
*
|
||||
* Data members in the information structures are only valid during the
|
||||
* duration of the callback. If they are required after the callback is
|
||||
* finished, a deep copy must be performed.
|
||||
*
|
||||
* \subsection server_subsec Server information
|
||||
*
|
||||
* The server can be queried about its name, the environment it's running on
|
||||
* and the currently active global defaults. Calling
|
||||
* pa_context_get_server_info() will get access to a pa_server_info structure
|
||||
* containing all of these.
|
||||
*
|
||||
* \subsection memstat_subsec Memory usage
|
||||
*
|
||||
* Statistics about memory usage can be fetched using pa_context_stat(),
|
||||
* giving a pa_stat_info structure.
|
||||
*
|
||||
* \subsection sinksrc_subsec Sinks and sources
|
||||
*
|
||||
* The server can have an arbitrary number of sinks and sources. Each sink
|
||||
* and source have both an index and a name associated with it. As such
|
||||
* there are three ways to get access to them:
|
||||
*
|
||||
* \li By index - pa_context_get_sink_info_by_index() /
|
||||
* pa_context_get_source_info_by_index()
|
||||
* \li By name - pa_context_get_sink_info_by_name() /
|
||||
* pa_context_get_source_info_by_name()
|
||||
* \li All - pa_context_get_sink_info_list() /
|
||||
* pa_context_get_source_info_list()
|
||||
*
|
||||
* All three method use the same callback and will provide a pa_sink_info or
|
||||
* pa_source_info structure.
|
||||
*
|
||||
* \subsection siso_subsec Sink inputs and source outputs
|
||||
*
|
||||
* Sink inputs and source outputs are the representations of the client ends
|
||||
* of streams inside the server. I.e. they connect a client stream to one of
|
||||
* the global sinks or sources.
|
||||
*
|
||||
* Sink inputs and source outputs only have an index to identify them. As
|
||||
* such, there are only two ways to get information about them:
|
||||
*
|
||||
* \li By index - pa_context_get_sink_input_info() /
|
||||
* pa_context_get_source_output_info()
|
||||
* \li All - pa_context_get_sink_input_info_list() /
|
||||
* pa_context_get_source_output_info_list()
|
||||
*
|
||||
* The structure returned is the pa_sink_input_info or pa_source_output_info
|
||||
* structure.
|
||||
*
|
||||
* \subsection samples_subsec Samples
|
||||
*
|
||||
* The list of cached samples can be retrieved from the server. Three methods
|
||||
* exist for querying the sample cache list:
|
||||
*
|
||||
* \li By index - pa_context_get_sample_info_by_index()
|
||||
* \li By name - pa_context_get_sample_info_by_name()
|
||||
* \li All - pa_context_get_sample_info_list()
|
||||
*
|
||||
* Note that this only retrieves information about the sample, not the sample
|
||||
* data itself.
|
||||
*
|
||||
* \subsection module_subsec Modules
|
||||
*
|
||||
* Polypaudio modules are identified by index and are retrieved using either
|
||||
* pa_context_get_module_info() or pa_context_get_module_info_list(). The
|
||||
* information structure is called pa_module_info.
|
||||
*
|
||||
* \subsection autoload_subsec Autoload entries
|
||||
*
|
||||
* Modules can be autoloaded as a result of a client requesting a certain
|
||||
* sink or source. This mapping between sink/source names and modules can be
|
||||
* queried from the server:
|
||||
*
|
||||
* \li By index - pa_context_get_autoload_info_by_index()
|
||||
* \li By sink/source name - pa_context_get_autoload_info_by_name()
|
||||
* \li All - pa_context_get_autoload_info_list()
|
||||
*
|
||||
* \subsection client_subsec Clients
|
||||
*
|
||||
* Polypaudio clients are also identified by index and are retrieved using
|
||||
* either pa_context_get_client_info() or pa_context_get_client_info_list().
|
||||
* The information structure is called pa_client_info.
|
||||
*
|
||||
* \section ctrl_sec Control
|
||||
*
|
||||
* Some parts of the server are only possible to read, but most can also be
|
||||
* modified in different ways. Note that these changes will affect all
|
||||
* connected clients and not just the one issuing the request.
|
||||
*
|
||||
* \subsection sinksrc_subsec Sinks and sources
|
||||
*
|
||||
* The most common change one would want to do to sinks and sources is to
|
||||
* modify the volume of the audio. Identical to how sinks and sources can
|
||||
* be queried, there are two ways of identifying them:
|
||||
*
|
||||
* \li By index - pa_context_set_sink_volume_by_index() /
|
||||
* pa_context_set_source_volume_by_index()
|
||||
* \li By name - pa_context_set_sink_volume_by_name() /
|
||||
* pa_context_set_source_volume_by_name()
|
||||
*
|
||||
* It is also possible to mute a sink or source:
|
||||
*
|
||||
* \li By index - pa_context_set_sink_mute_by_index() /
|
||||
* pa_context_set_source_mute_by_index()
|
||||
* \li By name - pa_context_set_sink_mute_by_name() /
|
||||
* pa_context_set_source_mute_by_name()
|
||||
*
|
||||
* \subsection siso_subsec Sink inputs and source outputs
|
||||
*
|
||||
* If an application desires to modify the volume of just a single stream
|
||||
* (commonly one of its own streams), this can be done by setting the volume
|
||||
* of its associated sink input, using pa_context_set_sink_input_volume().
|
||||
*
|
||||
* There is no support for modifying the volume of source outputs.
|
||||
*
|
||||
* It is also possible to remove sink inputs and source outputs, terminating
|
||||
* the streams associated with them:
|
||||
*
|
||||
* \li Sink input - pa_context_kill_sink_input()
|
||||
* \li Source output - pa_context_kill_source_output()
|
||||
*
|
||||
* \subsection module_subsec Modules
|
||||
*
|
||||
* Server modules can be remotely loaded and unloaded using
|
||||
* pa_context_load_module() and pa_context_unload_module().
|
||||
*
|
||||
* \subsection autoload_subsec Autoload entries
|
||||
*
|
||||
* New module autoloading rules can be added, and existing can be removed
|
||||
* using pa_context_add_autoload() and pa_context_remove_autoload_by_index()
|
||||
* / pa_context_remove_autoload_by_name().
|
||||
*
|
||||
* \subsection client_subsec Clients
|
||||
*
|
||||
* The only operation supported on clients, is the possibility of kicking
|
||||
* them off the server using pa_context_kill_client().
|
||||
*/
|
||||
|
||||
/** \file
|
||||
*
|
||||
* Routines for daemon introspection. When enumerating all entitites
|
||||
* of a certain kind, use the pa_context_xxx_list() functions. The
|
||||
* specified callback function is called once for each entry. The
|
||||
* enumeration is finished by a call to the callback function with
|
||||
* eol=1 and i=NULL. Strings referenced in pa_xxx_info structures and
|
||||
* the structures themselves point to internal memory that may not be
|
||||
* modified. That memory is only valid during the call to the callback
|
||||
* function. A deep copy is required if you need this data outside the
|
||||
* callback functions. An error is signalled by a call to the callback
|
||||
* function with i=NULL and eol=0.
|
||||
*
|
||||
* When using the routines that ask fo a single entry only, a callback
|
||||
* with the same signature is used. However, no finishing call to the
|
||||
* routine is issued. */
|
||||
* Routines for daemon introspection.
|
||||
*/
|
||||
|
||||
PA_C_DECL_BEGIN
|
||||
|
||||
|
|
@ -121,7 +275,7 @@ typedef struct pa_server_info {
|
|||
|
||||
/** Callback prototype for pa_context_get_server_info() */
|
||||
typedef void (*pa_server_info_cb_t) (pa_context *c, const pa_server_info*i, void *userdata);
|
||||
|
||||
context_
|
||||
/** Get some information about the server */
|
||||
pa_operation* pa_context_get_server_info(pa_context *c, pa_server_info_cb_t cb, void *userdata);
|
||||
|
||||
|
|
|
|||
|
|
@ -27,6 +27,41 @@
|
|||
|
||||
PA_C_DECL_BEGIN
|
||||
|
||||
/** \page mainloop Mainloop
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* The built-in main loop implementation is based on the poll() system call.
|
||||
* It supports the functions defined in the main loop abstraction and very
|
||||
* little else.
|
||||
*
|
||||
* The main loop is created using pa_mainloop_new() and destroyed using
|
||||
* pa_mainloop_free(). To get access to the main loop abstraction,
|
||||
* pa_mainloop_get_api() is used.
|
||||
*
|
||||
* \section iter_sec Iteration
|
||||
*
|
||||
* The main loop is designed around the concept of iterations. Each iteration
|
||||
* consists of three steps that repeat during the application's entire
|
||||
* lifetime:
|
||||
*
|
||||
* -# Prepare - Dispatch deferred events, build a list of file descriptors
|
||||
* that need to be monitored and calculate the next timeout.
|
||||
* -# Poll - Execute the actuall poll() system call.
|
||||
* -# Dispatch - Dispatch any timeouts and file descriptors that have fired.
|
||||
*
|
||||
* When using the main loop, the application can either execute each
|
||||
* iteration, one at a time, using pa_mainloop_iterate(), or let the library
|
||||
* iterate automatically using pa_mainloop_run().
|
||||
*
|
||||
* \section thread_sec Threads
|
||||
*
|
||||
* The main loop functions are designed to be thread safe, but the objects
|
||||
* are not. What this means is that multiple main loops can be used, but only
|
||||
* one object per thread.
|
||||
*
|
||||
*/
|
||||
|
||||
/** \file
|
||||
*
|
||||
* A minimal main loop implementation based on the C library's poll()
|
||||
|
|
|
|||
|
|
@ -48,43 +48,49 @@
|
|||
* \section intro_sec Introduction
|
||||
*
|
||||
* This document describes the client API for the polypaudio sound
|
||||
* server. The API comes in two flavours:
|
||||
* server. The API comes in two flavours to accomodate different styles
|
||||
* of applications and different needs in complexity:
|
||||
*
|
||||
* \li The complete but somewhat complicated to use asynchronous API
|
||||
* \li And the simplified, easy to use, but limited synchronous API
|
||||
*
|
||||
* The polypaudio client libraries are thread safe as long as all
|
||||
* objects created by any library function are accessed from the thread
|
||||
* that created them only.
|
||||
* \li The simplified, easy to use, but limited synchronous API
|
||||
*
|
||||
* \section simple_sec Simple API
|
||||
*
|
||||
* Use this if you develop your program in synchronous style and just
|
||||
* need a way to play or record data on the sound server. See
|
||||
* \ref simple.h for more details.
|
||||
* \subpage simple for more details.
|
||||
*
|
||||
* \section async_api Asynchronous API
|
||||
* \section async_sec Asynchronous API
|
||||
*
|
||||
* Use this if you develop your programs in asynchronous, main loop
|
||||
* based style or want to use advanced features of the polypaudio
|
||||
* API. A good starting point is \ref context.h
|
||||
* Use this if you develop your programs in asynchronous, event loop
|
||||
* based style or if you want to use the advanced features of the
|
||||
* polypaudio API. A guide can be found in \subpage async.
|
||||
*
|
||||
* The asynchronous API relies on an abstract main loop API that is
|
||||
* described in \ref mainloop-api.h. Two distinct implementations are
|
||||
* available:
|
||||
* \section thread_sec Threads
|
||||
*
|
||||
* \li \ref mainloop.h : a minimal but fast implementation based on poll()
|
||||
* \li \ref glib-mainloop.h : a wrapper around GLIB's main loop
|
||||
* The polypaudio client libraries are not designed to be used in a
|
||||
* heavily threaded environment. They are however designed to be reentrant
|
||||
* safe.
|
||||
*
|
||||
* UNIX signals may be hooked to a main loop using the functions from
|
||||
* \ref mainloop-signal.h
|
||||
* To use a the libraries in a threaded environment, you must assure that
|
||||
* all objects are only used in the same thread they were created in.
|
||||
* Normally, this means that all objects belonging to a single context
|
||||
* must be accessed from the same thread.
|
||||
*
|
||||
* The included main loop implementation is also not thread safe. Take care
|
||||
* to make sure event lists are not manipulated when any library code is
|
||||
* using the main loop.
|
||||
*
|
||||
* \section pkgconfig pkg-config
|
||||
*
|
||||
* The polypaudio libraries provide pkg-config snippets for the different modules. To use the
|
||||
* asynchronous API use "polyplib" as pkg-config file. GLIB main loop
|
||||
* support is available as "glib-mainloop". The simple
|
||||
* synchronous API is available as "simple".
|
||||
* The polypaudio libraries provide pkg-config snippets for the different
|
||||
* modules:
|
||||
*
|
||||
* \li polyplib - The asynchronous API and the internal main loop
|
||||
* implementation.
|
||||
* \li polyplib-glib12-mainloop - GLIB 1.2 main loop bindings.
|
||||
* \li polyplib-glib-mainloop - GLIB 2.x main loop bindings.
|
||||
* \li polyplib-simple - The simple polypaudio API.
|
||||
*/
|
||||
|
||||
#endif
|
||||
|
|
|
|||
|
|
@ -28,6 +28,72 @@
|
|||
|
||||
#include <polyp/cdecl.h>
|
||||
|
||||
/** \page sample Sample format specifications
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* Polypaudio is capable of handling a multitude of sample formats, rates
|
||||
* and channels, transparently converting and mixing them as needed.
|
||||
*
|
||||
* \section format_sec Sample format
|
||||
*
|
||||
* Polypaudio supports the following sample formats:
|
||||
*
|
||||
* \li PA_SAMPLE_U8 - Unsigned 8 bit PCM.
|
||||
* \li PA_SAMPLE_S16LE - Signed 16 bit PCM, little endian.
|
||||
* \li PA_SAMPLE_S16BE - Signed 16 bit PCM, big endian.
|
||||
* \li PA_SAMPLE_FLOAT32LE - 32 bit IEEE floating point PCM, little endian.
|
||||
* \li PA_SAMPLE_FLOAT32BE - 32 bit IEEE floating point PCM, big endian.
|
||||
* \li PA_SAMPLE_ALAW - 8 bit a-Law.
|
||||
* \li PA_SAMPLE_ULAW - 8 bit mu-Law.
|
||||
*
|
||||
* The floating point sample formats have the range from -1 to 1.
|
||||
*
|
||||
* The sample formats that are sensitive to endianness have convenience
|
||||
* macros for native endian (NE), and reverse endian (RE).
|
||||
*
|
||||
* \section rate_sec Sample rates
|
||||
*
|
||||
* Polypaudio supports any sample rate between 1 Hz and 4 GHz. There is no
|
||||
* point trying to exceed the sample rate of the output device though as the
|
||||
* signal will only get downsampled, consuming CPU on the machine running the
|
||||
* server.
|
||||
*
|
||||
* \section chan_sec Channels
|
||||
*
|
||||
* Polypaudio supports up to 16 individiual channels. The order of the
|
||||
* channels is up to the application, but they must be continous. To map
|
||||
* channels to speakers, see \ref channelmap.
|
||||
*
|
||||
* \section calc_sec Calculations
|
||||
*
|
||||
* The Polypaudio library contains a number of convenience functions to do
|
||||
* calculations on sample formats:
|
||||
*
|
||||
* \li pa_bytes_per_second() - The number of bytes one second of audio will
|
||||
* take given a sample format.
|
||||
* \li pa_frame_size() - The size, in bytes, of one frame (i.e. one set of
|
||||
* samples, one for each channel).
|
||||
* \li pa_sample_size() - The size, in bytes, of one sample.
|
||||
* \li pa_bytes_to_usec() - Calculate the time it would take to play a buffer
|
||||
* of a certain size.
|
||||
*
|
||||
* \section util_sec Convenience functions
|
||||
*
|
||||
* The library also contains a couple of other convenience functions:
|
||||
*
|
||||
* \li pa_sample_spec_valid() - Tests if a sample format specification is
|
||||
* valid.
|
||||
* \li pa_sample_spec_equal() - Tests if the sample format specifications are
|
||||
* identical.
|
||||
* \li pa_sample_format_to_string() - Return a textual description of a
|
||||
* sample format.
|
||||
* \li pa_parse_sample_format() - Parse a text string into a sample format.
|
||||
* \li pa_sample_spec_snprint() - Create a textual description of a complete
|
||||
* sample format specification.
|
||||
* \li pa_bytes_snprint() - Pretty print a byte value (e.g. 2.5 MB).
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* Constants and routines for sample type handling */
|
||||
|
||||
|
|
|
|||
|
|
@ -28,6 +28,49 @@
|
|||
#include <polyp/stream.h>
|
||||
#include <polyp/cdecl.h>
|
||||
|
||||
/** \page scache Sample cache
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* The sample cache provides a simple way of overcoming high network latencies
|
||||
* and reducing bandwidth. Instead of streaming a sound precisely when it
|
||||
* should be played, it is stored on the server and only the command to start
|
||||
* playing it needs to be sent.
|
||||
*
|
||||
* \section create_sec Creation
|
||||
*
|
||||
* To create a sample, the normal stream API is used (see \ref streams). The
|
||||
* function pa_stream_connect_upload() will make sure the stream is stored as
|
||||
* a sample on the server.
|
||||
*
|
||||
* To complete the upload, pa_stream_finish_upload() is called and the sample
|
||||
* will receive the same name as the stream. If the upload should be aborted,
|
||||
* simply call pa_stream_disconnect().
|
||||
*
|
||||
* \section play_sec Playing samples
|
||||
*
|
||||
* To play back a sample, simply call pa_context_play_sample():
|
||||
*
|
||||
* \code
|
||||
* pa_operation *o;
|
||||
*
|
||||
* o = pa_context_play_sample(my_context,
|
||||
* "sample2", // Name of my sample
|
||||
* NULL, // Use default sink
|
||||
* PA_VOLUME_NORM, // Full volume
|
||||
* NULL, // Don't need a callback
|
||||
* NULL
|
||||
* );
|
||||
* if (o)
|
||||
* pa_operation_unref(o);
|
||||
* \endcode
|
||||
*
|
||||
* \section rem_sec Removing samples
|
||||
*
|
||||
* When a sample is no longer needed, it should be removed on the server to
|
||||
* save resources. The sample is deleted using pa_context_remove_sample().
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* All sample cache related routines */
|
||||
|
||||
|
|
|
|||
|
|
@ -28,9 +28,72 @@
|
|||
#include <polyp/def.h>
|
||||
#include <polyp/cdecl.h>
|
||||
|
||||
/** \page simple Simple API
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* The simple API is designed for applications with very basic sound
|
||||
* playback or capture needs. It can only support a single stream per
|
||||
* connection and has no handling of complex features like events, channel
|
||||
* mappings and volume control. It is, however, very simple to use and
|
||||
* quite sufficent for many programs.
|
||||
*
|
||||
* \section conn_sec Connecting
|
||||
*
|
||||
* The first step before using the sound system is to connect to the
|
||||
* server. This is normally done this way:
|
||||
*
|
||||
* \code
|
||||
* pa_simple *s;
|
||||
* pa_sample_spec ss;
|
||||
*
|
||||
* ss.format = S16_NE;
|
||||
* ss.channels = 2;
|
||||
* ss.rate = 44100;
|
||||
*
|
||||
* s = pa_simple_new(NULL, // Use the default server.
|
||||
* "Fooapp", // Our application's name.
|
||||
* PA_STREAM_PLAYBACK,
|
||||
* NULL, // Use the default device.
|
||||
* "Music", // Description of our stream.
|
||||
* &ss, // Our sample format.
|
||||
* NULL, // Use default buffering attributes.
|
||||
* NULL, // Ignore error code.
|
||||
* );
|
||||
* \endcode
|
||||
*
|
||||
* At this point a connected object is returned, or NULL if there was a
|
||||
* problem connecting.
|
||||
*
|
||||
* \section transfer_sec Transferring data
|
||||
*
|
||||
* Once the connection is established to the server, data can start flowing.
|
||||
* Using the connection is very similar to the normal read() and write()
|
||||
* system calls. The main difference is that they're call pa_simple_read()
|
||||
* and pa_simple_write(). Note that these operation are always blocking.
|
||||
*
|
||||
* \section ctrl_sec Buffer control
|
||||
*
|
||||
* If a playback stream is used then a few other operations are available:
|
||||
*
|
||||
* \li pa_simple_drain() - Will wait for all sent data to finish playing.
|
||||
* \li pa_simple_flush() - Will throw away all data currently in buffers.
|
||||
* \li pa_simple_get_playback_latency() - Will return the total latency of
|
||||
* the playback pipeline.
|
||||
*
|
||||
* \section cleanup_sec Cleanup
|
||||
*
|
||||
* Once playback or capture is complete, the connection should be closed
|
||||
* and resources freed. This is done through:
|
||||
*
|
||||
* \code
|
||||
* pa_simple_free(s);
|
||||
* \endcode
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* A simple but limited synchronous playback and recording
|
||||
* API. This is synchronouse, simplified wrapper around the standard
|
||||
* API. This is a synchronous, simplified wrapper around the standard
|
||||
* asynchronous API. */
|
||||
|
||||
/** \example pacat-simple.c
|
||||
|
|
|
|||
|
|
@ -31,6 +31,137 @@
|
|||
#include <polyp/cdecl.h>
|
||||
#include <polyp/operation.h>
|
||||
|
||||
/** \page streams Audio streams
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* Audio streams form the central functionality of the sound server. Data is
|
||||
* routed, converted and mixed from several sources before it is passed along
|
||||
* to a final output. Currently, there are three forms of audio streams:
|
||||
*
|
||||
* \li Playback streams - Data flows from the client to the server.
|
||||
* \li Record streams - Data flows from the server to the client.
|
||||
* \li Upload streams - Similar to playback streams, but the data is stored in
|
||||
* the sample cache. See \ref scache for more information
|
||||
* about controlling the sample cache.
|
||||
*
|
||||
* \section create_sec Creating
|
||||
*
|
||||
* To access a stream, a pa_stream object must be created using
|
||||
* pa_stream_new(). At this point the audio sample format and mapping of
|
||||
* channels must be specified. See \ref sample and \ref channelmap for more
|
||||
* information about those structures.
|
||||
*
|
||||
* This first step will only create a client-side object, representing the
|
||||
* stream. To use the stream, a server-side object must be created and
|
||||
* associated with the local object. Depending on which type of stream is
|
||||
* desired, a different function is needed:
|
||||
*
|
||||
* \li Playback stream - pa_stream_connect_playback()
|
||||
* \li Record stream - pa_stream_connect_record()
|
||||
* \li Upload stream - pa_stream_connect_upload() (see \ref scache)
|
||||
*
|
||||
* Similar to how connections are done in contexts, connecting a stream will
|
||||
* not generate a pa_operation object. Also like contexts, the application
|
||||
* should register a state change callback, using
|
||||
* pa_stream_set_state_callback(), and wait for the stream to enter an active
|
||||
* state.
|
||||
*
|
||||
* \subsection bufattr_subsec Buffer attributes
|
||||
*
|
||||
* Playback and record streams always have a buffer as part of the data flow.
|
||||
* The size of this buffer strikes a compromise between low latency and
|
||||
* sensitivity for buffer overflows/underruns.
|
||||
*
|
||||
* The buffer is described with a pa_buffer_attr structure which contains a
|
||||
* number of field:
|
||||
*
|
||||
* \li maxlength - The absolute maximum number of bytes that can be stored in
|
||||
* the buffer. If this value is exceeded then data will be
|
||||
* lost.
|
||||
* \li tlength - The target length of a playback buffer. The server will only
|
||||
* send requests for more data as long as the buffer has less
|
||||
* than this number of bytes of data.
|
||||
* \li prebuf - Number of bytes that need to be in the buffer before playback
|
||||
* will commence. Start of playback can be forced using
|
||||
* pa_stream_trigger() even though the prebuffer size hasn't been
|
||||
* reached.
|
||||
* \li minreq - Minimum free number of the bytes in the playback buffer before
|
||||
* the server will request more data.
|
||||
* \li fragsize - Maximum number of bytes that the server will push in one
|
||||
* chunk for record streams.
|
||||
*
|
||||
* \section transfer_sec Transferring data
|
||||
*
|
||||
* Once the stream is up, data can start flowing between the client and the
|
||||
* server. Two different access models can be used to transfer the data:
|
||||
*
|
||||
* \li Asynchronous - The application register a callback using
|
||||
* pa_stream_set_write_callback() and
|
||||
* pa_stream_set_read_callback() to receive notifications
|
||||
* that data can either be written or read.
|
||||
* \li Polled - Query the library for available data/space using
|
||||
* pa_stream_writable_size() and pa_stream_readable_size() and
|
||||
* transfer data as needed. The sizes are stored locally, in the
|
||||
* client end, so there is no delay when reading them.
|
||||
*
|
||||
* It is also possible to mix the two models freely.
|
||||
*
|
||||
* Once there is data/space available, it can be transferred using either
|
||||
* pa_stream_write() for playback, or pa_stream_peek() / pa_stream_drop() for
|
||||
* record. Make sure you do not overflow the playback buffers as data will be
|
||||
* dropped.
|
||||
*
|
||||
* \section bufctl_sec Buffer control
|
||||
*
|
||||
* The transfer buffers can be controlled through a number of operations:
|
||||
*
|
||||
* \li pa_stream_cork() - Start or stop the playback or recording.
|
||||
* \li pa_stream_trigger() - Start playback immediatly and do not wait for
|
||||
* the buffer to fill up to the set trigger level.
|
||||
* \li pa_stream_prebuf() - Reenable the playback trigger level.
|
||||
* \li pa_stream_drain() - Wait for the playback buffer to go empty. Will
|
||||
* return a pa_operation object that will indicate when
|
||||
* the buffer is completely drained.
|
||||
* \li pa_stream_flush() - Drop all data from the playback buffer and do not
|
||||
* wait for it to finish playing.
|
||||
*
|
||||
* \section latency_sec Latency
|
||||
*
|
||||
* A major problem with networked audio is the increased latency caused by
|
||||
* the network. To remedy this, Polypaudio supports an advanced system of
|
||||
* monitoring the current latency.
|
||||
*
|
||||
* To get the raw data needed to calculate latencies, call
|
||||
* pa_stream_get_timing_info(). This will give you a pa_timing_info structure
|
||||
* that contains everything that is known about buffers, transport delays
|
||||
* and the backend active in the server.
|
||||
*
|
||||
* If a more simplistic interface is prefered, you can call
|
||||
* pa_stream_get_time() or pa_stream_get_latency(). These will do all the
|
||||
* necessary calculations for you.
|
||||
*
|
||||
* The latency information is constantly updated from the server. Be aware
|
||||
* that between updates, old data will be returned. If you specify the flag
|
||||
* PA_STREAM_INTERPOLATE_TIMING when creating the stream, pa_stream_get_time()
|
||||
* and pa_stream_get_latency() will calculate the latency between updates
|
||||
* based on the time elapsed.
|
||||
*
|
||||
* \section flow_sec Overflow and underflow
|
||||
*
|
||||
* Even with the best precautions, buffers will sometime over- or underflow.
|
||||
* To handle this gracefully, the application can be notified when this
|
||||
* happens. Callbacks are registered using pa_stream_set_overflow_callback()
|
||||
* and pa_stream_set_underflow_callback().
|
||||
*
|
||||
* \section disc_sec Disconnecting
|
||||
*
|
||||
* When a stream has served is purpose it must be disconnected with
|
||||
* pa_stream_disconnect(). If you only unreference it, then it will live on
|
||||
* and eat resources both locally and on the server until you disconnect the
|
||||
* context.
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* Audio streams for input, output and sample upload */
|
||||
|
||||
|
|
|
|||
|
|
@ -28,11 +28,22 @@
|
|||
#include <polyp/context.h>
|
||||
#include <polyp/cdecl.h>
|
||||
|
||||
/** \page subscribe Event subscription
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* The application can be notified, asynchronously, whenever the internal
|
||||
* layout of the server changes. Possible notifications are desribed in the
|
||||
* \ref pa_subscription_event_type and \ref pa_subscription_mask
|
||||
* enumerations.
|
||||
*
|
||||
* The application sets the notification mask using pa_context_subscribe()
|
||||
* and the function that will be called whenever a notification occurs using
|
||||
* pa_context_set_subscribe_callback().
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* Daemon introspection event subscription subsystem. Use this
|
||||
* to be notified whenever the internal layout of daemon changes:
|
||||
* i.e. entities such as sinks or sources are create, removed or
|
||||
* modified. */
|
||||
* Daemon introspection event subscription subsystem. */
|
||||
|
||||
PA_C_DECL_BEGIN
|
||||
|
||||
|
|
|
|||
|
|
@ -26,6 +26,59 @@
|
|||
#include <polyp/cdecl.h>
|
||||
#include <polyp/sample.h>
|
||||
|
||||
/** \page volume Volume control
|
||||
*
|
||||
* \section overv_sec Overview
|
||||
*
|
||||
* Sinks, sources, sink inputs and samples can all have their own volumes.
|
||||
* To deal with these, The Polypaudio libray contains a number of functions
|
||||
* that ease handling.
|
||||
*
|
||||
* The basic volume type in Polypaudio is the \ref pa_volume_t type. Most of
|
||||
* the time, applications will use the aggregated pa_cvolume structure that
|
||||
* can store the volume of all channels at once.
|
||||
*
|
||||
* Volumes commonly span between muted (0%), and normal (100%). It is possible
|
||||
* to set volumes to higher than 100%, but clipping might occur.
|
||||
*
|
||||
* \section calc_sec Calculations
|
||||
*
|
||||
* The volumes in Polypaudio are logarithmic in nature and applications
|
||||
* shouldn't perform calculations with them directly. Instead, they should
|
||||
* be converted to and from either dB or a linear scale:
|
||||
*
|
||||
* \li dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB()
|
||||
* \li Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear()
|
||||
*
|
||||
* For simple multiplication, pa_sw_volume_multiply() and
|
||||
* pa_sw_cvolume_multiply() can be used.
|
||||
*
|
||||
* Calculations can only be reliably be performed on software volumes as
|
||||
* it is commonly unknown what scale hardware volumes use.
|
||||
*
|
||||
* \section conv_sec Convenience functions
|
||||
*
|
||||
* To handle the pa_cvolume structure, the Polypaudio library provides a
|
||||
* number of convenienc functions:
|
||||
*
|
||||
* \li pa_cvolume_valid() - Tests if a pa_cvolume structure is valid.
|
||||
* \li pa_cvolume_equal() - Tests if two pa_cvolume structures are identical.
|
||||
* \li pa_cvolume_channels_equal_to() - Tests if all channels of a pa_cvolume
|
||||
* structure have a given volume.
|
||||
* \li pa_cvolume_is_muted() - Tests if all channels of a pa_cvolume
|
||||
* structure are muted.
|
||||
* \li pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure
|
||||
* are at a normal volume.
|
||||
* \li pa_cvolume_set() - Set all channels of a pa_cvolume structure to a
|
||||
* certain volume.
|
||||
* \li pa_cvolume_reset() - Set all channels of a pa_cvolume structure to a
|
||||
* normal volume.
|
||||
* \li pa_cvolume_mute() - Set all channels of a pa_cvolume structure to a
|
||||
* muted volume.
|
||||
* \li pa_cvolume_avg() - Return the average volume of all channels.
|
||||
* \li pa_cvolume_snprint() - Pretty print a pa_cvolume structure.
|
||||
*/
|
||||
|
||||
/** \file
|
||||
* Constants and routines for volume handling */
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue