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