chiark - git - mdw - disorder/blob - lib/uaudio.h

   1 /*
   2  * This file is part of DisOrder.
   3  * Copyright (C) 2009, 2013 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
  26 struct sockaddr_storage;
  27
  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;
  34
  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
  40  *
  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.
  45  *
  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.
  49  */
  50 typedef size_t uaudio_callback(void *buffer,
  51                                size_t max_samples,
  52                                void *userdata);
  53
  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
  59  *
  60  * Used with uaudio_thread_start() etc.
  61  *
  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
  67  *
  68  * During a pause, the sample data is guaranteed to be 0.
  69  */
  70 typedef size_t uaudio_playcallback(void *buffer, size_t samples,
  71                                    unsigned flags);
  72
  73 /** @brief Start of a pause */
  74 #define UAUDIO_PAUSE 0x0001
  75
  76 /** @brief End of a pause */
  77 #define UAUDIO_RESUME 0x0002
  78
  79 /** @brief Currently playing */
  80 #define UAUDIO_PLAYING 0x0004
  81
  82 /** @brief Currently paused */
  83 #define UAUDIO_PAUSED 0x0008
  84
  85 /** @brief Audio API definition */
  86 struct uaudio {
  87   /** @brief Name of this API */
  88   const char *name;
  89
  90   /** @brief List of options, terminated by NULL */
  91   const char *const *options;
  92
  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
  97    *
  98    * This does resource-intensive setup for the output device.
  99    *
 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.
 103    */
 104   void (*start)(uaudio_callback *callback,
 105                 void *userdata);
 106
 107   /** @brief Tear down
 108    * @param ua Handle returned by uaudio_open()
 109    *
 110    * This undoes the effect of @c start.
 111    */
 112   void (*stop)(void);
 113
 114   /** @brief Enable output
 115    *
 116    * A background thread will start calling @c callback as set by @c
 117    * start and playing the audio data received from it.
 118    */
 119   void (*activate)(void);
 120
 121   /** @brief Disable output
 122    *
 123    * The background thread will stop calling @c callback.
 124    */
 125   void (*deactivate)(void);
 126
 127   /** @brief Open mixer device */
 128   void (*open_mixer)(void);
 129
 130   /** @brief Closer mixer device */
 131   void (*close_mixer)(void);
 132
 133   /** @brief Get volume
 134    * @param left Where to put the left-channel value
 135    * @param right Where to put the right-channel value
 136    *
 137    * 0 is silent and 100 is maximum volume.
 138    */
 139   void (*get_volume)(int *left, int *right);
 140
 141   /** @brief Set volume
 142    * @param left Pointer to left-channel value (updated)
 143    * @param right Pointer to right-channel value (updated)
 144    *
 145    * The values are updated with those actually set by the underlying system
 146    * call.
 147    *
 148    * 0 is silent and 100 is maximum volume.
 149    */
 150   void (*set_volume)(int *left, int *right);
 151
 152   /** @brief Set configuration */
 153   void (*configure)(void);
 154
 155   /** @brief Descriptive flags */
 156   unsigned flags;
 157 };
 158
 159 /** @brief API is suitable for clients */
 160 #define UAUDIO_API_CLIENT 0x0001
 161
 162 /** @brief API is suitable for servers */
 163 #define UAUDIO_API_SERVER 0x0002
 164
 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,
 169                          void *userdata,
 170                          uaudio_playcallback *playcallback,
 171                          size_t min,
 172                          size_t max,
 173                          unsigned flags);
 174
 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,
 183                                     unsigned context);
 184
 185 int rtp_add_recipient(const struct sockaddr_storage *sa);
 186 int rtp_remove_recipient(const struct sockaddr_storage *sa);
 187
 188 extern uint64_t uaudio_schedule_timestamp;
 189 extern int uaudio_schedule_reactivated;
 190
 191 #if HAVE_COREAUDIO_AUDIOHARDWARE_H
 192 extern const struct uaudio uaudio_coreaudio;
 193 #endif
 194
 195 #if HAVE_ALSA_ASOUNDLIB_H
 196 extern const struct uaudio uaudio_alsa;
 197 #endif
 198
 199 #if HAVE_SYS_SOUNDCARD_H || EMPEG_HOST
 200 extern const struct uaudio uaudio_oss;
 201 #endif
 202
 203 #if HAVE_PULSEAUDIO
 204 extern const struct uaudio uaudio_pulseaudio;
 205 #endif
 206
 207 extern const struct uaudio uaudio_rtp;
 208
 209 extern const struct uaudio uaudio_command;
 210
 211 extern const struct uaudio *const uaudio_apis[];
 212
 213 #endif /* UAUDIO_H */
 214
 215 /*
 216 Local Variables:
 217 c-basic-offset:2
 218 comment-column:40
 219 fill-column:79
 220 indent-tabs-mode:nil
 221 End:
 222 */