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