chiark / gitweb /
Correct setting of rtp-source-port.
[disorder] / lib / uaudio.h
CommitLineData
7a2c7068
RK
1/*
2 * This file is part of DisOrder.
3 * Copyright (C) 2009 Richard Kettlewell
4 *
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.
9 *
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.
14 *
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/>.
17 */
18
19/** @file lib/uaudio.h
20 * @brief Uniform audio interface
21 */
22
23#ifndef UAUDIO_H
24#define UAUDIO_H
25
4fd38868
RK
26extern int uaudio_rate;
27extern int uaudio_bits;
28extern int uaudio_channels;
29extern int uaudio_signed;
30extern size_t uaudio_sample_size;
31
7a2c7068
RK
32/** @brief Callback to get audio data
33 * @param buffer Where to put audio data
34 * @param max_samples How many samples to supply
35 * @param userdata As passed to uaudio_open()
36 * @return Number of samples filled
d4170ca7
RK
37 *
38 * This function should not block if possible (better to fill the buffer with
39 * 0s) and should definitely not block indefinitely. This great caution with
40 * any locks or syscalls! In particular avoid it taking a lock that may be
41 * held while any of the @ref uaudio members are called.
42 *
43 * If it's more convenient, it's OK to return less than the maximum number of
44 * samples (including 0) provided you expect to be called again for more
45 * samples immediately.
7a2c7068 46 */
4fd38868 47typedef size_t uaudio_callback(void *buffer,
7a2c7068
RK
48 size_t max_samples,
49 void *userdata);
50
4fd38868
RK
51/** @brief Callback to play audio data
52 * @param buffer Pointer to audio buffer
53 * @param samples Number of samples to play
54 * @return Number of samples played
55 *
56 * Used with uaudio_thread_start() etc.
57 */
58typedef size_t uaudio_playcallback(void *buffer, size_t samples);
59
7a2c7068
RK
60/** @brief Audio API definition */
61struct uaudio {
62 /** @brief Name of this API */
63 const char *name;
64
65 /** @brief List of options, terminated by NULL */
66 const char *const *options;
67
68 /** @brief Do slow setup
69 * @param ua Handle returned by uaudio_open()
70 * @param callback Called for audio data
71 * @param userdata Passed to @p callback
72 *
73 * This does resource-intensive setup for the output device.
74 *
75 * For instance it might open mixable audio devices or network sockets. It
76 * will create any background thread required. However, it must not exclude
77 * other processes from outputting sound.
78 */
79 void (*start)(uaudio_callback *callback,
80 void *userdata);
81
82 /** @brief Tear down
83 * @param ua Handle returned by uaudio_open()
84 *
85 * This undoes the effect of @c start.
86 */
87 void (*stop)(void);
88
89 /** @brief Enable output
90 *
91 * A background thread will start calling @c callback as set by @c
92 * start and playing the audio data received from it.
93 */
94 void (*activate)(void);
95
96 /** @brief Disable output
97 *
98 * The background thread will stop calling @c callback.
99 */
100 void (*deactivate)(void);
101
b50cfb8a
RK
102 /** @brief Open mixer device */
103 void (*open_mixer)(void);
104
105 /** @brief Closer mixer device */
106 void (*close_mixer)(void);
107
108 /** @brief Get volume
109 * @param left Where to put the left-channel value
110 * @param right Where to put the right-channel value
111 *
112 * 0 is silent and 100 is maximum volume.
113 */
114 void (*get_volume)(int *left, int *right);
115
116 /** @brief Set volume
117 * @param left Pointer to left-channel value (updated)
118 * @param right Pointer to right-channel value (updated)
119 *
120 * The values are updated with those actually set by the underlying system
121 * call.
122 *
123 * 0 is silent and 100 is maximum volume.
124 */
125 void (*set_volume)(int *left, int *right);
ba70caca
RK
126
127 /** @brief Set configuration */
128 void (*configure)(void);
b50cfb8a 129
7a2c7068 130};
4fd38868
RK
131
132void uaudio_set_format(int rate, int channels, int samplesize, int signed_);
7a2c7068 133void uaudio_set(const char *name, const char *value);
b50cfb8a 134char *uaudio_get(const char *name, const char *default_value);
4fd38868
RK
135void uaudio_thread_start(uaudio_callback *callback,
136 void *userdata,
137 uaudio_playcallback *playcallback,
138 size_t min,
63761c19
RK
139 size_t max,
140 unsigned flags);
141
142/** @brief Fake pauses
143 *
144 * This flag is used for audio backends that cannot sensibly be paused.
145 * The thread support code will supply silence while deactivated in this
146 * case.
147 */
148#define UAUDIO_THREAD_FAKE_PAUSE 0x00000001
149
4fd38868
RK
150void uaudio_thread_stop(void);
151void uaudio_thread_activate(void);
152void uaudio_thread_deactivate(void);
ec57f6c9
RK
153void uaudio_schedule_synchronize(void);
154void uaudio_schedule_update(size_t written_samples);
155void uaudio_schedule_init(void);
b50cfb8a 156const struct uaudio *uaudio_find(const char *name);
ec57f6c9
RK
157
158extern uint64_t uaudio_schedule_timestamp;
159extern int uaudio_schedule_reactivated;
7a2c7068
RK
160
161#if HAVE_COREAUDIO_AUDIOHARDWARE_H
162extern const struct uaudio uaudio_coreaudio;
163#endif
164
165#if HAVE_ALSA_ASOUNDLIB_H
166extern const struct uaudio uaudio_alsa;
167#endif
168
169#if HAVE_SYS_SOUNDCARD_H || EMPEG_HOST
170extern const struct uaudio uaudio_oss;
171#endif
172
173extern const struct uaudio uaudio_rtp;
174
66288757 175extern const struct uaudio uaudio_command;
7a2c7068 176
5b053666 177extern const struct uaudio *const uaudio_apis[];
efd23a80 178
7a2c7068
RK
179#endif /* UAUDIO_H */
180
181/*
182Local Variables:
183c-basic-offset:2
184comment-column:40
185fill-column:79
186indent-tabs-mode:nil
187End:
188*/