Audio streams for input, output and sample upload. More...

Typedefs
typedef struct pa_stream	pa_stream
	An opaque stream for playback or recording. More...

typedef void(*	pa_stream_success_cb_t) (pa_stream s, int success, void userdata)
	A generic callback for operation completion. More...

typedef void(*	pa_stream_request_cb_t) (pa_stream p, size_t nbytes, void userdata)
	A generic request callback. More...

typedef void(*	pa_stream_notify_cb_t) (pa_stream p, void userdata)
	A generic notification callback. More...

typedef void(*	pa_stream_event_cb_t) (pa_stream p, const char name, pa_proplist pl, void userdata)
	A callback for asynchronous meta/policy event messages. More...

Functions
pa_stream *	pa_stream_new (pa_context c, const char name, const pa_sample_spec ss, const pa_channel_map map)
	Create a new, unconnected stream with the specified name and sample type. More...

pa_stream *	pa_stream_new_with_proplist (pa_context c, const char name, const pa_sample_spec ss, const pa_channel_map map, pa_proplist *p)
	Create a new, unconnected stream with the specified name and sample type, and specify the initial stream property list. More...

pa_stream *	pa_stream_new_extended (pa_context c, const char name, pa_format_info const formats, unsigned int n_formats, pa_proplist *p)
	Create a new, unconnected stream with the specified name, the set of formats this client can provide, and an initial list of properties. More...

void	pa_stream_unref (pa_stream *s)
	Decrease the reference counter by one. More...

pa_stream *	pa_stream_ref (pa_stream *s)
	Increase the reference counter by one. More...

pa_stream_state_t	pa_stream_get_state (const pa_stream *p)
	Return the current state of the stream. More...

pa_context *	pa_stream_get_context (const pa_stream *p)
	Return the context this stream is attached to. More...

uint32_t	pa_stream_get_index (const pa_stream *s)
	Return the sink input resp. source output index this stream is identified in the server with. More...

uint32_t	pa_stream_get_device_index (const pa_stream *s)
	Return the index of the sink or source this stream is connected to in the server. More...

const char *	pa_stream_get_device_name (const pa_stream *s)
	Return the name of the sink or source this stream is connected to in the server. More...

int	pa_stream_is_suspended (const pa_stream *s)
	Return 1 if the sink or source this stream is connected to has been suspended. More...

int	pa_stream_is_corked (const pa_stream *s)
	Return 1 if the this stream has been corked. More...

int	pa_stream_connect_playback (pa_stream s, const char dev, const pa_buffer_attr attr, pa_stream_flags_t flags, const pa_cvolume volume, pa_stream *sync_stream)
	Connect the stream to a sink. More...

int	pa_stream_connect_record (pa_stream s, const char dev, const pa_buffer_attr *attr, pa_stream_flags_t flags)
	Connect the stream to a source. More...

int	pa_stream_disconnect (pa_stream *s)
	Disconnect a stream from a source/sink. More...

int	pa_stream_begin_write (pa_stream p, void data, size_t nbytes)
	Prepare writing data to the server (for playback streams). More...

int	pa_stream_cancel_write (pa_stream *p)
	Reverses the effect of pa_stream_begin_write() dropping all data that has already been placed in the memory area returned by pa_stream_begin_write(). More...

int	pa_stream_write (pa_stream p, const void data, size_t nbytes, pa_free_cb_t free_cb, int64_t offset, pa_seek_mode_t seek)
	Write some data to the server (for playback streams). More...

int	pa_stream_write_ext_free (pa_stream p, const void data, size_t nbytes, pa_free_cb_t free_cb, void *free_cb_data, int64_t offset, pa_seek_mode_t seek)
	Function does exactly the same as pa_stream_write() with the difference that free_cb_data is passed to free_cb instead of data. More...

int	pa_stream_peek (pa_stream p, const void data, size_t nbytes)
	Read the next fragment from the buffer (for recording streams). More...

int	pa_stream_drop (pa_stream *p)
	Remove the current fragment on record streams. More...

size_t	pa_stream_writable_size (const pa_stream *p)
	Return the number of bytes requested by the server that have not yet been written. More...

size_t	pa_stream_readable_size (const pa_stream *p)
	Return the number of bytes that may be read using pa_stream_peek(). More...

pa_operation *	pa_stream_drain (pa_stream s, pa_stream_success_cb_t cb, void userdata)
	Drain a playback stream. More...

