rename 'length' parameters in the API to 'bytes', to make their unit clear
[platform/upstream/pulseaudio.git] / src / pulse / stream.h
1 #ifndef foostreamhfoo
2 #define foostreamhfoo
3
4 /* $Id$ */
5
6 /***
7   This file is part of PulseAudio.
8
9   Copyright 2004-2006 Lennart Poettering
10   Copyright 2006 Pierre Ossman <ossman@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 device (sink input or source output) index this stream is connected to */
299 uint32_t pa_stream_get_index(pa_stream *s);
300
301 /** Connect the stream to a sink */
302 int pa_stream_connect_playback(
303         pa_stream *s                  /**< The stream to connect to a sink */,
304         const char *dev               /**< Name of the sink to connect to, or NULL for default */ ,
305         const pa_buffer_attr *attr    /**< Buffering attributes, or NULL for default */,
306         pa_stream_flags_t flags       /**< Additional flags, or 0 for default */,
307         pa_cvolume *volume            /**< Initial volume, or NULL for default */,
308         pa_stream *sync_stream        /**< Synchronize this stream with the specified one, or NULL for a standalone stream*/);
309
310 /** Connect the stream to a source */
311 int pa_stream_connect_record(
312         pa_stream *s                  /**< The stream to connect to a source */ ,
313         const char *dev               /**< Name of the source to connect to, or NULL for default */,
314         const pa_buffer_attr *attr    /**< Buffer attributes, or NULL for default */,
315         pa_stream_flags_t flags       /**< Additional flags, or 0 for default */);
316
317 /** Disconnect a stream from a source/sink */
318 int pa_stream_disconnect(pa_stream *s);
319
320 /** Write some data to the server (for playback sinks), if free_cb is
321  * non-NULL this routine is called when all data has been written out
322  * and an internal reference to the specified data is kept, the data
323  * is not copied. If NULL, the data is copied into an internal
324  * buffer. The client my freely seek around in the output buffer. For
325  * most applications passing 0 and PA_SEEK_RELATIVE as arguments for
326  * offset and seek should be useful.*/
327 int pa_stream_write(
328         pa_stream *p             /**< The stream to use */,
329         const void *data         /**< The data to write */,
330         size_t bytes             /**< The length of the data to write in bytes*/,
331         pa_free_cb_t free_cb     /**< A cleanup routine for the data or NULL to request an internal copy */,
332         int64_t offset,          /**< Offset for seeking, must be 0 for upload streams */
333         pa_seek_mode_t seek      /**< Seek mode, must be PA_SEEK_RELATIVE for upload streams */);
334
335 /** Read the next fragment from the buffer (for recording).
336  * data will point to the actual data and length will contain the size
337  * of the data in bytes (which can be less than a complete framgnet).
338  * Use pa_stream_drop() to actually remove the data from the
339  * buffer. If no data is available will return a NULL pointer  \since 0.8 */
340 int pa_stream_peek(
341         pa_stream *p                 /**< The stream to use */,
342         const void **data            /**< Pointer to pointer that will point to data */,
343         size_t *bytes                /**< The length of the data read in bytes */);
344
345 /** Remove the current fragment on record streams. It is invalid to do this without first
346  * calling pa_stream_peek(). \since 0.8 */
347 int pa_stream_drop(pa_stream *p);
348
349 /** Return the nember of bytes that may be written using pa_stream_write(), in bytes */
350 size_t pa_stream_writable_size(pa_stream *p);
351
352 /** Return the number of bytes that may be read using pa_stream_read(), in bytes \since 0.8 */
353 size_t pa_stream_readable_size(pa_stream *p);
354
355 /** Drain a playback stream. Use this for notification when the buffer is empty */
356 pa_operation* pa_stream_drain(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
357
358 /** Request a timing info structure update for a stream. Use
359  * pa_stream_get_timing_info() to get access to the raw timing data,
360  * or pa_stream_get_time() or pa_stream_get_latency() to get cleaned
361  * up values. */
362 pa_operation* pa_stream_update_timing_info(pa_stream *p, pa_stream_success_cb_t cb, void *userdata);
363
364 /** Set the callback function that is called whenever the state of the stream changes */
365 void pa_stream_set_state_callback(pa_stream *s, pa_stream_notify_cb_t cb, void *userdata);
366
367 /** Set the callback function that is called when new data may be
368  * written to the stream. */
369 void pa_stream_set_write_callback(pa_stream *p, pa_stream_request_cb_t cb, void *userdata);
370
371 /** Set the callback function that is called when new data is available from the stream.
372  * Return the number of bytes read. \since 0.8 */
373 void pa_stream_set_read_callback(pa_stream *p, pa_stream_request_cb_t cb, void *userdata);
374
375 /** Set the callback function that is called when a buffer overflow happens. (Only for playback streams) \since 0.8 */
376 void pa_stream_set_overflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
377
378 /** Set the callback function that is called when a buffer underflow happens. (Only for playback streams) \since 0.8 */
379 void pa_stream_set_underflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
380
381 /** Set the callback function that is called whenever a latency information update happens. Useful on PA_STREAM_AUTO_TIMING_UPDATE streams only. (Only for playback streams) \since 0.8.2 */
382 void pa_stream_set_latency_update_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
383
384 /** Pause (or resume) playback of this stream temporarily. Available on both playback and recording streams. \since 0.3 */
385 pa_operation* pa_stream_cork(pa_stream *s, int b, pa_stream_success_cb_t cb, void *userdata);
386
387 /** Flush the playback buffer of this stream. Most of the time you're
388  * better off using the parameter delta of pa_stream_write() instead of this
389  * function. Available on both playback and recording streams. \since 0.3 */
390 pa_operation* pa_stream_flush(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
391
392 /** Reenable prebuffering as specified in the pa_buffer_attr
393  * structure. Available for playback streams only. \since 0.6 */
394 pa_operation* pa_stream_prebuf(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
395
396 /** Request immediate start of playback on this stream. This disables
397  * prebuffering as specified in the pa_buffer_attr
398  * structure, temporarily. Available for playback streams only. \since 0.3 */
399 pa_operation* pa_stream_trigger(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
400
401 /** Rename the stream. \since 0.5 */
402 pa_operation* pa_stream_set_name(pa_stream *s, const char *name, pa_stream_success_cb_t cb, void *userdata);
403
404 /** Return the current playback/recording time. This is based on the
405  * data in the timing info structure returned by
406  * pa_stream_get_timing_info(). This function will usually only return
407  * new data if a timing info update has been recieved. Only if timing
408  * interpolation has been requested (PA_STREAM_INTERPOLATE_TIMING)
409  * the data from the last timing update is used for an estimation of
410  * the current playback/recording time based on the local time that
411  * passed since the timing info structure has been acquired. The time
412  * value returned by this function is guaranteed to increase
413  * monotonically. (that means: the returned value is always greater or
414  * equal to the value returned on the last call) This behaviour can
415  * be disabled by using PA_STREAM_NOT_MONOTONOUS. This may be
416  * desirable to deal better with bad estimations of transport
417  * latencies, but may have strange effects if the application is not
418  * able to deal with time going 'backwards'. \since 0.6 */
419 int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec);
420
421 /** Return the total stream latency. This function is based on
422  * pa_stream_get_time(). In case the stream is a monitoring stream the
423  * result can be negative, i.e. the captured samples are not yet
424  * played. In this case *negative is set to 1. \since 0.6 */
425 int pa_stream_get_latency(pa_stream *s, pa_usec_t *r_usec, int *negative);
426
427 /** Return the latest raw timing data structure. The returned pointer
428  * points to an internal read-only instance of the timing
429  * structure. The user should make a copy of this structure if he
430  * wants to modify it. An in-place update to this data structure may
431  * be requested using pa_stream_update_timing_info(). If no
432  * pa_stream_update_timing_info() call was issued before, this
433  * function will fail with PA_ERR_NODATA. Please note that the
434  * write_index member field (and only this field) is updated on each
435  * pa_stream_write() call, not just when a timing update has been
436  * recieved. \since 0.8 */
437 const pa_timing_info* pa_stream_get_timing_info(pa_stream *s);
438
439 /** Return a pointer to the stream's sample specification. \since 0.6 */
440 const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s);
441
442 /** Return a pointer to the stream's channel map. \since 0.8 */
443 const pa_channel_map* pa_stream_get_channel_map(pa_stream *s);
444
445 /** Return the buffer metrics of the stream. Only valid after the
446  * stream has been connected successfuly and if the server is at least
447  * PulseAudio 0.9. \since 0.9.0 */
448 const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
449
450 PA_C_DECL_END
451
452 #endif