├── README.md ├── a.wav ├── main.c ├── makefile ├── portaudio.h └── sndfile.h /README.md: -------------------------------------------------------------------------------- 1 | # play ![platform alt](https://img.shields.io/badge/platform-macOS-blue.svg?style=flat) 2 | Play audio files from terminal. 3 | 4 | ![Imgur](https://i.imgur.com/0YHDKpW.png) 5 | 6 | ## Quick Start 7 | 8 | 1. [Download the rep](https://github.com/roecrew/play/archive/master.zip) or clone the rep: git clone ht​tps://git@github.com:maelswarm/play.git 9 | 2. Install the appropriate libraries. 10 | * brew install portaudio 11 | * brew install libsndfile 12 | * brew install glfw3 13 | * brew install glew 14 | 3. make 15 | 4. ./play a.wav 16 | 17 | ## Flags 18 | 19 | -w ... opens visualization window 20 | 21 | -l ... loops audio 22 | 23 | -v ... verbose 24 | 25 | ## Supported Filetypes 26 | 27 | See [http://www.mega-nerd.com/libsndfile/#Features](http://www.mega-nerd.com/libsndfile/#Features) 28 | -------------------------------------------------------------------------------- /a.wav: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/maelswarm/play/8f9e21a155ab9dc0dea16319718250fa35c934e6/a.wav -------------------------------------------------------------------------------- /main.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | #include 5 | #include 6 | #include 7 | #include 8 | #include 9 | #include 10 | #include "portaudio.h" 11 | #include "sndfile.h" 12 | 13 | /* 14 | Data structure to pass to callback 15 | includes the sound file, info about the sound file, and a position 16 | cursor (where we are in the sound file) 17 | */ 18 | 19 | typedef struct SNDData { 20 | SNDFILE *sndFile; 21 | SF_INFO sfInfo; 22 | int position; 23 | } SNDData; 24 | 25 | SNDData *sndData; 26 | 27 | int loop; 28 | int *cursor; 29 | 30 | /* 31 | Callback function for audio output 32 | */ 33 | int Callback(const void *input, 34 | void *output, 35 | unsigned long frameCount, 36 | const PaStreamCallbackTimeInfo* paTimeInfo, 37 | PaStreamCallbackFlags statusFlags, 38 | void *userData) { 39 | 40 | SNDData *data = (SNDData *)userData; /* we passed a data structure 41 | into the callback so we have something to work with */ 42 | /* current pointer into the output */ 43 | int *out = (int *)output; 44 | int thisSize = frameCount; 45 | int thisRead; 46 | 47 | cursor = out; /* set the output cursor to the beginning */ 48 | while (thisSize > 0) { 49 | /* seek to our current file position */ 50 | sf_seek(data->sndFile, data->position, SEEK_SET); 51 | 52 | /* are we going to read past the end of the file?*/ 53 | if (thisSize > (data->sfInfo.frames - data->position) && loop) { 54 | /*if we are, only read to the end of the file*/ 55 | thisRead = data->sfInfo.frames - data->position; 56 | /* and then loop to the beginning of the file */ 57 | data->position = 0; 58 | } else { 59 | /* otherwise, we'll just fill up the rest of the output buffer */ 60 | thisRead = thisSize; 61 | /* and increment the file position */ 62 | data->position += thisRead; 63 | } 64 | 65 | /* since our output format and channel interleaving is the same as 66 | sf_readf_int's requirements */ 67 | /* we'll just read straight into the output buffer */ 68 | sf_readf_int(data->sndFile, cursor, thisRead); 69 | /* increment the output cursor*/ 70 | cursor += thisRead; 71 | /* decrement the number of samples left to process */ 72 | thisSize -= thisRead; 73 | } 74 | return paContinue; 75 | } 76 | 77 | /*******************************************************************/ 78 | 79 | struct vertex { 80 | double x; 81 | double y; 82 | double z; 83 | }; 84 | 85 | struct lines { 86 | struct vertex *vert1; 87 | struct vertex *vert2; 88 | }; 89 | 90 | struct lines **lines = NULL; 91 | 92 | void init() // Called before main loop to set up the program 93 | { 94 | glClearColor(0.0, 0.0, 0.0, 0.0); 95 | glEnable(GL_DEPTH_TEST); 96 | glShadeModel(GL_SMOOTH); 97 | } 98 | 99 | // Called at the start of the program, after a glutPostRedisplay() and during idle 100 | // to display a frame 101 | void display() { 102 | glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 103 | glLoadIdentity(); 104 | 105 | free(lines[0]->vert1); 106 | free(lines[0]->vert2); 107 | free(lines[0]); 108 | 109 | for (int i=1; i<1000; i++) { 110 | lines[i]->vert1->x -= .1f; 111 | lines[i]->vert2->x -= .1f; 112 | lines[i-1] = lines[i]; 113 | 114 | glBegin(GL_LINES); 115 | glVertex3f(lines[i-1]->vert1->x, lines[i-1]->vert1->y, lines[i-1]->vert1->z); 116 | glVertex3f(lines[i-1]->vert2->x,lines[i-1]->vert2->y, lines[i-1]->vert2->z); 117 | glEnd(); 118 | } 119 | lines[999] = malloc(sizeof(struct lines)); 120 | lines[999]->vert1 = malloc(sizeof(struct vertex)); 121 | lines[999]->vert1->x = 49.9; 122 | lines[999]->vert1->y = lines[998]->vert2->y; 123 | lines[999]->vert1->z = -250; 124 | lines[999]->vert2 = malloc(sizeof(struct vertex)); 125 | lines[999]->vert2->x = 50.0; 126 | if (cursor != NULL) { 127 | lines[999]->vert2->y = ((double)*cursor)/(INT_MAX/10.0); 128 | } 129 | lines[999]->vert2->z = -250; 130 | glutSwapBuffers(); 131 | } 132 | 133 | // Called every time a window is resized to resize the projection matrix 134 | void reshape(int w, int h) { 135 | glViewport(0, 0, w, h); 136 | glMatrixMode(GL_PROJECTION); 137 | glLoadIdentity(); 138 | glFrustum(-0.1, 0.1, -1 * (float)h/(10.0*(float)w), (float)h/(10.0*(float)w), 0.5, 1000.0); 139 | glMatrixMode(GL_MODELVIEW); 140 | glLoadIdentity(); 141 | } 142 | 143 | void glLoop() 144 | { 145 | // Update the positions of the objects 146 | // ...... 147 | // ...... 148 | glutPostRedisplay(); 149 | glutTimerFunc(1, glLoop, 0); 150 | } 151 | 152 | int main(int argc, char **argv) 153 | { 154 | loop = 0; 155 | char *filename; 156 | int visualization = 0; 157 | int verbose = 0; 158 | double duration = 0.0f; 159 | 160 | cursor = NULL; 161 | 162 | for (int i=1; ivert1 = malloc(sizeof(struct vertex)); 183 | lines[i]->vert1->x = 0.0; 184 | lines[i]->vert1->y = 0.0; 185 | lines[i]->vert1->z = -500.0; 186 | lines[i]->vert2 = malloc(sizeof(struct vertex)); 187 | lines[i]->vert2->x = 0.0; 188 | lines[i]->vert2->y = 0.0; 189 | lines[i]->vert2->z = -500.0; 190 | } 191 | 192 | sndData = (SNDData *)malloc(sizeof(SNDData)); 193 | PaStream *stream; 194 | PaError error; 195 | PaStreamParameters outputParameters; 196 | 197 | sndData->position = 0; 198 | sndData->sfInfo.format = 0; 199 | sndData->sndFile = sf_open(filename, SFM_READ, &sndData->sfInfo); 200 | 201 | if (!sndData->sndFile) { 202 | printf("error opening file\n"); 203 | return 1; 204 | } 205 | duration = ((double)sndData->sfInfo.frames/(double)sndData->sfInfo.samplerate); 206 | /* start portaudio */ 207 | Pa_Initialize(); 208 | 209 | /* set the output parameters */ 210 | outputParameters.device = Pa_GetDefaultOutputDevice(); /* use the 211 | default device */ 212 | outputParameters.channelCount = sndData->sfInfo.channels; /* use the 213 | same number of channels as our sound file */ 214 | outputParameters.sampleFormat = paInt32; /* 32bit int format */ 215 | outputParameters.suggestedLatency = 0.01; /* 200 ms ought to satisfy 216 | even the worst sound card */ 217 | outputParameters.hostApiSpecificStreamInfo = 0; /* no api specific data */ 218 | 219 | /* try to open the output */ 220 | error = Pa_OpenStream(&stream, /* stream is a 'token' that we need 221 | to save for future portaudio calls */ 222 | 0, /* no input */ 223 | &outputParameters, 224 | sndData->sfInfo.samplerate, /* use the same 225 | sample rate as the sound file */ 226 | paFramesPerBufferUnspecified, /* let 227 | portaudio choose the buffersize */ 228 | paNoFlag, /* no special modes (clip off, dither off) */ 229 | Callback, /* callback function defined above */ 230 | sndData); /* pass in our data structure so the 231 | callback knows what's up */ 232 | 233 | /* if we can't open it, then bail out */ 234 | if (error) 235 | { 236 | printf("error opening output, error code = %i\n", error); 237 | Pa_Terminate(); 238 | return 1; 239 | } 240 | 241 | /* when we start the stream, the callback starts getting called */ 242 | Pa_StartStream(stream); 243 | 244 | if (verbose) { 245 | printf("Filename: %s\n", filename); 246 | printf("Duration: %f seconds\n", duration); 247 | printf("Sample Rate: %d\n", sndData->sfInfo.samplerate); 248 | } 249 | 250 | if (visualization) { 251 | //glutInit(&argc, argv); // Initializes glut 252 | 253 | // Sets up a double buffer with RGBA components and a depth component 254 | glutInitDisplayMode(GLUT_DOUBLE | GLUT_DEPTH | GLUT_RGBA); 255 | 256 | // Sets the window size to 512*512 square pixels 257 | glutInitWindowSize(512, 512); 258 | 259 | // Sets the window position to the upper left 260 | glutInitWindowPosition(0, 0); 261 | // Creates a window using internal glut functionality 262 | glutCreateWindow(filename); 263 | // passes reshape and display functions to the OpenGL machine for callback 264 | glutReshapeFunc(reshape); 265 | glutDisplayFunc(display); 266 | glutIdleFunc(display); 267 | 268 | init(); 269 | 270 | glutTimerFunc(1, glLoop, 0); 271 | // Starts the program. 272 | glutMainLoop(); 273 | } 274 | 275 | if (!visualization && !loop) { 276 | Pa_Sleep(duration*1000.0f); 277 | } else if (!visualization && loop) { 278 | Pa_Sleep(LONG_MAX); 279 | } 280 | 281 | Pa_StopStream(stream); 282 | 283 | return 0; 284 | } 285 | -------------------------------------------------------------------------------- /makefile: -------------------------------------------------------------------------------- 1 | amp: main.c 2 | gcc -std=c11 -o play main.c -framework OpenGL -framework GLUT -L/usr/local/lib -lportaudio -lsndfile 3 | -------------------------------------------------------------------------------- /portaudio.h: -------------------------------------------------------------------------------- 1 | #ifndef PORTAUDIO_H 2 | #define PORTAUDIO_H 3 | /* 4 | * $Id: portaudio.h 1859 2012-09-01 00:10:13Z philburk $ 5 | * PortAudio Portable Real-Time Audio Library 6 | * PortAudio API Header File 7 | * Latest version available at: http://www.portaudio.com/ 8 | * 9 | * Copyright (c) 1999-2002 Ross Bencina and Phil Burk 10 | * 11 | * Permission is hereby granted, free of charge, to any person obtaining 12 | * a copy of this software and associated documentation files 13 | * (the "Software"), to deal in the Software without restriction, 14 | * including without limitation the rights to use, copy, modify, merge, 15 | * publish, distribute, sublicense, and/or sell copies of the Software, 16 | * and to permit persons to whom the Software is furnished to do so, 17 | * subject to the following conditions: 18 | * 19 | * The above copyright notice and this permission notice shall be 20 | * included in all copies or substantial portions of the Software. 21 | * 22 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 23 | * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 24 | * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 25 | * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR 26 | * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 27 | * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 28 | * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 29 | */ 30 | 31 | /* 32 | * The text above constitutes the entire PortAudio license; however, 33 | * the PortAudio community also makes the following non-binding requests: 34 | * 35 | * Any person wishing to distribute modifications to the Software is 36 | * requested to send the modifications to the original developer so that 37 | * they can be incorporated into the canonical version. It is also 38 | * requested that these non-binding requests be included along with the 39 | * license above. 40 | */ 41 | 42 | /** @file 43 | @ingroup public_header 44 | @brief The portable PortAudio API. 45 | */ 46 | 47 | 48 | #ifdef __cplusplus 49 | extern "C" 50 | { 51 | #endif /* __cplusplus */ 52 | 53 | 54 | /** Retrieve the release number of the currently running PortAudio build, 55 | eg 1900. 56 | */ 57 | int Pa_GetVersion( void ); 58 | 59 | 60 | /** Retrieve a textual description of the current PortAudio build, 61 | eg "PortAudio V19-devel 13 October 2002". 62 | */ 63 | const char* Pa_GetVersionText( void ); 64 | 65 | 66 | /** Error codes returned by PortAudio functions. 67 | Note that with the exception of paNoError, all PaErrorCodes are negative. 68 | */ 69 | 70 | typedef int PaError; 71 | typedef enum PaErrorCode 72 | { 73 | paNoError = 0, 74 | 75 | paNotInitialized = -10000, 76 | paUnanticipatedHostError, 77 | paInvalidChannelCount, 78 | paInvalidSampleRate, 79 | paInvalidDevice, 80 | paInvalidFlag, 81 | paSampleFormatNotSupported, 82 | paBadIODeviceCombination, 83 | paInsufficientMemory, 84 | paBufferTooBig, 85 | paBufferTooSmall, 86 | paNullCallback, 87 | paBadStreamPtr, 88 | paTimedOut, 89 | paInternalError, 90 | paDeviceUnavailable, 91 | paIncompatibleHostApiSpecificStreamInfo, 92 | paStreamIsStopped, 93 | paStreamIsNotStopped, 94 | paInputOverflowed, 95 | paOutputUnderflowed, 96 | paHostApiNotFound, 97 | paInvalidHostApi, 98 | paCanNotReadFromACallbackStream, 99 | paCanNotWriteToACallbackStream, 100 | paCanNotReadFromAnOutputOnlyStream, 101 | paCanNotWriteToAnInputOnlyStream, 102 | paIncompatibleStreamHostApi, 103 | paBadBufferPtr 104 | } PaErrorCode; 105 | 106 | 107 | /** Translate the supplied PortAudio error code into a human readable 108 | message. 109 | */ 110 | const char *Pa_GetErrorText( PaError errorCode ); 111 | 112 | 113 | /** Library initialization function - call this before using PortAudio. 114 | This function initializes internal data structures and prepares underlying 115 | host APIs for use. With the exception of Pa_GetVersion(), Pa_GetVersionText(), 116 | and Pa_GetErrorText(), this function MUST be called before using any other 117 | PortAudio API functions. 118 | 119 | If Pa_Initialize() is called multiple times, each successful 120 | call must be matched with a corresponding call to Pa_Terminate(). 121 | Pairs of calls to Pa_Initialize()/Pa_Terminate() may overlap, and are not 122 | required to be fully nested. 123 | 124 | Note that if Pa_Initialize() returns an error code, Pa_Terminate() should 125 | NOT be called. 126 | 127 | @return paNoError if successful, otherwise an error code indicating the cause 128 | of failure. 129 | 130 | @see Pa_Terminate 131 | */ 132 | PaError Pa_Initialize( void ); 133 | 134 | 135 | /** Library termination function - call this when finished using PortAudio. 136 | This function deallocates all resources allocated by PortAudio since it was 137 | initialized by a call to Pa_Initialize(). In cases where Pa_Initialise() has 138 | been called multiple times, each call must be matched with a corresponding call 139 | to Pa_Terminate(). The final matching call to Pa_Terminate() will automatically 140 | close any PortAudio streams that are still open. 141 | 142 | Pa_Terminate() MUST be called before exiting a program which uses PortAudio. 143 | Failure to do so may result in serious resource leaks, such as audio devices 144 | not being available until the next reboot. 145 | 146 | @return paNoError if successful, otherwise an error code indicating the cause 147 | of failure. 148 | 149 | @see Pa_Initialize 150 | */ 151 | PaError Pa_Terminate( void ); 152 | 153 | 154 | 155 | /** The type used to refer to audio devices. Values of this type usually 156 | range from 0 to (Pa_GetDeviceCount()-1), and may also take on the PaNoDevice 157 | and paUseHostApiSpecificDeviceSpecification values. 158 | 159 | @see Pa_GetDeviceCount, paNoDevice, paUseHostApiSpecificDeviceSpecification 160 | */ 161 | typedef int PaDeviceIndex; 162 | 163 | 164 | /** A special PaDeviceIndex value indicating that no device is available, 165 | or should be used. 166 | 167 | @see PaDeviceIndex 168 | */ 169 | #define paNoDevice ((PaDeviceIndex)-1) 170 | 171 | 172 | /** A special PaDeviceIndex value indicating that the device(s) to be used 173 | are specified in the host api specific stream info structure. 174 | 175 | @see PaDeviceIndex 176 | */ 177 | #define paUseHostApiSpecificDeviceSpecification ((PaDeviceIndex)-2) 178 | 179 | 180 | /* Host API enumeration mechanism */ 181 | 182 | /** The type used to enumerate to host APIs at runtime. Values of this type 183 | range from 0 to (Pa_GetHostApiCount()-1). 184 | 185 | @see Pa_GetHostApiCount 186 | */ 187 | typedef int PaHostApiIndex; 188 | 189 | 190 | /** Retrieve the number of available host APIs. Even if a host API is 191 | available it may have no devices available. 192 | 193 | @return A non-negative value indicating the number of available host APIs 194 | or, a PaErrorCode (which are always negative) if PortAudio is not initialized 195 | or an error is encountered. 196 | 197 | @see PaHostApiIndex 198 | */ 199 | PaHostApiIndex Pa_GetHostApiCount( void ); 200 | 201 | 202 | /** Retrieve the index of the default host API. The default host API will be 203 | the lowest common denominator host API on the current platform and is 204 | unlikely to provide the best performance. 205 | 206 | @return A non-negative value ranging from 0 to (Pa_GetHostApiCount()-1) 207 | indicating the default host API index or, a PaErrorCode (which are always 208 | negative) if PortAudio is not initialized or an error is encountered. 209 | */ 210 | PaHostApiIndex Pa_GetDefaultHostApi( void ); 211 | 212 | 213 | /** Unchanging unique identifiers for each supported host API. This type 214 | is used in the PaHostApiInfo structure. The values are guaranteed to be 215 | unique and to never change, thus allowing code to be written that 216 | conditionally uses host API specific extensions. 217 | 218 | New type ids will be allocated when support for a host API reaches 219 | "public alpha" status, prior to that developers should use the 220 | paInDevelopment type id. 221 | 222 | @see PaHostApiInfo 223 | */ 224 | typedef enum PaHostApiTypeId 225 | { 226 | paInDevelopment=0, /* use while developing support for a new host API */ 227 | paDirectSound=1, 228 | paMME=2, 229 | paASIO=3, 230 | paSoundManager=4, 231 | paCoreAudio=5, 232 | paOSS=7, 233 | paALSA=8, 234 | paAL=9, 235 | paBeOS=10, 236 | paWDMKS=11, 237 | paJACK=12, 238 | paWASAPI=13, 239 | paAudioScienceHPI=14 240 | } PaHostApiTypeId; 241 | 242 | 243 | /** A structure containing information about a particular host API. */ 244 | 245 | typedef struct PaHostApiInfo 246 | { 247 | /** this is struct version 1 */ 248 | int structVersion; 249 | /** The well known unique identifier of this host API @see PaHostApiTypeId */ 250 | PaHostApiTypeId type; 251 | /** A textual description of the host API for display on user interfaces. */ 252 | const char *name; 253 | 254 | /** The number of devices belonging to this host API. This field may be 255 | used in conjunction with Pa_HostApiDeviceIndexToDeviceIndex() to enumerate 256 | all devices for this host API. 257 | @see Pa_HostApiDeviceIndexToDeviceIndex 258 | */ 259 | int deviceCount; 260 | 261 | /** The default input device for this host API. The value will be a 262 | device index ranging from 0 to (Pa_GetDeviceCount()-1), or paNoDevice 263 | if no default input device is available. 264 | */ 265 | PaDeviceIndex defaultInputDevice; 266 | 267 | /** The default output device for this host API. The value will be a 268 | device index ranging from 0 to (Pa_GetDeviceCount()-1), or paNoDevice 269 | if no default output device is available. 270 | */ 271 | PaDeviceIndex defaultOutputDevice; 272 | 273 | } PaHostApiInfo; 274 | 275 | 276 | /** Retrieve a pointer to a structure containing information about a specific 277 | host Api. 278 | 279 | @param hostApi A valid host API index ranging from 0 to (Pa_GetHostApiCount()-1) 280 | 281 | @return A pointer to an immutable PaHostApiInfo structure describing 282 | a specific host API. If the hostApi parameter is out of range or an error 283 | is encountered, the function returns NULL. 284 | 285 | The returned structure is owned by the PortAudio implementation and must not 286 | be manipulated or freed. The pointer is only guaranteed to be valid between 287 | calls to Pa_Initialize() and Pa_Terminate(). 288 | */ 289 | const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi ); 290 | 291 | 292 | /** Convert a static host API unique identifier, into a runtime 293 | host API index. 294 | 295 | @param type A unique host API identifier belonging to the PaHostApiTypeId 296 | enumeration. 297 | 298 | @return A valid PaHostApiIndex ranging from 0 to (Pa_GetHostApiCount()-1) or, 299 | a PaErrorCode (which are always negative) if PortAudio is not initialized 300 | or an error is encountered. 301 | 302 | The paHostApiNotFound error code indicates that the host API specified by the 303 | type parameter is not available. 304 | 305 | @see PaHostApiTypeId 306 | */ 307 | PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type ); 308 | 309 | 310 | /** Convert a host-API-specific device index to standard PortAudio device index. 311 | This function may be used in conjunction with the deviceCount field of 312 | PaHostApiInfo to enumerate all devices for the specified host API. 313 | 314 | @param hostApi A valid host API index ranging from 0 to (Pa_GetHostApiCount()-1) 315 | 316 | @param hostApiDeviceIndex A valid per-host device index in the range 317 | 0 to (Pa_GetHostApiInfo(hostApi)->deviceCount-1) 318 | 319 | @return A non-negative PaDeviceIndex ranging from 0 to (Pa_GetDeviceCount()-1) 320 | or, a PaErrorCode (which are always negative) if PortAudio is not initialized 321 | or an error is encountered. 322 | 323 | A paInvalidHostApi error code indicates that the host API index specified by 324 | the hostApi parameter is out of range. 325 | 326 | A paInvalidDevice error code indicates that the hostApiDeviceIndex parameter 327 | is out of range. 328 | 329 | @see PaHostApiInfo 330 | */ 331 | PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi, 332 | int hostApiDeviceIndex ); 333 | 334 | 335 | 336 | /** Structure used to return information about a host error condition. 337 | */ 338 | typedef struct PaHostErrorInfo{ 339 | PaHostApiTypeId hostApiType; /**< the host API which returned the error code */ 340 | long errorCode; /**< the error code returned */ 341 | const char *errorText; /**< a textual description of the error if available, otherwise a zero-length string */ 342 | }PaHostErrorInfo; 343 | 344 | 345 | /** Return information about the last host error encountered. The error 346 | information returned by Pa_GetLastHostErrorInfo() will never be modified 347 | asynchronously by errors occurring in other PortAudio owned threads 348 | (such as the thread that manages the stream callback.) 349 | 350 | This function is provided as a last resort, primarily to enhance debugging 351 | by providing clients with access to all available error information. 352 | 353 | @return A pointer to an immutable structure constraining information about 354 | the host error. The values in this structure will only be valid if a 355 | PortAudio function has previously returned the paUnanticipatedHostError 356 | error code. 357 | */ 358 | const PaHostErrorInfo* Pa_GetLastHostErrorInfo( void ); 359 | 360 | 361 | 362 | /* Device enumeration and capabilities */ 363 | 364 | /** Retrieve the number of available devices. The number of available devices 365 | may be zero. 366 | 367 | @return A non-negative value indicating the number of available devices or, 368 | a PaErrorCode (which are always negative) if PortAudio is not initialized 369 | or an error is encountered. 370 | */ 371 | PaDeviceIndex Pa_GetDeviceCount( void ); 372 | 373 | 374 | /** Retrieve the index of the default input device. The result can be 375 | used in the inputDevice parameter to Pa_OpenStream(). 376 | 377 | @return The default input device index for the default host API, or paNoDevice 378 | if no default input device is available or an error was encountered. 379 | */ 380 | PaDeviceIndex Pa_GetDefaultInputDevice( void ); 381 | 382 | 383 | /** Retrieve the index of the default output device. The result can be 384 | used in the outputDevice parameter to Pa_OpenStream(). 385 | 386 | @return The default output device index for the default host API, or paNoDevice 387 | if no default output device is available or an error was encountered. 388 | 389 | @note 390 | On the PC, the user can specify a default device by 391 | setting an environment variable. For example, to use device #1. 392 | 
 393 |  set PA_RECOMMENDED_OUTPUT_DEVICE=1
 394 |