pa_operation *	pa_stream_update_timing_info (pa_stream p, pa_stream_success_cb_t cb, void userdata)
	Request a timing info structure update for a stream. More...

void	pa_stream_set_state_callback (pa_stream s, pa_stream_notify_cb_t cb, void userdata)
	Set the callback function that is called whenever the state of the stream changes. More...

void	pa_stream_set_write_callback (pa_stream p, pa_stream_request_cb_t cb, void userdata)
	Set the callback function that is called when new data may be written to the stream. More...

void	pa_stream_set_read_callback (pa_stream p, pa_stream_request_cb_t cb, void userdata)
	Set the callback function that is called when new data is available from the stream. More...

void	pa_stream_set_overflow_callback (pa_stream p, pa_stream_notify_cb_t cb, void userdata)
	Set the callback function that is called when a buffer overflow happens. More...

int64_t	pa_stream_get_underflow_index (const pa_stream *p)
	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). More...

void	pa_stream_set_underflow_callback (pa_stream p, pa_stream_notify_cb_t cb, void userdata)
	Set the callback function that is called when a buffer underflow happens. More...

void	pa_stream_set_started_callback (pa_stream p, pa_stream_notify_cb_t cb, void userdata)
	Set the callback function that is called when the server starts playback after an underrun or on initial startup. More...

void	pa_stream_set_latency_update_callback (pa_stream p, pa_stream_notify_cb_t cb, void userdata)
	Set the callback function that is called whenever a latency information update happens. More...

void	pa_stream_set_moved_callback (pa_stream p, pa_stream_notify_cb_t cb, void userdata)
	Set the callback function that is called whenever the stream is moved to a different sink/source. More...

void	pa_stream_set_suspended_callback (pa_stream p, pa_stream_notify_cb_t cb, void userdata)
	Set the callback function that is called whenever the sink/source this stream is connected to is suspended or resumed. More...

void	pa_stream_set_event_callback (pa_stream p, pa_stream_event_cb_t cb, void userdata)
	Set the callback function that is called whenever a meta/policy control event is received. More...

void	pa_stream_set_buffer_attr_callback (pa_stream p, pa_stream_notify_cb_t cb, void userdata)
	Set the callback function that is called whenever the buffer attributes on the server side change. More...

pa_operation *	pa_stream_cork (pa_stream s, int b, pa_stream_success_cb_t cb, void userdata)
	Pause (or resume) playback of this stream temporarily. More...

pa_operation *	pa_stream_flush (pa_stream s, pa_stream_success_cb_t cb, void userdata)
	Flush the playback or record buffer of this stream. More...

pa_operation *	pa_stream_prebuf (pa_stream s, pa_stream_success_cb_t cb, void userdata)
	Reenable prebuffering if specified in the pa_buffer_attr structure. More...

pa_operation *	pa_stream_trigger (pa_stream s, pa_stream_success_cb_t cb, void userdata)
	Request immediate start of playback on this stream. More...

pa_operation *	pa_stream_set_name (pa_stream s, const char name, pa_stream_success_cb_t cb, void *userdata)
	Rename the stream. More...

int	pa_stream_get_time (pa_stream s, pa_usec_t r_usec)
	Return the current playback/recording time. More...

int	pa_stream_get_latency (pa_stream s, pa_usec_t r_usec, int *negative)
	Determine the total stream latency. More...

const pa_timing_info *	pa_stream_get_timing_info (pa_stream *s)
	Return the latest raw timing data structure. More...

const pa_sample_spec *	pa_stream_get_sample_spec (pa_stream *s)
	Return a pointer to the stream's sample specification. More...

const pa_channel_map *	pa_stream_get_channel_map (pa_stream *s)
	Return a pointer to the stream's channel map. More...

const pa_format_info *	pa_stream_get_format_info (const pa_stream *s)
	Return a pointer to the stream's format. More...

const pa_buffer_attr *	pa_stream_get_buffer_attr (pa_stream *s)
	Return the per-stream server-side buffer metrics of the stream. More...

pa_operation *	pa_stream_set_buffer_attr (pa_stream s, const pa_buffer_attr attr, pa_stream_success_cb_t cb, void *userdata)
	Change the buffer metrics of the stream during playback. More...

pa_operation *	pa_stream_update_sample_rate (pa_stream s, uint32_t rate, pa_stream_success_cb_t cb, void userdata)
	Change the stream sampling rate during playback. More...

