1 #ifndef PORT_AUDIO_H 2 #define PORT_AUDIO_H 3 4 #ifdef __cplusplus 5 extern "C" { 6 #endif /* __cplusplus */ 7 8 /* 9 * PortAudio Portable Real-Time Audio Library 10 * PortAudio API Header File 11 * Latest version available at: http://www.audiomulch.com/portaudio/ 12 * 13 * Copyright (c) 1999-2000 Ross Bencina and Phil Burk 14 * 15 * Permission is hereby granted, free of charge, to any person obtaining 16 * a copy of this software and associated documentation files 17 * (the "Software"), to deal in the Software without restriction, 18 * including without limitation the rights to use, copy, modify, merge, 19 * publish, distribute, sublicense, and/or sell copies of the Software, 20 * and to permit persons to whom the Software is furnished to do so, 21 * subject to the following conditions: 22 * 23 * The above copyright notice and this permission notice shall be 24 * included in all copies or substantial portions of the Software. 25 * 26 * Any person wishing to distribute modifications to the Software is 27 * requested to send the modifications to the original developer so that 28 * they can be incorporated into the canonical version. 29 * 30 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 31 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 32 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 33 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR 34 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 35 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 36 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 37 * 38 */ 39 40 typedef int PaError; 41 typedef enum { 42 paNoError = 0, 43 44 paHostError = -10000, 45 paInvalidChannelCount, 46 paInvalidSampleRate, 47 paInvalidDeviceId, 48 paInvalidFlag, 49 paSampleFormatNotSupported, 50 paBadIODeviceCombination, 51 paInsufficientMemory, 52 paBufferTooBig, 53 paBufferTooSmall, 54 paNullCallback, 55 paBadStreamPtr, 56 paTimedOut, 57 paInternalError 58 } PaErrorNum; 59 60 /* 61 Pa_Initialize() is the library initialisation function - call this before 62 using the library. 63 */ 64 65 PaError Pa_Initialize( void ); 66 67 /* 68 Pa_Terminate() is the library termination function - call this after 69 using the library. 70 */ 71 72 PaError Pa_Terminate( void ); 73 74 /* 75 Return host specific error. 76 This can be called after receiving a paHostError. 77 */ 78 long Pa_GetHostError( void ); 79 80 /* 81 Translate the error number into a human readable message. 82 */ 83 const char *Pa_GetErrorText( PaError errnum ); 84 85 /* 86 Sample formats 87 88 These are formats used to pass sound data between the callback and the 89 stream. Each device has a "native" format which may be used when optimum 90 efficiency or control over conversion is required. 91 92 Formats marked "always available" are supported (emulated) by all devices. 93 94 The floating point representation uses +1.0 and -1.0 as the respective 95 maximum and minimum. 96 97 */ 98 99 typedef unsigned long PaSampleFormat; 100 #define paFloat32 ((PaSampleFormat) (1<<0)) /*always available*/ 101 #define paInt16 ((PaSampleFormat) (1<<1)) /*always available*/ 102 #define paInt32 ((PaSampleFormat) (1<<2)) /*always available*/ 103 #define paInt24 ((PaSampleFormat) (1<<3)) 104 #define paPackedInt24 ((PaSampleFormat) (1<<4)) 105 #define paInt8 ((PaSampleFormat) (1<<5)) 106 #define paUInt8 ((PaSampleFormat) (1<<6)) /* unsigned 8 bit, 128 is "ground" */ 107 #define paCustomFormat ((PaSampleFormat) (1<<16)) 108 109 /* 110 Device enumeration mechanism. 111 112 Device ids range from 0 to Pa_CountDevices()-1. 113 114 Devices may support input, output or both. Device 0 is always the "default" 115 device and should support at least stereo in and out if that is available 116 on the taget platform _even_ if this involves kludging an input/output 117 device on platforms that usually separate input from output. Other platform 118 specific devices are specified by positive device ids. 119 */ 120 121 typedef int PaDeviceID; 122 #define paNoDevice -1 123 124 typedef struct{ 125 int structVersion; 126 const char *name; 127 int maxInputChannels; 128 int maxOutputChannels; 129 /* Number of discrete rates, or -1 if range supported. */ 130 int numSampleRates; 131 /* Array of supported sample rates, or {min,max} if range supported. */ 132 const double *sampleRates; 133 PaSampleFormat nativeSampleFormats; 134 } PaDeviceInfo; 135 136 137 int Pa_CountDevices(); 138 /* 139 Pa_GetDefaultInputDeviceID(), Pa_GetDefaultOutputDeviceID() 140 141 Return the default device ID or paNoDevice if there is no devices. 142 The result can be passed to Pa_OpenStream(). 143 144 On the PC, the user can specify a default device by 145 setting an environment variable. For example, to use device #1. 146 147 set PA_RECOMMENDED_OUTPUT_DEVICE=1 148 149 The user should first determine the available device ID by using 150 the supplied application "pa_devs". 151 */ 152 PaDeviceID Pa_GetDefaultInputDeviceID( void ); 153 PaDeviceID Pa_GetDefaultOutputDeviceID( void ); 154 155 /* 156 PaTimestamp is used to represent a continuous sample clock with arbitrary 157 start time useful for syncronisation. The type is used in the outTime 158 argument to the callback function and the result of Pa_StreamTime() 159 */ 160 161 typedef double PaTimestamp; 162 163 /* 164 Pa_GetDeviceInfo() returns a pointer to an immutable PaDeviceInfo structure 165 referring to the device specified by id. 166 If id is out of range the function returns NULL. 167 168 The returned structure is owned by the PortAudio implementation and must 169 not be manipulated or freed. The pointer is guaranteed to be valid until 170 between calls to Pa_Initialize() and Pa_Terminate(). 171 */ 172 173 const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceID devID ); 174 175 /* 176 PortAudioCallback is implemented by clients of the portable audio api. 177 178 inputBuffer and outputBuffer are arrays of interleaved samples, 179 the format, packing and number of channels used by the buffers are 180 determined by parameters to Pa_OpenStream() (see below). 181 182 framesPerBuffer is the number of sample frames to be processed by the callback. 183 184 outTime is the time in samples when the buffer(s) processed by 185 this callback will begin being played at the audio output. 186 See also Pa_StreamTime() 187 188 userData is the value of a user supplied pointer passed to Pa_OpenStream() 189 intended for storing synthesis data etc. 190 191 return value: 192 The callback can return a nonzero value to stop the stream. This may be 193 useful in applications such as soundfile players where a specific duration 194 of output is required. However, it is not necessary to utilise this mechanism 195 as StopStream() will also terminate the stream. A callback returning a 196 nonzero value must fill the entire outputBuffer. 197 198 NOTE: None of the other stream functions may be called from within the 199 callback function except for Pa_GetCPULoad(). 200 201 */ 202 203 typedef int (PortAudioCallback)( 204 void *inputBuffer, void *outputBuffer, 205 unsigned long framesPerBuffer, 206 PaTimestamp outTime, void *userData ); 207 208 209 /* 210 Stream flags 211 212 These flags may be supplied (ored together) in the streamFlags argument to 213 the Pa_OpenStream() function. 214 215 [ suggestions? ] 216 */ 217 218 #define paNoFlag (0) 219 #define paClipOff (1<<0) /* disable defult clipping of out of range samples */ 220 #define paDitherOff (1<<1) /* disable default dithering */ 221 #define paPlatformSpecificFlags (0x00010000) 222 typedef unsigned long PaStreamFlags; 223 224 /* 225 A single PortAudioStream provides multiple channels of real-time 226 input and output audio streaming to a client application. 227 Pointers to PortAudioStream objects are passed between PortAudio functions. 228 */ 229 230 typedef void PortAudioStream; 231 #define PaStream PortAudioStream 232 233 /* 234 Pa_OpenStream() opens a stream for either input, output or both. 235 236 stream is the address of a PortAudioStream pointer which will receive 237 a pointer to the newly opened stream. 238 239 inputDevice is the id of the device used for input (see PaDeviceID above.) 240 inputDevice may be paNoDevice to indicate that an input device is not required. 241 242 numInputChannels is the number of channels of sound to be delivered to the 243 callback. It can range from 1 to the value of maxInputChannels in the 244 device input record for the device specified in the inputDevice parameter. 245 If inputDevice is paNoDevice numInputChannels is ignored. 246 247 inputSampleFormat is the format of inputBuffer provided to the callback 248 function. inputSampleFormat may be any of the formats described by the 249 PaSampleFormat enumeration (see above). PortAudio guarantees support for 250 the sound devices native formats (nativeSampleFormats in the device info 251 record) and additionally 16 and 32 bit integer and 32 bit floating point 252 formats. Support for other formats is implementation defined. 253 254 inputDriverInfo is a pointer to an optional driver specific data structure 255 containing additional information for device setup or stream processing. 256 inputDriverInfo is never required for correct operation. If not used 257 inputDriverInfo should be NULL. 258 259 outputDevice is the id of the device used for output (see PaDeviceID above.) 260 outputDevice may be paNoDevice to indicate that an output device is not required. 261 262 numOutputChannels is the number of channels of sound to be supplied by the 263 callback. See the definition of numInputChannels above for more details. 264 265 outputSampleFormat is the sample format of the outputBuffer filled by the 266 callback function. See the definition of inputSampleFormat above for more 267 details. 268 269 outputDriverInfo is a pointer to an optional driver specific data structure 270 containing additional information for device setup or stream processing. 271 outputDriverInfo is never required for correct operation. If not used 272 outputDriverInfo should be NULL. 273 274 sampleRate is the desired sampleRate for input and output 275 276 framesPerBuffer is the length in sample frames of all internal sample buffers 277 used for communication with platform specific audio routines. Wherever 278 possible this corresponds to the framesPerBuffer parameter passed to the 279 callback function. 280 281 numberOfBuffers is the number of buffers used for multibuffered 282 communication with the platform specific audio routines. This parameter is 283 provided only as a guide - and does not imply that an implementation must 284 use multibuffered i/o when reliable double buffering is available (such as 285 SndPlayDoubleBuffer() on the Macintosh.) 286 287 streamFlags may contain a combination of flags ORed together. 288 These flags modify the behavior of the 289 streaming process. Some flags may only be relevant to certain buffer formats. 290 291 callback is a pointer to a client supplied function that is responsible 292 for processing and filling input and output buffers (see above for details.) 293 294 userData is a client supplied pointer which is passed to the callback 295 function. It could for example, contain a pointer to instance data necessary 296 for processing the audio buffers. 297 298 return value: 299 Apon success Pa_OpenStream() returns PaNoError and places a pointer to a 300 valid PortAudioStream in the stream argument. The stream is inactive (stopped). 301 If a call to Pa_OpenStream() fails a nonzero error code is returned (see 302 PAError above) and the value of stream is invalid. 303 304 */ 305 306 PaError Pa_OpenStream( PortAudioStream** stream, 307 PaDeviceID inputDevice, 308 int numInputChannels, 309 PaSampleFormat inputSampleFormat, 310 void *inputDriverInfo, 311 PaDeviceID outputDevice, 312 int numOutputChannels, 313 PaSampleFormat outputSampleFormat, 314 void *outputDriverInfo, 315 double sampleRate, 316 unsigned long framesPerBuffer, 317 unsigned long numberOfBuffers, 318 PaStreamFlags streamFlags, 319 PortAudioCallback *callback, 320 void *userData ); 321 322 323 /* 324 Pa_OpenDefaultStream() is a simplified version of Pa_OpenStream() that 325 opens the default input and/or ouput devices. Most parameters have 326 identical meaning to their Pa_OpenStream() counterparts, with the following 327 exceptions: 328 329 If either numInputChannels or numOutputChannels is 0 the respective device 330 is not opened (same as passing paNoDevice in the device arguments to Pa_OpenStream() ) 331 332 sampleFormat applies to both the input and output buffers. 333 */ 334 335 PaError Pa_OpenDefaultStream( PortAudioStream** stream, 336 int numInputChannels, 337 int numOutputChannels, 338 PaSampleFormat sampleFormat, 339 double sampleRate, 340 unsigned long framesPerBuffer, 341 unsigned long numberOfBuffers, 342 PortAudioCallback *callback, 343 void *userData ); 344 345 /* 346 Pa_CloseStream() closes an audio stream, flushing any pending buffers. 347 */ 348 349 PaError Pa_CloseStream( PortAudioStream* ); 350 351 /* 352 Pa_StartStream() and Pa_StopStream() begin and terminate audio processing. 353 Pa_StopStream() waits until all pending audio buffers have been played. 354 Pa_AbortStream() stops playing immediately without waiting for pending 355 buffers to complete. 356 */ 357 358 PaError Pa_StartStream( PortAudioStream *stream ); 359 360 PaError Pa_StopStream( PortAudioStream *stream ); 361 362 PaError Pa_AbortStream( PortAudioStream *stream ); 363 364 /* 365 Pa_StreamActive() returns one when the stream is playing audio, 366 zero when not playing, or a negative error number if the 367 stream is invalid. 368 The stream is active between calls to Pa_StartStream() and Pa_StopStream(), 369 but may also become inactive if the callback returns a non-zero value. 370 In the latter case, the stream is considered inactive after the last 371 buffer has finished playing. 372 */ 373 374 PaError Pa_StreamActive( PortAudioStream *stream ); 375 376 /* 377 Pa_StreamTime() returns the current output time for the stream in samples. 378 This time may be used as a time reference (for example syncronising audio to 379 MIDI). 380 */ 381 382 PaTimestamp Pa_StreamTime( PortAudioStream *stream ); 383 384 /* 385 The "CPU Load" is a fraction of total CPU time consumed by the 386 stream's audio processing. 387 A value of 0.5 would imply that PortAudio and the sound generating 388 callback was consuming roughly 50% of the available CPU time. 389 This function may be called from the callback function or the application. 390 */ 391 double Pa_GetCPULoad( PortAudioStream* stream ); 392 393 /* 394 Use Pa_GetMinNumBuffers() to determine minimum number of buffers required for 395 the current host based on minimum latency. 396 On the PC, for the DirectSound implementation, latency can be optionally set 397 by user by setting an environment variable. 398 For example, to set latency to 200 msec, put: 399 400 set PA_MIN_LATENCY_MSEC=200 401 402 in the AUTOEXEC.BAT file and reboot. 403 If the environment variable is not set, then the latency will be determined 404 based on the OS. Windows NT has higher latency than Win95. 405 */ 406 407 int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate ); 408 409 /* 410 Sleep for at least 'msec' milliseconds. 411 You may sleep longer than the requested time so don't rely 412 on this for accurate musical timing. 413 */ 414 void Pa_Sleep( long msec ); 415 416 /* 417 Return size in bytes of a single sample in a given PaSampleFormat 418 or paSampleFormatNotSupported. 419 */ 420 PaError Pa_GetSampleSize( PaSampleFormat format ); 421 422 #ifdef __cplusplus 423 } 424 #endif /* __cplusplus */ 425 #endif /* PORT_AUDIO_H */ 426