Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.27/doc/api.html @ 40:1df64224f5ac

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