Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.27/doc/api.html @ 169:223a55898ab9 tip default

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