interpreter/lib/src/libsndfile-1.0.25/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 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 &lt;stdio.h&gt;
  63       #include &lt;sndfile.h&gt;
  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 &lt;sndfile.h&gt; 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 &lt; 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>