00001 /* 00002 ** Copyright (C) 1999-2004 Erik de Castro Lopo <erikd@mega-nerd.com> 00003 ** 00004 ** This program is free software; you can redistribute it and/or modify 00005 ** it under the terms of the GNU Lesser General Public License as published by 00006 ** the Free Software Foundation; either version 2.1 of the License, or 00007 ** (at your option) any later version. 00008 ** 00009 ** This program is distributed in the hope that it will be useful, 00010 ** but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 ** GNU Lesser General Public License for more details. 00013 ** 00014 ** You should have received a copy of the GNU Lesser General Public License 00015 ** along with this program; if not, write to the Free Software 00016 ** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 00017 */ 00018 00019 /* 00020 ** sndfile.h -- system-wide definitions 00021 ** 00022 ** API documentation is in the doc/ directory of the source code tarball 00023 ** and at http://www.mega-nerd.com/libsndfile/api.html. 00024 */ 00025 00026 #ifndef SNDFILE_H 00027 #define SNDFILE_H 00028 00029 /* This is the version 1.0.X header file. */ 00030 #define SNDFILE_1 00031 00032 #include <stdio.h> 00033 00034 /* For the Metrowerks CodeWarrior Pro Compiler (mainly MacOS) */ 00035 00036 #if (defined (__MWERKS__)) 00037 #include <unix.h> 00038 #else 00039 #include <sys/types.h> 00040 #endif 00041 00042 #ifdef __cplusplus 00043 extern "C" { 00044 #endif /* __cplusplus */ 00045 00046 /* The following file types can be read and written. 00047 ** A file type would consist of a major type (ie SF_FORMAT_WAV) bitwise 00048 ** ORed with a minor type (ie SF_FORMAT_PCM). SF_FORMAT_TYPEMASK and 00049 ** SF_FORMAT_SUBMASK can be used to separate the major and minor file 00050 ** types. 00051 */ 00052 00053 enum 00054 { /* Major formats. */ 00055 SF_FORMAT_WAV = 0x010000, /* Microsoft WAV format (little endian). */ 00056 SF_FORMAT_AIFF = 0x020000, /* Apple/SGI AIFF format (big endian). */ 00057 SF_FORMAT_AU = 0x030000, /* Sun/NeXT AU format (big endian). */ 00058 SF_FORMAT_RAW = 0x040000, /* RAW PCM data. */ 00059 SF_FORMAT_PAF = 0x050000, /* Ensoniq PARIS file format. */ 00060 SF_FORMAT_SVX = 0x060000, /* Amiga IFF / SVX8 / SV16 format. */ 00061 SF_FORMAT_NIST = 0x070000, /* Sphere NIST format. */ 00062 SF_FORMAT_VOC = 0x080000, /* VOC files. */ 00063 SF_FORMAT_IRCAM = 0x0A0000, /* Berkeley/IRCAM/CARL */ 00064 SF_FORMAT_W64 = 0x0B0000, /* Sonic Foundry's 64 bit RIFF/WAV */ 00065 SF_FORMAT_MAT4 = 0x0C0000, /* Matlab (tm) V4.2 / GNU Octave 2.0 */ 00066 SF_FORMAT_MAT5 = 0x0D0000, /* Matlab (tm) V5.0 / GNU Octave 2.1 */ 00067 SF_FORMAT_PVF = 0x0E0000, /* Portable Voice Format */ 00068 SF_FORMAT_XI = 0x0F0000, /* Fasttracker 2 Extended Instrument */ 00069 SF_FORMAT_HTK = 0x100000, /* HMM Tool Kit format */ 00070 SF_FORMAT_SDS = 0x110000, /* Midi Sample Dump Standard */ 00071 SF_FORMAT_AVR = 0x120000, /* Audio Visual Research */ 00072 SF_FORMAT_WAVEX = 0x130000, /* MS WAVE with WAVEFORMATEX */ 00073 00074 /* Subtypes from here on. */ 00075 00076 SF_FORMAT_PCM_S8 = 0x0001, /* Signed 8 bit data */ 00077 SF_FORMAT_PCM_16 = 0x0002, /* Signed 16 bit data */ 00078 SF_FORMAT_PCM_24 = 0x0003, /* Signed 24 bit data */ 00079 SF_FORMAT_PCM_32 = 0x0004, /* Signed 32 bit data */ 00080 00081 SF_FORMAT_PCM_U8 = 0x0005, /* Unsigned 8 bit data (WAV and RAW only) */ 00082 00083 SF_FORMAT_FLOAT = 0x0006, /* 32 bit float data */ 00084 SF_FORMAT_DOUBLE = 0x0007, /* 64 bit float data */ 00085 00086 SF_FORMAT_ULAW = 0x0010, /* U-Law encoded. */ 00087 SF_FORMAT_ALAW = 0x0011, /* A-Law encoded. */ 00088 SF_FORMAT_IMA_ADPCM = 0x0012, /* IMA ADPCM. */ 00089 SF_FORMAT_MS_ADPCM = 0x0013, /* Microsoft ADPCM. */ 00090 00091 SF_FORMAT_GSM610 = 0x0020, /* GSM 6.10 encoding. */ 00092 SF_FORMAT_VOX_ADPCM = 0x0021, /* OKI / Dialogix ADPCM */ 00093 00094 SF_FORMAT_G721_32 = 0x0030, /* 32kbs G721 ADPCM encoding. */ 00095 SF_FORMAT_G723_24 = 0x0031, /* 24kbs G723 ADPCM encoding. */ 00096 SF_FORMAT_G723_40 = 0x0032, /* 40kbs G723 ADPCM encoding. */ 00097 00098 SF_FORMAT_DWVW_12 = 0x0040, /* 12 bit Delta Width Variable Word encoding. */ 00099 SF_FORMAT_DWVW_16 = 0x0041, /* 16 bit Delta Width Variable Word encoding. */ 00100 SF_FORMAT_DWVW_24 = 0x0042, /* 24 bit Delta Width Variable Word encoding. */ 00101 SF_FORMAT_DWVW_N = 0x0043, /* N bit Delta Width Variable Word encoding. */ 00102 00103 SF_FORMAT_DPCM_8 = 0x0050, /* 8 bit differential PCM (XI only) */ 00104 SF_FORMAT_DPCM_16 = 0x0051, /* 16 bit differential PCM (XI only) */ 00105 00106 00107 /* Endian-ness options. */ 00108 00109 SF_ENDIAN_FILE = 0x00000000, /* Default file endian-ness. */ 00110 SF_ENDIAN_LITTLE = 0x10000000, /* Force little endian-ness. */ 00111 SF_ENDIAN_BIG = 0x20000000, /* Force big endian-ness. */ 00112 SF_ENDIAN_CPU = 0x30000000, /* Force CPU endian-ness. */ 00113 00114 SF_FORMAT_SUBMASK = 0x0000FFFF, 00115 SF_FORMAT_TYPEMASK = 0x0FFF0000, 00116 SF_FORMAT_ENDMASK = 0x30000000 00117 } ; 00118 00119 /* 00120 ** The following are the valid command numbers for the sf_command() 00121 ** interface. The use of these commands is documented in the file 00122 ** command.html in the doc directory of the source code distribution. 00123 */ 00124 00125 enum 00126 { SFC_GET_LIB_VERSION = 0x1000, 00127 SFC_GET_LOG_INFO = 0x1001, 00128 00129 SFC_GET_NORM_DOUBLE = 0x1010, 00130 SFC_GET_NORM_FLOAT = 0x1011, 00131 SFC_SET_NORM_DOUBLE = 0x1012, 00132 SFC_SET_NORM_FLOAT = 0x1013, 00133 00134 SFC_GET_SIMPLE_FORMAT_COUNT = 0x1020, 00135 SFC_GET_SIMPLE_FORMAT = 0x1021, 00136 00137 SFC_GET_FORMAT_INFO = 0x1028, 00138 00139 SFC_GET_FORMAT_MAJOR_COUNT = 0x1030, 00140 SFC_GET_FORMAT_MAJOR = 0x1031, 00141 SFC_GET_FORMAT_SUBTYPE_COUNT = 0x1032, 00142 SFC_GET_FORMAT_SUBTYPE = 0x1033, 00143 00144 SFC_CALC_SIGNAL_MAX = 0x1040, 00145 SFC_CALC_NORM_SIGNAL_MAX = 0x1041, 00146 SFC_CALC_MAX_ALL_CHANNELS = 0x1042, 00147 SFC_CALC_NORM_MAX_ALL_CHANNELS = 0x1043, 00148 00149 SFC_SET_ADD_PEAK_CHUNK = 0x1050, 00150 00151 SFC_UPDATE_HEADER_NOW = 0x1060, 00152 SFC_SET_UPDATE_HEADER_AUTO = 0x1061, 00153 00154 SFC_FILE_TRUNCATE = 0x1080, 00155 00156 SFC_SET_RAW_START_OFFSET = 0x1090, 00157 00158 SFC_SET_DITHER_ON_WRITE = 0x10A0, 00159 SFC_SET_DITHER_ON_READ = 0x10A1, 00160 00161 SFC_GET_DITHER_INFO_COUNT = 0x10A2, 00162 SFC_GET_DITHER_INFO = 0x10A3, 00163 00164 SFC_GET_EMBED_FILE_INFO = 0x10B0, 00165 00166 SFC_SET_CLIPPING = 0x10C0, 00167 SFC_GET_CLIPPING = 0x10C1, 00168 00169 SFC_GET_INSTRUMENT = 0x10D0, 00170 SFC_SET_INSTRUMENT = 0x10D1, 00171 00172 /* Following commands for testing only. */ 00173 SFC_TEST_IEEE_FLOAT_REPLACE = 0x6001, 00174 00175 /* 00176 ** SFC_SET_ADD_* values are deprecated and will disappear at some 00177 ** time in the future. They are guaranteed to be here up to and 00178 ** including version 1.0.8 to avoid breakage of existng software. 00179 ** They currently do nothing and will continue to do nothing. 00180 */ 00181 SFC_SET_ADD_DITHER_ON_WRITE = 0x1070, 00182 SFC_SET_ADD_DITHER_ON_READ = 0x1071 00183 } ; 00184 00185 00186 /* 00187 ** String types that can be set and read from files. Not all file types 00188 ** support this and even the file types which support one, may not support 00189 ** all string types. 00190 */ 00191 00192 enum 00193 { SF_STR_TITLE = 0x01, 00194 SF_STR_COPYRIGHT = 0x02, 00195 SF_STR_SOFTWARE = 0x03, 00196 SF_STR_ARTIST = 0x04, 00197 SF_STR_COMMENT = 0x05, 00198 SF_STR_DATE = 0x06 00199 } ; 00200 00201 enum 00202 { /* True and false */ 00203 SF_FALSE = 0, 00204 SF_TRUE = 1, 00205 00206 /* Modes for opening files. */ 00207 SFM_READ = 0x10, 00208 SFM_WRITE = 0x20, 00209 SFM_RDWR = 0x30 00210 } ; 00211 00212 /* Pubic error values. These are guaranteed to remain unchanged for the duration 00213 ** of the library major version number. 00214 ** There are also a large number of private error numbers which are internal to 00215 ** the library which can change at any time. 00216 */ 00217 00218 enum 00219 { SF_ERR_NO_ERROR = 0, 00220 SF_ERR_UNRECOGNISED_FORMAT = 1, 00221 SF_ERR_SYSTEM = 2 00222 } ; 00223 00224 /* A SNDFILE* pointer can be passed around much like stdio.h's FILE* pointer. */ 00225 00226 typedef struct SNDFILE_tag SNDFILE ; 00227 00228 /* The following typedef is system specific and is defined when libsndfile is. 00229 ** compiled. sf_count_t can be one of loff_t (Linux), off_t (*BSD), 00230 ** off64_t (Solaris), __int64_t (Win32) etc. 00231 */ 00232 00233 typedef __int64 sf_count_t ; 00234 00235 #define SF_COUNT_MAX 0x7FFFFFFFFFFFFFFFi64 00236 00237 /* A pointer to a SF_INFO structure is passed to sf_open_read () and filled in. 00238 ** On write, the SF_INFO structure is filled in by the user and passed into 00239 ** sf_open_write (). 00240 */ 00241 00242 struct SF_INFO 00243 { sf_count_t frames ; /* Used to be called samples. Changed to avoid confusion. */ 00244 int samplerate ; 00245 int channels ; 00246 int format ; 00247 int sections ; 00248 int seekable ; 00249 } ; 00250 00251 typedef struct SF_INFO SF_INFO ; 00252 00253 /* The SF_FORMAT_INFO struct is used to retrieve information about the sound 00254 ** file formats libsndfile supports using the sf_command () interface. 00255 ** 00256 ** Using this interface will allow applications to support new file formats 00257 ** and encoding types when libsndfile is upgraded, without requiring 00258 ** re-compilation of the application. 00259 ** 00260 ** Please consult the libsndfile documentation (particularly the information 00261 ** on the sf_command () interface) for examples of its use. 00262 */ 00263 00264 typedef struct 00265 { int format ; 00266 const char *name ; 00267 const char *extension ; 00268 } SF_FORMAT_INFO ; 00269 00270 /* 00271 ** Enums and typedefs for adding dither on read and write. 00272 ** See the html documentation for sf_command(), SFC_SET_DITHER_ON_WRITE 00273 ** and SFC_SET_DITHER_ON_READ. 00274 */ 00275 00276 enum 00277 { SFD_DEFAULT_LEVEL = 0, 00278 SFD_CUSTOM_LEVEL = 0x40000000, 00279 00280 SFD_NO_DITHER = 500, 00281 SFD_WHITE = 501, 00282 SFD_TRIANGULAR_PDF = 502 00283 } ; 00284 00285 typedef struct 00286 { int type ; 00287 double level ; 00288 const char *name ; 00289 } SF_DITHER_INFO ; 00290 00291 /* Struct used to retrieve information about a file embedded within a 00292 ** larger file. See SFC_GET_EMBED_FILE_INFO. 00293 */ 00294 00295 typedef struct 00296 { sf_count_t offset ; 00297 sf_count_t length ; 00298 } SF_EMBED_FILE_INFO ; 00299 00300 /* Struct used to retrieve music sample information from a file. 00301 */ 00302 00303 typedef struct 00304 { int basenote ; 00305 int gain ; 00306 int sustain_mode ; 00307 int sustain_start, sustain_end ; 00308 int release_mode ; 00309 int release_start, reslease_end ; 00310 } SF_INSTRUMENT ; 00311 00312 /* sustain_mode and release_mode will be one of the following. */ 00313 00314 enum 00315 { SF_LOOP_NONE = 800, 00316 SF_LOOP_FORWARD, 00317 SF_LOOP_BACKWARD 00318 } ; 00319 00320 /* Open the specified file for read, write or both. On error, this will 00321 ** return a NULL pointer. To find the error number, pass a NULL SNDFILE 00322 ** to sf_perror () or sf_error_str (). 00323 ** All calls to sf_open() should be matched with a call to sf_close(). 00324 */ 00325 00326 SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ; 00327 00328 /* Use the existing file descriptor to create a SNDFILE object. If close_desc 00329 ** is TRUE, the file descriptor will be closed when sf_close() is called. If 00330 ** it is FALSE, the descritor will not be closed. 00331 ** When passed a descriptor like this, the library will assume that the start 00332 ** of file header is at the current file offset. This allows sound files within 00333 ** larger container files to be read and/or written. 00334 ** On error, this will return a NULL pointer. To find the error number, pass a 00335 ** NULL SNDFILE to sf_perror () or sf_error_str (). 00336 ** All calls to sf_open_fd() should be matched with a call to sf_close(). 00337 00338 */ 00339 00340 SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ; 00341 00342 /* sf_error () returns a error number which can be translated to a text 00343 ** string using sf_error_number(). 00344 */ 00345 00346 int sf_error (SNDFILE *sndfile) ; 00347 00348 /* sf_strerror () returns to the caller a pointer to the current error message for 00349 ** the given SNDFILE. 00350 */ 00351 00352 const char* sf_strerror (SNDFILE *sndfile) ; 00353 00354 /* sf_error_number () allows the retrieval of the error string for each internal 00355 ** error number. 00356 ** 00357 */ 00358 00359 const char* sf_error_number (int errnum) ; 00360 00361 /* The following three error functions are deprecated but they will remain in the 00362 ** library for the forseeable future. The function sf_strerror() should be used 00363 ** in their place. 00364 */ 00365 00366 int sf_perror (SNDFILE *sndfile) ; 00367 int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ; 00368 00369 00370 /* Return TRUE if fields of the SF_INFO struct are a valid combination of values. */ 00371 00372 int sf_command (SNDFILE *sndfile, int command, void *data, int datasize) ; 00373 00374 /* Return TRUE if fields of the SF_INFO struct are a valid combination of values. */ 00375 00376 int sf_format_check (const SF_INFO *info) ; 00377 00378 /* Seek within the waveform data chunk of the SNDFILE. sf_seek () uses 00379 ** the same values for whence (SEEK_SET, SEEK_CUR and SEEK_END) as 00380 ** stdio.h function fseek (). 00381 ** An offset of zero with whence set to SEEK_SET will position the 00382 ** read / write pointer to the first data sample. 00383 ** On success sf_seek returns the current position in (multi-channel) 00384 ** samples from the start of the file. 00385 ** Please see the libsndfile documentation for moving the read pointer 00386 ** separately from the write pointer on files open in mode SFM_RDWR. 00387 ** On error all of these functions return -1. 00388 */ 00389 00390 sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ; 00391 00392 /* Functions for retrieving and setting string data within sound files. 00393 ** Not all file types support this features; AIFF and WAV do. For both 00394 ** functions, the str_type parameter must be one of the SF_STR_* values 00395 ** defined above. 00396 ** On error, sf_set_string() returns non-zero while sf_get_string() 00397 ** returns NULL. 00398 */ 00399 00400 int sf_set_string (SNDFILE *sndfile, int str_type, const char* str) ; 00401 00402 const char* sf_get_string (SNDFILE *sndfile, int str_type) ; 00403 00404 /* Functions for reading/writing the waveform data of a sound file. 00405 */ 00406 00407 sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; 00408 sf_count_t sf_write_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; 00409 00410 /* Functions for reading and writing the data chunk in terms of frames. 00411 ** The number of items actually read/written = frames * number of channels. 00412 ** sf_xxxx_raw read/writes the raw data bytes from/to the file 00413 ** sf_xxxx_short passes data in the native short format 00414 ** sf_xxxx_int passes data in the native int format 00415 ** sf_xxxx_float passes data in the native float format 00416 ** sf_xxxx_double passes data in the native double format 00417 ** All of these read/write function return number of frames read/written. 00418 */ 00419 00420 sf_count_t sf_readf_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; 00421 sf_count_t sf_writef_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; 00422 00423 sf_count_t sf_readf_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; 00424 sf_count_t sf_writef_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; 00425 00426 sf_count_t sf_readf_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; 00427 sf_count_t sf_writef_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; 00428 00429 sf_count_t sf_readf_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; 00430 sf_count_t sf_writef_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; 00431 00432 /* Functions for reading and writing the data chunk in terms of items. 00433 ** Otherwise similar to above. 00434 ** All of these read/write function return number of items read/written. 00435 */ 00436 00437 sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; 00438 sf_count_t sf_write_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; 00439 00440 sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; 00441 sf_count_t sf_write_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; 00442 00443 sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; 00444 sf_count_t sf_write_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; 00445 00446 sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; 00447 sf_count_t sf_write_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; 00448 00449 /* Close the SNDFILE and clean up all memory allocations associated with this 00450 ** file. 00451 ** Returns 0 on success, or an error number. 00452 */ 00453 00454 int sf_close (SNDFILE *sndfile) ; 00455 00456 #ifdef __cplusplus 00457 } /* extern "C" */ 00458 #endif /* __cplusplus */ 00459 00460 #endif /* SNDFILE_H */ 00461 00462 /* 00463 ** Do not edit or modify anything in this comment block. 00464 ** The arch-tag line is a file identity tag for the GNU Arch 00465 ** revision control system. 00466 ** 00467 ** arch-tag: 906bb197-18f2-4f66-a395-b4722bab5114 00468 */ 00469
1.5.8