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 struct sockaddr_storage
;
28 extern int uaudio_rate
;
29 extern int uaudio_bits
;
30 extern int uaudio_channels
;
31 extern int uaudio_signed
;
32 extern size_t uaudio_sample_size
;
33 extern int uaudio_buffer
;
35 /** @brief Callback to get audio data
36 * @param buffer Where to put audio data
37 * @param max_samples How many samples to supply
38 * @param userdata As passed to uaudio_open()
39 * @return Number of samples filled
41 * This function should not block if possible (better to fill the buffer with
42 * 0s) and should definitely not block indefinitely. This great caution with
43 * any locks or syscalls! In particular avoid it taking a lock that may be
44 * held while any of the @ref uaudio members are called.
46 * If it's more convenient, it's OK to return less than the maximum number of
47 * samples (including 0) provided you expect to be called again for more
48 * samples immediately.
50 typedef size_t uaudio_callback(void *buffer
,
54 /** @brief Callback to play audio data
55 * @param buffer Pointer to audio buffer
56 * @param samples Number of samples to play
57 * @param flags Flags word
58 * @return Number of samples played
60 * Used with uaudio_thread_start() etc.
62 * @p flags is a bitmap giving the current pause state and transitions:
63 * - @ref UAUDIO_PAUSE if this is the first call of a pause
64 * - @ref UAUDIO_RESUME if this is the first call of a resumse
65 * - @ref UAUDIO_PLAYING if this is outside a pause
66 * - @ref UAUDIO_PAUSED if this is in a pause
68 * During a pause, the sample data is guaranteed to be 0.
70 typedef size_t uaudio_playcallback(void *buffer
, size_t samples
,
73 /** @brief Start of a pause */
74 #define UAUDIO_PAUSE 0x0001
76 /** @brief End of a pause */
77 #define UAUDIO_RESUME 0x0002
79 /** @brief Currently playing */
80 #define UAUDIO_PLAYING 0x0004
82 /** @brief Currently paused */
83 #define UAUDIO_PAUSED 0x0008
85 /** @brief Audio API definition */
87 /** @brief Name of this API */
90 /** @brief List of options, terminated by NULL */
91 const char *const *options
;
93 /** @brief Do slow setup
94 * @param ua Handle returned by uaudio_open()
95 * @param callback Called for audio data
96 * @param userdata Passed to @p callback
98 * This does resource-intensive setup for the output device.
100 * For instance it might open mixable audio devices or network sockets. It
101 * will create any background thread required. However, it must not exclude
102 * other processes from outputting sound.
104 void (*start
)(uaudio_callback
*callback
,
108 * @param ua Handle returned by uaudio_open()
110 * This undoes the effect of @c start.
114 /** @brief Enable output
116 * A background thread will start calling @c callback as set by @c
117 * start and playing the audio data received from it.
119 void (*activate
)(void);
121 /** @brief Disable output
123 * The background thread will stop calling @c callback.
125 void (*deactivate
)(void);
127 /** @brief Open mixer device */
128 void (*open_mixer
)(void);
130 /** @brief Closer mixer device */
131 void (*close_mixer
)(void);
133 /** @brief Get volume
134 * @param left Where to put the left-channel value
135 * @param right Where to put the right-channel value
137 * 0 is silent and 100 is maximum volume.
139 void (*get_volume
)(int *left
, int *right
);
141 /** @brief Set volume
142 * @param left Pointer to left-channel value (updated)
143 * @param right Pointer to right-channel value (updated)
145 * The values are updated with those actually set by the underlying system
148 * 0 is silent and 100 is maximum volume.
150 void (*set_volume
)(int *left
, int *right
);
152 /** @brief Set configuration */
153 void (*configure
)(void);
155 /** @brief Descriptive flags */
159 /** @brief API is suitable for clients */
160 #define UAUDIO_API_CLIENT 0x0001
162 /** @brief API is suitable for servers */
163 #define UAUDIO_API_SERVER 0x0002
165 void uaudio_set_format(int rate
, int channels
, int samplesize
, int signed_
);
166 void uaudio_set(const char *name
, const char *value
);
167 char *uaudio_get(const char *name
, const char *default_value
);
168 void uaudio_thread_start(uaudio_callback
*callback
,
170 uaudio_playcallback
*playcallback
,
175 void uaudio_thread_stop(void);
176 void uaudio_thread_activate(void);
177 void uaudio_thread_deactivate(void);
178 uint32_t uaudio_schedule_sync(void);
179 void uaudio_schedule_sent(size_t nsamples_sent
);
180 void uaudio_schedule_init(void);
181 const struct uaudio
*uaudio_find(const char *name
);
182 const struct uaudio
*uaudio_default(const struct uaudio
*const *apis
,
185 int rtp_add_recipient(const struct sockaddr_storage
*sa
);
186 int rtp_remove_recipient(const struct sockaddr_storage
*sa
);
188 extern uint64_t uaudio_schedule_timestamp
;
189 extern int uaudio_schedule_reactivated
;
191 #if HAVE_COREAUDIO_AUDIOHARDWARE_H
192 extern const struct uaudio uaudio_coreaudio
;
195 #if HAVE_ALSA_ASOUNDLIB_H
196 extern const struct uaudio uaudio_alsa
;
199 #if HAVE_SYS_SOUNDCARD_H || EMPEG_HOST
200 extern const struct uaudio uaudio_oss
;
204 extern const struct uaudio uaudio_pulseaudio
;
207 extern const struct uaudio uaudio_rtp
;
209 extern const struct uaudio uaudio_command
;
211 extern const struct uaudio
*const uaudio_apis
[];
213 #endif /* UAUDIO_H */