Home | History | Annotate | Download | only in pulse
      1 #ifndef foostreamhfoo
      2 #define foostreamhfoo
      3 
      4 /* $Id: stream.h 2067 2007-11-21 01:30:40Z lennart $ */
      5 
      6 /***
      7   This file is part of PulseAudio.
      8 
      9   Copyright 2004-2006 Lennart Poettering
     10   Copyright 2006 Pierre Ossman <ossman (at) cendio.se> for Cendio AB
     11 
     12   PulseAudio is free software; you can redistribute it and/or modify
     13   it under the terms of the GNU Lesser General Public License as published
     14   by the Free Software Foundation; either version 2 of the License,
     15   or (at your option) any later version.
     16 
     17   PulseAudio is distributed in the hope that it will be useful, but
     18   WITHOUT ANY WARRANTY; without even the implied warranty of
     19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
     20   General Public License for more details.
     21 
     22   You should have received a copy of the GNU Lesser General Public License
     23   along with PulseAudio; if not, write to the Free Software
     24   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
     25   USA.
     26 ***/
     27 
     28 #include <sys/types.h>
     29 
     30 #include <pulse/sample.h>
     31 #include <pulse/channelmap.h>
     32 #include <pulse/volume.h>
     33 #include <pulse/def.h>
     34 #include <pulse/cdecl.h>
     35 #include <pulse/operation.h>
     36 
     37 /** \page streams Audio Streams
     38  *
     39  * \section overv_sec Overview
     40  *
     41  * Audio streams form the central functionality of the sound server. Data is
     42  * routed, converted and mixed from several sources before it is passed along
     43  * to a final output. Currently, there are three forms of audio streams:
     44  *
     45  * \li Playback streams - Data flows from the client to the server.
     46  * \li Record streams - Data flows from the server to the client.
     47  * \li Upload streams - Similar to playback streams, but the data is stored in
     48  *                      the sample cache. See \ref scache for more information
     49  *                      about controlling the sample cache.
     50  *
     51  * \section create_sec Creating
     52  *
     53  * To access a stream, a pa_stream object must be created using
     54  * pa_stream_new(). At this point the audio sample format and mapping of
     55  * channels must be specified. See \ref sample and \ref channelmap for more
     56  * information about those structures.
     57  *
     58  * This first step will only create a client-side object, representing the
     59  * stream. To use the stream, a server-side object must be created and
     60  * associated with the local object. Depending on which type of stream is
     61  * desired, a different function is needed:
     62  *
     63  * \li Playback stream - pa_stream_connect_playback()
     64  * \li Record stream - pa_stream_connect_record()
     65  * \li Upload stream - pa_stream_connect_upload() (see \ref scache)
     66  *
     67  * Similar to how connections are done in contexts, connecting a stream will
     68  * not generate a pa_operation object. Also like contexts, the application
     69  * should register a state change callback, using
     70  * pa_stream_set_state_callback(), and wait for the stream to enter an active
     71  * state.
     72  *
     73  * \subsection bufattr_subsec Buffer Attributes
     74  *
     75  * Playback and record streams always have a server side buffer as
     76  * part of the data flow.  The size of this buffer strikes a
     77  * compromise between low latency and sensitivity for buffer
     78  * overflows/underruns.
     79  *
     80  * The buffer metrics may be controlled by the application. They are
     81  * described with a pa_buffer_attr structure which contains a number
     82  * of fields:
     83  *
     84  * \li maxlength - The absolute maximum number of bytes that can be stored in
     85  *                 the buffer. If this value is exceeded then data will be
     86  *                 lost.
     87  * \li tlength - The target length of a playback buffer. The server will only
     88  *               send requests for more data as long as the buffer has less
     89  *               than this number of bytes of data.
     90  * \li prebuf - Number of bytes that need to be in the buffer before
     91  * playback will commence. Start of playback can be forced using
     92  * pa_stream_trigger() even though the prebuffer size hasn't been
     93  * reached. If a buffer underrun occurs, this prebuffering will be
     94  * again enabled. If the playback shall never stop in case of a buffer
     95  * underrun, this value should be set to 0. In that case the read
     96  * index of the output buffer overtakes the write index, and hence the
     97  * fill level of the buffer is negative.
     98  * \li minreq - Minimum free number of the bytes in the playback buffer before
     99  *              the server will request more data.
    100  * \li fragsize - Maximum number of bytes that the server will push in one
    101  *                chunk for record streams.
    102  *
    103  * The server side playback buffers are indexed by a write and a read
    104  * index. The application writes to the write index and the sound
    105  * device reads from the read index. The read index is increased
    106  * monotonically, while the write index may be freely controlled by
    107  * the application. Substracting the read index from the write index
    108  * will give you the current fill level of the buffer. The read/write
    109  * indexes are 64bit values and measured in bytes, they will never
    110  * wrap. The current read/write index may be queried using
    111  * pa_stream_get_timing_info() (see below for more information). In
    112  * case of a buffer underrun the read index is equal or larger than
    113  * the write index. Unless the prebuf value is 0, PulseAudio will
    114  * temporarily pause playback in such a case, and wait until the
    115  * buffer is filled up to prebuf bytes again. If prebuf is 0, the
    116  * read index may be larger than the write index, in which case
    117  * silence is played. If the application writes data to indexes lower
    118  * than the read index, the data is immediately lost.
    119  *
    120  * \section transfer_sec Transferring Data
    121  *
    122  * Once the stream is up, data can start flowing between the client and the
    123  * server. Two different access models can be used to transfer the data:
    124  *
    125  * \li Asynchronous - The application register a callback using
    126  *                    pa_stream_set_write_callback() and
    127  *                    pa_stream_set_read_callback() to receive notifications
    128  *                    that data can either be written or read.
    129  * \li Polled - Query the library for available data/space using
    130  *              pa_stream_writable_size() and pa_stream_readable_size() and
    131  *              transfer data as needed. The sizes are stored locally, in the
    132  *              client end, so there is no delay when reading them.
    133  *
    134  * It is also possible to mix the two models freely.
    135  *
    136  * Once there is data/space available, it can be transferred using either
    137  * pa_stream_write() for playback, or pa_stream_peek() / pa_stream_drop() for
    138  * record. Make sure you do not overflow the playback buffers as data will be
    139  * dropped.
    140  *
    141  * \section bufctl_sec Buffer Control
    142  *
    143  * The transfer buffers can be controlled through a number of operations:
    144  *
    145  * \li pa_stream_cork() - Start or stop the playback or recording.
    146  * \li pa_stream_trigger() - Start playback immediatly and do not wait for
    147  *                           the buffer to fill up to the set trigger level.
    148  * \li pa_stream_prebuf() - Reenable the playback trigger level.
    149  * \li pa_stream_drain() - Wait for the playback buffer to go empty. Will
    150  *                         return a pa_operation object that will indicate when
    151  *                         the buffer is completely drained.
    152  * \li pa_stream_flush() - Drop all data from the playback buffer and do not
    153  *                         wait for it to finish playing.
    154  *
    155  * \section seek_modes Seeking in the Playback Buffer
    156  *
    157  * A client application may freely seek in the playback buffer. To
    158  * accomplish that the pa_stream_write() function takes a seek mode
    159  * and an offset argument. The seek mode is one of:
    160  *
    161  * \li PA_SEEK_RELATIVE - seek relative to the current write index
    162  * \li PA_SEEK_ABSOLUTE - seek relative to the beginning of the playback buffer, (i.e. the first that was ever played in the stream)
    163  * \li PA_SEEK_RELATIVE_ON_READ - seek relative to the current read index. Use this to write data to the output buffer that should be played as soon as possible
    164  * \li PA_SEEK_RELATIVE_END - seek relative to the last byte ever written.
    165  *
    166  * If an application just wants to append some data to the output
    167  * buffer, PA_SEEK_RELATIVE and an offset of 0 should be used.
    168  *
    169  * After a call to pa_stream_write() the write index will be left at
    170  * the position right after the last byte of the written data.
    171  *
    172  * \section latency_sec Latency
    173  *
    174  * A major problem with networked audio is the increased latency caused by
    175  * the network. To remedy this, PulseAudio supports an advanced system of
    176  * monitoring the current latency.
    177  *
    178  * To get the raw data needed to calculate latencies, call
    179  * pa_stream_get_timing_info(). This will give you a pa_timing_info
    180  * structure that contains everything that is known about the server
    181  * side buffer transport delays and the backend active in the
    182  * server. (Besides other things it contains the write and read index
    183  * values mentioned above.)
    184  *
    185  * This structure is updated every time a
    186  * pa_stream_update_timing_info() operation is executed. (i.e. before
    187  * the first call to this function the timing information structure is
    188  * not available!) Since it is a lot of work to keep this structure
    189  * up-to-date manually, PulseAudio can do that automatically for you:
    190  * if PA_STREAM_AUTO_TIMING_UPDATE is passed when connecting the
    191  * stream PulseAudio will automatically update the structure every
    192  * 100ms and every time a function is called that might invalidate the
    193  * previously known timing data (such as pa_stream_write() or
    194  * pa_stream_flush()). Please note however, that there always is a
    195  * short time window when the data in the timing information structure
    196  * is out-of-date. PulseAudio tries to mark these situations by
    197  * setting the write_index_corrupt and read_index_corrupt fields
    198  * accordingly.
    199  *
    200  * The raw timing data in the pa_timing_info structure is usually hard
    201  * to deal with. Therefore a more simplistic interface is available:
    202  * you can call pa_stream_get_time() or pa_stream_get_latency(). The
    203  * former will return the current playback time of the hardware since
    204  * the stream has been started. The latter returns the time a sample
    205  * that you write now takes to be played by the hardware. These two
    206  * functions base their calculations on the same data that is returned
    207  * by pa_stream_get_timing_info(). Hence the same rules for keeping
    208  * the timing data up-to-date apply here. In case the write or read
    209  * index is corrupted, these two functions will fail with
    210  * PA_ERR_NODATA set.
    211  *
    212  * Since updating the timing info structure usually requires a full
    213  * network round trip and some applications monitor the timing very
    214  * often PulseAudio offers a timing interpolation system. If
    215  * PA_STREAM_INTERPOLATE_TIMING is passed when connecting the stream,
    216  * pa_stream_get_time() and pa_stream_get_latency() will try to
    217  * interpolate the current playback time/latency by estimating the
    218  * number of samples that have been played back by the hardware since
    219  * the last regular timing update. It is espcially useful to combine
    220  * this option with PA_STREAM_AUTO_TIMING_UPDATE, which will enable
    221  * you to monitor the current playback time/latency very precisely and
    222  * very frequently without requiring a network round trip every time.
    223  *
    224  * \section flow_sec Overflow and underflow
    225  *
    226  * Even with the best precautions, buffers will sometime over - or
    227  * underflow.  To handle this gracefully, the application can be
    228  * notified when this happens. Callbacks are registered using
    229  * pa_stream_set_overflow_callback() and
    230  * pa_stream_set_underflow_callback().
    231  *
    232  * \section sync_streams Sychronizing Multiple Playback Streams
    233  *
    234  * PulseAudio allows applications to fully synchronize multiple
    235  * playback streams that are connected to the same output device. That
    236  * means the streams will always be played back sample-by-sample
    237  * synchronously. If stream operations like pa_stream_cork() are
    238  * issued on one of the synchronized streams, they are simultaneously
    239  * issued on the others.
    240  *
    241  * To synchronize a stream to another, just pass the "master" stream
    242  * as last argument to pa_stream_connect_playack(). To make sure that
    243  * the freshly created stream doesn't start playback right-away, make
    244  * sure to pass PA_STREAM_START_CORKED and - after all streams have
    245  * been created - uncork them all with a single call to
    246  * pa_stream_cork() for the master stream.
    247  *
    248  * To make sure that a particular stream doesn't stop to play when a
    249  * server side buffer underrun happens on it while the other
    250  * synchronized streams continue playing and hence deviate you need to
    251  * pass a "prebuf" pa_buffer_attr of 0 when connecting it.
    252  *
    253  * \section disc_sec Disconnecting
    254  *
    255  * When a stream has served is purpose it must be disconnected with
    256  * pa_stream_disconnect(). If you only unreference it, then it will live on
    257  * and eat resources both locally and on the server until you disconnect the
    258  * context.
    259  *
    260  */
    261 
    262 /** \file
    263  * Audio streams for input, output and sample upload */
    264 
    265 PA_C_DECL_BEGIN
    266 
    267 /** An opaque stream for playback or recording */
    268 typedef struct pa_stream pa_stream;
    269 
    270 /** A generic callback for operation completion */
    271 typedef void (*pa_stream_success_cb_t) (pa_stream*s, int success, void *userdata);
    272 
    273 /** A generic request callback */
    274 typedef void (*pa_stream_request_cb_t)(pa_stream *p, size_t bytes, void *userdata);
    275 
    276 /** A generic notification callback */
    277 typedef void (*pa_stream_notify_cb_t)(pa_stream *p, void *userdata);
    278 
    279 /** Create a new, unconnected stream with the specified name and sample type */
    280 pa_stream* pa_stream_new(
    281         pa_context *c                     /**< The context to create this stream in */,
    282         const char *name                  /**< A name for this stream */,
    283         const pa_sample_spec *ss          /**< The desired sample format */,
    284         const pa_channel_map *map         /**< The desired channel map, or NULL for default */);
    285 
    286 /** Decrease the reference counter by one */
    287 void pa_stream_unref(pa_stream *s);
    288 
    289 /** Increase the reference counter by one */
    290 pa_stream *pa_stream_ref(pa_stream *s);
    291 
    292 /** Return the current state of the stream */
    293 pa_stream_state_t pa_stream_get_state(pa_stream *p);
    294 
    295 /** Return the context this stream is attached to */
    296 pa_context* pa_stream_get_context(pa_stream *p);
    297 
    298 /** Return the sink input resp. source output index this stream is
    299  * identified in the server with. This is useful for usage with the
    300  * introspection functions, such as pa_context_get_sink_input_info()
    301  * resp. pa_context_get_source_output_info(). */
    302 uint32_t pa_stream_get_index(pa_stream *s);
    303 
    304 /** Return the index of the sink or source this stream is connected to
    305  * in the server. This is useful for usage with the introspection
    306  * functions, such as pa_context_get_sink_info_by_index()
    307  * resp. pa_context_get_source_info_by_index(). Please note that
    308  * streams may be moved between sinks/sources and thus it is
    309  * recommended to use pa_stream_set_moved_callback() to be notified
    310  * about this. This function will return with PA_ERR_NOTSUPPORTED when the
    311  * server is older than 0.9.8. \since 0.9.8 */
    312 uint32_t pa_stream_get_device_index(pa_stream *s);
    313 
    314 /** Return the name of the sink or source this stream is connected to
    315  * in the server. This is useful for usage with the introspection
    316  * functions, such as pa_context_get_sink_info_by_name()
    317  * resp. pa_context_get_source_info_by_name(). Please note that
    318  * streams may be moved between sinks/sources and thus it is
    319  * recommended to use pa_stream_set_moved_callback() to be notified
    320  * about this. This function will return with PA_ERR_NOTSUPPORTED when the
    321  * server is older than 0.9.8. \since 0.9.8 */
    322 const char *pa_stream_get_device_name(pa_stream *s);
    323 
    324 /** Return 1 if the sink or source this stream is connected to has
    325  * been suspended. This will return 0 if not, and negative on
    326  * error. This function will return with PA_ERR_NOTSUPPORTED when the
    327  * server is older than 0.9.8. \since 0.9.8 */
    328 int pa_stream_is_suspended(pa_stream *s);
    329 
    330 /** Connect the stream to a sink */
    331 int pa_stream_connect_playback(
    332         pa_stream *s                  /**< The stream to connect to a sink */,
    333         const char *dev               /**< Name of the sink to connect to, or NULL for default */ ,
    334         const pa_buffer_attr *attr    /**< Buffering attributes, or NULL for default */,
    335         pa_stream_flags_t flags       /**< Additional flags, or 0 for default */,
    336         pa_cvolume *volume            /**< Initial volume, or NULL for default */,
    337         pa_stream *sync_stream        /**< Synchronize this stream with the specified one, or NULL for a standalone stream*/);
    338 
    339 /** Connect the stream to a source */
    340 int pa_stream_connect_record(
    341         pa_stream *s                  /**< The stream to connect to a source */ ,
    342         const char *dev               /**< Name of the source to connect to, or NULL for default */,
    343         const pa_buffer_attr *attr    /**< Buffer attributes, or NULL for default */,
    344         pa_stream_flags_t flags       /**< Additional flags, or 0 for default */);
    345 
    346 /** Disconnect a stream from a source/sink */
    347 int pa_stream_disconnect(pa_stream *s);
    348 
    349 /** Write some data to the server (for playback sinks), if free_cb is
    350  * non-NULL this routine is called when all data has been written out
    351  * and an internal reference to the specified data is kept, the data
    352  * is not copied. If NULL, the data is copied into an internal
    353  * buffer. The client my freely seek around in the output buffer. For
    354  * most applications passing 0 and PA_SEEK_RELATIVE as arguments for
    355  * offset and seek should be useful.*/
    356 int pa_stream_write(
    357         pa_stream *p             /**< The stream to use */,
    358         const void *data         /**< The data to write */,
    359         size_t bytes             /**< The length of the data to write in bytes*/,
    360         pa_free_cb_t free_cb     /**< A cleanup routine for the data or NULL to request an internal copy */,
    361         int64_t offset,          /**< Offset for seeking, must be 0 for upload streams */
    362         pa_seek_mode_t seek      /**< Seek mode, must be PA_SEEK_RELATIVE for upload streams */);
    363 
    364 /** Read the next fragment from the buffer (for recording).
    365  * data will point to the actual data and length will contain the size
    366  * of the data in bytes (which can be less than a complete framgnet).
    367  * Use pa_stream_drop() to actually remove the data from the
    368  * buffer. If no data is available will return a NULL pointer  \since 0.8 */
    369 int pa_stream_peek(
    370         pa_stream *p                 /**< The stream to use */,
    371         const void **data            /**< Pointer to pointer that will point to data */,
    372         size_t *bytes                /**< The length of the data read in bytes */);
    373 
    374 /** Remove the current fragment on record streams. It is invalid to do this without first
    375  * calling pa_stream_peek(). \since 0.8 */
    376 int pa_stream_drop(pa_stream *p);
    377 
    378 /** Return the number of bytes that may be written using pa_stream_write() */
    379 size_t pa_stream_writable_size(pa_stream *p);
    380 
    381 /** Return the number of bytes that may be read using pa_stream_read() \since 0.8 */
    382 size_t pa_stream_readable_size(pa_stream *p);
    383 
    384 /** Drain a playback stream. Use this for notification when the buffer is empty */
    385 pa_operation* pa_stream_drain(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
    386 
    387 /** Request a timing info structure update for a stream. Use
    388  * pa_stream_get_timing_info() to get access to the raw timing data,
    389  * or pa_stream_get_time() or pa_stream_get_latency() to get cleaned
    390  * up values. */
    391 pa_operation* pa_stream_update_timing_info(pa_stream *p, pa_stream_success_cb_t cb, void *userdata);
    392 
    393 /** Set the callback function that is called whenever the state of the stream changes */
    394 void pa_stream_set_state_callback(pa_stream *s, pa_stream_notify_cb_t cb, void *userdata);
    395 
    396 /** Set the callback function that is called when new data may be
    397  * written to the stream. */
    398 void pa_stream_set_write_callback(pa_stream *p, pa_stream_request_cb_t cb, void *userdata);
    399 
    400 /** Set the callback function that is called when new data is available from the stream.
    401  * Return the number of bytes read. \since 0.8 */
    402 void pa_stream_set_read_callback(pa_stream *p, pa_stream_request_cb_t cb, void *userdata);
    403 
    404 /** Set the callback function that is called when a buffer overflow happens. (Only for playback streams) \since 0.8 */
    405 void pa_stream_set_overflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
    406 
    407 /** Set the callback function that is called when a buffer underflow happens. (Only for playback streams) \since 0.8 */
    408 void pa_stream_set_underflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
    409 
    410 /** Set the callback function that is called whenever a latency
    411  * information update happens. Useful on PA_STREAM_AUTO_TIMING_UPDATE
    412  * streams only. (Only for playback streams) \since 0.8.2 */
    413 void pa_stream_set_latency_update_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
    414 
    415 /** Set the callback function that is called whenever the stream is
    416  * moved to a different sink/source. Use pa_stream_get_device_name()or
    417  * pa_stream_get_device_index() to query the new sink/source. This
    418  * notification is only generated when the server is at least
    419  * 0.9.8. \since 0.9.8 */
    420 void pa_stream_set_moved_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
    421 
    422 /** Set the callback function that is called whenever the sink/source
    423  * this stream is connected to is suspended or resumed. Use
    424  * pa_stream_is_suspended() to query the new suspend status. Please
    425  * note that the suspend status might also change when the stream is
    426  * moved between devices. Thus if you call this function you very
    427  * likely want to call pa_stream_set_moved_callback, too. This
    428  * notification is only generated when the server is at least
    429  * 0.9.8. \since 0.9.8 */
    430 void pa_stream_set_suspended_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
    431 
    432 /** Pause (or resume) playback of this stream temporarily. Available on both playback and recording streams. \since 0.3 */
    433 pa_operation* pa_stream_cork(pa_stream *s, int b, pa_stream_success_cb_t cb, void *userdata);
    434 
    435 /** Flush the playback buffer of this stream. Most of the time you're
    436  * better off using the parameter delta of pa_stream_write() instead of this
    437  * function. Available on both playback and recording streams. \since 0.3 */
    438 pa_operation* pa_stream_flush(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
    439 
    440 /** Reenable prebuffering as specified in the pa_buffer_attr
    441  * structure. Available for playback streams only. \since 0.6 */
    442 pa_operation* pa_stream_prebuf(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
    443 
    444 /** Request immediate start of playback on this stream. This disables
    445  * prebuffering as specified in the pa_buffer_attr
    446  * structure, temporarily. Available for playback streams only. \since 0.3 */
    447 pa_operation* pa_stream_trigger(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
    448 
    449 /** Rename the stream. \since 0.5 */
    450 pa_operation* pa_stream_set_name(pa_stream *s, const char *name, pa_stream_success_cb_t cb, void *userdata);
    451 
    452 /** Return the current playback/recording time. This is based on the
    453  * data in the timing info structure returned by
    454  * pa_stream_get_timing_info(). This function will usually only return
    455  * new data if a timing info update has been recieved. Only if timing
    456  * interpolation has been requested (PA_STREAM_INTERPOLATE_TIMING)
    457  * the data from the last timing update is used for an estimation of
    458  * the current playback/recording time based on the local time that
    459  * passed since the timing info structure has been acquired. The time
    460  * value returned by this function is guaranteed to increase
    461  * monotonically. (that means: the returned value is always greater or
    462  * equal to the value returned on the last call) This behaviour can
    463  * be disabled by using PA_STREAM_NOT_MONOTONOUS. This may be
    464  * desirable to deal better with bad estimations of transport
    465  * latencies, but may have strange effects if the application is not
    466  * able to deal with time going 'backwards'. \since 0.6 */
    467 int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec);
    468 
    469 /** Return the total stream latency. This function is based on
    470  * pa_stream_get_time(). In case the stream is a monitoring stream the
    471  * result can be negative, i.e. the captured samples are not yet
    472  * played. In this case *negative is set to 1. \since 0.6 */
    473 int pa_stream_get_latency(pa_stream *s, pa_usec_t *r_usec, int *negative);
    474 
    475 /** Return the latest raw timing data structure. The returned pointer
    476  * points to an internal read-only instance of the timing
    477  * structure. The user should make a copy of this structure if he
    478  * wants to modify it. An in-place update to this data structure may
    479  * be requested using pa_stream_update_timing_info(). If no
    480  * pa_stream_update_timing_info() call was issued before, this
    481  * function will fail with PA_ERR_NODATA. Please note that the
    482  * write_index member field (and only this field) is updated on each
    483  * pa_stream_write() call, not just when a timing update has been
    484  * recieved. \since 0.8 */
    485 const pa_timing_info* pa_stream_get_timing_info(pa_stream *s);
    486 
    487 /** Return a pointer to the stream's sample specification. \since 0.6 */
    488 const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s);
    489 
    490 /** Return a pointer to the stream's channel map. \since 0.8 */
    491 const pa_channel_map* pa_stream_get_channel_map(pa_stream *s);
    492 
    493 /** Return the buffer metrics of the stream. Only valid after the
    494  * stream has been connected successfuly and if the server is at least
    495  * PulseAudio 0.9. \since 0.9.0 */
    496 const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
    497 
    498 /** Change the buffer metrics of the stream during playback. The
    499  * server might have chosen different buffer metrics then
    500  * requested. The selected metrics may be queried with
    501  * pa_stream_get_buffer_attr() as soon as the callback is called. Only
    502  * valid after the stream has been connected successfully and if the
    503  * server is at least PulseAudio 0.9.8. \since 0.9.8 */
    504 pa_operation *pa_stream_set_buffer_attr(pa_stream *s, const pa_buffer_attr *attr, pa_stream_success_cb_t cb, void *userdata);
    505 
    506 /* Change the stream sampling rate during playback. You need to pass
    507  * PA_STREAM_VARIABLE_RATE in the flags parameter of
    508  * pa_stream_connect() if you plan to use this function. Only valid
    509  * after the stream has been connected successfully and if the server
    510  * is at least PulseAudio 0.9.8. \since 0.9.8 */
    511 pa_operation *pa_stream_update_sample_rate(pa_stream *s, uint32_t rate, pa_stream_success_cb_t cb, void *userdata);
    512 
    513 PA_C_DECL_END
    514 
    515 #endif
    516