stream.h File Reference

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

Go to the source code of this file.

Typedefs

typedef struct pa_stream pa_stream
 An opaque stream for playback or recording.
typedef void(* pa_stream_success_cb_t )(pa_stream *s, int success, void *userdata)
 A generic callback for operation completion.
typedef void(* pa_stream_request_cb_t )(pa_stream *p, size_t bytes, void *userdata)
 A generic request callback.
typedef void(* pa_stream_notify_cb_t )(pa_stream *p, void *userdata)
 A generic notification callback.

Functions

pa_streampa_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.
void pa_stream_unref (pa_stream *s)
 Decrease the reference counter by one.
pa_streampa_stream_ref (pa_stream *s)
 Increase the reference counter by one.
pa_stream_state_t pa_stream_get_state (pa_stream *p)
 Return the current state of the stream.
pa_contextpa_stream_get_context (pa_stream *p)
 Return the context this stream is attached to.
uint32_t pa_stream_get_index (pa_stream *s)
 Return the sink input resp.
uint32_t pa_stream_get_device_index (pa_stream *s)
 Return the index of the sink or source this stream is connected to in the server.
const char * pa_stream_get_device_name (pa_stream *s)
 Return the name of the sink or source this stream is connected to in the server.
int pa_stream_is_suspended (pa_stream *s)
 Return 1 if the sink or source this stream is connected to has been suspended.
int pa_stream_connect_playback (pa_stream *s, const char *dev, const pa_buffer_attr *attr, pa_stream_flags_t flags, pa_cvolume *volume, pa_stream *sync_stream)
 Connect the stream to a sink.
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.
int pa_stream_disconnect (pa_stream *s)
 Disconnect a stream from a source/sink.
int pa_stream_write (pa_stream *p, const void *data, size_t bytes, pa_free_cb_t free_cb, int64_t offset, pa_seek_mode_t seek)
 Write some data to the server (for playback sinks), if free_cb is non-NULL this routine is called when all data has been written out and an internal reference to the specified data is kept, the data is not copied.
int pa_stream_peek (pa_stream *p, const void **data, size_t *bytes)
 Read the next fragment from the buffer (for recording).
int pa_stream_drop (pa_stream *p)
 Remove the current fragment on record streams.
size_t pa_stream_writable_size (pa_stream *p)
 Return the number of bytes that may be written using pa_stream_write().
size_t pa_stream_readable_size (pa_stream *p)
 Return the number of bytes that may be read using pa_stream_read().
pa_operationpa_stream_drain (pa_stream *s, pa_stream_success_cb_t cb, void *userdata)
 Drain a playback stream.
pa_operationpa_stream_update_timing_info (pa_stream *p, pa_stream_success_cb_t cb, void *userdata)
 Request a timing info structure update for a stream.
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.
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.
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.
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.
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.
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.
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.
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.
pa_operationpa_stream_cork (pa_stream *s, int b, pa_stream_success_cb_t cb, void *userdata)
 Pause (or resume) playback of this stream temporarily.
pa_operationpa_stream_flush (pa_stream *s, pa_stream_success_cb_t cb, void *userdata)
 Flush the playback buffer of this stream.
pa_operationpa_stream_prebuf (pa_stream *s, pa_stream_success_cb_t cb, void *userdata)
 Reenable prebuffering as specified in the pa_buffer_attr structure.
pa_operationpa_stream_trigger (pa_stream *s, pa_stream_success_cb_t cb, void *userdata)
 Request immediate start of playback on this stream.
pa_operationpa_stream_set_name (pa_stream *s, const char *name, pa_stream_success_cb_t cb, void *userdata)
 Rename the stream.
int pa_stream_get_time (pa_stream *s, pa_usec_t *r_usec)
 Return the current playback/recording time.
int pa_stream_get_latency (pa_stream *s, pa_usec_t *r_usec, int *negative)
 Return the total stream latency.
const pa_timing_infopa_stream_get_timing_info (pa_stream *s)
 Return the latest raw timing data structure.
const pa_sample_specpa_stream_get_sample_spec (pa_stream *s)
 Return a pointer to the stream's sample specification.
const pa_channel_mappa_stream_get_channel_map (pa_stream *s)
 Return a pointer to the stream's channel map.
const pa_buffer_attrpa_stream_get_buffer_attr (pa_stream *s)
 Return the buffer metrics of the stream.
pa_operationpa_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.
pa_operationpa_stream_update_sample_rate (pa_stream *s, uint32_t rate, pa_stream_success_cb_t cb, void *userdata)


Detailed Description

Audio streams for input, output and sample upload.


Typedef Documentation

typedef struct pa_stream pa_stream

An opaque stream for playback or recording.

Examples:
pacat.c, and paplay.c.

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

A generic notification callback.

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

A generic request callback.

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

A generic callback for operation completion.


Function Documentation

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

Connect the stream to a sink.

Parameters:
s  The stream to connect to a sink
dev  Name of the sink to connect to, or NULL for default
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
Examples:
pacat.c, and paplay.c.

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.

Parameters:
s  The stream to connect to a source
dev  Name of the source to connect to, or NULL for default
attr  Buffer attributes, or NULL for default
flags  Additional flags, or 0 for default
Examples:
pacat.c.

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.

Since:
0.3

int pa_stream_disconnect ( pa_stream s  ) 

Disconnect a stream from a source/sink.

