7 This file is part of PulseAudio.
9 Copyright 2004-2006 Lennart Poettering
10 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
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
14 published by the Free Software Foundation; either version 2.1 of the
15 License, or (at your option) any later version.
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 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public
23 License along with PulseAudio; if not, write to the Free Software
24 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
32 #include <pulse/cdecl.h>
33 #include <pulse/sample.h>
36 * Global definitions */
40 /** The state of a connection context */
41 typedef enum pa_context_state {
42 PA_CONTEXT_UNCONNECTED, /**< The context hasn't been connected yet */
43 PA_CONTEXT_CONNECTING, /**< A connection is being established */
44 PA_CONTEXT_AUTHORIZING, /**< The client is authorizing itself to the daemon */
45 PA_CONTEXT_SETTING_NAME, /**< The client is passing its application name to the daemon */
46 PA_CONTEXT_READY, /**< The connection is established, the context is ready to execute operations */
47 PA_CONTEXT_FAILED, /**< The connection failed or was disconnected */
48 PA_CONTEXT_TERMINATED /**< The connection was terminated cleanly */
51 /** Return non-zero if the passed state is one of the connected states */
52 static inline int PA_CONTEXT_IS_GOOD(pa_context_state_t x) {
54 x == PA_CONTEXT_CONNECTING ||
55 x == PA_CONTEXT_AUTHORIZING ||
56 x == PA_CONTEXT_SETTING_NAME ||
57 x == PA_CONTEXT_READY;
60 /** The state of a stream */
61 typedef enum pa_stream_state {
62 PA_STREAM_UNCONNECTED, /**< The stream is not yet connected to any sink or source */
63 PA_STREAM_CREATING, /**< The stream is being created */
64 PA_STREAM_READY, /**< The stream is established, you may pass audio data to it now */
65 PA_STREAM_FAILED, /**< An error occured that made the stream invalid */
66 PA_STREAM_TERMINATED /**< The stream has been terminated cleanly */
69 /** Return non-zero if the passed state is one of the connected states */
70 static inline int PA_STREAM_IS_GOOD(pa_stream_state_t x) {
72 x == PA_STREAM_CREATING ||
76 /** The state of an operation */
77 typedef enum pa_operation_state {
78 PA_OPERATION_RUNNING, /**< The operation is still running */
79 PA_OPERATION_DONE, /**< The operation has been completed */
80 PA_OPERATION_CANCELED /**< The operation has been canceled */
81 } pa_operation_state_t;
83 /** An invalid index */
84 #define PA_INVALID_INDEX ((uint32_t) -1)
86 /** Some special flags for contexts. */
87 typedef enum pa_context_flags {
88 PA_CONTEXT_NOAUTOSPAWN = 1 /**< Disabled autospawning of the PulseAudio daemon if required */
91 /** The direction of a pa_stream object */
92 typedef enum pa_stream_direction {
93 PA_STREAM_NODIRECTION, /**< Invalid direction */
94 PA_STREAM_PLAYBACK, /**< Playback stream */
95 PA_STREAM_RECORD, /**< Record stream */
96 PA_STREAM_UPLOAD /**< Sample upload stream */
97 } pa_stream_direction_t;
99 /** Some special flags for stream connections. */
100 typedef enum pa_stream_flags {
101 PA_STREAM_START_CORKED = 1, /**< Create the stream corked, requiring an explicit pa_stream_cork() call to uncork it. */
102 PA_STREAM_INTERPOLATE_TIMING = 2, /**< Interpolate the latency for
103 * this stream. When enabled,
104 * pa_stream_get_latency() and
105 * pa_stream_get_time() will try
106 * to estimate the current
107 * record/playback time based on
108 * the local time that passed
109 * since the last timing info
110 * update. Using this option
111 * has the advantage of not
112 * requiring a whole roundtrip
114 * playback/recording time is
115 * needed. Consider using this
116 * option when requesting
117 * latency information
118 * frequently. This is
119 * especially useful on long
121 * connections. It makes a lot
122 * of sense to combine this
124 * PA_STREAM_AUTO_TIMING_UPDATE. */
125 PA_STREAM_NOT_MONOTONOUS = 4, /**< Don't force the time to
126 * increase monotonically. If
127 * this option is enabled,
128 * pa_stream_get_time() will not
129 * necessarily return always
130 * monotonically increasing time
131 * values on each call. This may
132 * confuse applications which
133 * cannot deal with time going
134 * 'backwards', but has the
135 * advantage that bad transport
136 * latency estimations that
137 * caused the time to to jump
138 * ahead can be corrected
139 * quickly, without the need to
141 PA_STREAM_AUTO_TIMING_UPDATE = 8, /**< If set timing update requests
142 * are issued periodically
143 * automatically. Combined with
144 * PA_STREAM_INTERPOLATE_TIMING
145 * you will be able to query the
146 * current time and latency with
147 * pa_stream_get_time() and
148 * pa_stream_get_latency() at
149 * all times without a packet
151 PA_STREAM_NO_REMAP_CHANNELS = 16, /**< Don't remap channels by
152 * their name, instead map them
155 * PA_STREAM_NO_REMIX_CHANNELS. Only
156 * supported when the server is
157 * at least PA 0.9.8. It is
159 * servers.\since 0.9.8 */
160 PA_STREAM_NO_REMIX_CHANNELS = 32, /**< When remapping channels by
161 * name, don't upmix or downmix
163 * channels. Copy them into
164 * matching channels of the
165 * device 1:1. Only supported
166 * when the server is at least
167 * PA 0.9.8. It is ignored on
168 * older servers. \since
170 PA_STREAM_FIX_FORMAT = 64, /**< Use the sample format of the
171 * sink/device this stream is being
172 * connected to, and possibly ignore
173 * the format the sample spec contains
174 * -- but you still have to pass a
175 * valid value in it as a hint to
176 * PulseAudio what would suit your
177 * stream best. If this is used you
178 * should query the used sample format
179 * after creating the stream by using
180 * pa_stream_get_sample_spec(). Also,
181 * if you specified manual buffer
182 * metrics it is recommended to update
184 * pa_stream_set_buffer_attr() to
185 * compensate for the changed frame
186 * sizes. Only supported when the
187 * server is at least PA 0.9.8. It is
188 * ignored on older servers. \since
191 PA_STREAM_FIX_RATE = 128, /**< Use the sample rate of the sink,
192 * and possibly ignore the rate the
193 * sample spec contains. Usage similar
194 * to PA_STREAM_FIX_FORMAT.Only
195 * supported when the server is at least
196 * PA 0.9.8. It is ignored on older
197 * servers. \since 0.9.8 */
199 PA_STREAM_FIX_CHANNELS = 256, /**< Use the number of channels and
200 * the channel map of the sink, and
201 * possibly ignore the number of
202 * channels and the map the sample spec
203 * and the passed channel map
204 * contains. Usage similar to
205 * PA_STREAM_FIX_FORMAT. Only supported
206 * when the server is at least PA
207 * 0.9.8. It is ignored on older
208 * servers. \since 0.9.8 */
209 PA_STREAM_DONT_MOVE = 512, /**< Don't allow moving of this stream to
210 * another sink/device. Useful if you use
211 * any of the PA_STREAM_FIX_ flags and
212 * want to make sure that resampling
213 * never takes place -- which might
214 * happen if the stream is moved to
215 * another sink/source whith a different
216 * sample spec/channel map. Only
217 * supported when the server is at least
218 * PA 0.9.8. It is ignored on older
219 * servers. \since 0.9.8 */
220 PA_STREAM_VARIABLE_RATE = 1024, /**< Allow dynamic changing of the
221 * sampling rate during playback
223 * pa_stream_update_sample_rate(). Only
224 * supported when the server is at
225 * least PA 0.9.8. It is ignored
226 * on older servers. \since
228 PA_STREAM_PEAK_DETECT = 2048, /**< Find peaks instead of
229 * resampling. \since 0.9.11 */
231 PA_STREAM_START_MUTED = 4096, /**< Create in muted state. \since 0.9.11 */
234 PA_STREAM_ADJUST_LATENCY = 8192, /**< Try to adjust the latency of
235 * the sink/source based on the
236 * requested buffer metrics and
237 * adjust buffer metrics
238 * accordingly. \since 0.9.11 */
242 /** English is an evil language \since 0.9.11 */
243 #define PA_STREAM_NOT_MONOTONIC PA_STREAM_NOT_MONOTONOUS
245 /** Playback and record buffer metrics */
246 typedef struct pa_buffer_attr {
247 uint32_t maxlength; /**< Maximum length of the
248 * buffer. Setting this to 0 will
249 * initialize this to the maximum value
250 * supported by server, which is
252 uint32_t tlength; /**< Playback only: target length of the
253 * buffer. The server tries to assure
254 * that at least tlength bytes are always
255 * available in the buffer. It is
256 * recommended to set this to 0, which
257 * will initialize this to a value that
258 * is deemed sensible by the
259 * server. However, this value will
260 * default to something like 2s, i.e. for
261 * applications that have specific
262 * latency requirements this value should
263 * be set to the maximum latency that the
264 * application can deal with. */
265 uint32_t prebuf; /**< Playback only: pre-buffering. The
266 * server does not start with playback
267 * before at least prebug bytes are
268 * available in the buffer. It is
269 * recommended to set this to 0, which
270 * will initialize this to the same value
271 * as tlength, whatever that may be. */
272 uint32_t minreq; /**< Playback only: minimum request. The
273 * server does not request less than
274 * minreq bytes from the client, instead
275 * waits until the buffer is free enough
276 * to request more bytes at once. It is
277 * recommended to set this to 0, which
278 * will initialize this to a value that
279 * is deemed sensible by the server. */
280 uint32_t fragsize; /**< Recording only: fragment size. The
281 * server sends data in blocks of
282 * fragsize bytes size. Large values
283 * deminish interactivity with other
284 * operations on the connection context
285 * but decrease control overhead. It is
286 * recommended to set this to 0, which
287 * will initialize this to a value that
288 * is deemed sensible by the
289 * server. However, this value will
290 * default to something like 2s, i.e. for
291 * applications that have specific
292 * latency requirements this value should
293 * be set to the maximum latency that the
294 * application can deal with. */
297 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
299 PA_OK = 0, /**< No error */
300 PA_ERR_ACCESS, /**< Access failure */
301 PA_ERR_COMMAND, /**< Unknown command */
302 PA_ERR_INVALID, /**< Invalid argument */
303 PA_ERR_EXIST, /**< Entity exists */
304 PA_ERR_NOENTITY, /**< No such entity */
305 PA_ERR_CONNECTIONREFUSED, /**< Connection refused */
306 PA_ERR_PROTOCOL, /**< Protocol error */
307 PA_ERR_TIMEOUT, /**< Timeout */
308 PA_ERR_AUTHKEY, /**< No authorization key */
309 PA_ERR_INTERNAL, /**< Internal error */
310 PA_ERR_CONNECTIONTERMINATED, /**< Connection terminated */
311 PA_ERR_KILLED, /**< Entity killed */
312 PA_ERR_INVALIDSERVER, /**< Invalid server */
313 PA_ERR_MODINITFAILED, /**< Module initialization failed */
314 PA_ERR_BADSTATE, /**< Bad state */
315 PA_ERR_NODATA, /**< No data */
316 PA_ERR_VERSION, /**< Incompatible protocol version */
317 PA_ERR_TOOLARGE, /**< Data too large */
318 PA_ERR_NOTSUPPORTED, /**< Operation not supported \since 0.9.5 */
319 PA_ERR_UNKNOWN, /**< The error code was unknown to the client */
320 PA_ERR_MAX /**< Not really an error but the first invalid error code */
323 /** Subscription event mask, as used by pa_context_subscribe() */
324 typedef enum pa_subscription_mask {
325 PA_SUBSCRIPTION_MASK_NULL = 0, /**< No events */
326 PA_SUBSCRIPTION_MASK_SINK = 1, /**< Sink events */
327 PA_SUBSCRIPTION_MASK_SOURCE = 2, /**< Source events */
328 PA_SUBSCRIPTION_MASK_SINK_INPUT = 4, /**< Sink input events */
329 PA_SUBSCRIPTION_MASK_SOURCE_OUTPUT = 8, /**< Source output events */
330 PA_SUBSCRIPTION_MASK_MODULE = 16, /**< Module events */
331 PA_SUBSCRIPTION_MASK_CLIENT = 32, /**< Client events */
332 PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 64, /**< Sample cache events */
333 PA_SUBSCRIPTION_MASK_SERVER = 128, /**< Other global server changes. */
334 PA_SUBSCRIPTION_MASK_AUTOLOAD = 256, /**< Autoload table events. */
335 PA_SUBSCRIPTION_MASK_ALL = 511 /**< Catch all events */
336 } pa_subscription_mask_t;
338 /** Subscription event types, as used by pa_context_subscribe() */
339 typedef enum pa_subscription_event_type {
340 PA_SUBSCRIPTION_EVENT_SINK = 0, /**< Event type: Sink */
341 PA_SUBSCRIPTION_EVENT_SOURCE = 1, /**< Event type: Source */
342 PA_SUBSCRIPTION_EVENT_SINK_INPUT = 2, /**< Event type: Sink input */
343 PA_SUBSCRIPTION_EVENT_SOURCE_OUTPUT = 3, /**< Event type: Source output */
344 PA_SUBSCRIPTION_EVENT_MODULE = 4, /**< Event type: Module */
345 PA_SUBSCRIPTION_EVENT_CLIENT = 5, /**< Event type: Client */
346 PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 6, /**< Event type: Sample cache item */
347 PA_SUBSCRIPTION_EVENT_SERVER = 7, /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. */
348 PA_SUBSCRIPTION_EVENT_AUTOLOAD = 8, /**< Event type: Autoload table changes. */
349 PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 15, /**< A mask to extract the event type from an event value */
351 PA_SUBSCRIPTION_EVENT_NEW = 0, /**< A new object was created */
352 PA_SUBSCRIPTION_EVENT_CHANGE = 16, /**< A property of the object was modified */
353 PA_SUBSCRIPTION_EVENT_REMOVE = 32, /**< An object was removed */
354 PA_SUBSCRIPTION_EVENT_TYPE_MASK = 16+32 /**< A mask to extract the event operation from an event value */
355 } pa_subscription_event_type_t;
357 /** Return one if an event type t matches an event mask bitfield */
358 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
360 /** A structure for all kinds of timing information of a stream. See
361 * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
362 * total output latency a sample that is written with
363 * pa_stream_write() takes to be played may be estimated by
364 * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined
365 * as pa_bytes_to_usec(write_index-read_index)) The output buffer
366 * which buffer_usec relates to may be manipulated freely (with
367 * pa_stream_write()'s seek argument, pa_stream_flush() and friends),
368 * the buffers sink_usec and source_usec relate to are first-in
369 * first-out (FIFO) buffers which cannot be flushed or manipulated in
370 * any way. The total input latency a sample that is recorded takes to
371 * be delivered to the application is:
372 * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
373 * sign issues!) When connected to a monitor source sink_usec contains
374 * the latency of the owning sink. The two latency estimations
375 * described here are implemented in pa_stream_get_latency(). Please
376 * note that this structure can be extended as part of evolutionary
377 * API updates at any time in any new release.*/
378 typedef struct pa_timing_info {
379 struct timeval timestamp; /**< The time when this timing info structure was current */
380 int synchronized_clocks; /**< Non-zero if the local and the
381 * remote machine have synchronized
382 * clocks. If synchronized clocks are
383 * detected transport_usec becomes much
384 * more reliable. However, the code that
385 * detects synchronized clocks is very
386 * limited und unreliable itself. */
388 pa_usec_t sink_usec; /**< Time in usecs a sample takes to be played on the sink. For playback streams and record streams connected to a monitor source. */
389 pa_usec_t source_usec; /**< Time in usecs a sample takes from being recorded to being delivered to the application. Only for record streams. */
390 pa_usec_t transport_usec; /**< Estimated time in usecs a sample takes to be transferred to/from the daemon. For both playback and record streams. */
392 int playing; /**< Non-zero when the stream is
393 * currently not underrun and data is
394 * being passed on to the device. Only
395 * for playback streams. This field does
396 * not say whether the data is actually
397 * already being played. To determine
398 * this check whether since_underrun
399 * (converted to usec) is larger than
402 int write_index_corrupt; /**< Non-zero if write_index is not
403 * up-to-date because a local write
404 * command that corrupted it has been
405 * issued in the time since this latency
406 * info was current . Only write
407 * commands with SEEK_RELATIVE_ON_READ
408 * and SEEK_RELATIVE_END can corrupt
410 int64_t write_index; /**< Current write index into the
411 * playback buffer in bytes. Think twice before
412 * using this for seeking purposes: it
413 * might be out of date a the time you
414 * want to use it. Consider using
415 * PA_SEEK_RELATIVE instead. */
417 int read_index_corrupt; /**< Non-zero if read_index is not
418 * up-to-date because a local pause or
419 * flush request that corrupted it has
420 * been issued in the time since this
421 * latency info was current. */
423 int64_t read_index; /**< Current read index into the
424 * playback buffer in bytes. Think twice before
425 * using this for seeking purposes: it
426 * might be out of date a the time you
427 * want to use it. Consider using
428 * PA_SEEK_RELATIVE_ON_READ
431 pa_usec_t configured_sink_usec; /**< The static configured latency for
432 * the sink. \since 0.9.11 */
433 pa_usec_t configured_source_usec; /**< The static configured latency for
434 * the source. \since 0.9.11 */
436 int64_t since_underrun; /**< Bytes that were handed to the sink
437 since the last underrun happened, or
438 since playback started again after
439 the last underrun. playing will tell
440 you which case it is. \since
445 /** A structure for the spawn api. This may be used to integrate auto
446 * spawned daemons into your application. For more information see
447 * pa_context_connect(). When spawning a new child process the
448 * waitpid() is used on the child's PID. The spawn routine will not
449 * block or ignore SIGCHLD signals, since this cannot be done in a
450 * thread compatible way. You might have to do this in
451 * prefork/postfork. */
452 typedef struct pa_spawn_api {
453 void (*prefork)(void); /**< Is called just before the fork in the parent process. May be NULL. */
454 void (*postfork)(void); /**< Is called immediately after the fork in the parent process. May be NULL.*/
455 void (*atfork)(void); /**< Is called immediately after the
456 * fork in the child process. May be
457 * NULL. It is not safe to close all
458 * file descriptors in this function
459 * unconditionally, since a UNIX socket
460 * (created using socketpair()) is
461 * passed to the new process. */
464 /** Seek type for pa_stream_write(). */
465 typedef enum pa_seek_mode {
466 PA_SEEK_RELATIVE = 0, /**< Seek relatively to the write index */
467 PA_SEEK_ABSOLUTE = 1, /**< Seek relatively to the start of the buffer queue */
468 PA_SEEK_RELATIVE_ON_READ = 2, /**< Seek relatively to the read index. */
469 PA_SEEK_RELATIVE_END = 3 /**< Seek relatively to the current end of the buffer queue. */
472 /** Special sink flags. */
473 typedef enum pa_sink_flags {
474 PA_SINK_HW_VOLUME_CTRL = 1, /**< Supports hardware volume control */
475 PA_SINK_LATENCY = 2, /**< Supports latency querying */
476 PA_SINK_HARDWARE = 4, /**< Is a hardware sink of some kind, in contrast to "virtual"/software sinks \since 0.9.3 */
477 PA_SINK_NETWORK = 8, /**< Is a networked sink of some kind. \since 0.9.7 */
478 PA_SINK_HW_MUTE_CTRL = 16, /**< Supports hardware mute control \since 0.9.11 */
479 PA_SINK_DECIBEL_VOLUME = 32 /**< Volume can be translated to dB with pa_sw_volume_to_dB() \since 0.9.11 */
482 /** Special source flags. */
483 typedef enum pa_source_flags {
484 PA_SOURCE_HW_VOLUME_CTRL = 1, /**< Supports hardware volume control */
485 PA_SOURCE_LATENCY = 2, /**< Supports latency querying */
486 PA_SOURCE_HARDWARE = 4, /**< Is a hardware source of some kind, in contrast to "virtual"/software source \since 0.9.3 */
487 PA_SOURCE_NETWORK = 8, /**< Is a networked sink of some kind. \since 0.9.7 */
488 PA_SOURCE_HW_MUTE_CTRL = 16, /**< Supports hardware mute control \since 0.9.11 */
489 PA_SOURCE_DECIBEL_VOLUME = 32 /**< Volume can be translated to dB with pa_sw_volume_to_dB() \since 0.9.11 */
492 /** A generic free() like callback prototype */
493 typedef void (*pa_free_cb_t)(void *p);