* pa_stream_set_state_callback(), and wait for the stream to enter an active
* state.
*
+ * Note: there is a user-controllable slider in mixer applications such as
+ * pavucontrol corresponding to each of the created streams. Multiple
+ * (especially identically named) volume sliders for the same application might
+ * confuse the user. Also, the server supports only a limited number of
+ * simultaneous streams. Because of this, it is not always appropriate to
+ * create multiple streams in one application that needs to output multiple
+ * sounds. The rough guideline is: if there is no use case that would require
+ * separate user-initiated volume changes for each stream, perform the mixing
+ * inside the application.
+ *
* \subsection bufattr_subsec Buffer Attributes
*
* Playback and record streams always have a server-side buffer as
* \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
+ * \li pa_stream_flush() - Drop all data from the playback or record buffer. Do not
* wait for it to finish playing.
*
* \section seek_modes Seeking in the Playback Buffer
* by pa_stream_get_timing_info(). Hence the same rules for keeping
* the timing data up-to-date apply here. In case the write or read
* index is corrupted, these two functions will fail with
- * PA_ERR_NODATA set.
+ * -PA_ERR_NODATA set.
*
* Since updating the timing info structure usually requires a full
* network round trip and some applications monitor the timing very
*
* Please note that streams may be moved between sinks/sources and thus
* it is recommended to use pa_stream_set_moved_callback() to be notified
- * about this. This function will return with PA_ERR_NOTSUPPORTED when the
+ * about this. This function will return with -PA_ERR_NOTSUPPORTED when the
* server is older than 0.9.8. \since 0.9.8 */
uint32_t pa_stream_get_device_index(pa_stream *s);
*
* Please note that streams may be moved between sinks/sources and thus
* it is recommended to use pa_stream_set_moved_callback() to be notified
- * about this. This function will return with PA_ERR_NOTSUPPORTED when the
+ * about this. This function will return with -PA_ERR_NOTSUPPORTED when the
* server is older than 0.9.8. \since 0.9.8 */
const char *pa_stream_get_device_name(pa_stream *s);
/** Return 1 if the sink or source this stream is connected to has
* been suspended. This will return 0 if not, and a negative value on
- * error. This function will return with PA_ERR_NOTSUPPORTED when the
+ * error. This function will return with -PA_ERR_NOTSUPPORTED when the
* server is older than 0.9.8. \since 0.9.8 */
int pa_stream_is_suspended(pa_stream *s);
* an absolute device volume. Since 0.9.20 it is an absolute volume when
* the sink is in flat volume mode, and relative otherwise, thus
* making sure the volume passed here has always the same semantics as
- * the volume passed to pa_context_set_sink_input_volume(). */
+ * the volume passed to pa_context_set_sink_input_volume(). It is possible
+ * to figure out whether flat volume mode is in effect for a given sink
+ * by calling pa_context_get_sink_info_by_name(). */
int pa_stream_connect_playback(
pa_stream *s /**< The stream to connect to a sink */,
const char *dev /**< Name of the sink to connect to, or NULL for default */ ,
pa_seek_mode_t seek /**< Seek mode, must be PA_SEEK_RELATIVE for upload streams */);
/** Read the next fragment from the buffer (for recording streams).
- * \a data will point to the actual data and \a nbytes will contain the size
- * of the data in bytes (which can be less or more than a complete
- * fragment). Use pa_stream_drop() to actually remove the data from
- * the buffer. If no data is available this will return a NULL
- * pointer. */
+ * If there is data at the current read index, \a data will point to
+ * the actual data and \a nbytes will contain the size of the data in
+ * bytes (which can be less or more than a complete fragment).
+ *
+ * If there is no data at the current read index, it means that either
+ * the buffer is empty or it contains a hole (that is, the write index
+ * is ahead of the read index but there's no data where the read index
+ * points at). If the buffer is empty, \a data will be NULL and
+ * \a nbytes will be 0. If there is a hole, \a data will be NULL and
+ * \a nbytes will contain the length of the hole.
+ *
+ * Use pa_stream_drop() to actually remove the data from the buffer
+ * and move the read index forward. pa_stream_drop() should not be
+ * called if the buffer is empty, but it should be called if there is
+ * a hole. */
int pa_stream_peek(
pa_stream *p /**< The stream to use */,
const void **data /**< Pointer to pointer that will point to data */,
* 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. This discards any audio data
+/** Flush the playback or record buffer of this stream. This discards any audio data
* 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. */
+ * \a seek of pa_stream_write() instead of this function. */
pa_operation* pa_stream_flush(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
/** Reenable prebuffering if specified in the pa_buffer_attr
* pa_stream_update_timing_info().
*
* If no timing information has been
- * received yet this call will return PA_ERR_NODATA. For more details
+ * received yet this call will return -PA_ERR_NODATA. For more details
* see pa_stream_get_timing_info(). */
int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec);
-/** Return the total stream latency. This function is based on
+/** Determine the total stream latency. This function is based on
* pa_stream_get_time().
*
- * In case the stream is a monitoring stream the result can be
- * negative, i.e. the captured samples are not yet played. In this
- * case \a *negative is set to 1.
+ * The latency is stored in \a *r_usec. In case the stream is a
+ * monitoring stream the result can be negative, i.e. the captured
+ * samples are not yet played. In this case \a *negative is set to 1.
*
* If no timing information has been received yet, this call will
- * return PA_ERR_NODATA. For more details see
- * pa_stream_get_timing_info() and pa_stream_get_time(). */
+ * return -PA_ERR_NODATA. On success, it will return 0.
+ *
+ * For more details see pa_stream_get_timing_info() and
+ * pa_stream_get_time(). */
int pa_stream_get_latency(pa_stream *s, pa_usec_t *r_usec, int *negative);
/** Return the latest raw timing data structure. The returned pointer
* If no timing information has been received before (i.e. by
* requesting pa_stream_update_timing_info() or by using
* PA_STREAM_AUTO_TIMING_UPDATE), this function will fail with
- * PA_ERR_NODATA.
+ * -PA_ERR_NODATA.
*
* Please note that the write_index member field (and only this field)
* is updated on each pa_stream_write() call, not just when a timing