#include <sys/types.h>
#include <pulse/sample.h>
+#include <pulse/format.h>
#include <pulse/channelmap.h>
#include <pulse/volume.h>
#include <pulse/def.h>
* pa_stream_get_time() and pa_stream_get_latency() will try to
* interpolate the current playback time/latency by estimating the
* number of samples that have been played back by the hardware since
- * the last regular timing update. It is espcially useful to combine
+ * the last regular timing update. It is especially useful to combine
* this option with PA_STREAM_AUTO_TIMING_UPDATE, which will enable
* you to monitor the current playback time/latency very precisely and
* very frequently without requiring a network round trip every time.
*/
/** \file
- * Audio streams for input, output and sample upload */
+ * Audio streams for input, output and sample upload
+ *
+ * See also \subpage streams
+ */
PA_C_DECL_BEGIN
const pa_channel_map *map /**< The desired channel map, or NULL for default */,
pa_proplist *p /**< The initial property list */);
+/* Create a new, unconnected stream with the specified name, the set of formats
+ * this client can provide, and an initial list of properties. While
+ * connecting, the server will select the most appropriate format which the
+ * client must then provide. \since 1.0 */
+pa_stream *pa_stream_new_extended(
+ pa_context *c /**< The context to create this stream in */,
+ const char *name /**< A name for this stream */,
+ pa_format_info * const * formats /**< The list of formats that can be provided */,
+ unsigned int n_formats /**< The number of formats being passed in */,
+ pa_proplist *p /**< The initial property list */);
+
/** Decrease the reference counter by one */
void pa_stream_unref(pa_stream *s);
/** Return the number of bytes that may be read using pa_stream_peek()*/
size_t pa_stream_readable_size(pa_stream *p);
-/** Drain a playback stream. Use this for notification when the buffer
- * is empty. Please note that only one drain operation per stream may
- * be issued at a time. */
+/** Drain a playback stream. Use this for notification when the
+ * playback buffer is empty after playing all the audio in the buffer.
+ * Please note that only one drain operation per stream may be issued
+ * at a time. */
pa_operation* pa_stream_drain(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
/** Request a timing info structure update for a stream. Use
/** Set the callback function that is called when a buffer overflow happens. (Only for playback streams) */
void pa_stream_set_overflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
+/** Return at what position the latest underflow occurred, or -1 if this information is not
+ * known (e g if no underflow has occurred, or server is older than 1.0).
+ * Can be used inside the underflow callback to get information about the current underflow.
+ * (Only for playback streams) \since 1.0 */
+int64_t pa_stream_get_underflow_index(pa_stream *p);
+
/** Set the callback function that is called when a buffer underflow happens. (Only for playback streams) */
void pa_stream_set_underflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
* of the stream it will be created in corked state. */
pa_operation* pa_stream_cork(pa_stream *s, int b, pa_stream_success_cb_t cb, void *userdata);
-/** Flush the playback buffer of this stream. Most of the time you're
- * better off using the parameter delta of pa_stream_write() instead
- * of this function. Available on both playback and recording
- * streams. */
+/** Flush the playback buffer of this stream. This discards any audio
+ * in the buffer. Most of the time you're better off using the parameter
+ * delta of pa_stream_write() instead of this function. Available on both
+ * playback and recording streams. */
pa_operation* pa_stream_flush(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
/** Reenable prebuffering as specified in the pa_buffer_attr
/** Return a pointer to the stream's channel map. */
const pa_channel_map* pa_stream_get_channel_map(pa_stream *s);
+/** Return a pointer to the stream's format \since 1.0 */
+const pa_format_info* pa_stream_get_format_info(pa_stream *s);
+
/** Return the per-stream server-side buffer metrics of the
* stream. Only valid after the stream has been connected successfuly
* and if the server is at least PulseAudio 0.9. This will return the