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 published
12 by the Free Software Foundation; either version 2.1 of the License,
13 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 General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with PulseAudio; if not, write to the Free Software
22 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
26 #include <sys/types.h>
28 #include <pulse/sample.h>
29 #include <pulse/channelmap.h>
30 #include <pulse/def.h>
31 #include <pulse/cdecl.h>
32 #include <pulse/version.h>
34 /** \page simple Simple API
36 * \section overv_sec Overview
38 * The simple API is designed for applications with very basic sound
39 * playback or capture needs. It can only support a single stream per
40 * connection and has no support for handling of complex features like
41 * events, channel mappings and volume control. It is, however, very simple
42 * to use and quite sufficient for many programs.
44 * \section conn_sec Connecting
46 * The first step before using the sound system is to connect to the
47 * server. This is normally done this way:
53 * ss.format = PA_SAMPLE_S16NE;
57 * s = pa_simple_new(NULL, // Use the default server.
58 * "Fooapp", // Our application's name.
60 * NULL, // Use the default device.
61 * "Music", // Description of our stream.
62 * &ss, // Our sample format.
63 * NULL, // Use default channel map
64 * NULL, // Use default buffering attributes.
65 * NULL, // Ignore error code.
69 * At this point a connected object is returned, or NULL if there was a
72 * \section transfer_sec Transferring data
74 * Once the connection is established to the server, data can start flowing.
75 * Using the connection is very similar to the normal read() and write()
76 * system calls. The main difference is that they're called pa_simple_read()
77 * and pa_simple_write(). Note that these operations always block.
79 * \section ctrl_sec Buffer control
81 * \li pa_simple_get_latency() - Will return the total latency of
82 * the playback or record pipeline, respectively.
84 * If a playback stream is used then a few other operations are available:
86 * \li pa_simple_drain() - Will wait for all sent data to finish playing.
87 * \li pa_simple_flush() - Will throw away all data currently in buffers.
89 * \section cleanup_sec Cleanup
91 * Once playback or capture is complete, the connection should be closed
92 * and resources freed. This is done through:
100 * A simple but limited synchronous playback and recording
101 * API. This is a synchronous, simplified wrapper around the standard
104 * See also \subpage simple
107 /** \example pacat-simple.c
108 * A simple playback tool using the simple API */
110 /** \example parec-simple.c
111 * A simple recording tool using the simple API */
115 /** \struct pa_simple
116 * An opaque simple connection object */
117 typedef struct pa_simple pa_simple
;
119 /** Create a new connection to the server. */
120 pa_simple
* pa_simple_new(
121 const char *server
, /**< Server name, or NULL for default */
122 const char *name
, /**< A descriptive name for this client (application name, ...) */
123 pa_stream_direction_t dir
, /**< Open this stream for recording or playback? */
124 const char *dev
, /**< Sink (resp. source) name, or NULL for default */
125 const char *stream_name
, /**< A descriptive name for this stream (application name, song title, ...) */
126 const pa_sample_spec
*ss
, /**< The sample type to use */
127 const pa_channel_map
*map
, /**< The channel map to use, or NULL for default */
128 const pa_buffer_attr
*attr
, /**< Buffering attributes, or NULL for default */
129 int *error
/**< A pointer where the error code is stored when the routine returns NULL. It is OK to pass NULL here. */
132 /** Close and free the connection to the server. The connection object becomes invalid when this is called. */
133 void pa_simple_free(pa_simple
*s
);
135 /** Write some data to the server. */
136 int pa_simple_write(pa_simple
*s
, const void *data
, size_t bytes
, int *error
);
138 /** Wait until all data already written is played by the daemon. */
139 int pa_simple_drain(pa_simple
*s
, int *error
);
141 /** Read some data from the server. This function blocks until \a bytes amount
142 * of data has been received from the server, or until an error occurs.
143 * Returns a negative value on failure. */
145 pa_simple
*s
, /**< The connection object. */
146 void *data
, /**< A pointer to a buffer. */
147 size_t bytes
, /**< The number of bytes to read. */
149 /**< A pointer where the error code is stored when the function returns
150 * a negative value. It is OK to pass NULL here. */
153 /** Return the playback or record latency. */
154 pa_usec_t
pa_simple_get_latency(pa_simple
*s
, int *error
);
156 /** Flush the playback buffer. This discards any audio in the buffer. */
157 int pa_simple_flush(pa_simple
*s
, int *error
);