Alexandre Lision | 7c6f4a6 | 2013-09-05 13:27:01 -0400 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <HTML> |
| 3 | |
| 4 | <HEAD> |
| 5 | <TITLE> |
| 6 | The libsndfile API |
| 7 | </TITLE> |
| 8 | <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)"> |
| 9 | <META NAME="Description" CONTENT="The libsndfile API."> |
| 10 | <META NAME="Keywords" CONTENT="WAV AIFF AU libsndfile sound audio dsp Linux"> |
| 11 | <LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all"> |
| 12 | <LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print"> |
| 13 | </HEAD> |
| 14 | |
| 15 | <BODY> |
| 16 | |
| 17 | <BR> |
| 18 | <H1><B>libsndfile</B></H1> |
| 19 | <P> |
| 20 | Libsndfile is a library designed to allow the reading and writing of many |
| 21 | different sampled sound file formats (such as MS Windows WAV and the Apple/SGI |
| 22 | AIFF format) through one standard library interface. |
| 23 | </P> |
| 24 | <!-- pepper --> |
| 25 | <P> |
| 26 | During read and write operations, formats are seamlessly converted between the |
| 27 | format the application program has requested or supplied and the file's data |
| 28 | format. The application programmer can remain blissfully unaware of issues |
| 29 | such as file endian-ness and data format. See <A HREF="#note1">Note 1</A> and |
| 30 | <A HREF="#note2">Note 2</A>. |
| 31 | </P> |
| 32 | <!-- pepper --> |
| 33 | <P> |
| 34 | Every effort is made to keep these documents up-to-date, error free and |
| 35 | unambiguous. |
| 36 | However, since maintaining the documentation is the least fun part of working |
| 37 | on libsndfile, these docs can and do fall behind the behaviour of library. |
| 38 | If any errors, omissions or ambiguities are found, please notify me (erikd) |
| 39 | at mega-nerd dot com. |
| 40 | </P> |
| 41 | <!-- pepper --> |
| 42 | <P> |
| 43 | To supplement this reference documentation, there are simple example programs |
| 44 | included in the source code tarball. |
| 45 | The test suite which is also part of the source code tarball is also a good |
| 46 | place to look for the correct usage of the library functions. |
| 47 | </P> |
| 48 | <!-- pepper --> |
| 49 | <P> |
| 50 | <B> Finally, if you think there is some feature missing from libsndfile, check that |
| 51 | it isn't already implemented (and documented) |
| 52 | <A HREF="command.html">here</A>. |
| 53 | </B> |
| 54 | </P> |
| 55 | |
| 56 | <H2><B>Synopsis</B></H2> |
| 57 | <P> |
| 58 | The functions of libsndfile are defined as follows: |
| 59 | </P> |
| 60 | <!-- pepper --> |
| 61 | <PRE> |
| 62 | #include <stdio.h> |
| 63 | #include <sndfile.h> |
| 64 | |
| 65 | SNDFILE* <A HREF="#open">sf_open</A> (const char *path, int mode, SF_INFO *sfinfo) ; |
| 66 | SNDFILE* <A HREF="#open_fd">sf_open_fd</A> (int fd, int mode, SF_INFO *sfinfo, int close_desc) ; |
| 67 | SNDFILE* <A HREF="#open_virtual">sf_open_virtual</A> (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ; |
| 68 | int <A HREF="#check">sf_format_check</A> (const SF_INFO *info) ; |
| 69 | |
| 70 | sf_count_t <A HREF="#seek">sf_seek</A> (SNDFILE *sndfile, sf_count_t frames, int whence) ; |
| 71 | |
| 72 | int <A HREF="command.html">sf_command</A> (SNDFILE *sndfile, int cmd, void *data, int datasize) ; |
| 73 | |
| 74 | int <A HREF="#error">sf_error</A> (SNDFILE *sndfile) ; |
| 75 | const char* <A HREF="#error">sf_strerror</A> (SNDFILE *sndfile) ; |
| 76 | const char* <A HREF="#error">sf_error_number</A> (int errnum) ; |
| 77 | |
| 78 | int <A HREF="#error">sf_perror</A> (SNDFILE *sndfile) ; |
| 79 | int <A HREF="#error">sf_error_str</A> (SNDFILE *sndfile, char* str, size_t len) ; |
| 80 | |
| 81 | int <A HREF="#close">sf_close</A> (SNDFILE *sndfile) ; |
| 82 | void <A HREF="#write_sync">sf_write_sync</A> (SNDFILE *sndfile) ; |
| 83 | |
| 84 | sf_count_t <A HREF="#read">sf_read_short</A> (SNDFILE *sndfile, short *ptr, sf_count_t items) ; |
| 85 | sf_count_t <A HREF="#read">sf_read_int</A> (SNDFILE *sndfile, int *ptr, sf_count_t items) ; |
| 86 | sf_count_t <A HREF="#read">sf_read_float</A> (SNDFILE *sndfile, float *ptr, sf_count_t items) ; |
| 87 | sf_count_t <A HREF="#read">sf_read_double</A> (SNDFILE *sndfile, double *ptr, sf_count_t items) ; |
| 88 | |
| 89 | sf_count_t <A HREF="#readf">sf_readf_short</A> (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; |
| 90 | sf_count_t <A HREF="#readf">sf_readf_int</A> (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; |
| 91 | sf_count_t <A HREF="#readf">sf_readf_float</A> (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; |
| 92 | sf_count_t <A HREF="#readf">sf_readf_double</A> (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; |
| 93 | |
| 94 | sf_count_t <A HREF="#write">sf_write_short</A> (SNDFILE *sndfile, short *ptr, sf_count_t items) ; |
| 95 | sf_count_t <A HREF="#write">sf_write_int</A> (SNDFILE *sndfile, int *ptr, sf_count_t items) ; |
| 96 | sf_count_t <A HREF="#write">sf_write_float</A> (SNDFILE *sndfile, float *ptr, sf_count_t items) ; |
| 97 | sf_count_t <A HREF="#write">sf_write_double</A> (SNDFILE *sndfile, double *ptr, sf_count_t items) ; |
| 98 | |
| 99 | sf_count_t <A HREF="#writef">sf_writef_short</A> (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; |
| 100 | sf_count_t <A HREF="#writef">sf_writef_int</A> (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; |
| 101 | sf_count_t <A HREF="#writef">sf_writef_float</A> (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; |
| 102 | sf_count_t <A HREF="#writef">sf_writef_double</A> (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; |
| 103 | |
| 104 | sf_count_t <A HREF="#raw">sf_read_raw</A> (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; |
| 105 | sf_count_t <A HREF="#raw">sf_write_raw</A> (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; |
| 106 | |
| 107 | const char* <A HREF="#string">sf_get_string</A> (SNDFILE *sndfile, int str_type) ; |
| 108 | int <A HREF="#string">sf_set_string</A> (SNDFILE *sndfile, int str_type, const char* str) ; |
| 109 | |
| 110 | </PRE> |
| 111 | <!-- pepper --> |
| 112 | <P> |
| 113 | SNDFILE* is an anonymous pointer to data which is private to the library. |
| 114 | </P> |
| 115 | |
| 116 | |
| 117 | <A NAME="open"></A> |
| 118 | <H2><B>File Open Function</B></H2> |
| 119 | |
| 120 | <PRE> |
| 121 | SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ; |
| 122 | </PRE> |
| 123 | |
| 124 | <P> |
| 125 | The SF_INFO structure is for passing data between the calling function and the library |
| 126 | when opening a file for reading or writing. It is defined in sndfile.h as follows: |
| 127 | </P> |
| 128 | <!-- pepper --> |
| 129 | <PRE> |
| 130 | typedef struct |
| 131 | { sf_count_t frames ; /* Used to be called samples. */ |
| 132 | int samplerate ; |
| 133 | int channels ; |
| 134 | int format ; |
| 135 | int sections ; |
| 136 | int seekable ; |
| 137 | } SF_INFO ; |
| 138 | </PRE> |
| 139 | |
| 140 | <P> |
| 141 | The mode parameter for this function can be any one of the following three values: |
| 142 | </P> |
| 143 | <!-- pepper --> |
| 144 | <PRE> |
| 145 | SFM_READ - read only mode |
| 146 | SFM_WRITE - write only mode |
| 147 | SFM_RDWR - read/write mode |
| 148 | </PRE> |
| 149 | |
| 150 | <P> |
| 151 | When opening a file for read, the <b>format</B> field should be set to zero before |
| 152 | calling sf_open(). |
| 153 | The only exception to this is the case of RAW files where the caller has to set |
| 154 | the samplerate, channels and format fields to valid values. |
| 155 | All other fields of the structure are filled in by the library. |
| 156 | </P> |
| 157 | <!-- pepper --> |
| 158 | <P> |
| 159 | When opening a file for write, the caller must fill in structure members samplerate, |
| 160 | channels, and format. |
| 161 | </P> |
| 162 | <!-- pepper --> |
| 163 | <P> |
| 164 | The format field in the above SF_INFO structure is made up of the bit-wise OR of a |
| 165 | major format type (values between 0x10000 and 0x08000000), a minor format type |
| 166 | (with values less than 0x10000) and an optional endian-ness value. |
| 167 | The currently understood formats are listed in sndfile.h as follows and also include |
| 168 | bitmasks for separating major and minor file types. |
| 169 | Not all combinations of endian-ness and major and minor file types are valid. |
| 170 | </P> |
| 171 | <!-- pepper --> |
| 172 | <PRE> |
| 173 | enum |
| 174 | { /* Major formats. */ |
| 175 | SF_FORMAT_WAV = 0x010000, /* Microsoft WAV format (little endian). */ |
| 176 | SF_FORMAT_AIFF = 0x020000, /* Apple/SGI AIFF format (big endian). */ |
| 177 | SF_FORMAT_AU = 0x030000, /* Sun/NeXT AU format (big endian). */ |
| 178 | SF_FORMAT_RAW = 0x040000, /* RAW PCM data. */ |
| 179 | SF_FORMAT_PAF = 0x050000, /* Ensoniq PARIS file format. */ |
| 180 | SF_FORMAT_SVX = 0x060000, /* Amiga IFF / SVX8 / SV16 format. */ |
| 181 | SF_FORMAT_NIST = 0x070000, /* Sphere NIST format. */ |
| 182 | SF_FORMAT_VOC = 0x080000, /* VOC files. */ |
| 183 | SF_FORMAT_IRCAM = 0x0A0000, /* Berkeley/IRCAM/CARL */ |
| 184 | SF_FORMAT_W64 = 0x0B0000, /* Sonic Foundry's 64 bit RIFF/WAV */ |
| 185 | SF_FORMAT_MAT4 = 0x0C0000, /* Matlab (tm) V4.2 / GNU Octave 2.0 */ |
| 186 | SF_FORMAT_MAT5 = 0x0D0000, /* Matlab (tm) V5.0 / GNU Octave 2.1 */ |
| 187 | SF_FORMAT_PVF = 0x0E0000, /* Portable Voice Format */ |
| 188 | SF_FORMAT_XI = 0x0F0000, /* Fasttracker 2 Extended Instrument */ |
| 189 | SF_FORMAT_HTK = 0x100000, /* HMM Tool Kit format */ |
| 190 | SF_FORMAT_SDS = 0x110000, /* Midi Sample Dump Standard */ |
| 191 | SF_FORMAT_AVR = 0x120000, /* Audio Visual Research */ |
| 192 | SF_FORMAT_WAVEX = 0x130000, /* MS WAVE with WAVEFORMATEX */ |
| 193 | SF_FORMAT_SD2 = 0x160000, /* Sound Designer 2 */ |
| 194 | SF_FORMAT_FLAC = 0x170000, /* FLAC lossless file format */ |
| 195 | SF_FORMAT_CAF = 0x180000, /* Core Audio File format */ |
| 196 | SF_FORMAT_WVE = 0x190000, /* Psion WVE format */ |
| 197 | SF_FORMAT_OGG = 0x200000, /* Xiph OGG container */ |
| 198 | SF_FORMAT_MPC2K = 0x210000, /* Akai MPC 2000 sampler */ |
| 199 | SF_FORMAT_RF64 = 0x220000, /* RF64 WAV file */ |
| 200 | |
| 201 | /* Subtypes from here on. */ |
| 202 | |
| 203 | SF_FORMAT_PCM_S8 = 0x0001, /* Signed 8 bit data */ |
| 204 | SF_FORMAT_PCM_16 = 0x0002, /* Signed 16 bit data */ |
| 205 | SF_FORMAT_PCM_24 = 0x0003, /* Signed 24 bit data */ |
| 206 | SF_FORMAT_PCM_32 = 0x0004, /* Signed 32 bit data */ |
| 207 | |
| 208 | SF_FORMAT_PCM_U8 = 0x0005, /* Unsigned 8 bit data (WAV and RAW only) */ |
| 209 | |
| 210 | SF_FORMAT_FLOAT = 0x0006, /* 32 bit float data */ |
| 211 | SF_FORMAT_DOUBLE = 0x0007, /* 64 bit float data */ |
| 212 | |
| 213 | SF_FORMAT_ULAW = 0x0010, /* U-Law encoded. */ |
| 214 | SF_FORMAT_ALAW = 0x0011, /* A-Law encoded. */ |
| 215 | SF_FORMAT_IMA_ADPCM = 0x0012, /* IMA ADPCM. */ |
| 216 | SF_FORMAT_MS_ADPCM = 0x0013, /* Microsoft ADPCM. */ |
| 217 | |
| 218 | SF_FORMAT_GSM610 = 0x0020, /* GSM 6.10 encoding. */ |
| 219 | SF_FORMAT_VOX_ADPCM = 0x0021, /* Oki Dialogic ADPCM encoding. */ |
| 220 | |
| 221 | SF_FORMAT_G721_32 = 0x0030, /* 32kbs G721 ADPCM encoding. */ |
| 222 | SF_FORMAT_G723_24 = 0x0031, /* 24kbs G723 ADPCM encoding. */ |
| 223 | SF_FORMAT_G723_40 = 0x0032, /* 40kbs G723 ADPCM encoding. */ |
| 224 | |
| 225 | SF_FORMAT_DWVW_12 = 0x0040, /* 12 bit Delta Width Variable Word encoding. */ |
| 226 | SF_FORMAT_DWVW_16 = 0x0041, /* 16 bit Delta Width Variable Word encoding. */ |
| 227 | SF_FORMAT_DWVW_24 = 0x0042, /* 24 bit Delta Width Variable Word encoding. */ |
| 228 | SF_FORMAT_DWVW_N = 0x0043, /* N bit Delta Width Variable Word encoding. */ |
| 229 | |
| 230 | SF_FORMAT_DPCM_8 = 0x0050, /* 8 bit differential PCM (XI only) */ |
| 231 | SF_FORMAT_DPCM_16 = 0x0051, /* 16 bit differential PCM (XI only) */ |
| 232 | |
| 233 | SF_FORMAT_VORBIS = 0x0060, /* Xiph Vorbis encoding. */ |
| 234 | |
| 235 | /* Endian-ness options. */ |
| 236 | |
| 237 | SF_ENDIAN_FILE = 0x00000000, /* Default file endian-ness. */ |
| 238 | SF_ENDIAN_LITTLE = 0x10000000, /* Force little endian-ness. */ |
| 239 | SF_ENDIAN_BIG = 0x20000000, /* Force big endian-ness. */ |
| 240 | SF_ENDIAN_CPU = 0x30000000, /* Force CPU endian-ness. */ |
| 241 | |
| 242 | SF_FORMAT_SUBMASK = 0x0000FFFF, |
| 243 | SF_FORMAT_TYPEMASK = 0x0FFF0000, |
| 244 | SF_FORMAT_ENDMASK = 0x30000000 |
| 245 | } ; |
| 246 | </PRE> |
| 247 | <!-- pepper --> |
| 248 | <P> |
| 249 | Every call to sf_open() should be matched with a call to sf_close() to free up |
| 250 | memory allocated during the call to sf_open(). |
| 251 | </P> |
| 252 | <!-- pepper --> |
| 253 | <P> |
| 254 | On success, the sf_open function returns a non-NULL pointer which should be |
| 255 | passed as the first parameter to all subsequent libsndfile calls dealing with |
| 256 | that audio file. |
| 257 | On fail, the sf_open function returns a NULL pointer. |
| 258 | An explanation of the error can obtained by passing NULL to |
| 259 | <A HREF="#error">sf_strerror</A>. |
| 260 | </P> |
| 261 | |
| 262 | <A NAME="open_fd"></A> |
| 263 | <H3><B>File Descriptor Open</B></H3> |
| 264 | |
| 265 | <PRE> |
| 266 | SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ; |
| 267 | </PRE> |
| 268 | |
| 269 | <P> |
| 270 | <b>Note:</b> On Microsoft Windows, this function does not work if the |
| 271 | application and the libsndfile DLL are linked to different versions of the |
| 272 | Microsoft C runtime DLL. |
| 273 | </P> |
| 274 | <P> |
| 275 | The second open function takes a file descriptor of a file that has already been |
| 276 | opened. |
| 277 | Care should be taken to ensure that the mode of the file represented by the |
| 278 | descriptor matches the mode argument. |
| 279 | This function is useful in the following circumstances: |
| 280 | </P> |
| 281 | |
| 282 | <UL> |
| 283 | <LI>Opening temporary files securely (ie use the tmpfile() to return a |
| 284 | FILE* pointer and then using fileno() to retrieve the file descriptor |
| 285 | which is then passed to libsndfile). |
| 286 | <LI>Opening files with file names using OS specific character encodings |
| 287 | and then passing the file descriptor to sf_open_fd(). |
| 288 | <LI>Opening sound files embedded within larger files. |
| 289 | <A HREF="embedded_files.html">More info</A>. |
| 290 | </UL> |
| 291 | |
| 292 | <P> |
| 293 | Every call to sf_open_fd() should be matched with a call to sf_close() to free up |
| 294 | memory allocated during the call to sf_open(). |
| 295 | </P> |
| 296 | |
| 297 | <P> |
| 298 | When sf_close() is called, the file descriptor is only closed if the <B>close_desc</B> |
| 299 | parameter was TRUE when the sf_open_fd() function was called. |
| 300 | </P> |
| 301 | |
| 302 | <P> |
| 303 | On success, the sf_open_fd function returns a non-NULL pointer which should be |
| 304 | passed as the first parameter to all subsequent libsndfile calls dealing with |
| 305 | that audio file. |
| 306 | On fail, the sf_open_fd function returns a NULL pointer. |
| 307 | </P> |
| 308 | |
| 309 | <A NAME="open_virtual"></A> |
| 310 | <h3><b>Virtual File Open Function</b></h3> |
| 311 | <pre> |
| 312 | SNDFILE* sf_open_virtual (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ; |
| 313 | </pre> |
| 314 | <p> |
| 315 | Opens a soundfile from a virtual file I/O context which is provided |
| 316 | by the caller. This is usually used to interface libsndfile to a stream or buffer |
| 317 | based system. Apart from the sfvirtual and the user_data parameters this function behaves |
| 318 | like <a href="#open">sf_open</a>. |
| 319 | </p> |
| 320 | |
| 321 | <pre> |
| 322 | typedef struct |
| 323 | { sf_vio_get_filelen get_filelen ; |
| 324 | sf_vio_seek seek ; |
| 325 | sf_vio_read read ; |
| 326 | sf_vio_write write ; |
| 327 | sf_vio_tell tell ; |
| 328 | } SF_VIRTUAL_IO ; |
| 329 | </pre> |
| 330 | <p> |
| 331 | Libsndfile calls the callbacks provided by the SF_VIRTUAL_IO structure when opening, reading |
| 332 | and writing to the virtual file context. The user_data pointer is a user defined context which |
| 333 | will be available in the callbacks. |
| 334 | </p> |
| 335 | <pre> |
| 336 | typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ; |
| 337 | typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ; |
| 338 | typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ; |
| 339 | typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ; |
| 340 | typedef sf_count_t (*sf_vio_tell) (void *user_data) ; |
| 341 | </pre> |
| 342 | <h4>sf_vio_get_filelen</h4> |
| 343 | <pre> |
| 344 | typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ; |
| 345 | </pre> |
| 346 | <p> |
| 347 | The virtual file contex must return the length of the virtual file in bytes.<br> |
| 348 | </p> |
| 349 | <h4>sf_vio_seek</h4> |
| 350 | <pre> |
| 351 | typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ; |
| 352 | </pre> |
| 353 | <p> |
| 354 | The virtual file context must seek to offset using the seek mode provided by whence which is one of<br> |
| 355 | </p> |
| 356 | <pre> |
| 357 | SEEK_CUR |
| 358 | SEEK_SET |
| 359 | SEEK_END |
| 360 | </pre> |
| 361 | <p> |
| 362 | The return value must contain the new offset in the file. |
| 363 | </p> |
| 364 | <h4>sf_vio_read</h4> |
| 365 | <pre> |
| 366 | typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ; |
| 367 | </pre> |
| 368 | <p> |
| 369 | The virtual file context must copy ("read") "count" bytes into the |
| 370 | buffer provided by ptr and return the count of actually copied bytes. |
| 371 | </p> |
| 372 | <h4>sf_vio_write</h4> |
| 373 | <pre> |
| 374 | typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ; |
| 375 | </pre> |
| 376 | <p> |
| 377 | The virtual file context must process "count" bytes stored in the |
| 378 | buffer passed with ptr and return the count of actually processed bytes.<br> |
| 379 | </p> |
| 380 | <h4>sf_vio_tell</h4> |
| 381 | <pre> |
| 382 | typedef sf_count_t (*sf_vio_tell) (void *user_data) ; |
| 383 | </pre> |
| 384 | <p> |
| 385 | Return the current position of the virtual file context.<br> |
| 386 | </p> |
| 387 | |
| 388 | |
| 389 | <A NAME="check"></A> |
| 390 | <BR><H2><B>Format Check Function</B></H2> |
| 391 | |
| 392 | <PRE> |
| 393 | int sf_format_check (const SF_INFO *info) ; |
| 394 | </PRE> |
| 395 | <!-- pepper --> |
| 396 | <P> |
| 397 | This function allows the caller to check if a set of parameters in the SF_INFO struct |
| 398 | is valid before calling sf_open (SFM_WRITE). |
| 399 | </P> |
| 400 | <P> |
| 401 | sf_format_check returns TRUE if the parameters are valid and FALSE otherwise. |
| 402 | </P> |
| 403 | |
| 404 | <A NAME="seek"></A> |
| 405 | <BR><H2><B>File Seek Functions</B></H2> |
| 406 | |
| 407 | <PRE> |
| 408 | sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ; |
| 409 | </PRE> |
| 410 | |
| 411 | <P> |
| 412 | The file seek functions work much like lseek in unistd.h with the exception that |
| 413 | the non-audio data is ignored and the seek only moves within the audio data section of |
| 414 | the file. |
| 415 | In addition, seeks are defined in number of (multichannel) frames. |
| 416 | Therefore, a seek in a stereo file from the current position forward with an offset |
| 417 | of 1 would skip forward by one sample of both channels. |
| 418 | </P> |
| 419 | |
| 420 | <P> |
| 421 | like lseek(), the whence parameter can be any one of the following three values: |
| 422 | </P> |
| 423 | |
| 424 | <PRE> |
| 425 | SEEK_SET - The offset is set to the start of the audio data plus offset (multichannel) frames. |
| 426 | SEEK_CUR - The offset is set to its current location plus offset (multichannel) frames. |
| 427 | SEEK_END - The offset is set to the end of the data plus offset (multichannel) frames. |
| 428 | </PRE> |
| 429 | <!-- pepper --> |
| 430 | <P> |
| 431 | Internally, libsndfile keeps track of the read and write locations using separate |
| 432 | read and write pointers. |
| 433 | If a file has been opened with a mode of SFM_RDWR, bitwise OR-ing the standard whence |
| 434 | values above with either SFM_READ or SFM_WRITE allows the read and write pointers to |
| 435 | be modified separately. |
| 436 | If the SEEK_* values are used on their own, the read and write pointers are |
| 437 | both modified. |
| 438 | </P> |
| 439 | |
| 440 | <P> |
| 441 | Note that the frames offset can be negative and in fact should be when SEEK_END is used for the |
| 442 | whence parameter. |
| 443 | </P> |
| 444 | <P> |
| 445 | sf_seek will return the offset in (multichannel) frames from the start of the audio data |
| 446 | or -1 if an error occured (ie an attempt is made to seek beyond the start or end of the file). |
| 447 | </P> |
| 448 | |
| 449 | <A NAME="error"></A> |
| 450 | <H2><BR><B>Error Reporting Functions</B></H2> |
| 451 | |
| 452 | |
| 453 | <PRE> |
| 454 | int sf_error (SNDFILE *sndfile) ; |
| 455 | </PRE> |
| 456 | <P> |
| 457 | This function returns the current error number for the given SNDFILE. |
| 458 | The error number may be one of the following: |
| 459 | </P> |
| 460 | <PRE> |
| 461 | enum |
| 462 | { SF_ERR_NO_ERROR = 0, |
| 463 | SF_ERR_UNRECOGNISED_FORMAT = 1, |
| 464 | SF_ERR_SYSTEM = 2, |
| 465 | SF_ERR_MALFORMED_FILE = 3, |
| 466 | SF_ERR_UNSUPPORTED_ENCODING = 4 |
| 467 | } ; |
| 468 | </PRE> |
| 469 | <!-- pepper --> |
| 470 | <P> |
| 471 | or any one of many other internal error values. |
| 472 | Applications should only test the return value against error values defined in |
| 473 | <sndfile.h> as the internal error values are subject to change at any |
| 474 | time. |
| 475 | For errors not in the above list, the function sf_error_number() can be used to |
| 476 | convert it to an error string. |
| 477 | </P> |
| 478 | |
| 479 | <PRE> |
| 480 | const char* sf_strerror (SNDFILE *sndfile) ; |
| 481 | const char* sf_error_number (int errnum) ; |
| 482 | </PRE> |
| 483 | |
| 484 | <P> |
| 485 | The error functions sf_strerror() and sf_error_number() convert the library's internal |
| 486 | error enumerations into text strings. |
| 487 | </P> |
| 488 | <PRE> |
| 489 | int sf_perror (SNDFILE *sndfile) ; |
| 490 | int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ; |
| 491 | </PRE> |
| 492 | |
| 493 | <P> |
| 494 | The functions sf_perror() and sf_error_str() are deprecated and will be dropped |
| 495 | from the library at some later date. |
| 496 | </P> |
| 497 | |
| 498 | <A NAME="close"></A> |
| 499 | <H2><BR><B>File Close Function</B></H2> |
| 500 | |
| 501 | <PRE> |
| 502 | int sf_close (SNDFILE *sndfile) ; |
| 503 | </PRE> |
| 504 | <!-- pepper --> |
| 505 | <P> |
| 506 | The close function closes the file, deallocates its internal buffers and returns |
| 507 | 0 on success or an error value otherwise. |
| 508 | </P> |
| 509 | <BR> |
| 510 | |
| 511 | <A NAME="write_sync"></A> |
| 512 | <H2><BR><B>Write Sync Function</B></H2> |
| 513 | |
| 514 | <PRE> |
| 515 | void sf_write_sync (SNDFILE *sndfile) ; |
| 516 | </PRE> |
| 517 | <!-- pepper --> |
| 518 | <P> |
| 519 | If the file is opened SFM_WRITE or SFM_RDWR, call the operating system's function |
| 520 | to force the writing of all file cache buffers to disk. If the file is opened |
| 521 | SFM_READ no action is taken. |
| 522 | </P> |
| 523 | <BR> |
| 524 | |
| 525 | |
| 526 | <A NAME="read"></A> |
| 527 | <H2><BR><B>File Read Functions (Items)</B></H2> |
| 528 | |
| 529 | <PRE> |
| 530 | sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; |
| 531 | sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; |
| 532 | sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; |
| 533 | sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; |
| 534 | </PRE> |
| 535 | |
| 536 | <P> |
| 537 | The file read items functions fill the array pointed to by ptr with the requested |
| 538 | number of items. The items parameter must be an integer product of the number |
| 539 | of channels or an error will occur. |
| 540 | </P> |
| 541 | <!-- pepper --> |
| 542 | <P> |
| 543 | It is important to note that the data type used by the calling program and the data |
| 544 | format of the file do not need to be the same. For instance, it is possible to open |
| 545 | a 16 bit PCM encoded WAV file and read the data using sf_read_float(). The library |
| 546 | seamlessly converts between the two formats on-the-fly. See |
| 547 | <A HREF="#note1">Note 1</A>. |
| 548 | </P> |
| 549 | <!-- pepper --> |
| 550 | <P> |
| 551 | The sf_read_XXXX functions return the number of items read. |
| 552 | Unless the end of the file was reached during the read, the return value should |
| 553 | equal the number of items requested. |
| 554 | Attempts to read beyond the end of the file will not result in an error but will |
| 555 | cause the sf_read_XXXX functions to return less than the number of items requested |
| 556 | or 0 if already at the end of the file. |
| 557 | </P> |
| 558 | |
| 559 | <A NAME="readf"></A> |
| 560 | <H2><BR><B>File Read Functions (Frames)</B></H2> |
| 561 | |
| 562 | <PRE> |
| 563 | sf_count_t sf_readf_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; |
| 564 | sf_count_t sf_readf_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; |
| 565 | sf_count_t sf_readf_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; |
| 566 | sf_count_t sf_readf_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; |
| 567 | </PRE> |
| 568 | <!-- pepper --> |
| 569 | <P> |
| 570 | The file read frames functions fill the array pointed to by ptr with the requested |
| 571 | number of frames of data. The array must be large enough to hold the product of |
| 572 | frames and the number of channels. |
| 573 | </P> |
| 574 | |
| 575 | <P><B> |
| 576 | Care must be taken to ensure that there is enough space in the array pointed to by |
| 577 | ptr, to take (frames * channels) number of items (shorts, ints, floats or doubles). |
| 578 | </B></P> |
| 579 | |
| 580 | <P> |
| 581 | The sf_readf_XXXX functions return the number of frames read. |
| 582 | Unless the end of the file was reached during the read, the return value should equal |
| 583 | the number of frames requested. |
| 584 | Attempts to read beyond the end of the file will not result in an error but will cause |
| 585 | the sf_readf_XXXX functions to return less than the number of frames requested or 0 if |
| 586 | already at the end of the file. |
| 587 | </P> |
| 588 | |
| 589 | <A NAME="write"></A> |
| 590 | <H2><BR><B>File Write Functions (Items)</B></H2> |
| 591 | |
| 592 | <PRE> |
| 593 | sf_count_t sf_write_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; |
| 594 | sf_count_t sf_write_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; |
| 595 | sf_count_t sf_write_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; |
| 596 | sf_count_t sf_write_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; |
| 597 | </PRE> |
| 598 | |
| 599 | <P> |
| 600 | The file write items functions write the data in the array pointed to by ptr to the file. |
| 601 | The items parameter must be an integer product of the number of channels or an error |
| 602 | will occur. |
| 603 | </P> |
| 604 | <!-- pepper --> |
| 605 | <P> |
| 606 | It is important to note that the data type used by the calling program and the data |
| 607 | format of the file do not need to be the same. For instance, it is possible to open |
| 608 | a 16 bit PCM encoded WAV file and write the data using sf_write_float(). The library |
| 609 | seamlessly converts between the two formats on-the-fly. See |
| 610 | <A HREF="#note1">Note 1</A>. |
| 611 | </P> |
| 612 | <P> |
| 613 | The sf_write_XXXX functions return the number of items written (which should be the |
| 614 | same as the items parameter). |
| 615 | </P> |
| 616 | |
| 617 | <A NAME="writef"></A> |
| 618 | <H2><BR><B>File Write Functions (Frames)</B></H2> |
| 619 | |
| 620 | <PRE> |
| 621 | sf_count_t sf_writef_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; |
| 622 | sf_count_t sf_writef_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; |
| 623 | sf_count_t sf_writef_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; |
| 624 | sf_count_t sf_writef_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; |
| 625 | </PRE> |
| 626 | |
| 627 | <P> |
| 628 | The file write frames functions write the data in the array pointed to by ptr to the file. |
| 629 | The array must be large enough to hold the product of frames and the number of channels. |
| 630 | </P> |
| 631 | <P> |
| 632 | The sf_writef_XXXX functions return the number of frames written (which should be the |
| 633 | same as the frames parameter). |
| 634 | </P> |
| 635 | |
| 636 | <A NAME="raw"></A> |
| 637 | <H2><BR><B>Raw File Read and Write Functions</B></H2> |
| 638 | <!-- pepper --> |
| 639 | <PRE> |
| 640 | sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; |
| 641 | sf_count_t sf_write_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; |
| 642 | </PRE> |
| 643 | |
| 644 | <P> |
| 645 | <b>Note:</b> Unless you are writing an external decoder/encode that uses |
| 646 | libsndfile to handle the file headers, you should not be using these |
| 647 | functions. |
| 648 | </P> |
| 649 | |
| 650 | <P> |
| 651 | The raw read and write functions read raw audio data from the audio file (not to be |
| 652 | confused with reading RAW header-less PCM files). The number of bytes read or written |
| 653 | must always be an integer multiple of the number of channels multiplied by the number |
| 654 | of bytes required to represent one sample from one channel. |
| 655 | </P> |
| 656 | <!-- pepper --> |
| 657 | <P> |
| 658 | The raw read and write functions return the number of bytes read or written (which |
| 659 | should be the same as the bytes parameter). |
| 660 | </P> |
| 661 | |
| 662 | <P> |
| 663 | <B> |
| 664 | Note : The result of using of both regular reads/writes and raw reads/writes on |
| 665 | compressed file formats other than SF_FORMAT_ALAW and SF_FORMAT_ULAW is undefined. |
| 666 | </B> |
| 667 | </P> |
| 668 | |
| 669 | <p> |
| 670 | See also : <a href="command.html#SFC_RAW_NEEDS_ENDSWAP">SFC_RAW_NEEDS_ENDSWAP</a> |
| 671 | </p> |
| 672 | |
| 673 | <A NAME="string"></A> |
| 674 | <H2><BR><B>Functions for Reading and Writing String Data</B></H2> |
| 675 | |
| 676 | |
| 677 | <PRE> |
| 678 | const char* sf_get_string (SNDFILE *sndfile, int str_type) ; |
| 679 | int sf_set_string (SNDFILE *sndfile, int str_type, const char* str) ; |
| 680 | </PRE> |
| 681 | |
| 682 | <P> |
| 683 | These functions allow strings to be set on files opened for write and to be |
| 684 | retrieved from files opened for read where supported by the given file type. |
| 685 | The <B>str_type</B> parameter can be any one of the following string types: |
| 686 | </P> |
| 687 | |
| 688 | <PRE> |
| 689 | enum |
| 690 | { SF_STR_TITLE, |
| 691 | SF_STR_COPYRIGHT, |
| 692 | SF_STR_SOFTWARE, |
| 693 | SF_STR_ARTIST, |
| 694 | SF_STR_COMMENT, |
| 695 | SF_STR_DATE, |
| 696 | SF_STR_ALBUM, |
| 697 | SF_STR_LICENSE, |
| 698 | SF_STR_TRACKNUMBER, |
| 699 | SF_STR_GENRE |
| 700 | } ; |
| 701 | </PRE> |
| 702 | |
| 703 | <P> |
| 704 | The sf_get_string() function returns the specified string if it exists and a |
| 705 | NULL pointer otherwise. |
| 706 | In addition to the string ids above, SF_STR_FIRST (== SF_STR_TITLE) and |
| 707 | SF_STR_LAST (always the same as the highest numbers string id) are also |
| 708 | available to allow iteration over all the available string ids. |
| 709 | </P> |
| 710 | |
| 711 | <P> |
| 712 | The sf_set_string() function sets the string data. |
| 713 | It returns zero on success and non-zero on error. |
| 714 | The error code can be converted to a string using sf_error_number(). |
| 715 | </P> |
| 716 | |
| 717 | |
| 718 | <P> |
| 719 | |
| 720 | </P> |
| 721 | |
| 722 | <HR> |
| 723 | |
| 724 | <A NAME="note1"></A> |
| 725 | <H2><BR><B>Note 1</B></H2> |
| 726 | <!-- pepper --> |
| 727 | <P> |
| 728 | When converting between integer PCM formats of differing size (ie using sf_read_int() |
| 729 | to read a 16 bit PCM encoded WAV file) libsndfile obeys one simple rule: |
| 730 | </P> |
| 731 | |
| 732 | <P CLASS=indent_block> |
| 733 | Whenever integer data is moved from one sized container to another sized container, |
| 734 | the most significant bit in the source container will become the most significant bit |
| 735 | in the destination container. |
| 736 | </P> |
| 737 | |
| 738 | <P> |
| 739 | When converting between integer data and floating point data, different rules apply. |
| 740 | The default behaviour when reading floating point data (sf_read_float() or |
| 741 | sf_read_double ()) from a file with integer data is normalisation. Regardless of |
| 742 | whether data in the file is 8, 16, 24 or 32 bit wide, the data will be read as |
| 743 | floating point data in the range [-1.0, 1.0]. Similarly, data in the range [-1.0, 1.0] |
| 744 | will be written to an integer PCM file so that a data value of 1.0 will be the largest |
| 745 | allowable integer for the given bit width. This normalisation can be turned on or off |
| 746 | using the <A HREF="command.html">sf_command</A> interface. |
| 747 | </P> |
| 748 | |
| 749 | <A NAME="note2"></A> |
| 750 | <H2><BR><B>Note 2</B></H2> |
| 751 | |
| 752 | <P> |
| 753 | Reading a file containg floating point data (allowable with WAV, AIFF, AU and other |
| 754 | file formats) using integer read methods (sf_read_short() or sf_read_int()) can |
| 755 | produce unexpected results. |
| 756 | For instance the data in the file may have a maximum absolute value < 1.0 which |
| 757 | would mean that all sample values read from the file will be zero. |
| 758 | In order to read these files correctly using integer read methods, it is recommended |
| 759 | that you use the |
| 760 | <A HREF="command.html">sf_command</A> |
| 761 | interface, a command of |
| 762 | <A HREF="command.html#SFC_SET_SCALE_FLOAT_INT_READ">SFC_SET_SCALE_FLOAT_INT_READ</A> |
| 763 | and a parameter of SF_TRUE to force correct scaling. |
| 764 | </P> |
| 765 | <!-- pepper --> |
| 766 | <HR> |
| 767 | <!-- pepper --> |
| 768 | <P> |
| 769 | The libsndfile home page is |
| 770 | <A HREF="http://www.mega-nerd.com/libsndfile/">here</A>. |
| 771 | </P> |
| 772 | <P> |
| 773 | Version : 1.0.25 |
| 774 | </P> |
| 775 | <!-- pepper --> |
| 776 | <!-- pepper --> |
| 777 | <!-- pepper --> |
| 778 | <!-- pepper --> |
| 779 | |
| 780 | </BODY> |
| 781 | </HTML> |