Mercurial > hg > sv-dependency-builds

comparison src/libsndfile-1.0.25/doc/api.html @ 0:c7265573341e

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