pa_operation *	pa_stream_proplist_update (pa_stream s, pa_update_mode_t mode, pa_proplist p, pa_stream_success_cb_t cb, void *userdata)
	Update the property list of the sink input/source output of this stream, adding new entries. More...

pa_operation *	pa_stream_proplist_remove (pa_stream s, const char const keys[], pa_stream_success_cb_t cb, void *userdata)
	Update the property list of the sink input/source output of this stream, remove entries. More...

int	pa_stream_set_monitor_stream (pa_stream *s, uint32_t sink_input_idx)
	For record streams connected to a monitor source: monitor only a very specific sink input of the sink. More...

uint32_t	pa_stream_get_monitor_stream (const pa_stream *s)
	Return the sink input index previously set with pa_stream_set_monitor_stream(). More...

Detailed Description

Audio streams for input, output and sample upload.

Typedef Documentation

◆ pa_stream

typedef struct pa_stream pa_stream

An opaque stream for playback or recording.

◆ pa_stream_event_cb_t

typedef void(* pa_stream_event_cb_t) (pa_stream *p, const char *name, pa_proplist *pl, void *userdata)

A callback for asynchronous meta/policy event messages.

Well known event names are PA_STREAM_EVENT_REQUEST_CORK and PA_STREAM_EVENT_REQUEST_UNCORK. The set of defined events can be extended at any time. Also, server modules may introduce additional message types so make sure that your callback function ignores messages it doesn't know.

Since: 0.9.15

◆ pa_stream_notify_cb_t

typedef void(* pa_stream_notify_cb_t) (pa_stream *p, void *userdata)

A generic notification callback.

◆ pa_stream_request_cb_t

typedef void(* pa_stream_request_cb_t) (pa_stream *p, size_t nbytes, void *userdata)

A generic request callback.

◆ pa_stream_success_cb_t

typedef void(* pa_stream_success_cb_t) (pa_stream *s, int success, void *userdata)

A generic callback for operation completion.

Function Documentation

◆ pa_stream_begin_write()

int pa_stream_begin_write	(	pa_stream *	p,
		void **	data,
		size_t *	nbytes
	)

Prepare writing data to the server (for playback streams).

This function may be used to optimize the number of memory copies when doing playback ("zero-copy"). It is recommended to call this function before each call to pa_stream_write().

Pass in the address to a pointer and an address of the number of bytes you want to write. On return the two values will contain a pointer where you can place the data to write and the maximum number of bytes you can write. *nbytes can be smaller or have the same value as you passed in. You need to be able to handle both cases. Accessing memory beyond the returned *nbytes value is invalid. Accessing the memory returned after the following pa_stream_write() or pa_stream_cancel_write() is invalid.

On invocation only *nbytes needs to be initialized, on return both *data and *nbytes will be valid. If you place (size_t) -1 in *nbytes on invocation the memory size will be chosen automatically (which is recommended to do). After placing your data in the memory area returned, call pa_stream_write() with data set to an address within this memory area and an nbytes value that is smaller or equal to what was returned by this function to actually execute the write.

An invocation of pa_stream_write() should follow "quickly" on pa_stream_begin_write(). It is not recommended letting an unbounded amount of time pass after calling pa_stream_begin_write() and before calling pa_stream_write(). If you want to cancel a previously called pa_stream_begin_write() without calling pa_stream_write() use pa_stream_cancel_write(). Calling pa_stream_begin_write() twice without calling pa_stream_write() or pa_stream_cancel_write() in between will return exactly the same data pointer and nbytes values.

On success, will return zero and a valid (non-NULL) pointer. If the return value is non-zero, or the pointer is NULL, this indicates an error. Callers should also pay careful attention to the returned length, which may not be the same as that passed in, as mentioned above.

Since: 0.9.16

◆ pa_stream_cancel_write()

int pa_stream_cancel_write ( pa_stream * p )

Reverses the effect of pa_stream_begin_write() dropping all data that has already been placed in the memory area returned by pa_stream_begin_write().

Only valid to call if pa_stream_begin_write() was called before and neither pa_stream_cancel_write() nor pa_stream_write() have been called yet. Accessing the memory previously returned by pa_stream_begin_write() after this call is invalid. Any further explicit freeing of the memory area is not necessary. Returns zero on success.

Since: 0.9.16

