2 * This file is part of DisOrder.
3 * Copyright (C) 2009, 2013 Richard Kettlewell
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 /** @file lib/uaudio.h
20 * @brief Uniform audio interface
26 extern int uaudio_rate;
27 extern int uaudio_bits;
28 extern int uaudio_channels;
29 extern int uaudio_signed;
30 extern size_t uaudio_sample_size;
31 extern int uaudio_buffer;
33 /** @brief Callback to get audio data
34 * @param buffer Where to put audio data
35 * @param max_samples How many samples to supply
36 * @param userdata As passed to uaudio_open()
37 * @return Number of samples filled
39 * This function should not block if possible (better to fill the buffer with
40 * 0s) and should definitely not block indefinitely. This great caution with
41 * any locks or syscalls! In particular avoid it taking a lock that may be
42 * held while any of the @ref uaudio members are called.
44 * If it's more convenient, it's OK to return less than the maximum number of
45 * samples (including 0) provided you expect to be called again for more
46 * samples immediately.
48 typedef size_t uaudio_callback(void *buffer,
52 /** @brief Callback to play audio data
53 * @param buffer Pointer to audio buffer
54 * @param samples Number of samples to play
55 * @param flags Flags word
56 * @return Number of samples played
58 * Used with uaudio_thread_start() etc.
60 * @p flags is a bitmap giving the current pause state and transitions:
61 * - @ref UAUDIO_PAUSE if this is the first call of a pause
62 * - @ref UAUDIO_RESUME if this is the first call of a resumse
63 * - @ref UAUDIO_PLAYING if this is outside a pause
64 * - @ref UAUDIO_PAUSED if this is in a pause
66 * During a pause, the sample data is guaranteed to be 0.
68 typedef size_t uaudio_playcallback(void *buffer, size_t samples,
71 /** @brief Start of a pause */
72 #define UAUDIO_PAUSE 0x0001
74 /** @brief End of a pause */
75 #define UAUDIO_RESUME 0x0002
77 /** @brief Currently playing */
78 #define UAUDIO_PLAYING 0x0004
80 /** @brief Currently paused */
81 #define UAUDIO_PAUSED 0x0008
83 /** @brief Audio API definition */
85 /** @brief Name of this API */
88 /** @brief List of options, terminated by NULL */
89 const char *const *options;
91 /** @brief Do slow setup
92 * @param ua Handle returned by uaudio_open()
93 * @param callback Called for audio data
94 * @param userdata Passed to @p callback
96 * This does resource-intensive setup for the output device.
98 * For instance it might open mixable audio devices or network sockets. It
99 * will create any background thread required. However, it must not exclude
100 * other processes from outputting sound.
102 void (*start)(uaudio_callback *callback,
106 * @param ua Handle returned by uaudio_open()
108 * This undoes the effect of @c start.
112 /** @brief Enable output
114 * A background thread will start calling @c callback as set by @c
115 * start and playing the audio data received from it.
117 void (*activate)(void);
119 /** @brief Disable output
121 * The background thread will stop calling @c callback.
123 void (*deactivate)(void);
125 /** @brief Open mixer device */
126 void (*open_mixer)(void);
128 /** @brief Closer mixer device */
129 void (*close_mixer)(void);
131 /** @brief Get volume
132 * @param left Where to put the left-channel value
133 * @param right Where to put the right-channel value
135 * 0 is silent and 100 is maximum volume.
137 void (*get_volume)(int *left, int *right);
139 /** @brief Set volume
140 * @param left Pointer to left-channel value (updated)
141 * @param right Pointer to right-channel value (updated)
143 * The values are updated with those actually set by the underlying system
146 * 0 is silent and 100 is maximum volume.
148 void (*set_volume)(int *left, int *right);
150 /** @brief Set configuration */
151 void (*configure)(void);
155 void uaudio_set_format(int rate, int channels, int samplesize, int signed_);
156 void uaudio_set(const char *name, const char *value);
157 char *uaudio_get(const char *name, const char *default_value);
158 void uaudio_thread_start(uaudio_callback *callback,
160 uaudio_playcallback *playcallback,
165 void uaudio_thread_stop(void);
166 void uaudio_thread_activate(void);
167 void uaudio_thread_deactivate(void);
168 uint32_t uaudio_schedule_sync(void);
169 void uaudio_schedule_sent(size_t nsamples_sent);
170 void uaudio_schedule_init(void);
171 const struct uaudio *uaudio_find(const char *name);
173 extern uint64_t uaudio_schedule_timestamp;
174 extern int uaudio_schedule_reactivated;
176 #if HAVE_COREAUDIO_AUDIOHARDWARE_H
177 extern const struct uaudio uaudio_coreaudio;
180 #if HAVE_ALSA_ASOUNDLIB_H
181 extern const struct uaudio uaudio_alsa;
184 #if HAVE_SYS_SOUNDCARD_H || EMPEG_HOST
185 extern const struct uaudio uaudio_oss;
188 extern const struct uaudio uaudio_rtp;
190 extern const struct uaudio uaudio_command;
192 extern const struct uaudio *const uaudio_apis[];
194 #endif /* UAUDIO_H */