Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.25/doc/api.html @ 83:ae30d91d2ffe

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