◆ pa_stream_connect_playback()

int pa_stream_connect_playback	(	pa_stream *	s,
		const char *	dev,
		const pa_buffer_attr *	attr,
		pa_stream_flags_t	flags,
		const pa_cvolume *	volume,
		pa_stream *	sync_stream
	)

Connect the stream to a sink.

It is strongly recommended to pass NULL in both dev and volume and to set neither PA_STREAM_START_MUTED nor PA_STREAM_START_UNMUTED – unless these options are directly dependent on user input or configuration.

If you follow this rule then the sound server will have the full flexibility to choose the device, volume and mute status automatically, based on server-side policies, heuristics and stored information from previous uses. Also the server may choose to reconfigure audio devices to make other sinks/sources or capabilities available to be able to accept the stream.

Before 0.9.20 it was not defined whether the volume parameter was interpreted relative to the sink's current volume or treated as 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(). 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().

Since 5.0, it's possible to specify a single-channel volume even if the stream has multiple channels. In that case the same volume is applied to all channels.

Returns zero on success.

Parameters

s	The stream to connect to a sink
dev	Name of the sink to connect to, or NULL to let the server decide
attr	Buffering attributes, or NULL for default
flags	Additional flags, or 0 for default
volume	Initial volume, or NULL for default
sync_stream	Synchronize this stream with the specified one, or NULL for a standalone stream

◆ pa_stream_connect_record()

int pa_stream_connect_record	(	pa_stream *	s,
		const char *	dev,
		const pa_buffer_attr *	attr,
		pa_stream_flags_t	flags
	)

Connect the stream to a source.

Returns zero on success.

Parameters

s	The stream to connect to a source
dev	Name of the source to connect to, or NULL to let the server decide
attr	Buffer attributes, or NULL for default
flags	Additional flags, or 0 for default

◆ pa_stream_cork()

