doc/api.html

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