Gitiles
Code Review Sign In
review.jami.net / jami-client-android / 3874e557ab7b54f78566363f6deeb3d08933f5dd / . / jni / libsndfile / doc / api.html
blob: 33d53dd02f8fe4c0ee88e513e6d5c7aa2aafe385 [file] [log] [blame]
Alexandre Lision7c6f4a62013-09-05 13:27:01 -0400[diff] [blame]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>
58The 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>
113SNDFILE* 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>
125The SF_INFO structure is for passing data between the calling function and the library
126when 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>
141The 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>
151When opening a file for read, the <b>format</B> field should be set to zero before
152calling sf_open().
153The only exception to this is the case of RAW files where the caller has to set
154the samplerate, channels and format fields to valid values.
155All other fields of the structure are filled in by the library.
156</P>
157<!-- pepper -->
158<P>
159When opening a file for write, the caller must fill in structure members samplerate,
160channels, and format.
161</P>
162<!-- pepper -->
163<P>
164The format field in the above SF_INFO structure is made up of the bit-wise OR of a
165major format type (values between 0x10000 and 0x08000000), a minor format type
166(with values less than 0x10000) and an optional endian-ness value.
167The currently understood formats are listed in sndfile.h as follows and also include
168bitmasks for separating major and minor file types.
169Not 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>
249Every call to sf_open() should be matched with a call to sf_close() to free up
250memory allocated during the call to sf_open().
251</P>
252<!-- pepper -->
253<P>
254On success, the sf_open function returns a non-NULL pointer which should be
255passed as the first parameter to all subsequent libsndfile calls dealing with
256that audio file.
257On fail, the sf_open function returns a NULL pointer.
258An 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
271application and the libsndfile DLL are linked to different versions of the
272Microsoft C runtime DLL.
273</P>
274<P>
275The second open function takes a file descriptor of a file that has already been
276opened.
277Care should be taken to ensure that the mode of the file represented by the
278descriptor matches the mode argument.
279This 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>
293Every call to sf_open_fd() should be matched with a call to sf_close() to free up
294memory allocated during the call to sf_open().
295</P>
296
297<P>
298When sf_close() is called, the file descriptor is only closed if the <B>close_desc</B>
299parameter was TRUE when the sf_open_fd() function was called.
300</P>
301
302<P>
303On success, the sf_open_fd function returns a non-NULL pointer which should be
304passed as the first parameter to all subsequent libsndfile calls dealing with
305that audio file.
306On 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>
331Libsndfile calls the callbacks provided by the SF_VIRTUAL_IO structure when opening, reading
332and writing to the virtual file context. The user_data pointer is a user defined context which
333will 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>
347The 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>
354The 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>
362The 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>
369The virtual file context must copy ("read") "count" bytes into the
370buffer 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>
377The virtual file context must process "count" bytes stored in the
378buffer 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>
385Return 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>
397This function allows the caller to check if a set of parameters in the SF_INFO struct
398is valid before calling sf_open (SFM_WRITE).
399</P>
400<P>
401sf_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>
412The file seek functions work much like lseek in unistd.h with the exception that
413the non-audio data is ignored and the seek only moves within the audio data section of
414the file.
415In addition, seeks are defined in number of (multichannel) frames.
416Therefore, a seek in a stereo file from the current position forward with an offset
417of 1 would skip forward by one sample of both channels.
418</P>
419
420<P>
421like 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>
431Internally, libsndfile keeps track of the read and write locations using separate
432read and write pointers.
433If a file has been opened with a mode of SFM_RDWR, bitwise OR-ing the standard whence
434values above with either SFM_READ or SFM_WRITE allows the read and write pointers to
435be modified separately.
436If the SEEK_* values are used on their own, the read and write pointers are
437both modified.
438</P>
439
440<P>
441Note that the frames offset can be negative and in fact should be when SEEK_END is used for the
442whence parameter.
443</P>
444<P>
445sf_seek will return the offset in (multichannel) frames from the start of the audio data
446or -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>
457This function returns the current error number for the given SNDFILE.
458The 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>
471or any one of many other internal error values.
472Applications 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
474time.
475For errors not in the above list, the function sf_error_number() can be used to
476convert 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>
485The error functions sf_strerror() and sf_error_number() convert the library's internal
486error 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>
494The functions sf_perror() and sf_error_str() are deprecated and will be dropped
495from 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>
506The close function closes the file, deallocates its internal buffers and returns
5070 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>
519If the file is opened SFM_WRITE or SFM_RDWR, call the operating system's function
520to force the writing of all file cache buffers to disk. If the file is opened
521SFM_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>
537The file read items functions fill the array pointed to by ptr with the requested
538number of items. The items parameter must be an integer product of the number
539of channels or an error will occur.
540</P>
541<!-- pepper -->
542<P>
543It is important to note that the data type used by the calling program and the data
544format of the file do not need to be the same. For instance, it is possible to open
545a 16 bit PCM encoded WAV file and read the data using sf_read_float(). The library
546seamlessly converts between the two formats on-the-fly. See
547<A HREF="#note1">Note 1</A>.
548</P>
549<!-- pepper -->
550<P>
551The sf_read_XXXX functions return the number of items read.
552Unless the end of the file was reached during the read, the return value should
553equal the number of items requested.
554Attempts to read beyond the end of the file will not result in an error but will
555cause the sf_read_XXXX functions to return less than the number of items requested
556or 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>
570The file read frames functions fill the array pointed to by ptr with the requested
571number of frames of data. The array must be large enough to hold the product of
572frames and the number of channels.
573</P>
574
575<P><B>
576Care must be taken to ensure that there is enough space in the array pointed to by
577ptr, to take (frames * channels) number of items (shorts, ints, floats or doubles).
578</B></P>
579
580<P>
581The sf_readf_XXXX functions return the number of frames read.
582Unless the end of the file was reached during the read, the return value should equal
583the number of frames requested.
584Attempts to read beyond the end of the file will not result in an error but will cause
585the sf_readf_XXXX functions to return less than the number of frames requested or 0 if
586already 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>
600The file write items functions write the data in the array pointed to by ptr to the file.
601The items parameter must be an integer product of the number of channels or an error
602will occur.
603</P>
604<!-- pepper -->
605<P>
606It is important to note that the data type used by the calling program and the data
607format of the file do not need to be the same. For instance, it is possible to open
608a 16 bit PCM encoded WAV file and write the data using sf_write_float(). The library
609seamlessly converts between the two formats on-the-fly. See
610<A HREF="#note1">Note 1</A>.
611</P>
612<P>
613The sf_write_XXXX functions return the number of items written (which should be the
614same 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>
628The file write frames functions write the data in the array pointed to by ptr to the file.
629The array must be large enough to hold the product of frames and the number of channels.
630</P>
631<P>
632The sf_writef_XXXX functions return the number of frames written (which should be the
633same 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
646libsndfile to handle the file headers, you should not be using these
647functions.
648</P>
649
650<P>
651The raw read and write functions read raw audio data from the audio file (not to be
652confused with reading RAW header-less PCM files). The number of bytes read or written
653must always be an integer multiple of the number of channels multiplied by the number
654of bytes required to represent one sample from one channel.
655</P>
656<!-- pepper -->
657<P>
658The raw read and write functions return the number of bytes read or written (which
659should be the same as the bytes parameter).
660</P>
661
662<P>
663<B>
664Note : The result of using of both regular reads/writes and raw reads/writes on
665compressed file formats other than SF_FORMAT_ALAW and SF_FORMAT_ULAW is undefined.
666</B>
667</P>
668
669<p>
670See 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>
683These functions allow strings to be set on files opened for write and to be
684retrieved from files opened for read where supported by the given file type.
685The <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>
704The sf_get_string() function returns the specified string if it exists and a
705NULL pointer otherwise.
706In addition to the string ids above, SF_STR_FIRST (== SF_STR_TITLE) and
707SF_STR_LAST (always the same as the highest numbers string id) are also
708available to allow iteration over all the available string ids.
709</P>
710
711<P>
712The sf_set_string() function sets the string data.
713It returns zero on success and non-zero on error.
714The 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>
728When converting between integer PCM formats of differing size (ie using sf_read_int()
729to read a 16 bit PCM encoded WAV file) libsndfile obeys one simple rule:
730</P>
731
732<P CLASS=indent_block>
733Whenever integer data is moved from one sized container to another sized container,
734the most significant bit in the source container will become the most significant bit
735in the destination container.
736</P>
737
738<P>
739When converting between integer data and floating point data, different rules apply.
740The default behaviour when reading floating point data (sf_read_float() or
741sf_read_double ()) from a file with integer data is normalisation. Regardless of
742whether data in the file is 8, 16, 24 or 32 bit wide, the data will be read as
743floating point data in the range [-1.0, 1.0]. Similarly, data in the range [-1.0, 1.0]
744will be written to an integer PCM file so that a data value of 1.0 will be the largest
745allowable integer for the given bit width. This normalisation can be turned on or off
746using 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>
753Reading a file containg floating point data (allowable with WAV, AIFF, AU and other
754file formats) using integer read methods (sf_read_short() or sf_read_int()) can
755produce unexpected results.
756For instance the data in the file may have a maximum absolute value &lt; 1.0 which
757would mean that all sample values read from the file will be zero.
758In order to read these files correctly using integer read methods, it is recommended
759that you use the
760 <A HREF="command.html">sf_command</A>
761interface, a command of
762 <A HREF="command.html#SFC_SET_SCALE_FLOAT_INT_READ">SFC_SET_SCALE_FLOAT_INT_READ</A>
763and 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>
773Version : 1.0.25
774</P>
775<!-- pepper -->
776<!-- pepper -->
777<!-- pepper -->
778<!-- pepper -->
779
780</BODY>
781</HTML>