395 | The user should first determine the available device ids by using 396 | the supplied application "pa_devs". 397 | */ 398 | PaDeviceIndex Pa_GetDefaultOutputDevice( void ); 399 | 400 | 401 | /** The type used to represent monotonic time in seconds. PaTime is 402 | used for the fields of the PaStreamCallbackTimeInfo argument to the 403 | PaStreamCallback and as the result of Pa_GetStreamTime(). 404 | 405 | PaTime values have unspecified origin. 406 | 407 | @see PaStreamCallback, PaStreamCallbackTimeInfo, Pa_GetStreamTime 408 | */ 409 | typedef double PaTime; 410 | 411 | 412 | /** A type used to specify one or more sample formats. Each value indicates 413 | a possible format for sound data passed to and from the stream callback, 414 | Pa_ReadStream and Pa_WriteStream. 415 | 416 | The standard formats paFloat32, paInt16, paInt32, paInt24, paInt8 417 | and aUInt8 are usually implemented by all implementations. 418 | 419 | The floating point representation (paFloat32) uses +1.0 and -1.0 as the 420 | maximum and minimum respectively. 421 | 422 | paUInt8 is an unsigned 8 bit format where 128 is considered "ground" 423 | 424 | The paNonInterleaved flag indicates that audio data is passed as an array 425 | of pointers to separate buffers, one buffer for each channel. Usually, 426 | when this flag is not used, audio data is passed as a single buffer with 427 | all channels interleaved. 428 | 429 | @see Pa_OpenStream, Pa_OpenDefaultStream, PaDeviceInfo 430 | @see paFloat32, paInt16, paInt32, paInt24, paInt8 431 | @see paUInt8, paCustomFormat, paNonInterleaved 432 | */ 433 | typedef unsigned long PaSampleFormat; 434 | 435 | 436 | #define paFloat32 ((PaSampleFormat) 0x00000001) /**< @see PaSampleFormat */ 437 | #define paInt32 ((PaSampleFormat) 0x00000002) /**< @see PaSampleFormat */ 438 | #define paInt24 ((PaSampleFormat) 0x00000004) /**< Packed 24 bit format. @see PaSampleFormat */ 439 | #define paInt16 ((PaSampleFormat) 0x00000008) /**< @see PaSampleFormat */ 440 | #define paInt8 ((PaSampleFormat) 0x00000010) /**< @see PaSampleFormat */ 441 | #define paUInt8 ((PaSampleFormat) 0x00000020) /**< @see PaSampleFormat */ 442 | #define paCustomFormat ((PaSampleFormat) 0x00010000) /**< @see PaSampleFormat */ 443 | 444 | #define paNonInterleaved ((PaSampleFormat) 0x80000000) /**< @see PaSampleFormat */ 445 | 446 | /** A structure providing information and capabilities of PortAudio devices. 447 | Devices may support input, output or both input and output. 448 | */ 449 | typedef struct PaDeviceInfo 450 | { 451 | int structVersion; /* this is struct version 2 */ 452 | const char *name; 453 | PaHostApiIndex hostApi; /**< note this is a host API index, not a type id*/ 454 | 455 | int maxInputChannels; 456 | int maxOutputChannels; 457 | 458 | /** Default latency values for interactive performance. */ 459 | PaTime defaultLowInputLatency; 460 | PaTime defaultLowOutputLatency; 461 | /** Default latency values for robust non-interactive applications (eg. playing sound files). */ 462 | PaTime defaultHighInputLatency; 463 | PaTime defaultHighOutputLatency; 464 | 465 | double defaultSampleRate; 466 | } PaDeviceInfo; 467 | 468 | 469 | /** Retrieve a pointer to a PaDeviceInfo structure containing information 470 | about the specified device. 471 | @return A pointer to an immutable PaDeviceInfo structure. If the device 472 | parameter is out of range the function returns NULL. 473 | 474 | @param device A valid device index in the range 0 to (Pa_GetDeviceCount()-1) 475 | 476 | @note PortAudio manages the memory referenced by the returned pointer, 477 | the client must not manipulate or free the memory. The pointer is only 478 | guaranteed to be valid between calls to Pa_Initialize() and Pa_Terminate(). 479 | 480 | @see PaDeviceInfo, PaDeviceIndex 481 | */ 482 | const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device ); 483 | 484 | 485 | /** Parameters for one direction (input or output) of a stream. 486 | */ 487 | typedef struct PaStreamParameters 488 | { 489 | /** A valid device index in the range 0 to (Pa_GetDeviceCount()-1) 490 | specifying the device to be used or the special constant 491 | paUseHostApiSpecificDeviceSpecification which indicates that the actual 492 | device(s) to use are specified in hostApiSpecificStreamInfo. 493 | This field must not be set to paNoDevice. 494 | */ 495 | PaDeviceIndex device; 496 | 497 | /** The number of channels of sound to be delivered to the 498 | stream callback or accessed by Pa_ReadStream() or Pa_WriteStream(). 499 | It can range from 1 to the value of maxInputChannels in the 500 | PaDeviceInfo record for the device specified by the device parameter. 501 | */ 502 | int channelCount; 503 | 504 | /** The sample format of the buffer provided to the stream callback, 505 | a_ReadStream() or Pa_WriteStream(). It may be any of the formats described 506 | by the PaSampleFormat enumeration. 507 | */ 508 | PaSampleFormat sampleFormat; 509 | 510 | /** The desired latency in seconds. Where practical, implementations should 511 | configure their latency based on these parameters, otherwise they may 512 | choose the closest viable latency instead. Unless the suggested latency 513 | is greater than the absolute upper limit for the device implementations 514 | should round the suggestedLatency up to the next practical value - ie to 515 | provide an equal or higher latency than suggestedLatency wherever possible. 516 | Actual latency values for an open stream may be retrieved using the 517 | inputLatency and outputLatency fields of the PaStreamInfo structure 518 | returned by Pa_GetStreamInfo(). 519 | @see default*Latency in PaDeviceInfo, *Latency in PaStreamInfo 520 | */ 521 | PaTime suggestedLatency; 522 | 523 | /** An optional pointer to a host api specific data structure 524 | containing additional information for device setup and/or stream processing. 525 | hostApiSpecificStreamInfo is never required for correct operation, 526 | if not used it should be set to NULL. 527 | */ 528 | void *hostApiSpecificStreamInfo; 529 | 530 | } PaStreamParameters; 531 | 532 | 533 | /** Return code for Pa_IsFormatSupported indicating success. */ 534 | #define paFormatIsSupported (0) 535 | 536 | /** Determine whether it would be possible to open a stream with the specified 537 | parameters. 538 | 539 | @param inputParameters A structure that describes the input parameters used to 540 | open a stream. The suggestedLatency field is ignored. See PaStreamParameters 541 | for a description of these parameters. inputParameters must be NULL for 542 | output-only streams. 543 | 544 | @param outputParameters A structure that describes the output parameters used 545 | to open a stream. The suggestedLatency field is ignored. See PaStreamParameters 546 | for a description of these parameters. outputParameters must be NULL for 547 | input-only streams. 548 | 549 | @param sampleRate The required sampleRate. For full-duplex streams it is the 550 | sample rate for both input and output 551 | 552 | @return Returns 0 if the format is supported, and an error code indicating why 553 | the format is not supported otherwise. The constant paFormatIsSupported is 554 | provided to compare with the return value for success. 555 | 556 | @see paFormatIsSupported, PaStreamParameters 557 | */ 558 | PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters, 559 | const PaStreamParameters *outputParameters, 560 | double sampleRate ); 561 | 562 | 563 | 564 | /* Streaming types and functions */ 565 | 566 | 567 | /** 568 | A single PaStream can provide multiple channels of real-time 569 | streaming audio input and output to a client application. A stream 570 | provides access to audio hardware represented by one or more 571 | PaDevices. Depending on the underlying Host API, it may be possible 572 | to open multiple streams using the same device, however this behavior 573 | is implementation defined. Portable applications should assume that 574 | a PaDevice may be simultaneously used by at most one PaStream. 575 | 576 | Pointers to PaStream objects are passed between PortAudio functions that 577 | operate on streams. 578 | 579 | @see Pa_OpenStream, Pa_OpenDefaultStream, Pa_OpenDefaultStream, Pa_CloseStream, 580 | Pa_StartStream, Pa_StopStream, Pa_AbortStream, Pa_IsStreamActive, 581 | Pa_GetStreamTime, Pa_GetStreamCpuLoad 582 | 583 | */ 584 | typedef void PaStream; 585 | 586 | 587 | /** Can be passed as the framesPerBuffer parameter to Pa_OpenStream() 588 | or Pa_OpenDefaultStream() to indicate that the stream callback will 589 | accept buffers of any size. 590 | */ 591 | #define paFramesPerBufferUnspecified (0) 592 | 593 | 594 | /** Flags used to control the behavior of a stream. They are passed as 595 | parameters to Pa_OpenStream or Pa_OpenDefaultStream. Multiple flags may be 596 | ORed together. 597 | 598 | @see Pa_OpenStream, Pa_OpenDefaultStream 599 | @see paNoFlag, paClipOff, paDitherOff, paNeverDropInput, 600 | paPrimeOutputBuffersUsingStreamCallback, paPlatformSpecificFlags 601 | */ 602 | typedef unsigned long PaStreamFlags; 603 | 604 | /** @see PaStreamFlags */ 605 | #define paNoFlag ((PaStreamFlags) 0) 606 | 607 | /** Disable default clipping of out of range samples. 608 | @see PaStreamFlags 609 | */ 610 | #define paClipOff ((PaStreamFlags) 0x00000001) 611 | 612 | /** Disable default dithering. 613 | @see PaStreamFlags 614 | */ 615 | #define paDitherOff ((PaStreamFlags) 0x00000002) 616 | 617 | /** Flag requests that where possible a full duplex stream will not discard 618 | overflowed input samples without calling the stream callback. This flag is 619 | only valid for full duplex callback streams and only when used in combination 620 | with the paFramesPerBufferUnspecified (0) framesPerBuffer parameter. Using 621 | this flag incorrectly results in a paInvalidFlag error being returned from 622 | Pa_OpenStream and Pa_OpenDefaultStream. 623 | 624 | @see PaStreamFlags, paFramesPerBufferUnspecified 625 | */ 626 | #define paNeverDropInput ((PaStreamFlags) 0x00000004) 627 | 628 | /** Call the stream callback to fill initial output buffers, rather than the 629 | default behavior of priming the buffers with zeros (silence). This flag has 630 | no effect for input-only and blocking read/write streams. 631 | 632 | @see PaStreamFlags 633 | */ 634 | #define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008) 635 | 636 | /** A mask specifying the platform specific bits. 637 | @see PaStreamFlags 638 | */ 639 | #define paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000) 640 | 641 | /** 642 | Timing information for the buffers passed to the stream callback. 643 | 644 | Time values are expressed in seconds and are synchronised with the time base used by Pa_GetStreamTime() for the associated stream. 645 | 646 | @see PaStreamCallback, Pa_GetStreamTime 647 | */ 648 | typedef struct PaStreamCallbackTimeInfo{ 649 | PaTime inputBufferAdcTime; /**< The time when the first sample of the input buffer was captured at the ADC input */ 650 | PaTime currentTime; /**< The time when the stream callback was invoked */ 651 | PaTime outputBufferDacTime; /**< The time when the first sample of the output buffer will output the DAC */ 652 | } PaStreamCallbackTimeInfo; 653 | 654 | 655 | /** 656 | Flag bit constants for the statusFlags to PaStreamCallback. 657 | 658 | @see paInputUnderflow, paInputOverflow, paOutputUnderflow, paOutputOverflow, 659 | paPrimingOutput 660 | */ 661 | typedef unsigned long PaStreamCallbackFlags; 662 | 663 | /** In a stream opened with paFramesPerBufferUnspecified, indicates that 664 | input data is all silence (zeros) because no real data is available. In a 665 | stream opened without paFramesPerBufferUnspecified, it indicates that one or 666 | more zero samples have been inserted into the input buffer to compensate 667 | for an input underflow. 668 | @see PaStreamCallbackFlags 669 | */ 670 | #define paInputUnderflow ((PaStreamCallbackFlags) 0x00000001) 671 | 672 | /** In a stream opened with paFramesPerBufferUnspecified, indicates that data 673 | prior to the first sample of the input buffer was discarded due to an 674 | overflow, possibly because the stream callback is using too much CPU time. 675 | Otherwise indicates that data prior to one or more samples in the 676 | input buffer was discarded. 677 | @see PaStreamCallbackFlags 678 | */ 679 | #define paInputOverflow ((PaStreamCallbackFlags) 0x00000002) 680 | 681 | /** Indicates that output data (or a gap) was inserted, possibly because the 682 | stream callback is using too much CPU time. 683 | @see PaStreamCallbackFlags 684 | */ 685 | #define paOutputUnderflow ((PaStreamCallbackFlags) 0x00000004) 686 | 687 | /** Indicates that output data will be discarded because no room is available. 688 | @see PaStreamCallbackFlags 689 | */ 690 | #define paOutputOverflow ((PaStreamCallbackFlags) 0x00000008) 691 | 692 | /** Some of all of the output data will be used to prime the stream, input 693 | data may be zero. 694 | @see PaStreamCallbackFlags 695 | */ 696 | #define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010) 697 | 698 | /** 699 | Allowable return values for the PaStreamCallback. 700 | @see PaStreamCallback 701 | */ 702 | typedef enum PaStreamCallbackResult 703 | { 704 | paContinue=0, /**< Signal that the stream should continue invoking the callback and processing audio. */ 705 | paComplete=1, /**< Signal that the stream should stop invoking the callback and finish once all output samples have played. */ 706 | paAbort=2 /**< Signal that the stream should stop invoking the callback and finish as soon as possible. */ 707 | } PaStreamCallbackResult; 708 | 709 | 710 | /** 711 | Functions of type PaStreamCallback are implemented by PortAudio clients. 712 | They consume, process or generate audio in response to requests from an 713 | active PortAudio stream. 714 | 715 | When a stream is running, PortAudio calls the stream callback periodically. 716 | The callback function is responsible for processing buffers of audio samples 717 | passed via the input and output parameters. 718 | 719 | The PortAudio stream callback runs at very high or real-time priority. 720 | It is required to consistently meet its time deadlines. Do not allocate 721 | memory, access the file system, call library functions or call other functions 722 | from the stream callback that may block or take an unpredictable amount of 723 | time to complete. 724 | 725 | In order for a stream to maintain glitch-free operation the callback 726 | must consume and return audio data faster than it is recorded and/or 727 | played. PortAudio anticipates that each callback invocation may execute for 728 | a duration approaching the duration of frameCount audio frames at the stream 729 | sample rate. It is reasonable to expect to be able to utilise 70% or more of 730 | the available CPU time in the PortAudio callback. However, due to buffer size 731 | adaption and other factors, not all host APIs are able to guarantee audio 732 | stability under heavy CPU load with arbitrary fixed callback buffer sizes. 733 | When high callback CPU utilisation is required the most robust behavior 734 | can be achieved by using paFramesPerBufferUnspecified as the 735 | Pa_OpenStream() framesPerBuffer parameter. 736 | 737 | @param input and @param output are either arrays of interleaved samples or; 738 | if non-interleaved samples were requested using the paNonInterleaved sample 739 | format flag, an array of buffer pointers, one non-interleaved buffer for 740 | each channel. 741 | 742 | The format, packing and number of channels used by the buffers are 743 | determined by parameters to Pa_OpenStream(). 744 | 745 | @param frameCount The number of sample frames to be processed by 746 | the stream callback. 747 | 748 | @param timeInfo Timestamps indicating the ADC capture time of the first sample 749 | in the input buffer, the DAC output time of the first sample in the output buffer 750 | and the time the callback was invoked. 751 | See PaStreamCallbackTimeInfo and Pa_GetStreamTime() 752 | 753 | @param statusFlags Flags indicating whether input and/or output buffers 754 | have been inserted or will be dropped to overcome underflow or overflow 755 | conditions. 756 | 757 | @param userData The value of a user supplied pointer passed to 758 | Pa_OpenStream() intended for storing synthesis data etc. 759 | 760 | @return 761 | The stream callback should return one of the values in the 762 | ::PaStreamCallbackResult enumeration. To ensure that the callback continues 763 | to be called, it should return paContinue (0). Either paComplete or paAbort 764 | can be returned to finish stream processing, after either of these values is 765 | returned the callback will not be called again. If paAbort is returned the 766 | stream will finish as soon as possible. If paComplete is returned, the stream 767 | will continue until all buffers generated by the callback have been played. 768 | This may be useful in applications such as soundfile players where a specific 769 | duration of output is required. However, it is not necessary to utilize this 770 | mechanism as Pa_StopStream(), Pa_AbortStream() or Pa_CloseStream() can also 771 | be used to stop the stream. The callback must always fill the entire output 772 | buffer irrespective of its return value. 773 | 774 | @see Pa_OpenStream, Pa_OpenDefaultStream 775 | 776 | @note With the exception of Pa_GetStreamCpuLoad() it is not permissible to call 777 | PortAudio API functions from within the stream callback. 778 | */ 779 | typedef int PaStreamCallback( 780 | const void *input, void *output, 781 | unsigned long frameCount, 782 | const PaStreamCallbackTimeInfo* timeInfo, 783 | PaStreamCallbackFlags statusFlags, 784 | void *userData ); 785 | 786 | 787 | /** Opens a stream for either input, output or both. 788 | 789 | @param stream The address of a PaStream pointer which will receive 790 | a pointer to the newly opened stream. 791 | 792 | @param inputParameters A structure that describes the input parameters used by 793 | the opened stream. See PaStreamParameters for a description of these parameters. 794 | inputParameters must be NULL for output-only streams. 795 | 796 | @param outputParameters A structure that describes the output parameters used by 797 | the opened stream. See PaStreamParameters for a description of these parameters. 798 | outputParameters must be NULL for input-only streams. 799 | 800 | @param sampleRate The desired sampleRate. For full-duplex streams it is the 801 | sample rate for both input and output 802 | 803 | @param framesPerBuffer The number of frames passed to the stream callback 804 | function, or the preferred block granularity for a blocking read/write stream. 805 | The special value paFramesPerBufferUnspecified (0) may be used to request that 806 | the stream callback will receive an optimal (and possibly varying) number of 807 | frames based on host requirements and the requested latency settings. 808 | Note: With some host APIs, the use of non-zero framesPerBuffer for a callback 809 | stream may introduce an additional layer of buffering which could introduce 810 | additional latency. PortAudio guarantees that the additional latency 811 | will be kept to the theoretical minimum however, it is strongly recommended 812 | that a non-zero framesPerBuffer value only be used when your algorithm 813 | requires a fixed number of frames per stream callback. 814 | 815 | @param streamFlags Flags which modify the behavior of the streaming process. 816 | This parameter may contain a combination of flags ORed together. Some flags may 817 | only be relevant to certain buffer formats. 818 | 819 | @param streamCallback A pointer to a client supplied function that is responsible 820 | for processing and filling input and output buffers. If this parameter is NULL 821 | the stream will be opened in 'blocking read/write' mode. In blocking mode, 822 | the client can receive sample data using Pa_ReadStream and write sample data 823 | using Pa_WriteStream, the number of samples that may be read or written 824 | without blocking is returned by Pa_GetStreamReadAvailable and 825 | Pa_GetStreamWriteAvailable respectively. 826 | 827 | @param userData A client supplied pointer which is passed to the stream callback 828 | function. It could for example, contain a pointer to instance data necessary 829 | for processing the audio buffers. This parameter is ignored if streamCallback 830 | is NULL. 831 | 832 | @return 833 | Upon success Pa_OpenStream() returns paNoError and places a pointer to a 834 | valid PaStream in the stream argument. The stream is inactive (stopped). 835 | If a call to Pa_OpenStream() fails, a non-zero error code is returned (see 836 | PaError for possible error codes) and the value of stream is invalid. 837 | 838 | @see PaStreamParameters, PaStreamCallback, Pa_ReadStream, Pa_WriteStream, 839 | Pa_GetStreamReadAvailable, Pa_GetStreamWriteAvailable 840 | */ 841 | PaError Pa_OpenStream( PaStream** stream, 842 | const PaStreamParameters *inputParameters, 843 | const PaStreamParameters *outputParameters, 844 | double sampleRate, 845 | unsigned long framesPerBuffer, 846 | PaStreamFlags streamFlags, 847 | PaStreamCallback *streamCallback, 848 | void *userData ); 849 | 850 | 851 | /** A simplified version of Pa_OpenStream() that opens the default input 852 | and/or output devices. 853 | 854 | @param stream The address of a PaStream pointer which will receive 855 | a pointer to the newly opened stream. 856 | 857 | @param numInputChannels The number of channels of sound that will be supplied 858 | to the stream callback or returned by Pa_ReadStream. It can range from 1 to 859 | the value of maxInputChannels in the PaDeviceInfo record for the default input 860 | device. If 0 the stream is opened as an output-only stream. 861 | 862 | @param numOutputChannels The number of channels of sound to be delivered to the 863 | stream callback or passed to Pa_WriteStream. It can range from 1 to the value 864 | of maxOutputChannels in the PaDeviceInfo record for the default output device. 865 | If 0 the stream is opened as an output-only stream. 866 | 867 | @param sampleFormat The sample format of both the input and output buffers 868 | provided to the callback or passed to and from Pa_ReadStream and Pa_WriteStream. 869 | sampleFormat may be any of the formats described by the PaSampleFormat 870 | enumeration. 871 | 872 | @param sampleRate Same as Pa_OpenStream parameter of the same name. 873 | @param framesPerBuffer Same as Pa_OpenStream parameter of the same name. 874 | @param streamCallback Same as Pa_OpenStream parameter of the same name. 875 | @param userData Same as Pa_OpenStream parameter of the same name. 876 | 877 | @return As for Pa_OpenStream 878 | 879 | @see Pa_OpenStream, PaStreamCallback 880 | */ 881 | PaError Pa_OpenDefaultStream( PaStream** stream, 882 | int numInputChannels, 883 | int numOutputChannels, 884 | PaSampleFormat sampleFormat, 885 | double sampleRate, 886 | unsigned long framesPerBuffer, 887 | PaStreamCallback *streamCallback, 888 | void *userData ); 889 | 890 | 891 | /** Closes an audio stream. If the audio stream is active it 892 | discards any pending buffers as if Pa_AbortStream() had been called. 893 | */ 894 | PaError Pa_CloseStream( PaStream *stream ); 895 | 896 | 897 | /** Functions of type PaStreamFinishedCallback are implemented by PortAudio 898 | clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback 899 | function. Once registered they are called when the stream becomes inactive 900 | (ie once a call to Pa_StopStream() will not block). 901 | A stream will become inactive after the stream callback returns non-zero, 902 | or when Pa_StopStream or Pa_AbortStream is called. For a stream providing audio 903 | output, if the stream callback returns paComplete, or Pa_StopStream is called, 904 | the stream finished callback will not be called until all generated sample data 905 | has been played. 906 | 907 | @param userData The userData parameter supplied to Pa_OpenStream() 908 | 909 | @see Pa_SetStreamFinishedCallback 910 | */ 911 | typedef void PaStreamFinishedCallback( void *userData ); 912 | 913 | 914 | /** Register a stream finished callback function which will be called when the 915 | stream becomes inactive. See the description of PaStreamFinishedCallback for 916 | further details about when the callback will be called. 917 | 918 | @param stream a pointer to a PaStream that is in the stopped state - if the 919 | stream is not stopped, the stream's finished callback will remain unchanged 920 | and an error code will be returned. 921 | 922 | @param streamFinishedCallback a pointer to a function with the same signature 923 | as PaStreamFinishedCallback, that will be called when the stream becomes 924 | inactive. Passing NULL for this parameter will un-register a previously 925 | registered stream finished callback function. 926 | 927 | @return on success returns paNoError, otherwise an error code indicating the cause 928 | of the error. 929 | 930 | @see PaStreamFinishedCallback 931 | */ 932 | PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback ); 933 | 934 | 935 | /** Commences audio processing. 936 | */ 937 | PaError Pa_StartStream( PaStream *stream ); 938 | 939 | 940 | /** Terminates audio processing. It waits until all pending 941 | audio buffers have been played before it returns. 942 | */ 943 | PaError Pa_StopStream( PaStream *stream ); 944 | 945 | 946 | /** Terminates audio processing immediately without waiting for pending 947 | buffers to complete. 948 | */ 949 | PaError Pa_AbortStream( PaStream *stream ); 950 | 951 | 952 | /** Determine whether the stream is stopped. 953 | A stream is considered to be stopped prior to a successful call to 954 | Pa_StartStream and after a successful call to Pa_StopStream or Pa_AbortStream. 955 | If a stream callback returns a value other than paContinue the stream is NOT 956 | considered to be stopped. 957 | 958 | @return Returns one (1) when the stream is stopped, zero (0) when 959 | the stream is running or, a PaErrorCode (which are always negative) if 960 | PortAudio is not initialized or an error is encountered. 961 | 962 | @see Pa_StopStream, Pa_AbortStream, Pa_IsStreamActive 963 | */ 964 | PaError Pa_IsStreamStopped( PaStream *stream ); 965 | 966 | 967 | /** Determine whether the stream is active. 968 | A stream is active after a successful call to Pa_StartStream(), until it 969 | becomes inactive either as a result of a call to Pa_StopStream() or 970 | Pa_AbortStream(), or as a result of a return value other than paContinue from 971 | the stream callback. In the latter case, the stream is considered inactive 972 | after the last buffer has finished playing. 973 | 974 | @return Returns one (1) when the stream is active (ie playing or recording 975 | audio), zero (0) when not playing or, a PaErrorCode (which are always negative) 976 | if PortAudio is not initialized or an error is encountered. 977 | 978 | @see Pa_StopStream, Pa_AbortStream, Pa_IsStreamStopped 979 | */ 980 | PaError Pa_IsStreamActive( PaStream *stream ); 981 | 982 | 983 | 984 | /** A structure containing unchanging information about an open stream. 985 | @see Pa_GetStreamInfo 986 | */ 987 | 988 | typedef struct PaStreamInfo 989 | { 990 | /** this is struct version 1 */ 991 | int structVersion; 992 | 993 | /** The input latency of the stream in seconds. This value provides the most 994 | accurate estimate of input latency available to the implementation. It may 995 | differ significantly from the suggestedLatency value passed to Pa_OpenStream(). 996 | The value of this field will be zero (0.) for output-only streams. 997 | @see PaTime 998 | */ 999 | PaTime inputLatency; 1000 | 1001 | /** The output latency of the stream in seconds. This value provides the most 1002 | accurate estimate of output latency available to the implementation. It may 1003 | differ significantly from the suggestedLatency value passed to Pa_OpenStream(). 1004 | The value of this field will be zero (0.) for input-only streams. 1005 | @see PaTime 1006 | */ 1007 | PaTime outputLatency; 1008 | 1009 | /** The sample rate of the stream in Hertz (samples per second). In cases 1010 | where the hardware sample rate is inaccurate and PortAudio is aware of it, 1011 | the value of this field may be different from the sampleRate parameter 1012 | passed to Pa_OpenStream(). If information about the actual hardware sample 1013 | rate is not available, this field will have the same value as the sampleRate 1014 | parameter passed to Pa_OpenStream(). 1015 | */ 1016 | double sampleRate; 1017 | 1018 | } PaStreamInfo; 1019 | 1020 | 1021 | /** Retrieve a pointer to a PaStreamInfo structure containing information 1022 | about the specified stream. 1023 | @return A pointer to an immutable PaStreamInfo structure. If the stream 1024 | parameter is invalid, or an error is encountered, the function returns NULL. 1025 | 1026 | @param stream A pointer to an open stream previously created with Pa_OpenStream. 1027 | 1028 | @note PortAudio manages the memory referenced by the returned pointer, 1029 | the client must not manipulate or free the memory. The pointer is only 1030 | guaranteed to be valid until the specified stream is closed. 1031 | 1032 | @see PaStreamInfo 1033 | */ 1034 | const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream ); 1035 | 1036 | 1037 | /** Returns the current time in seconds for a stream according to the same clock used 1038 | to generate callback PaStreamCallbackTimeInfo timestamps. The time values are 1039 | monotonically increasing and have unspecified origin. 1040 | 1041 | Pa_GetStreamTime returns valid time values for the entire life of the stream, 1042 | from when the stream is opened until it is closed. Starting and stopping the stream 1043 | does not affect the passage of time returned by Pa_GetStreamTime. 1044 | 1045 | This time may be used for synchronizing other events to the audio stream, for 1046 | example synchronizing audio to MIDI. 1047 | 1048 | @return The stream's current time in seconds, or 0 if an error occurred. 1049 | 1050 | @see PaTime, PaStreamCallback, PaStreamCallbackTimeInfo 1051 | */ 1052 | PaTime Pa_GetStreamTime( PaStream *stream ); 1053 | 1054 | 1055 | /** Retrieve CPU usage information for the specified stream. 1056 | The "CPU Load" is a fraction of total CPU time consumed by a callback stream's 1057 | audio processing routines including, but not limited to the client supplied 1058 | stream callback. This function does not work with blocking read/write streams. 1059 | 1060 | This function may be called from the stream callback function or the 1061 | application. 1062 | 1063 | @return 1064 | A floating point value, typically between 0.0 and 1.0, where 1.0 indicates 1065 | that the stream callback is consuming the maximum number of CPU cycles possible 1066 | to maintain real-time operation. A value of 0.5 would imply that PortAudio and 1067 | the stream callback was consuming roughly 50% of the available CPU time. The 1068 | return value may exceed 1.0. A value of 0.0 will always be returned for a 1069 | blocking read/write stream, or if an error occurs. 1070 | */ 1071 | double Pa_GetStreamCpuLoad( PaStream* stream ); 1072 | 1073 | 1074 | /** Read samples from an input stream. The function doesn't return until 1075 | the entire buffer has been filled - this may involve waiting for the operating 1076 | system to supply the data. 1077 | 1078 | @param stream A pointer to an open stream previously created with Pa_OpenStream. 1079 | 1080 | @param buffer A pointer to a buffer of sample frames. The buffer contains 1081 | samples in the format specified by the inputParameters->sampleFormat field 1082 | used to open the stream, and the number of channels specified by 1083 | inputParameters->numChannels. If non-interleaved samples were requested using 1084 | the paNonInterleaved sample format flag, buffer is a pointer to the first element 1085 | of an array of buffer pointers, one non-interleaved buffer for each channel. 1086 | 1087 | @param frames The number of frames to be read into buffer. This parameter 1088 | is not constrained to a specific range, however high performance applications 1089 | will want to match this parameter to the framesPerBuffer parameter used 1090 | when opening the stream. 1091 | 1092 | @return On success PaNoError will be returned, or PaInputOverflowed if input 1093 | data was discarded by PortAudio after the previous call and before this call. 1094 | */ 1095 | PaError Pa_ReadStream( PaStream* stream, 1096 | void *buffer, 1097 | unsigned long frames ); 1098 | 1099 | 1100 | /** Write samples to an output stream. This function doesn't return until the 1101 | entire buffer has been consumed - this may involve waiting for the operating 1102 | system to consume the data. 1103 | 1104 | @param stream A pointer to an open stream previously created with Pa_OpenStream. 1105 | 1106 | @param buffer A pointer to a buffer of sample frames. The buffer contains 1107 | samples in the format specified by the outputParameters->sampleFormat field 1108 | used to open the stream, and the number of channels specified by 1109 | outputParameters->numChannels. If non-interleaved samples were requested using 1110 | the paNonInterleaved sample format flag, buffer is a pointer to the first element 1111 | of an array of buffer pointers, one non-interleaved buffer for each channel. 1112 | 1113 | @param frames The number of frames to be written from buffer. This parameter 1114 | is not constrained to a specific range, however high performance applications 1115 | will want to match this parameter to the framesPerBuffer parameter used 1116 | when opening the stream. 1117 | 1118 | @return On success PaNoError will be returned, or paOutputUnderflowed if 1119 | additional output data was inserted after the previous call and before this 1120 | call. 1121 | */ 1122 | PaError Pa_WriteStream( PaStream* stream, 1123 | const void *buffer, 1124 | unsigned long frames ); 1125 | 1126 | 1127 | /** Retrieve the number of frames that can be read from the stream without 1128 | waiting. 1129 | 1130 | @return Returns a non-negative value representing the maximum number of frames 1131 | that can be read from the stream without blocking or busy waiting or, a 1132 | PaErrorCode (which are always negative) if PortAudio is not initialized or an 1133 | error is encountered. 1134 | */ 1135 | signed long Pa_GetStreamReadAvailable( PaStream* stream ); 1136 | 1137 | 1138 | /** Retrieve the number of frames that can be written to the stream without 1139 | waiting. 1140 | 1141 | @return Returns a non-negative value representing the maximum number of frames 1142 | that can be written to the stream without blocking or busy waiting or, a 1143 | PaErrorCode (which are always negative) if PortAudio is not initialized or an 1144 | error is encountered. 1145 | */ 1146 | signed long Pa_GetStreamWriteAvailable( PaStream* stream ); 1147 | 1148 | 1149 | /* Miscellaneous utilities */ 1150 | 1151 | 1152 | /** Retrieve the size of a given sample format in bytes. 1153 | 1154 | @return The size in bytes of a single sample in the specified format, 1155 | or paSampleFormatNotSupported if the format is not supported. 1156 | */ 1157 | PaError Pa_GetSampleSize( PaSampleFormat format ); 1158 | 1159 | 1160 | /** Put the caller to sleep for at least 'msec' milliseconds. This function is 1161 | provided only as a convenience for authors of portable code (such as the tests 1162 | and examples in the PortAudio distribution.) 1163 | 1164 | The function may sleep longer than requested so don't rely on this for accurate 1165 | musical timing. 1166 | */ 1167 | void Pa_Sleep( long msec ); 1168 | 1169 | 1170 | 1171 | #ifdef __cplusplus 1172 | } 1173 | #endif /* __cplusplus */ 1174 | #endif /* PORTAUDIO_H */ 1175 | -------------------------------------------------------------------------------- /sndfile.h: -------------------------------------------------------------------------------- 1 | /* 2 | ** Copyright (C) 1999-2016 Erik de Castro Lopo 3 | ** 4 | ** This program is free software; you can redistribute it and/or modify 5 | ** it under the terms of the GNU Lesser General Public License as published by 6 | ** the Free Software Foundation; either version 2.1 of the License, or 7 | ** (at your option) any later version. 8 | ** 9 | ** This program is distributed in the hope that it will be useful, 10 | ** but WITHOUT ANY WARRANTY; without even the implied warranty of 11 | ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 | ** GNU Lesser General Public License for more details. 13 | ** 14 | ** You should have received a copy of the GNU Lesser General Public License 15 | ** along with this program; if not, write to the Free Software 16 | ** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 17 | */ 18 | 19 | /* 20 | ** sndfile.h -- system-wide definitions 21 | ** 22 | ** API documentation is in the doc/ directory of the source code tarball 23 | ** and at http://www.mega-nerd.com/libsndfile/api.html. 24 | */ 25 | 26 | #ifndef SNDFILE_H 27 | #define SNDFILE_H 28 | 29 | /* This is the version 1.0.X header file. */ 30 | #define SNDFILE_1 31 | 32 | #include 33 | #include 34 | #include 35 | 36 | #ifdef __cplusplus 37 | extern "C" { 38 | #endif /* __cplusplus */ 39 | 40 | /* The following file types can be read and written. 41 | ** A file type would consist of a major type (ie SF_FORMAT_WAV) bitwise 42 | ** ORed with a minor type (ie SF_FORMAT_PCM). SF_FORMAT_TYPEMASK and 43 | ** SF_FORMAT_SUBMASK can be used to separate the major and minor file 44 | ** types. 45 | */ 46 | 47 | enum 48 | { /* Major formats. */ 49 | SF_FORMAT_WAV = 0x010000, /* Microsoft WAV format (little endian default). */ 50 | SF_FORMAT_AIFF = 0x020000, /* Apple/SGI AIFF format (big endian). */ 51 | SF_FORMAT_AU = 0x030000, /* Sun/NeXT AU format (big endian). */ 52 | SF_FORMAT_RAW = 0x040000, /* RAW PCM data. */ 53 | SF_FORMAT_PAF = 0x050000, /* Ensoniq PARIS file format. */ 54 | SF_FORMAT_SVX = 0x060000, /* Amiga IFF / SVX8 / SV16 format. */ 55 | SF_FORMAT_NIST = 0x070000, /* Sphere NIST format. */ 56 | SF_FORMAT_VOC = 0x080000, /* VOC files. */ 57 | SF_FORMAT_IRCAM = 0x0A0000, /* Berkeley/IRCAM/CARL */ 58 | SF_FORMAT_W64 = 0x0B0000, /* Sonic Foundry's 64 bit RIFF/WAV */ 59 | SF_FORMAT_MAT4 = 0x0C0000, /* Matlab (tm) V4.2 / GNU Octave 2.0 */ 60 | SF_FORMAT_MAT5 = 0x0D0000, /* Matlab (tm) V5.0 / GNU Octave 2.1 */ 61 | SF_FORMAT_PVF = 0x0E0000, /* Portable Voice Format */ 62 | SF_FORMAT_XI = 0x0F0000, /* Fasttracker 2 Extended Instrument */ 63 | SF_FORMAT_HTK = 0x100000, /* HMM Tool Kit format */ 64 | SF_FORMAT_SDS = 0x110000, /* Midi Sample Dump Standard */ 65 | SF_FORMAT_AVR = 0x120000, /* Audio Visual Research */ 66 | SF_FORMAT_WAVEX = 0x130000, /* MS WAVE with WAVEFORMATEX */ 67 | SF_FORMAT_SD2 = 0x160000, /* Sound Designer 2 */ 68 | SF_FORMAT_FLAC = 0x170000, /* FLAC lossless file format */ 69 | SF_FORMAT_CAF = 0x180000, /* Core Audio File format */ 70 | SF_FORMAT_WVE = 0x190000, /* Psion WVE format */ 71 | SF_FORMAT_OGG = 0x200000, /* Xiph OGG container */ 72 | SF_FORMAT_MPC2K = 0x210000, /* Akai MPC 2000 sampler */ 73 | SF_FORMAT_RF64 = 0x220000, /* RF64 WAV file */ 74 | 75 | /* Subtypes from here on. */ 76 | 77 | SF_FORMAT_PCM_S8 = 0x0001, /* Signed 8 bit data */ 78 | SF_FORMAT_PCM_16 = 0x0002, /* Signed 16 bit data */ 79 | SF_FORMAT_PCM_24 = 0x0003, /* Signed 24 bit data */ 80 | SF_FORMAT_PCM_32 = 0x0004, /* Signed 32 bit data */ 81 | 82 | SF_FORMAT_PCM_U8 = 0x0005, /* Unsigned 8 bit data (WAV and RAW only) */ 83 | 84 | SF_FORMAT_FLOAT = 0x0006, /* 32 bit float data */ 85 | SF_FORMAT_DOUBLE = 0x0007, /* 64 bit float data */ 86 | 87 | SF_FORMAT_ULAW = 0x0010, /* U-Law encoded. */ 88 | SF_FORMAT_ALAW = 0x0011, /* A-Law encoded. */ 89 | SF_FORMAT_IMA_ADPCM = 0x0012, /* IMA ADPCM. */ 90 | SF_FORMAT_MS_ADPCM = 0x0013, /* Microsoft ADPCM. */ 91 | 92 | SF_FORMAT_GSM610 = 0x0020, /* GSM 6.10 encoding. */ 93 | SF_FORMAT_VOX_ADPCM = 0x0021, /* OKI / Dialogix ADPCM */ 94 | 95 | SF_FORMAT_G721_32 = 0x0030, /* 32kbs G721 ADPCM encoding. */ 96 | SF_FORMAT_G723_24 = 0x0031, /* 24kbs G723 ADPCM encoding. */ 97 | SF_FORMAT_G723_40 = 0x0032, /* 40kbs G723 ADPCM encoding. */ 98 | 99 | SF_FORMAT_DWVW_12 = 0x0040, /* 12 bit Delta Width Variable Word encoding. */ 100 | SF_FORMAT_DWVW_16 = 0x0041, /* 16 bit Delta Width Variable Word encoding. */ 101 | SF_FORMAT_DWVW_24 = 0x0042, /* 24 bit Delta Width Variable Word encoding. */ 102 | SF_FORMAT_DWVW_N = 0x0043, /* N bit Delta Width Variable Word encoding. */ 103 | 104 | SF_FORMAT_DPCM_8 = 0x0050, /* 8 bit differential PCM (XI only) */ 105 | SF_FORMAT_DPCM_16 = 0x0051, /* 16 bit differential PCM (XI only) */ 106 | 107 | SF_FORMAT_VORBIS = 0x0060, /* Xiph Vorbis encoding. */ 108 | 109 | SF_FORMAT_ALAC_16 = 0x0070, /* Apple Lossless Audio Codec (16 bit). */ 110 | SF_FORMAT_ALAC_20 = 0x0071, /* Apple Lossless Audio Codec (20 bit). */ 111 | SF_FORMAT_ALAC_24 = 0x0072, /* Apple Lossless Audio Codec (24 bit). */ 112 | SF_FORMAT_ALAC_32 = 0x0073, /* Apple Lossless Audio Codec (32 bit). */ 113 | 114 | /* Endian-ness options. */ 115 | 116 | SF_ENDIAN_FILE = 0x00000000, /* Default file endian-ness. */ 117 | SF_ENDIAN_LITTLE = 0x10000000, /* Force little endian-ness. */ 118 | SF_ENDIAN_BIG = 0x20000000, /* Force big endian-ness. */ 119 | SF_ENDIAN_CPU = 0x30000000, /* Force CPU endian-ness. */ 120 | 121 | SF_FORMAT_SUBMASK = 0x0000FFFF, 122 | SF_FORMAT_TYPEMASK = 0x0FFF0000, 123 | SF_FORMAT_ENDMASK = 0x30000000 124 | } ; 125 | 126 | /* 127 | ** The following are the valid command numbers for the sf_command() 128 | ** interface. The use of these commands is documented in the file 129 | ** command.html in the doc directory of the source code distribution. 130 | */ 131 | 132 | enum 133 | { SFC_GET_LIB_VERSION = 0x1000, 134 | SFC_GET_LOG_INFO = 0x1001, 135 | SFC_GET_CURRENT_SF_INFO = 0x1002, 136 | 137 | 138 | SFC_GET_NORM_DOUBLE = 0x1010, 139 | SFC_GET_NORM_FLOAT = 0x1011, 140 | SFC_SET_NORM_DOUBLE = 0x1012, 141 | SFC_SET_NORM_FLOAT = 0x1013, 142 | SFC_SET_SCALE_FLOAT_INT_READ = 0x1014, 143 | SFC_SET_SCALE_INT_FLOAT_WRITE = 0x1015, 144 | 145 | SFC_GET_SIMPLE_FORMAT_COUNT = 0x1020, 146 | SFC_GET_SIMPLE_FORMAT = 0x1021, 147 | 148 | SFC_GET_FORMAT_INFO = 0x1028, 149 | 150 | SFC_GET_FORMAT_MAJOR_COUNT = 0x1030, 151 | SFC_GET_FORMAT_MAJOR = 0x1031, 152 | SFC_GET_FORMAT_SUBTYPE_COUNT = 0x1032, 153 | SFC_GET_FORMAT_SUBTYPE = 0x1033, 154 | 155 | SFC_CALC_SIGNAL_MAX = 0x1040, 156 | SFC_CALC_NORM_SIGNAL_MAX = 0x1041, 157 | SFC_CALC_MAX_ALL_CHANNELS = 0x1042, 158 | SFC_CALC_NORM_MAX_ALL_CHANNELS = 0x1043, 159 | SFC_GET_SIGNAL_MAX = 0x1044, 160 | SFC_GET_MAX_ALL_CHANNELS = 0x1045, 161 | 162 | SFC_SET_ADD_PEAK_CHUNK = 0x1050, 163 | SFC_SET_ADD_HEADER_PAD_CHUNK = 0x1051, 164 | 165 | SFC_UPDATE_HEADER_NOW = 0x1060, 166 | SFC_SET_UPDATE_HEADER_AUTO = 0x1061, 167 | 168 | SFC_FILE_TRUNCATE = 0x1080, 169 | 170 | SFC_SET_RAW_START_OFFSET = 0x1090, 171 | 172 | SFC_SET_DITHER_ON_WRITE = 0x10A0, 173 | SFC_SET_DITHER_ON_READ = 0x10A1, 174 | 175 | SFC_GET_DITHER_INFO_COUNT = 0x10A2, 176 | SFC_GET_DITHER_INFO = 0x10A3, 177 | 178 | SFC_GET_EMBED_FILE_INFO = 0x10B0, 179 | 180 | SFC_SET_CLIPPING = 0x10C0, 181 | SFC_GET_CLIPPING = 0x10C1, 182 | 183 | SFC_GET_CUE_COUNT = 0x10CD, 184 | SFC_GET_CUE = 0x10CE, 185 | SFC_SET_CUE = 0x10CF, 186 | 187 | SFC_GET_INSTRUMENT = 0x10D0, 188 | SFC_SET_INSTRUMENT = 0x10D1, 189 | 190 | SFC_GET_LOOP_INFO = 0x10E0, 191 | 192 | SFC_GET_BROADCAST_INFO = 0x10F0, 193 | SFC_SET_BROADCAST_INFO = 0x10F1, 194 | 195 | SFC_GET_CHANNEL_MAP_INFO = 0x1100, 196 | SFC_SET_CHANNEL_MAP_INFO = 0x1101, 197 | 198 | SFC_RAW_DATA_NEEDS_ENDSWAP = 0x1110, 199 | 200 | /* Support for Wavex Ambisonics Format */ 201 | SFC_WAVEX_SET_AMBISONIC = 0x1200, 202 | SFC_WAVEX_GET_AMBISONIC = 0x1201, 203 | 204 | /* 205 | ** RF64 files can be set so that on-close, writable files that have less 206 | ** than 4GB of data in them are converted to RIFF/WAV, as per EBU 207 | ** recommendations. 208 | */ 209 | SFC_RF64_AUTO_DOWNGRADE = 0x1210, 210 | 211 | SFC_SET_VBR_ENCODING_QUALITY = 0x1300, 212 | SFC_SET_COMPRESSION_LEVEL = 0x1301, 213 | 214 | /* Cart Chunk support */ 215 | SFC_SET_CART_INFO = 0x1400, 216 | SFC_GET_CART_INFO = 0x1401, 217 | 218 | /* Following commands for testing only. */ 219 | SFC_TEST_IEEE_FLOAT_REPLACE = 0x6001, 220 | 221 | /* 222 | ** SFC_SET_ADD_* values are deprecated and will disappear at some 223 | ** time in the future. They are guaranteed to be here up to and 224 | ** including version 1.0.8 to avoid breakage of existing software. 225 | ** They currently do nothing and will continue to do nothing. 226 | */ 227 | SFC_SET_ADD_DITHER_ON_WRITE = 0x1070, 228 | SFC_SET_ADD_DITHER_ON_READ = 0x1071 229 | } ; 230 | 231 | 232 | /* 233 | ** String types that can be set and read from files. Not all file types 234 | ** support this and even the file types which support one, may not support 235 | ** all string types. 236 | */ 237 | 238 | enum 239 | { SF_STR_TITLE = 0x01, 240 | SF_STR_COPYRIGHT = 0x02, 241 | SF_STR_SOFTWARE = 0x03, 242 | SF_STR_ARTIST = 0x04, 243 | SF_STR_COMMENT = 0x05, 244 | SF_STR_DATE = 0x06, 245 | SF_STR_ALBUM = 0x07, 246 | SF_STR_LICENSE = 0x08, 247 | SF_STR_TRACKNUMBER = 0x09, 248 | SF_STR_GENRE = 0x10 249 | } ; 250 | 251 | /* 252 | ** Use the following as the start and end index when doing metadata 253 | ** transcoding. 254 | */ 255 | 256 | #define SF_STR_FIRST SF_STR_TITLE 257 | #define SF_STR_LAST SF_STR_GENRE 258 | 259 | enum 260 | { /* True and false */ 261 | SF_FALSE = 0, 262 | SF_TRUE = 1, 263 | 264 | /* Modes for opening files. */ 265 | SFM_READ = 0x10, 266 | SFM_WRITE = 0x20, 267 | SFM_RDWR = 0x30, 268 | 269 | SF_AMBISONIC_NONE = 0x40, 270 | SF_AMBISONIC_B_FORMAT = 0x41 271 | } ; 272 | 273 | /* Public error values. These are guaranteed to remain unchanged for the duration 274 | ** of the library major version number. 275 | ** There are also a large number of private error numbers which are internal to 276 | ** the library which can change at any time. 277 | */ 278 | 279 | enum 280 | { SF_ERR_NO_ERROR = 0, 281 | SF_ERR_UNRECOGNISED_FORMAT = 1, 282 | SF_ERR_SYSTEM = 2, 283 | SF_ERR_MALFORMED_FILE = 3, 284 | SF_ERR_UNSUPPORTED_ENCODING = 4 285 | } ; 286 | 287 | 288 | /* Channel map values (used with SFC_SET/GET_CHANNEL_MAP). 289 | */ 290 | 291 | enum 292 | { SF_CHANNEL_MAP_INVALID = 0, 293 | SF_CHANNEL_MAP_MONO = 1, 294 | SF_CHANNEL_MAP_LEFT, /* Apple calls this 'Left' */ 295 | SF_CHANNEL_MAP_RIGHT, /* Apple calls this 'Right' */ 296 | SF_CHANNEL_MAP_CENTER, /* Apple calls this 'Center' */ 297 | SF_CHANNEL_MAP_FRONT_LEFT, 298 | SF_CHANNEL_MAP_FRONT_RIGHT, 299 | SF_CHANNEL_MAP_FRONT_CENTER, 300 | SF_CHANNEL_MAP_REAR_CENTER, /* Apple calls this 'Center Surround', Msft calls this 'Back Center' */ 301 | SF_CHANNEL_MAP_REAR_LEFT, /* Apple calls this 'Left Surround', Msft calls this 'Back Left' */ 302 | SF_CHANNEL_MAP_REAR_RIGHT, /* Apple calls this 'Right Surround', Msft calls this 'Back Right' */ 303 | SF_CHANNEL_MAP_LFE, /* Apple calls this 'LFEScreen', Msft calls this 'Low Frequency' */ 304 | SF_CHANNEL_MAP_FRONT_LEFT_OF_CENTER, /* Apple calls this 'Left Center' */ 305 | SF_CHANNEL_MAP_FRONT_RIGHT_OF_CENTER, /* Apple calls this 'Right Center */ 306 | SF_CHANNEL_MAP_SIDE_LEFT, /* Apple calls this 'Left Surround Direct' */ 307 | SF_CHANNEL_MAP_SIDE_RIGHT, /* Apple calls this 'Right Surround Direct' */ 308 | SF_CHANNEL_MAP_TOP_CENTER, /* Apple calls this 'Top Center Surround' */ 309 | SF_CHANNEL_MAP_TOP_FRONT_LEFT, /* Apple calls this 'Vertical Height Left' */ 310 | SF_CHANNEL_MAP_TOP_FRONT_RIGHT, /* Apple calls this 'Vertical Height Right' */ 311 | SF_CHANNEL_MAP_TOP_FRONT_CENTER, /* Apple calls this 'Vertical Height Center' */ 312 | SF_CHANNEL_MAP_TOP_REAR_LEFT, /* Apple and MS call this 'Top Back Left' */ 313 | SF_CHANNEL_MAP_TOP_REAR_RIGHT, /* Apple and MS call this 'Top Back Right' */ 314 | SF_CHANNEL_MAP_TOP_REAR_CENTER, /* Apple and MS call this 'Top Back Center' */ 315 | 316 | SF_CHANNEL_MAP_AMBISONIC_B_W, 317 | SF_CHANNEL_MAP_AMBISONIC_B_X, 318 | SF_CHANNEL_MAP_AMBISONIC_B_Y, 319 | SF_CHANNEL_MAP_AMBISONIC_B_Z, 320 | 321 | SF_CHANNEL_MAP_MAX 322 | } ; 323 | 324 | 325 | /* A SNDFILE* pointer can be passed around much like stdio.h's FILE* pointer. */ 326 | 327 | typedef struct SNDFILE_tag SNDFILE ; 328 | 329 | /* The following typedef is system specific and is defined when libsndfile is 330 | ** compiled. sf_count_t will be a 64 bit value when the underlying OS allows 331 | ** 64 bit file offsets. 332 | ** On windows, we need to allow the same header file to be compiler by both GCC 333 | ** and the Microsoft compiler. 334 | */ 335 | 336 | #if (defined (_MSCVER) || defined (_MSC_VER) && (_MSC_VER < 1310)) 337 | typedef __int64 sf_count_t ; 338 | #define SF_COUNT_MAX 0x7fffffffffffffffi64 339 | #else 340 | typedef int64_t sf_count_t ; 341 | #define SF_COUNT_MAX 0x7FFFFFFFFFFFFFFFLL 342 | #endif 343 | 344 | 345 | /* A pointer to a SF_INFO structure is passed to sf_open () and filled in. 346 | ** On write, the SF_INFO structure is filled in by the user and passed into 347 | ** sf_open (). 348 | */ 349 | 350 | struct SF_INFO 351 | { sf_count_t frames ; /* Used to be called samples. Changed to avoid confusion. */ 352 | int samplerate ; 353 | int channels ; 354 | int format ; 355 | int sections ; 356 | int seekable ; 357 | } ; 358 | 359 | typedef struct SF_INFO SF_INFO ; 360 | 361 | /* The SF_FORMAT_INFO struct is used to retrieve information about the sound 362 | ** file formats libsndfile supports using the sf_command () interface. 363 | ** 364 | ** Using this interface will allow applications to support new file formats 365 | ** and encoding types when libsndfile is upgraded, without requiring 366 | ** re-compilation of the application. 367 | ** 368 | ** Please consult the libsndfile documentation (particularly the information 369 | ** on the sf_command () interface) for examples of its use. 370 | */ 371 | 372 | typedef struct 373 | { int format ; 374 | const char *name ; 375 | const char *extension ; 376 | } SF_FORMAT_INFO ; 377 | 378 | /* 379 | ** Enums and typedefs for adding dither on read and write. 380 | ** See the html documentation for sf_command(), SFC_SET_DITHER_ON_WRITE 381 | ** and SFC_SET_DITHER_ON_READ. 382 | */ 383 | 384 | enum 385 | { SFD_DEFAULT_LEVEL = 0, 386 | SFD_CUSTOM_LEVEL = 0x40000000, 387 | 388 | SFD_NO_DITHER = 500, 389 | SFD_WHITE = 501, 390 | SFD_TRIANGULAR_PDF = 502 391 | } ; 392 | 393 | typedef struct 394 | { int type ; 395 | double level ; 396 | const char *name ; 397 | } SF_DITHER_INFO ; 398 | 399 | /* Struct used to retrieve information about a file embedded within a 400 | ** larger file. See SFC_GET_EMBED_FILE_INFO. 401 | */ 402 | 403 | typedef struct 404 | { sf_count_t offset ; 405 | sf_count_t length ; 406 | } SF_EMBED_FILE_INFO ; 407 | 408 | /* 409 | ** Struct used to retrieve cue marker information from a file 410 | */ 411 | 412 | typedef struct 413 | { int32_t indx ; 414 | uint32_t position ; 415 | int32_t fcc_chunk ; 416 | int32_t chunk_start ; 417 | int32_t block_start ; 418 | uint32_t sample_offset ; 419 | char name [256] ; 420 | } SF_CUE_POINT ; 421 | 422 | #define SF_CUES_VAR(count) \ 423 | struct \ 424 | { uint32_t cue_count ; \ 425 | SF_CUE_POINT cue_points [count] ; \ 426 | } 427 | 428 | typedef SF_CUES_VAR (100) SF_CUES ; 429 | 430 | /* 431 | ** Structs used to retrieve music sample information from a file. 432 | */ 433 | 434 | enum 435 | { /* 436 | ** The loop mode field in SF_INSTRUMENT will be one of the following. 437 | */ 438 | SF_LOOP_NONE = 800, 439 | SF_LOOP_FORWARD, 440 | SF_LOOP_BACKWARD, 441 | SF_LOOP_ALTERNATING 442 | } ; 443 | 444 | typedef struct 445 | { int gain ; 446 | char basenote, detune ; 447 | char velocity_lo, velocity_hi ; 448 | char key_lo, key_hi ; 449 | int loop_count ; 450 | 451 | struct 452 | { int mode ; 453 | uint32_t start ; 454 | uint32_t end ; 455 | uint32_t count ; 456 | } loops [16] ; /* make variable in a sensible way */ 457 | } SF_INSTRUMENT ; 458 | 459 | 460 | 461 | /* Struct used to retrieve loop information from a file.*/ 462 | typedef struct 463 | { 464 | short time_sig_num ; /* any positive integer > 0 */ 465 | short time_sig_den ; /* any positive power of 2 > 0 */ 466 | int loop_mode ; /* see SF_LOOP enum */ 467 | 468 | int num_beats ; /* this is NOT the amount of quarter notes !!!*/ 469 | /* a full bar of 4/4 is 4 beats */ 470 | /* a full bar of 7/8 is 7 beats */ 471 | 472 | float bpm ; /* suggestion, as it can be calculated using other fields:*/ 473 | /* file's length, file's sampleRate and our time_sig_den*/ 474 | /* -> bpms are always the amount of _quarter notes_ per minute */ 475 | 476 | int root_key ; /* MIDI note, or -1 for None */ 477 | int future [6] ; 478 | } SF_LOOP_INFO ; 479 | 480 | 481 | /* Struct used to retrieve broadcast (EBU) information from a file. 482 | ** Strongly (!) based on EBU "bext" chunk format used in Broadcast WAVE. 483 | */ 484 | #define SF_BROADCAST_INFO_VAR(coding_hist_size) \ 485 | struct \ 486 | { char description [256] ; \ 487 | char originator [32] ; \ 488 | char originator_reference [32] ; \ 489 | char origination_date [10] ; \ 490 | char origination_time [8] ; \ 491 | uint32_t time_reference_low ; \ 492 | uint32_t time_reference_high ; \ 493 | short version ; \ 494 | char umid [64] ; \ 495 | char reserved [190] ; \ 496 | uint32_t coding_history_size ; \ 497 | char coding_history [coding_hist_size] ; \ 498 | } 499 | 500 | /* SF_BROADCAST_INFO is the above struct with coding_history field of 256 bytes. */ 501 | typedef SF_BROADCAST_INFO_VAR (256) SF_BROADCAST_INFO ; 502 | 503 | struct SF_CART_TIMER 504 | { char usage [4] ; 505 | int32_t value ; 506 | } ; 507 | 508 | typedef struct SF_CART_TIMER SF_CART_TIMER ; 509 | 510 | #define SF_CART_INFO_VAR(p_tag_text_size) \ 511 | struct \ 512 | { char version [4] ; \ 513 | char title [64] ; \ 514 | char artist [64] ; \ 515 | char cut_id [64] ; \ 516 | char client_id [64] ; \ 517 | char category [64] ; \ 518 | char classification [64] ; \ 519 | char out_cue [64] ; \ 520 | char start_date [10] ; \ 521 | char start_time [8] ; \ 522 | char end_date [10] ; \ 523 | char end_time [8] ; \ 524 | char producer_app_id [64] ; \ 525 | char producer_app_version [64] ; \ 526 | char user_def [64] ; \ 527 | int32_t level_reference ; \ 528 | SF_CART_TIMER post_timers [8] ; \ 529 | char reserved [276] ; \ 530 | char url [1024] ; \ 531 | uint32_t tag_text_size ; \ 532 | char tag_text [p_tag_text_size] ; \ 533 | } 534 | 535 | typedef SF_CART_INFO_VAR (256) SF_CART_INFO ; 536 | 537 | /* Virtual I/O functionality. */ 538 | 539 | typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ; 540 | typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ; 541 | typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ; 542 | typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ; 543 | typedef sf_count_t (*sf_vio_tell) (void *user_data) ; 544 | 545 | struct SF_VIRTUAL_IO 546 | { sf_vio_get_filelen get_filelen ; 547 | sf_vio_seek seek ; 548 | sf_vio_read read ; 549 | sf_vio_write write ; 550 | sf_vio_tell tell ; 551 | } ; 552 | 553 | typedef struct SF_VIRTUAL_IO SF_VIRTUAL_IO ; 554 | 555 | 556 | /* Open the specified file for read, write or both. On error, this will 557 | ** return a NULL pointer. To find the error number, pass a NULL SNDFILE 558 | ** to sf_strerror (). 559 | ** All calls to sf_open() should be matched with a call to sf_close(). 560 | */ 561 | 562 | SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ; 563 | 564 | 565 | /* Use the existing file descriptor to create a SNDFILE object. If close_desc 566 | ** is TRUE, the file descriptor will be closed when sf_close() is called. If 567 | ** it is FALSE, the descriptor will not be closed. 568 | ** When passed a descriptor like this, the library will assume that the start 569 | ** of file header is at the current file offset. This allows sound files within 570 | ** larger container files to be read and/or written. 571 | ** On error, this will return a NULL pointer. To find the error number, pass a 572 | ** NULL SNDFILE to sf_strerror (). 573 | ** All calls to sf_open_fd() should be matched with a call to sf_close(). 574 | 575 | */ 576 | 577 | SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ; 578 | 579 | SNDFILE* sf_open_virtual (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ; 580 | 581 | 582 | /* sf_error () returns a error number which can be translated to a text 583 | ** string using sf_error_number(). 584 | */ 585 | 586 | int sf_error (SNDFILE *sndfile) ; 587 | 588 | 589 | /* sf_strerror () returns to the caller a pointer to the current error message for 590 | ** the given SNDFILE. 591 | */ 592 | 593 | const char* sf_strerror (SNDFILE *sndfile) ; 594 | 595 | 596 | /* sf_error_number () allows the retrieval of the error string for each internal 597 | ** error number. 598 | ** 599 | */ 600 | 601 | const char* sf_error_number (int errnum) ; 602 | 603 | 604 | /* The following two error functions are deprecated but they will remain in the 605 | ** library for the foreseeable future. The function sf_strerror() should be used 606 | ** in their place. 607 | */ 608 | 609 | int sf_perror (SNDFILE *sndfile) ; 610 | int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ; 611 | 612 | 613 | /* Return TRUE if fields of the SF_INFO struct are a valid combination of values. */ 614 | 615 | int sf_command (SNDFILE *sndfile, int command, void *data, int datasize) ; 616 | 617 | 618 | /* Return TRUE if fields of the SF_INFO struct are a valid combination of values. */ 619 | 620 | int sf_format_check (const SF_INFO *info) ; 621 | 622 | 623 | /* Seek within the waveform data chunk of the SNDFILE. sf_seek () uses 624 | ** the same values for whence (SEEK_SET, SEEK_CUR and SEEK_END) as 625 | ** stdio.h function fseek (). 626 | ** An offset of zero with whence set to SEEK_SET will position the 627 | ** read / write pointer to the first data sample. 628 | ** On success sf_seek returns the current position in (multi-channel) 629 | ** samples from the start of the file. 630 | ** Please see the libsndfile documentation for moving the read pointer 631 | ** separately from the write pointer on files open in mode SFM_RDWR. 632 | ** On error all of these functions return -1. 633 | */ 634 | 635 | enum 636 | { SF_SEEK_SET = SEEK_SET, 637 | SF_SEEK_CUR = SEEK_CUR, 638 | SF_SEEK_END = SEEK_END 639 | } ; 640 | 641 | sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ; 642 | 643 | 644 | /* Functions for retrieving and setting string data within sound files. 645 | ** Not all file types support this features; AIFF and WAV do. For both 646 | ** functions, the str_type parameter must be one of the SF_STR_* values 647 | ** defined above. 648 | ** On error, sf_set_string() returns non-zero while sf_get_string() 649 | ** returns NULL. 650 | */ 651 | 652 | int sf_set_string (SNDFILE *sndfile, int str_type, const char* str) ; 653 | 654 | const char* sf_get_string (SNDFILE *sndfile, int str_type) ; 655 | 656 | 657 | /* Return the library version string. */ 658 | 659 | const char * sf_version_string (void) ; 660 | 661 | /* Return the current byterate at this point in the file. The byte rate in this 662 | ** case is the number of bytes per second of audio data. For instance, for a 663 | ** stereo, 18 bit PCM encoded file with an 16kHz sample rate, the byte rate 664 | ** would be 2 (stereo) * 2 (two bytes per sample) * 16000 => 64000 bytes/sec. 665 | ** For some file formats the returned value will be accurate and exact, for some 666 | ** it will be a close approximation, for some it will be the average bitrate for 667 | ** the whole file and for some it will be a time varying value that was accurate 668 | ** when the file was most recently read or written. 669 | ** To get the bitrate, multiple this value by 8. 670 | ** Returns -1 for unknown. 671 | */ 672 | int sf_current_byterate (SNDFILE *sndfile) ; 673 | 674 | /* Functions for reading/writing the waveform data of a sound file. 675 | */ 676 | 677 | sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; 678 | sf_count_t sf_write_raw (SNDFILE *sndfile, const void *ptr, sf_count_t bytes) ; 679 | 680 | 681 | /* Functions for reading and writing the data chunk in terms of frames. 682 | ** The number of items actually read/written = frames * number of channels. 683 | ** sf_xxxx_raw read/writes the raw data bytes from/to the file 684 | ** sf_xxxx_short passes data in the native short format 685 | ** sf_xxxx_int passes data in the native int format 686 | ** sf_xxxx_float passes data in the native float format 687 | ** sf_xxxx_double passes data in the native double format 688 | ** All of these read/write function return number of frames read/written. 689 | */ 690 | 691 | sf_count_t sf_readf_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; 692 | sf_count_t sf_writef_short (SNDFILE *sndfile, const short *ptr, sf_count_t frames) ; 693 | 694 | sf_count_t sf_readf_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; 695 | sf_count_t sf_writef_int (SNDFILE *sndfile, const int *ptr, sf_count_t frames) ; 696 | 697 | sf_count_t sf_readf_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; 698 | sf_count_t sf_writef_float (SNDFILE *sndfile, const float *ptr, sf_count_t frames) ; 699 | 700 | sf_count_t sf_readf_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; 701 | sf_count_t sf_writef_double (SNDFILE *sndfile, const double *ptr, sf_count_t frames) ; 702 | 703 | 704 | /* Functions for reading and writing the data chunk in terms of items. 705 | ** Otherwise similar to above. 706 | ** All of these read/write function return number of items read/written. 707 | */ 708 | 709 | sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; 710 | sf_count_t sf_write_short (SNDFILE *sndfile, const short *ptr, sf_count_t items) ; 711 | 712 | sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; 713 | sf_count_t sf_write_int (SNDFILE *sndfile, const int *ptr, sf_count_t items) ; 714 | 715 | sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; 716 | sf_count_t sf_write_float (SNDFILE *sndfile, const float *ptr, sf_count_t items) ; 717 | 718 | sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; 719 | sf_count_t sf_write_double (SNDFILE *sndfile, const double *ptr, sf_count_t items) ; 720 | 721 | 722 | /* Close the SNDFILE and clean up all memory allocations associated with this 723 | ** file. 724 | ** Returns 0 on success, or an error number. 725 | */ 726 | 727 | int sf_close (SNDFILE *sndfile) ; 728 | 729 | 730 | /* If the file is opened SFM_WRITE or SFM_RDWR, call fsync() on the file 731 | ** to force the writing of data to disk. If the file is opened SFM_READ 732 | ** no action is taken. 733 | */ 734 | 735 | void sf_write_sync (SNDFILE *sndfile) ; 736 | 737 | 738 | 739 | /* The function sf_wchar_open() is Windows Only! 740 | ** Open a file passing in a Windows Unicode filename. Otherwise, this is 741 | ** the same as sf_open(). 742 | ** 743 | ** In order for this to work, you need to do the following: 744 | ** 745 | ** #include 746 | ** #define ENABLE_SNDFILE_WINDOWS_PROTOTYPES 1 747 | ** #including 748 | */ 749 | 750 | #if (defined (ENABLE_SNDFILE_WINDOWS_PROTOTYPES) && ENABLE_SNDFILE_WINDOWS_PROTOTYPES) 751 | SNDFILE* sf_wchar_open (LPCWSTR wpath, int mode, SF_INFO *sfinfo) ; 752 | #endif 753 | 754 | 755 | 756 | 757 | /* Getting and setting of chunks from within a sound file. 758 | ** 759 | ** These functions allow the getting and setting of chunks within a sound file 760 | ** (for those formats which allow it). 761 | ** 762 | ** These functions fail safely. Specifically, they will not allow you to overwrite 763 | ** existing chunks or add extra versions of format specific reserved chunks but 764 | ** should allow you to retrieve any and all chunks (may not be implemented for 765 | ** all chunks or all file formats). 766 | */ 767 | 768 | struct SF_CHUNK_INFO 769 | { char id [64] ; /* The chunk identifier. */ 770 | unsigned id_size ; /* The size of the chunk identifier. */ 771 | unsigned datalen ; /* The size of that data. */ 772 | void *data ; /* Pointer to the data. */ 773 | } ; 774 | 775 | typedef struct SF_CHUNK_INFO SF_CHUNK_INFO ; 776 | 777 | /* Set the specified chunk info (must be done before any audio data is written 778 | ** to the file). This will fail for format specific reserved chunks. 779 | ** The chunk_info->data pointer must be valid until the file is closed. 780 | ** Returns SF_ERR_NO_ERROR on success or non-zero on failure. 781 | */ 782 | int sf_set_chunk (SNDFILE * sndfile, const SF_CHUNK_INFO * chunk_info) ; 783 | 784 | /* 785 | ** An opaque structure to an iterator over the all chunks of a given id 786 | */ 787 | typedef struct SF_CHUNK_ITERATOR SF_CHUNK_ITERATOR ; 788 | 789 | /* Get an iterator for all chunks matching chunk_info. 790 | ** The iterator will point to the first chunk matching chunk_info. 791 | ** Chunks are matching, if (chunk_info->id) matches the first 792 | ** (chunk_info->id_size) bytes of a chunk found in the SNDFILE* handle. 793 | ** If chunk_info is NULL, an iterator to all chunks in the SNDFILE* handle 794 | ** is returned. 795 | ** The values of chunk_info->datalen and chunk_info->data are ignored. 796 | ** If no matching chunks are found in the sndfile, NULL is returned. 797 | ** The returned iterator will stay valid until one of the following occurs: 798 | ** a) The sndfile is closed. 799 | ** b) A new chunk is added using sf_set_chunk(). 800 | ** c) Another chunk iterator function is called on the same SNDFILE* handle 801 | ** that causes the iterator to be modified. 802 | ** The memory for the iterator belongs to the SNDFILE* handle and is freed when 803 | ** sf_close() is called. 804 | */ 805 | SF_CHUNK_ITERATOR * 806 | sf_get_chunk_iterator (SNDFILE * sndfile, const SF_CHUNK_INFO * chunk_info) ; 807 | 808 | /* Iterate through chunks by incrementing the iterator. 809 | ** Increments the iterator and returns a handle to the new one. 810 | ** After this call, iterator will no longer be valid, and you must use the 811 | ** newly returned handle from now on. 812 | ** The returned handle can be used to access the next chunk matching 813 | ** the criteria as defined in sf_get_chunk_iterator(). 814 | ** If iterator points to the last chunk, this will free all resources 815 | ** associated with iterator and return NULL. 816 | ** The returned iterator will stay valid until sf_get_chunk_iterator_next 817 | ** is called again, the sndfile is closed or a new chunk us added. 818 | */ 819 | SF_CHUNK_ITERATOR * 820 | sf_next_chunk_iterator (SF_CHUNK_ITERATOR * iterator) ; 821 | 822 | 823 | /* Get the size of the specified chunk. 824 | ** If the specified chunk exists, the size will be returned in the 825 | ** datalen field of the SF_CHUNK_INFO struct. 826 | ** Additionally, the id of the chunk will be copied to the id 827 | ** field of the SF_CHUNK_INFO struct and it's id_size field will 828 | ** be updated accordingly. 829 | ** If the chunk doesn't exist chunk_info->datalen will be zero, and the 830 | ** id and id_size fields will be undefined. 831 | ** The function will return SF_ERR_NO_ERROR on success or non-zero on 832 | ** failure. 833 | */ 834 | int 835 | sf_get_chunk_size (const SF_CHUNK_ITERATOR * it, SF_CHUNK_INFO * chunk_info) ; 836 | 837 | /* Get the specified chunk data. 838 | ** If the specified chunk exists, up to chunk_info->datalen bytes of 839 | ** the chunk data will be copied into the chunk_info->data buffer 840 | ** (allocated by the caller) and the chunk_info->datalen field 841 | ** updated to reflect the size of the data. The id and id_size 842 | ** field will be updated according to the retrieved chunk 843 | ** If the chunk doesn't exist chunk_info->datalen will be zero, and the 844 | ** id and id_size fields will be undefined. 845 | ** The function will return SF_ERR_NO_ERROR on success or non-zero on 846 | ** failure. 847 | */ 848 | int 849 | sf_get_chunk_data (const SF_CHUNK_ITERATOR * it, SF_CHUNK_INFO * chunk_info) ; 850 | 851 | 852 | #ifdef __cplusplus 853 | } /* extern "C" */ 854 | #endif /* __cplusplus */ 855 | 856 | #endif /* SNDFILE_H */ 857 | 858 | --------------------------------------------------------------------------------