Examples:
pacat.c, and paplay.c.

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 buffer is empty

Examples:
pacat.c, and paplay.c.

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

Since:
0.8
Examples:
pacat.c.

pa_operation* pa_stream_flush ( pa_stream s,
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.

Since:
0.3

const pa_buffer_attr* pa_stream_get_buffer_attr ( pa_stream s  ) 

Return the buffer metrics of the stream.

Only valid after the stream has been connected successfuly and if the server is at least PulseAudio 0.9.

Since:
0.9.0
Examples:
pacat.c.

const pa_channel_map* pa_stream_get_channel_map ( pa_stream s  ) 

Return a pointer to the stream's channel map.

Since:
0.8
Examples:
pacat.c.

pa_context* pa_stream_get_context ( pa_stream p  ) 

Return the context this stream is attached to.

Examples:
pacat.c, and paplay.c.

uint32_t pa_stream_get_device_index ( pa_stream s  ) 

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

This is useful for usage with the introspection functions, such as pa_context_get_sink_info_by_index() resp. 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_ERR_NOTSUPPORTED when the server is older than 0.9.8.

Since:
0.9.8
Examples:
pacat.c.

const char* pa_stream_get_device_name ( pa_stream s  ) 

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

This is useful for usage with the introspection functions, such as pa_context_get_sink_info_by_name() resp. 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 return with PA_ERR_NOTSUPPORTED when the server is older than 0.9.8.

Since:
0.9.8
Examples:
pacat.c.

uint32_t pa_stream_get_index ( pa_stream s  ) 

Return the sink input resp.

source output index this stream is identified in the server with. This is useful for usage with the introspection functions, such as pa_context_get_sink_input_info() resp. pa_context_get_source_output_info().

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

Return 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 *negative is set to 1.

Since:
0.6
Examples:
pacat.c.

const pa_sample_spec* pa_stream_get_sample_spec ( pa_stream s  ) 

Return a pointer to the stream's sample specification.

Since:
0.6
Examples:
pacat.c.

pa_stream_state_t pa_stream_get_state ( pa_stream p  ) 

Return the current state of the stream.

Examples:
pacat.c, and paplay.c.

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(). This function will usually only return new data if a timing info update has been recieved. 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. (that means: the returned value is always greater or equal to the value returned on the last call) This behaviour can be disabled by using PA_STREAM_NOT_MONOTONOUS. This may be desirable to deal better with bad estimations of transport latencies, but may have strange effects if the application is not able to deal with time going 'backwards'.

Since:
0.6
Examples:
pacat.c.

const pa_timing_info* pa_stream_get_timing_info ( pa_stream s  ) 

Return the latest raw timing data structure.

The returned pointer points to an internal read-only instance of the timing structure. The user should make a copy of this structure if he wants to modify it. An in-place update to this data structure may be requested using pa_stream_update_timing_info(). If no pa_stream_update_timing_info() call was issued before, this function will fail with 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 update has been recieved.

Since:
0.8

int pa_stream_is_suspended ( 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 negative on error. This function will return with PA_ERR_NOTSUPPORTED when the server is older than 0.9.8.

Since:
0.9.8
Examples:
pacat.c.

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.

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
Examples:
pacat.c, and paplay.c.

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

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

data will point to the actual data and length will contain the size of the data in bytes (which can be less than a complete framgnet). Use pa_stream_drop() to actually remove the data from the buffer. If no data is available will return a NULL pointer

Since:
0.8
Parameters:
p  The stream to use
data  Pointer to pointer that will point to data
bytes  The length of the data read in bytes
Examples:
pacat.c.

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

Reenable prebuffering as specified in the pa_buffer_attr structure.

Available for playback streams only.

Since:
0.6

size_t pa_stream_readable_size ( pa_stream p  ) 

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

Since:
0.8

pa_stream* pa_stream_ref ( pa_stream s  ) 

Increase the reference counter by one.

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 then 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.

Since:
0.9.8

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. (Only for playback streams)

Since:
0.8.2

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
Examples:
pacat.c.

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

Rename the stream.

Since:
0.5

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)

Since:
0.8

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.

Return the number of bytes read.

Since:
0.8
Examples:
pacat.c.

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.

Examples:
pacat.c, and paplay.c.

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
Examples:
pacat.c.

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)

Since:
0.8

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.

Examples:
pacat.c, and paplay.c.

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 as specified in the pa_buffer_attr structure, temporarily. Available for playback streams only.

Since:
0.3

void pa_stream_unref ( pa_stream s  ) 

Decrease the reference counter by one.

Examples:
pacat.c, and paplay.c.

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

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.

Examples:
pacat.c.

size_t pa_stream_writable_size ( pa_stream p  ) 

Return the number of bytes that may be written using pa_stream_write().

Examples:
pacat.c.

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

Write some data to the server (for playback sinks), if free_cb is non-NULL this routine is called when all data has been written out and 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 my freely seek around in the output buffer. For most applications passing 0 and PA_SEEK_RELATIVE as arguments for offset and seek should be useful.

Parameters:
p  The stream to use
data  The data to write
bytes  The length of the data to write in bytes
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
seek  Seek mode, must be PA_SEEK_RELATIVE for upload streams
Examples:
pacat.c, and paplay.c.


Generated on Mon Sep 29 02:44:36 2008 for PulseAudio by  doxygen 1.5.6