pa_operation* pa_stream_cork	(	pa_stream *	s,
		int	b,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Pause (or resume) playback of this stream temporarily.

Available on both playback and recording streams. If b is 1 the stream is paused. If b is 0 the stream is resumed. The pause/resume operation is executed as quickly as possible. If a cork is very quickly followed by an uncork or the other way round, this might not actually have any effect on the stream that is output. You can use pa_stream_is_corked() to find out whether the stream is currently paused or not. Normally a stream will be created in uncorked state. If you pass PA_STREAM_START_CORKED as a flag when connecting the stream, it will be created in corked state.

◆ pa_stream_disconnect()

int pa_stream_disconnect ( pa_stream * s )

Disconnect a stream from a source/sink.

Returns zero on success.

◆ pa_stream_drain()

pa_operation* pa_stream_drain	(	pa_stream *	s,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

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_stream_drop()

int pa_stream_drop ( pa_stream * p )

Remove the current fragment on record streams.

It is invalid to do this without first calling pa_stream_peek(). Returns zero on success.

◆ pa_stream_flush()

pa_operation* pa_stream_flush	(	pa_stream *	s,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

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 seek of pa_stream_write() instead of this function.

◆ pa_stream_get_buffer_attr()

const pa_buffer_attr* pa_stream_get_buffer_attr ( pa_stream * s )

Return the per-stream server-side buffer metrics of the stream.

Only valid after the stream has been connected successfully and if the server is at least PulseAudio 0.9. This will return the actual configured buffering metrics, which may differ from what was requested during pa_stream_connect_record() or pa_stream_connect_playback(). This call will always return the actual per-stream server-side buffer metrics, regardless whether PA_STREAM_ADJUST_LATENCY is set or not.

Since: 0.9.0

◆ pa_stream_get_channel_map()

const pa_channel_map* pa_stream_get_channel_map ( pa_stream * s )

Return a pointer to the stream's channel map.

◆ pa_stream_get_context()

pa_context* pa_stream_get_context ( const pa_stream * p )

Return the context this stream is attached to.

◆ pa_stream_get_device_index()

uint32_t pa_stream_get_device_index ( const pa_stream * s )

Return the index of the sink or source this stream is connected to in the server.

This is useful with the introspection functions such as pa_context_get_sink_info_by_index() or pa_context_get_source_info_by_index().

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_INVALID_INDEX on failure, including the being server older than 0.9.8.

Since: 0.9.8

◆ pa_stream_get_device_name()

const char* pa_stream_get_device_name ( const pa_stream * s )

Return the name of the sink or source this stream is connected to in the server.

This is useful with the introspection functions such as pa_context_get_sink_info_by_name() or pa_context_get_source_info_by_name().

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 fail when the server is older than 0.9.8.

Since: 0.9.8

◆ pa_stream_get_format_info()

const pa_format_info* pa_stream_get_format_info ( const pa_stream * s )

Return a pointer to the stream's format.

Since: 1.0

◆ pa_stream_get_index()

uint32_t pa_stream_get_index ( const pa_stream * s )

Return the sink input resp. source output index this stream is identified in the server with.

This is useful with the introspection functions such as pa_context_get_sink_input_info() or pa_context_get_source_output_info(). This returns PA_INVALID_INDEX on failure.

◆ pa_stream_get_latency()

int pa_stream_get_latency	(	pa_stream *	s,
		pa_usec_t *	r_usec,
		int *	negative
	)

Determine the total stream latency.

This function is based on pa_stream_get_time(). The returned time is in the sound card clock domain, which usually runs at a slightly different rate than the system clock.

The latency is stored in *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 *negative is set to 1.

If no timing information has been received yet, this call will return -PA_ERR_NODATA. On success, it will return 0.

For more details see pa_stream_get_timing_info() and pa_stream_get_time().

◆ pa_stream_get_monitor_stream()

uint32_t pa_stream_get_monitor_stream ( const pa_stream * s )

Return the sink input index previously set with pa_stream_set_monitor_stream().

Returns PA_INVALID_INDEX on failure.

Since: 0.9.11

◆ pa_stream_get_sample_spec()

const pa_sample_spec* pa_stream_get_sample_spec ( pa_stream * s )

Return a pointer to the stream's sample specification.

◆ pa_stream_get_state()

pa_stream_state_t pa_stream_get_state ( const pa_stream * p )

Return the current state of the stream.

◆ pa_stream_get_time()

int pa_stream_get_time	(	pa_stream *	s,
		pa_usec_t *	r_usec
	)

Return the current playback/recording time.

This is based on the data in the timing info structure returned by pa_stream_get_timing_info(). The returned time is in the sound card clock domain, which usually runs at a slightly different rate than the system clock.

This function will usually only return new data if a timing info update has been received. Only if timing interpolation has been requested (PA_STREAM_INTERPOLATE_TIMING) the data from the last timing update is used for an estimation of the current playback/recording time based on the local time that passed since the timing info structure has been acquired.

The time value returned by this function is guaranteed to increase monotonically (the returned value is always greater or equal to the value returned by the last call). This behaviour can be disabled by using PA_STREAM_NOT_MONOTONIC. This may be desirable to better deal with bad estimations of transport latencies, but may have strange effects if the application is not able to deal with time going 'backwards'.

The time interpolator activated by PA_STREAM_INTERPOLATE_TIMING favours 'smooth' time graphs over accurate ones to improve the smoothness of UI operations that are tied to the audio clock. If accuracy is more important to you, you might need to estimate your timing based on the data from pa_stream_get_timing_info() yourself or not work with interpolated timing at all and instead always query the server side for the most up to date timing with pa_stream_update_timing_info().

If no timing information has been received yet this call will return -PA_ERR_NODATA. For more details see pa_stream_get_timing_info().

Returns zero on success, negative on error.

◆ pa_stream_get_timing_info()

const pa_timing_info* pa_stream_get_timing_info ( pa_stream * s )

Return the latest raw timing data structure.

The returned pointer refers to an internal read-only instance of the timing structure. The user should make a copy of this structure if wanting to modify it. An in-place update to this data structure may be requested using pa_stream_update_timing_info().

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 return NULL.

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 update has been received.

◆ pa_stream_get_underflow_index()

int64_t pa_stream_get_underflow_index ( const pa_stream * p )

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

◆ pa_stream_is_corked()

int pa_stream_is_corked ( const pa_stream * s )

Return 1 if the this stream has been corked.

This will return 0 if not, and a negative value on error.

Since: 0.9.11

◆ pa_stream_is_suspended()

int pa_stream_is_suspended ( const 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 server is older than 0.9.8.

Since: 0.9.8

◆ pa_stream_new()

pa_stream* pa_stream_new	(	pa_context *	c,
		const char *	name,
		const pa_sample_spec *	ss,
		const pa_channel_map *	map
	)

Create a new, unconnected stream with the specified name and sample type.

It is recommended to use pa_stream_new_with_proplist() instead and specify some initial properties.

Parameters

c	The context to create this stream in
name	A name for this stream
ss	The desired sample format
map	The desired channel map, or NULL for default

◆ pa_stream_new_extended()

pa_stream* pa_stream_new_extended	(	pa_context *	c,
		const char *	name,
		pa_format_info const	formats,
		unsigned int	n_formats,
		pa_proplist *	p
	)

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

Parameters

c	The context to create this stream in
name	A name for this stream
formats	The list of formats that can be provided
n_formats	The number of formats being passed in
p	The initial property list

◆ pa_stream_new_with_proplist()

pa_stream* pa_stream_new_with_proplist	(	pa_context *	c,
		const char *	name,
		const pa_sample_spec *	ss,
		const pa_channel_map *	map,
		pa_proplist *	p
	)

Create a new, unconnected stream with the specified name and sample type, and specify the initial stream property list.

Since: 0.9.11

Parameters

c	The context to create this stream in
name	A name for this stream
ss	The desired sample format
map	The desired channel map, or NULL for default
p	The initial property list

◆ pa_stream_peek()

int pa_stream_peek	(	pa_stream *	p,
		const void **	data,
		size_t *	nbytes
	)

Read the next fragment from the buffer (for recording streams).

If there is data at the current read index, data will point to the actual data and 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, data will be NULL and nbytes will be 0. If there is a hole, data will be NULL and 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.

Returns zero on success, negative on error.

Parameters

p	The stream to use
data	Pointer to pointer that will point to data
nbytes	The length of the data read in bytes

◆ pa_stream_prebuf()

pa_operation* pa_stream_prebuf	(	pa_stream *	s,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Reenable prebuffering if specified in the pa_buffer_attr structure.

Available for playback streams only.

◆ pa_stream_proplist_remove()

pa_operation* pa_stream_proplist_remove	(	pa_stream *	s,
		const char *const	keys[],
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Update the property list of the sink input/source output of this stream, remove entries.

Since: 0.9.11

◆ pa_stream_proplist_update()

pa_operation* pa_stream_proplist_update	(	pa_stream *	s,
		pa_update_mode_t	mode,
		pa_proplist *	p,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Update the property list of the sink input/source output of this stream, adding new entries.

Please note that it is highly recommended to set as many properties initially via pa_stream_new_with_proplist() as possible instead a posteriori with this function, since that information may be used to route this stream to the right device.

Since: 0.9.11

◆ pa_stream_readable_size()

size_t pa_stream_readable_size ( const pa_stream * p )

Return the number of bytes that may be read using pa_stream_peek().

(size_t) -1 is returned on error.

◆ pa_stream_ref()

pa_stream* pa_stream_ref ( pa_stream * s )

Increase the reference counter by one.

◆ pa_stream_set_buffer_attr()

pa_operation* pa_stream_set_buffer_attr	(	pa_stream *	s,
		const pa_buffer_attr *	attr,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Change the buffer metrics of the stream during playback.

The server might have chosen different buffer metrics than requested. The selected metrics may be queried with pa_stream_get_buffer_attr() as soon as the callback is called. Only valid after the stream has been connected successfully and if the server is at least PulseAudio 0.9.8. Please be aware of the slightly different semantics of the call depending whether PA_STREAM_ADJUST_LATENCY is set or not.

Since: 0.9.8

◆ pa_stream_set_buffer_attr_callback()

void pa_stream_set_buffer_attr_callback	(	pa_stream *	p,
		pa_stream_notify_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called whenever the buffer attributes on the server side change.

Please note that the buffer attributes can change when moving a stream to a different sink/source too, hence if you use this callback you should use pa_stream_set_moved_callback() as well.

Since: 0.9.15

◆ pa_stream_set_event_callback()

void pa_stream_set_event_callback	(	pa_stream *	p,
		pa_stream_event_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called whenever a meta/policy control event is received.

Since: 0.9.15

◆ pa_stream_set_latency_update_callback()

void pa_stream_set_latency_update_callback	(	pa_stream *	p,
		pa_stream_notify_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called whenever a latency information update happens.

Useful on PA_STREAM_AUTO_TIMING_UPDATE streams only.

◆ pa_stream_set_monitor_stream()

int pa_stream_set_monitor_stream	(	pa_stream *	s,
		uint32_t	sink_input_idx
	)

For record streams connected to a monitor source: monitor only a very specific sink input of the sink.

This function needs to be called before pa_stream_connect_record() is called. Returns zero on success, negative on error.

Since: 0.9.11

◆ pa_stream_set_moved_callback()

void pa_stream_set_moved_callback	(	pa_stream *	p,
		pa_stream_notify_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called whenever the stream is moved to a different sink/source.

Use pa_stream_get_device_name() or pa_stream_get_device_index() to query the new sink/source. This notification is only generated when the server is at least 0.9.8.

Since: 0.9.8

◆ pa_stream_set_name()

pa_operation* pa_stream_set_name	(	pa_stream *	s,
		const char *	name,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Rename the stream.

◆ pa_stream_set_overflow_callback()

void pa_stream_set_overflow_callback	(	pa_stream *	p,
		pa_stream_notify_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called when a buffer overflow happens.

(Only for playback streams)

◆ pa_stream_set_read_callback()

void pa_stream_set_read_callback	(	pa_stream *	p,
		pa_stream_request_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called when new data is available from the stream.

◆ pa_stream_set_started_callback()

void pa_stream_set_started_callback	(	pa_stream *	p,
		pa_stream_notify_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called when the server starts playback after an underrun or on initial startup.

This only informs that audio is flowing again, it is no indication that audio started to reach the speakers already. (Only for playback streams)

Since: 0.9.11

◆ pa_stream_set_state_callback()

void pa_stream_set_state_callback	(	pa_stream *	s,
		pa_stream_notify_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called whenever the state of the stream changes.

◆ pa_stream_set_suspended_callback()

void pa_stream_set_suspended_callback	(	pa_stream *	p,
		pa_stream_notify_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called whenever the sink/source this stream is connected to is suspended or resumed.

Use pa_stream_is_suspended() to query the new suspend status. Please note that the suspend status might also change when the stream is moved between devices. Thus if you call this function you very likely want to call pa_stream_set_moved_callback() too. This notification is only generated when the server is at least 0.9.8.

Since: 0.9.8

◆ pa_stream_set_underflow_callback()

void pa_stream_set_underflow_callback	(	pa_stream *	p,
		pa_stream_notify_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called when a buffer underflow happens.

(Only for playback streams)

◆ pa_stream_set_write_callback()

void pa_stream_set_write_callback	(	pa_stream *	p,
		pa_stream_request_cb_t	cb,
		void *	userdata
	)

Set the callback function that is called when new data may be written to the stream.

◆ pa_stream_trigger()

pa_operation* pa_stream_trigger	(	pa_stream *	s,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Request immediate start of playback on this stream.

This disables prebuffering temporarily if specified in the pa_buffer_attr structure. Available for playback streams only.

◆ pa_stream_unref()

void pa_stream_unref ( pa_stream * s )

Decrease the reference counter by one.

◆ pa_stream_update_sample_rate()

pa_operation* pa_stream_update_sample_rate	(	pa_stream *	s,
		uint32_t	rate,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Change the stream sampling rate during playback.

You need to pass PA_STREAM_VARIABLE_RATE in the flags parameter of pa_stream_connect_playback() if you plan to use this function. Only valid after the stream has been connected successfully and if the server is at least PulseAudio 0.9.8.

Since: 0.9.8

◆ pa_stream_update_timing_info()

pa_operation* pa_stream_update_timing_info	(	pa_stream *	p,
		pa_stream_success_cb_t	cb,
		void *	userdata
	)

Request a timing info structure update for a stream.

Use pa_stream_get_timing_info() to get access to the raw timing data, or pa_stream_get_time() or pa_stream_get_latency() to get cleaned up values.

◆ pa_stream_writable_size()

size_t pa_stream_writable_size ( const pa_stream * p )

Return the number of bytes requested by the server that have not yet been written.

It is possible to write more than this amount, up to the stream's buffer_attr.maxlength bytes. This is usually not desirable, though, as it would increase stream latency to be higher than requested (buffer_attr.tlength).

(size_t) -1 is returned on error.

◆ pa_stream_write()

int pa_stream_write	(	pa_stream *	p,
		const void *	data,
		size_t	nbytes,
		pa_free_cb_t	free_cb,
		int64_t	offset,
		pa_seek_mode_t	seek
	)

Write some data to the server (for playback streams).

If free_cb is non-NULL this routine is called when all data has been written out. An internal reference to the specified data is kept, the data is not copied. If NULL, the data is copied into an internal buffer.

The client may freely seek around in the output buffer. For most applications it is typical to pass 0 and PA_SEEK_RELATIVE as values for the arguments offset and seek respectively. After a successful write call the write index will be at the position after where this chunk of data has been written to.

As an optimization for avoiding needless memory copies you may call pa_stream_begin_write() before this call and then place your audio data directly in the memory area returned by that call. Then, pass a pointer to that memory area to pa_stream_write(). After the invocation of pa_stream_write() the memory area may no longer be accessed. Any further explicit freeing of the memory area is not necessary. It is OK to write to the memory area returned by pa_stream_begin_write() only partially with this call, skipping bytes both at the end and at the beginning of the reserved memory area.

Returns zero on success.

Parameters

p	The stream to use
data	The data to write
nbytes	The length of the data to write in bytes, must be in multiples of the stream's sample spec frame size
free_cb	A cleanup routine for the data or NULL to request an internal copy
offset	Offset for seeking, must be 0 for upload streams, must be in multiples of the stream's sample spec frame size
seek	Seek mode, must be PA_SEEK_RELATIVE for upload streams

◆ pa_stream_write_ext_free()

int pa_stream_write_ext_free	(	pa_stream *	p,
		const void *	data,
		size_t	nbytes,
		pa_free_cb_t	free_cb,
		void *	free_cb_data,
		int64_t	offset,
		pa_seek_mode_t	seek
	)

Function does exactly the same as pa_stream_write() with the difference that free_cb_data is passed to free_cb instead of data.

Since: 6.0

Parameters

p	The stream to use
data	The data to write
nbytes	The length of the data to write in bytes
free_cb	A cleanup routine for the data or NULL to request an internal copy
free_cb_data	Argument passed to free_cb function
offset	Offset for seeking, must be 0 for upload streams
seek	Seek mode, must be PA_SEEK_RELATIVE for upload streams

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ pa_stream

◆ pa_stream_event_cb_t

◆ pa_stream_notify_cb_t

◆ pa_stream_request_cb_t

◆ pa_stream_success_cb_t

Function Documentation

◆ pa_stream_begin_write()

◆ pa_stream_cancel_write()

◆ pa_stream_connect_playback()

◆ pa_stream_connect_record()

◆ pa_stream_cork()

◆ pa_stream_disconnect()

◆ pa_stream_drain()

◆ pa_stream_drop()

◆ pa_stream_flush()

◆ pa_stream_get_buffer_attr()

◆ pa_stream_get_channel_map()

◆ pa_stream_get_context()

◆ pa_stream_get_device_index()

◆ pa_stream_get_device_name()

◆ pa_stream_get_format_info()

◆ pa_stream_get_index()

◆ pa_stream_get_latency()

◆ pa_stream_get_monitor_stream()

◆ pa_stream_get_sample_spec()

◆ pa_stream_get_state()

◆ pa_stream_get_time()

◆ pa_stream_get_timing_info()

◆ pa_stream_get_underflow_index()

◆ pa_stream_is_corked()

◆ pa_stream_is_suspended()

◆ pa_stream_new()

◆ pa_stream_new_extended()

◆ pa_stream_new_with_proplist()

◆ pa_stream_peek()

◆ pa_stream_prebuf()

◆ pa_stream_proplist_remove()

◆ pa_stream_proplist_update()

◆ pa_stream_readable_size()

◆ pa_stream_ref()

◆ pa_stream_set_buffer_attr()

◆ pa_stream_set_buffer_attr_callback()

◆ pa_stream_set_event_callback()

◆ pa_stream_set_latency_update_callback()

◆ pa_stream_set_monitor_stream()

◆ pa_stream_set_moved_callback()

◆ pa_stream_set_name()

◆ pa_stream_set_overflow_callback()

◆ pa_stream_set_read_callback()

◆ pa_stream_set_started_callback()

◆ pa_stream_set_state_callback()

◆ pa_stream_set_suspended_callback()

◆ pa_stream_set_underflow_callback()

◆ pa_stream_set_write_callback()

◆ pa_stream_trigger()

◆ pa_stream_unref()

◆ pa_stream_update_sample_rate()

◆ pa_stream_update_timing_info()

◆ pa_stream_writable_size()

◆ pa_stream_write()

◆ pa_stream_write_ext_free()