Mercurial > hg > sv-dependency-builds

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

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