Debian Codegraph @

docs/api.md

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