TorqueGameEngines/Torque3D
1
0
Fork 0
mirror of https://github.com/TorqueGameEngines/Torque3D.git synced 2026-04-29 16:25:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Initial commit

Browse source 
added libraries:
opus
flac
libsndfile

updated:
libvorbis
libogg
openal

- Everything works as expected for now. Bare in mind libsndfile needed the check for whether or not it could find the xiph libraries removed in order for this to work.
This commit is contained in:
marauder2k7 2024-03-21 17:33:47 +00:00
parent 05a083ca6f
commit a745fc3757
1954 changed files with 431332 additions and 21037 deletions
Download patch file Download diff file Expand all files Collapse all files

482
Engine/lib/libsndfile/docs/FAQ.md Normal file
View file

@ -0,0 +1,482 @@
---
layout: default
title: libsndfile : Frequently Asked Questions.
---
# libsndfile : Frequently Asked Questions
1. [Do you plan to support XYZ codec in libsndfile?](#Q001)
2. [In version 0 the SF\_INFO struct had a pcmbitwidth field but version 1 does not. Why?](#Q002)
3. [Compiling is really slow on MacOS X. Why?](#Q003)
4. [When trying to compile libsndfile on Solaris I get a "bad substitution" error during linking. What can I do to fix this?](#Q004)
5. [Why doesn't libsndfile do interleaving/de-interleaving?](#Q005)
6. [What's the best format for storing temporary files?](#Q006)
7. [On Linux/Unix/MacOS X, what's the best way of detecting the presence of libsndfile?](#Q007)
8. [I have libsndfile installed and now I want to use it. I just want a simple Makefile\! What do I do?](#Q008)
9. [How about adding the ability to write/read sound files to/from memory buffers?](#Q009)
10. [Reading a 16 bit PCM file as normalised floats and then writing them back changes some sample values. Why?](#Q010)
11. [I'm having problems with u-law encoded WAV files generated by libsndfile in Winamp. Why?](#Q011)
12. [I'm looking at sf\_read\*. What are items? What are frames?](#Q012)
13. [Why can't libsndfile open this Sound Designer II (SD2) file?](#Q013)
14. [I'd like to statically link libsndfile to my closed source application. Can I buy a license so that this is possible?](#Q014)
15. [My program is crashing during a call to a function in libsndfile. Is this a bug in libsndfile?](#Q015)
16. [Will you accept a fix for compiling libsndfile with compiler X?](#Q016)
17. [Can libsndfile read/write files from/to UNIX pipes?](#Q017)
18. [Is it possible to build a Universal Binary on Mac OS X?](#Q018)
19. [I have project files for Visual Studio / XCode / Whatever. Why don't you distribute them with libsndfile?](#Q019)
20. [Why doesn't libsndfile support MP3?](#Q020)
21. [How do I use libsndfile in a closed source or commercial program and comply with the license?](#Q021)
22. [What versions of windows does libsndfile work on?](#Q022)
23. [I'm cross compiling libsndfile for another platform. How can I run the test suite?](#Q023)
-----
## Q1 : Do you plan to support XYZ codec in libsndfile? {#Q001}
If source code for XYZ codec is available under a suitable license (LGPL, BSD,
MIT etc) then yes, I'd like to add it.
If suitable documentation is available on how to decode and encode the format
then maybe, depending on how much work is involved.
If XYZ is some proprietary codec where no source code or documentation is
available then no.
So if you want support for XYZ codec, first find existing source code or
documentation. If you can't find either then the answer is no.
## Q2 : In version 0 the SF\_INFO struct had a pcmbitwidth field but version 1 does not. Why? {#Q002}
This was dropped for a number of reasons:
- pcmbitwidth makes little sense on compressed or floating point formats
- with the new API you really don't need to know it
As documented [here](api.md#note-1) there is now a well defined behaviour which
ensures that no matter what the bit width of the source file, the scaling always
does something sensible. This makes it safe to read 8, 16, 24 and 32 bit PCM
files using `sf_read_short()` and always have the optimal behaviour.
## Q3 : Compiling is really slow on MacOS X. Why? {#Q003}
When you configure and compile libsndfile, it uses the /bin/sh shell for a
number of tasks (ie configure script and libtool). Older versions of OS X
(10.2?) shipped a really crappy Bourne shell as /bin/sh which resulted in
**really** slow compiles. Newer version of OS X ship GNU Bash as /bin/sh and
this answer doesn't apply in that case.
To fix this I suggest that you install the GNU Bash shell, rename /bin/sh to
/bin/sh.old and make a symlink from /bin/sh to the bash shell. Bash is designed
to behave as a Bourne shell when it is called as /bin/sh.
When I did this on my iBook running MacOS X, compile times dropped from 13
minutes to 3 minutes.
## Q4 : When trying to compile libsndfile on Solaris I get a "bad substitution" error on linking. Why? {#Q004}
It seems that the Solaris Bourne shell disagrees with GNU libtool.
To fix this I suggest that you install the GNU Bash shell, rename /bin/sh to
/bin/sh.old and make a symlink from /bin/sh to the bash shell. Bash is designed
to behave as a Bourne shell when it is called as /bin/sh.
## Q5 : Why doesn't libsndfile do interleaving/de-interleaving? {#Q005}
This problem is bigger than it may seem at first.
For a stereo file, it is a pretty safe bet that a simple interleaving/
de-interleaving could satisfy most users. However, for files with more than 2
channels this is unlikely to be the case. If the user has a 4 channel file and
want to play that file on a stereo output sound card they either want the first
2 channels or they want some mixed combination of the 4 channels.
When you add more channels, the combinations grow exponentially and it becomes
increasingly difficult to cover even a sensible subset of the possible
combinations. On top of that, coding any one style of interleaver/de-interleaver
is trivial, while coding one that can cover all combinations is far from
trivial. This means that this feature will not be added any time soon.
## Q6 : What's the best format for storing temporary files? {#Q006}
When you want to store temporary data there are a number of requirements:
- A simple, easy to parse header.
- The format must provide the fastest possible read and write rates (ie avoid
conversions and encoding/decoding).
- The file format must be reasonably common and playable by most players.
- Able to store data in either endian-ness.
The format which best meets these requirements is AU, which allows data to be
stored in any one of short, int, float and double (among others) formats.
For instance, if an application uses float data internally, its temporary files
should use a format of (SF_ENDIAN_CPU | SF_FORMAT_AU | SF_FORMAT_FLOAT) which
will store big endian float data in big endian CPUs and little endian float data
on little endian CPUs. Reading and writing this format will not require any
conversions or byte swapping regardless of the host CPU.
## Q7 : On Linux/Unix/MaxOS X, what's the best way of detecting the presence of libsndfile using autoconf? {#Q007}
libsndfile uses the pkg-config (man pkg-config) method of registering itself
with the host system. The best way of detecting its presence is using something
like this in configure.ac (or configure.in):
PKG_CHECK_MODULES(SNDFILE, sndfile >= 1.0.2, ac_cv_sndfile=1, ac_cv_sndfile=0)
AC_DEFINE_UNQUOTED([HAVE_SNDFILE],${ac_cv_sndfile},
[Set to 1 if you have libsndfile.])
AC_SUBST(SNDFILE_CFLAGS)
AC_SUBST(SNDFILE_LIBS)
This will automatically set the **SNDFILE_CFLAGS** and **SNDFILE_LIBS**
variables which can be used in Makefile.am like this:
SNDFILE_CFLAGS = @SNDFILE_CFLAGS@
SNDFILE_LIBS = @SNDFILE_LIBS@
If you install libsndfile from source, you will probably need to set the
**PKG_CONFIG_PATH** environment variable as suggested at the end of the
libsndfile configure process. For instance on my system I get this:
-=-=-=-=-=-=-=-=-=-= Configuration Complete =-=-=-=-=-=-=-=-=-=-
Configuration summary :
Version : ..................... 1.0.5
Experimental code : ........... no
Tools :
Compiler is GCC : ............. yes
GCC major version : ........... 3
Installation directories :
Library directory : ........... /usr/local/lib
Program directory : ........... /usr/local/bin
Pkgconfig directory : ......... /usr/local/lib/pkgconfig
Compiling some other packages against libsndfile may require
the addition of "/usr/local/lib/pkgconfig" to the
PKG_CONFIG_PATH environment variable.
## Q8 : I have libsndfile installed and now I want to use it. I just want a simple Makefile\! What do I do? {#Q008}
The **pkg-config** program makes finding the correct compiler flag values and
library location far easier. During the installation of libsndfile, a file named
**sndfile.pc** is installed in the directory **${libdir}/pkgconfig** (ie if
libsndfile is installed in **/usr/local/lib**, **sndfile.pc** will be installed
in **/usr/local/lib/pkgconfig/**).
In order for pkg-config to find sndfile.pc it may be necessary to point the
environment variable **PKG_CONFIG_PATH** in the right direction.
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
Then, to compile a C file into an object file, the command would be:
gcc `pkg-config --cflags sndfile` -c somefile.c
and to link a number of objects into an executable that links against
libsndfile, the command would be:
gcc `pkg-config --libs sndfile` obj1.o obj2.o -o program
## Q9 : How about adding the ability to write/read sound files to/from memory buffers? {#Q009}
This has been [added](api.md#open_virtual) for version 1.0.12.
## Q10 : Reading a 16 bit PCM file as normalised floats and then writing them back changes some sample values. Why? {#Q010}
This is caused by the fact that the conversion from 16 bit short to float is
done by dividing by 32768 (0x8000 in hexadecimal) while the conversion from
float to 16 bit short is done by multiplying by 32767 (0x7FFF in hex). So for
instance, a value in a 16 bit PCM file of 20000 gets read as a floating point
number of 0.6103515625 (20000.0 / 0x8000). Converting that back to a 16 bit
short results in a value of 19999.3896484375 (0.6103515625 \* 0x7FFF) which then
gets rounded down to 19999.
You will notice that for this particular case, the error is 1 in 20000 or
0.005%. Interestingly, for values of less than 16369, dividing by 0x8000
followed by multiplying by 0x7FFF and then rounding the result, gives back the
original value. It turns out that as long as the host operating system supplies
the 1999 ISO C Standard functions **lrintf** and **lrint** (or a replacement has
been supplied) then the maximum possible error is 1 in 16369 or about 0.006%.
Regardless of the size of the error, the reason why this is done is rather
subtle.
In a file containing 16 bit PCM samples, the values are restricted to the range
[-32768, 32767] while we want floating point values in the range [-1.0, 1.0].
The only way to do this conversion is to do a floating point division by a value
of 0x8000. Converting the other way, the only way to ensure that floating point
values in the range [-1.0, 1.0] are within the valid range allowed by a 16 bit
short is to multiply by 0x7FFF.
Some people would say that this is a severe short-coming of libsndfile. I would
counter that anybody who is constantly converting back and forth between 16 bit
shorts and normalised floats is going to suffer other losses in audio quality
that they should also be concerned about.
Since this problem only occurs when converting between integer data on disk and
normalized floats in the application, it can be avoided by using something other
than normalized floats in the application. Alternatives to normalized floats are
the **short** and **int** data types (ie using sf_read_short or sf_read_int) or
using un-normalized floats (see
[SFC_SET_NORM_FLOAT](command.html#sfc_set_norm_float)).
Another way to deal with this problem is to consider 16 bit short data as a
final destination format only, not as an intermediate storage format. All
intermediate data (ie which is going to be processed further) should be stored
in floating point format which is supported by all of the most common file
formats. If floating point files are considered too large (2 times the size of a
16 bit PCM file), it would also be possible to use 24 bit PCM as an intermediate
storage format (and which is also supported by most common file types).
## Q11 : I'm having problems with u-law encoded WAV files generated by libsndfile in Winamp. Why? {#Q011}
This is actually a Winamp problem. The official Microsoft spec suggests that the
'fmt ' chunk should be 18 bytes. Unfortunately at least one of Microsoft's own
applications (Sound Recorder on Win98 I believe) did not accept 18 bytes 'fmt '
chunks.
Michael Lee did some experimenting and found that:
> I have checked that Windows Media Player 9, QuickTime Player 6.4, RealOne
> Player 2.0 and GoldWave 5.06 can all play u-law files with 16-byte or 18-byte
> 'fmt ' chunk. Only Winamp (2.91) and foobar2000 are unable to play u-law files
> with 16-byte 'fmt ' chunk.
Even this is a very small sampling of all the players out there. For that reason
it is probably not a good idea to change this now because there is the risk of
breaking something that currently works.
## Q12 : I'm looking at sf_read*. What are items? What are frames? {#Q012}
An `item` is a single sample of the data type you are reading; ie a single
`short` value for `sf_read_short` or a single `float` for `sf_read_float`.
For a sound file with only one channel, a frame is the same as a item (ie a
single sample) while for multi channel sound files, a single frame contains a
single item for each channel.
Here are two simple, correct examples, both of which are assumed to be working
on a stereo file, first using items:
```c
#define CHANNELS 2
short data [CHANNELS * 100] ;
sf_count items_read = sf_read_short (file, data, 200) ;
assert (items_read == 200) ;
```
and now reading the exact same amount of data using frames:
```c
#define CHANNELS 2
short data [CHANNELS * 100] ;
sf_count frames_read = sf_readf_short (file, data, 100) ;
assert (frames_read == 100) ;
```
## Q13 : Why can't libsndfile open this Sound Designer II (SD2) file? {#Q013}
This is somewhat complicated. First some background.
SD2 files are native to the Apple Macintosh platform and use features of the Mac
filesystem (file resource forks) to store the file's sample rate, number of
channels, sample width and more. When you look at a file and its resource fork
on Mac OS X it looks like this:
-rw-r--r-- 1 erikd erikd 46512 Oct 18 22:57 file.sd2
-rw-r--r-- 1 erikd erikd 538 Oct 18 22:57 file.sd2/rsrc
Notice how the file itself looks like a directory containing a single file named
**rsrc**. When libsndfile is compiled for MacOS X, it should open (for write and
read) SD2 file with resource forks like this without any problems. It will also
handle files with the resource fork in a separate file as described below.
When SD2 files are moved to other platforms, the resource fork of the file can
sometimes be dropped altogether. All that remains is the raw audio data and no
information about the number of channels, sample rate or bit width which makes
it a little difficult for libsndfile to open the file.
However, it is possible to safely move an SD2 file to a Linux or Windows
machine. For instance, when an SD2 file is copied from inside MacOS X to a
windows shared directory or a Samba share (ie Linux), MacOS X is clever enough
to store the resource fork of the file in a separate hidden file in the same
directory like this:
-rw-r--r-- 1 erikd erikd 538 Oct 18 22:57 ._file.sd2
-rw-r--r-- 1 erikd erikd 46512 Oct 18 22:57 file.sd2
Regardless of what platform it is running on, when libsndfile is asked to open a
file named **"foo"** and it can't recognize the file type from the data in the
file, it will attempt to open the resource fork and if that fails, it then tries
to open a file named **"._foo"** to see if the file has a valid resource fork.
This is the same regardless of whether the file is being opened for read or
write.
In short, libsndfile should open SD2 files with a valid resource fork on all of
the platforms that libsndfile supports. If a file has lost its resource fork,
the only option is the open the file using the SF_FORMAT_RAW option and guessing
its sample rate, channel count and bit width.
Occasionally, when SD2 files are moved to other systems, the file is
[BinHexed](http://www.macdisk.com/binhexen.php3) which wraps the resource fork
and the data fork together. For these files, it would be possible to write a
BinHex parser but there is not a lot to gain considering how rare these BinHexed
SD2 files are.
## Q14 : I'd like to statically link libsndfile to my closed source application. Can I buy a license so that this is possible? {#Q014}
Unfortunately no. libsndfile contains code written by other people who have
agreed that their code be used under the GNU LGPL but no more. Even if they were
to agree, there would be significant difficulties in dividing up the payments
fairly.
The **only** way you can legally use libsndfile as a statically linked library
is if your application is released under the GNU GPL or LGPL.
## Q15 : My program is crashing during a call to a function in libsndfile. Is this a bug in libsndfile? {#Q015}
libsndfile is being used by large numbers of people all over the world without
any problems like this. That means that it is much more likely that your code
has a bug than libsndfile. However, it is still possible that there is a bug in
libsndfile.
To figure out whether it is your code or libsndfile you should do the following:
- Make sure you are compiling your code with warnings switched on and that you
fix as many warnings as possible. With the GNU compiler (gcc) I would
recommend at least **-W -Wall -Werror** which will force you to fix all
warnings before you can run the code.
- Try using a memory debugger. [Valgrind](http://valgrind.kde.org/) on x86 Linux
is excellent. [Purify](http://www.ibm.com/software/awdtools/purify/) also has
a good reputation.
- If the code is clean after the above two steps and you still get a crash in
libsndfile, then send me a small snippet of code (no more than 30-40 lines)
which includes the call to sf_open() and also shows how all variables passed
to/returned from sf_open() are defined.
## Q16 : Will you accept a fix for compiling libsndfile with compiler X? {#Q016}
If compiler X is a C++ compiler then no. C and C++ are different enough to make
writing code that compiles as valid C and valid C++ too difficult. I would
rather spend my time fixing bugs and adding features.
If compiler X is a C compiler then I will do what I can as long as that does not
hamper the correctness, portability and maintainability of the existing code. It
should be noted however that libsndfile uses features specified by the 1999 ISO
C Standard. This can make compiling libsndfile with some older compilers
difficult.
## Q17 : Can libsndfile read/write files from/to UNIX pipes? {#Q017}
Yes, libsndfile can read files from pipes. Unfortunately, the write case is much
more complicated.
File formats like AIFF and WAV have information at the start of the file (the
file header) which states the length of the file, the number of sample frames
etc. This information must be filled in correctly when the file header is
written, but this information is not reliably known until the file is closed.
This means that libsndfile cannot write AIFF, WAV and many other file types to a
pipe.
However, there is at least one file format (AU) which is specifically designed
to be written to a pipe. Like AIFF and WAV, AU has a header with a sample frames
field, but it is specifically allowable to set that frames field to 0x7FFFFFFF
if the file length is not known when the header is written. The AU file format
can also hold data in many of the standard formats (ie SF_FORMAT_PCM_16,
SF_FORMAT_PCM_24, SF_FORMAT_FLOAT etc) as well as allowing data in both big and
little endian format.
See also [FAQ Q6](#Q006).
## Q18 : Is it possible to build a Universal Binary on Mac OS X? {#Q018}
Yes, but you must do two separate configure/build/test runs; one on PowerPC and
one on Intel. It is then possible to merge the binaries into a single universal
binary using one of the programs in the Apple tool chain.
It is **not** possible to build a working universal binary via a single
compile/build run on a single CPU.
The problem is that the libsndfile build process detects features of the CPU its
being built for during the configure process and when building a universal
binary, configure is only run once and that data is then used for both CPUs.
That configure data will be wrong for one of those CPUs. You will still be able
to compile libsndfile, and the test suite will pass on the machine you compiled
it on. However, if you take the universal binary test suite programs compiled on
one CPU and run them on the other, the test suite will fail.
Part of the problem is that the CPU endian-ness is detected at configure time.
Yes, I know the Apple compiler defines one of the macros \_\_LITTLE\_ENDIAN\_\_
and \_\_BIG\_ENDIAN\_\_, but those macros are not part of the 1999 ISO C
Standard and they are not portable.
Endian issues are not the only reason why the cross compiled binary will fail.
The configure script also detects other CPU specific idiosyncrasies to provide
more optimized code.
Finally, the real show stopper problem with universal binaries is the problem
with the test suite. libsndfile contains a huge, comprehensive test suite. When
you compile a universal binary and run the test suite, you only test the native
compile. The cross compiled binary (the one with the much higher chance of
having problems) cannot be tested.
Now, if you have read this far you're probably thinking there must be a way to
fix this and there probably is. The problem is that its a hell of a lot of work
and would require significant changes to the configure process, the internal
code and the test suite. In addition, these changes must not break compilation
on any of the platforms libsndfile is currently working on.
## Q19 : I have project files for Visual Studio / XCode / Whatever. Why don't you distribute them with libsndfile? {#Q019}
Use CMake project.
## Q20 : Why doesn't libsndfile support MP3? {#Q020}
~~In the past, MP3 was not supported because the technology behind MP3 was
patented. Those patents have now expired and there is an
[open ticket](https://github.com/libsndfile/libsndfile/issues/258) to implement
MP3 support.~~
**Update :** Starting from version 1.1.0 libsndfile supports MP3 format.
## Q21 : How do I use libsndfile in a closed source or commercial program and comply with the license? {#Q021}
Here is a checklist of things you need to do to make sure your use of libsndfile
in a closed source or commercial project complies with the license libsndfile is
released under, the GNU Lesser General Public License (LGPL):
- Make sure you are linking to libsndfile as a shared library (Linux and Unix
systems), Dynamic Link Library (Microsoft Windows) or dynlib (Mac OS X). If
you are using some other operating system that doesn't allow dynamically
linked libraries, you will not be able to use libsndfile unless you release
the source code to your program.
- In the licensing documentation for your program, add a statement that your
software depends on libsndfile and that libsndfile is released under the GNU
Lesser General Public License, either
[version 2.1](http://www.gnu.org/licenses/lgpl-2.1.txt) or optionally
[version 3](http://www.gnu.org/licenses/lgpl.txt).
- Include the text for both versions of the license, possibly as separate files
named libsndfile_lgpl_v2_1.txt and libsndfile_lgpl_v3.txt.
## Q22 : What versions of Windows does libsndfile work on? {#Q022}
New versions of libsndfile binary releases require Wiindows Vista. If you need
Windows XP support, you can build DLL from sources, we don't use specific WinXP
features.
## Q23 : I'm cross compiling libsndfile for another platform. How can I run the test suite? {#Q023}
Since version 1.0.21 the top level Makefile has an extra make target,
'test-tarball'. Building this target creates a tarball called called:
` libsndfile-testsuite-${host_triplet}-${version}.tar.gz`
in the top level directory. This tarball can then be copied to the target
platform. Once untarred and test script `test_wrapper.sh` can be run from the
top level of the extracted tarball.

8
Engine/lib/libsndfile/docs/_config.yml Normal file
View file

@ -0,0 +1,8 @@
---
author: "The libsndfile team"
version: "1.2.2"
markdown: kramdown
plugins:
- jekyll-default-layout
---

1
Engine/lib/libsndfile/docs/_includes/logo.html Normal file
View file

@ -0,0 +1 @@
<img src="libsndfile.jpg" class="image-logo" height=98 width=367 alt="Logo">

18
Engine/lib/libsndfile/docs/_layouts/default.html Normal file
View file

@ -0,0 +1,18 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ page.title }}</title>
<link rel="stylesheet" href="libsndfile.css" type="text/css" media="all">
<link rel="stylesheet" href="print.css" type="text/css" media="print">
</head>
<body>
{{ content }}
<footer>
<hr>
<p>The libsndfile home page is <a href="http://libsndfile.github.io/libsndfile/">here</a>.</p>
<p>The libsndfile version: {{ site.version }}.</p>
</footer>
</body>
</html>

34
Engine/lib/libsndfile/docs/_layouts/home.html Normal file
View file

@ -0,0 +1,34 @@
---
layout: default
keywords: WAV AIFF AU SVX PAF NIST W64 libsndfile sound audio dsp Linux
robots: nofollow
title: libsndfile home page
---
<footer>
{% include logo.html %}
<nav>
<a href="#history">History</a> -+-
<a href="#features">Features</a> -+-
<a href="#similar-or-related-projects">Similar or related projects</a> -+-
<a href="https://github.com/libsndfile/libsndfile/blob/master/CHANGELOG.md">News</a>
<br>
<a href="development.html">Development</a> -+-
<a href="api.html">Programming interface</a> -+-
<a href="bugs.html">Bug reporting</a> -+-
<a href="#download">Download</a>
<br>
<a href="FAQ.html">FAQ</a> -+-
<a href="lists.html">Mailing lists</a> -+-
<a href="#licensing">Licensing information</a> -+-
<a href="#see-also">See also</a>
</nav>
<br><br>
</footer>
<main>
<article>
{{ content }}
</article>
</main>

10
Engine/lib/libsndfile/docs/_layouts/page.html Normal file
View file

@ -0,0 +1,10 @@
---
layout: default
---
<main>
<article>
{{ content }}
</article>
</main>

744
Engine/lib/libsndfile/docs/api.md Normal file
View file

@ -0,0 +1,744 @@
---
layout: page
title: The libsndfile API
---
# libsndfile
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.
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 [Note 1](#note-1) and [Note 2](#note-2).
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 the
library. If any errors, omissions or ambiguities are found, please notify me (erikd) at mega-nerd dot com.
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.
**Finally, if you think there is some feature missing from libsndfile, check that it isn't already implemented (and
documented) [here](command.md).**
## Synopsis
```c
#include <stdio.h>;
#include <sndfile.h>;
```
| Name | Description |
|:------------------------------------------------------------------------------------------------------------|:--------------------------------------- |
| [sf_open, sf_wchar_open](#open) | File open functions. |
| [sf_open_fd](#open_fd) | Open sound file using file descriptor. |
| [sf_open_virtual](#open_virtual) | Open sound file using virtual API. |
| [sf_format_check](#check) | Validate sound file info. |
| [sf_seek](#seek) | Seek position in sound file. |
| [sf_command](command.md) | Command interface. |
| [sf_error, sf_strerror, sf_error_number, sf_perror, sf_error_str](#error) | Error functions. |
| [sf_close](#close) | File close function. |
| [sf_write_sync](#write_sync) | Write sync function. |
| [sf_read_short, sf_read_int, sf_read_float, sf_read_double](#read) | File items read functions. |
| [sf_readf_short, sf_readf_int, sf_readf_float, sf_readf_double](#readf) | File frames read functions. |
| [sf_write_short, sf_write_int, sf_write_float, sf_write_double](#write) | File items write functions. |
| [sf_writef_short, sf_writef_int, sf_writef_float, sf_writef_double](#writef) | File frames write functions. |
| [sf_read_raw, sf_write_raw](#raw) | Raw read/write functions. |
| [sf_get_string, sf_set_string](#string) | Functions for reading and writing string data. |
| [sf_version_string](#version_string) | Retrieve library version string. |
| [sf_current_byterate](#current_byterate) | Retrieve current byterate. |
| [sf_set_chunk, sf_get_chunk_iterator, sf_next_chunk_iterator, sf_get_chunk_size, sf_get_chunk_data](#chunk) | RIFF chunks API. |
SNDFILE* is an anonymous pointer to data which is private to the library.
## File Open Function {#open}
```c
SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ;
```
The sf_open() function opens the sound file at the specified path. The filename is byte encoded, but may be utf-8 on
Linux, while on Mac OS X it will use the filesystem character set. On Windows, there is also a Windows specific
sf_wchar_open() that takes a UTF16_BE encoded filename.
```c
SNDFILE* sf_wchar_open (LPCWSTR wpath, int mode, SF_INFO *sfinfo) ;
```
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:
```c
typedef struct
{ sf_count_t frames ; /* Used to be called samples. */
int samplerate ;
int channels ;
int format ;
int sections ;
int seekable ;
} SF_INFO ;
```
The mode parameter for this function can be any one of the following three values:
SFM_READ
: read only mode
SFM_WRITE
: write only mode
SFM_RDWR
: read/write mode
When opening a file for read, the **format** 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.
**Note:** The libsndfile library will reject values ​​for field **channels** that
are greater than `1024`. These value ​​represent the maximum theoretical limit
and may be less for specific formats.
When opening a file for write, the caller must fill in structure members
**samplerate**, **channels**, and **format**.
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.
| Name | Value | Description |
|:-------------------------|:-----------|:-------------------------------------------|
| **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 |
| SF_FORMAT_MPEG | 0x230000 | MPEG-1/2 audio stream |
| **Subtypes.** |
| 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 / Dialogix ADPCM |
| SF_FORMAT_NMS_ADPCM_16 | 0x0022 | 16kbs NMS G721-variant encoding. |
| SF_FORMAT_NMS_ADPCM_24 | 0x0023 | 24kbs NMS G721-variant encoding. |
| SF_FORMAT_NMS_ADPCM_32 | 0x0024 | 32kbs NMS G721-variant 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. |
| SF_FORMAT_OPUS | 0x0064 | Xiph/Skype Opus encoding. |
| SF_FORMAT_ALAC_16 | 0x0070 | Apple Lossless Audio Codec (16 bit). |
| SF_FORMAT_ALAC_20 | 0x0071 | Apple Lossless Audio Codec (20 bit). |
| SF_FORMAT_ALAC_24 | 0x0072 | Apple Lossless Audio Codec (24 bit). |
| SF_FORMAT_ALAC_32 | 0x0073 | Apple Lossless Audio Codec (32 bit). |
| SF_FORMAT_MPEG_LAYER_I | 0x0080 | MPEG-1 Audio Layer I. |
| SF_FORMAT_MPEG_LAYER_II | 0x0081 | MPEG-1 Audio Layer II. |
| SF_FORMAT_MPEG_LAYER_III | 0x0082 | MPEG-2 Audio Layer III. |
| **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 | |
Every call to **sf_open**() should be matched with a call to
[**sf_close**()](#close) to free up memory allocated during the call to **sf_open**().
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 [**sf_strerror**()](#error).
### File Descriptor Open {#open_fd}
```c
SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ;
```
**Note:** 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.
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:
* 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).
* Opening files with file names using OS specific character encodings and then
passing the file descriptor to **sf_open_fd**().
* Opening sound files embedded within larger files. [More info](embedded_files.md).
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_fd().
When sf_close() is called, the file descriptor is only closed if the
**close_desc** parameter was TRUE when the sf_open_fd() function was called.
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.
### Virtual File Open Function {#open_virtual}
```c
SNDFILE* sf_open_virtual (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ;
```
Opens a soundfile from a virtual file I/O context which is provided by the
caller. This is usually used to interface libsndfile to write/read from memory
with a stream or buffer based system. Apart from the sfvirtual and the user_data
parameters this function behaves like [sf_open()](#open).
```c
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 ;
```
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.
```c
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) ;
```
#### sf_vio_get_filelen
```c
typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ;
```
The virtual file context must return the length of the virtual file in bytes.
#### sf_vio_seek
```c
typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ;
```
The virtual file context must seek to offset using the seek mode provided by
whence which is one of SEEK_CUR, SEEK_SET, SEEK_END.
The return value must contain the new offset in the file.
#### sf_vio_read
```c
typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ;
```
The virtual file context must copy ("read") "count" bytes into the buffer
provided by ptr and return the count of actually copied bytes.
#### sf_vio_write
```c
typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ;
```
The virtual file context must process "count" bytes stored in the buffer passed
with ptr and return the count of actually processed bytes.
#### sf_vio_tell
```c
typedef sf_count_t (*sf_vio_tell) (void *user_data) ;
```
Return the current position of the virtual file context.
## Format Check Function {#chek}
```c
int sf_format_check (const SF_INFO *info) ;
```
This function allows the caller to check if a set of parameters in the SF_INFO
struct is valid before calling [sf_open](#open) (SFM_WRITE).
sf_format_check() returns TRUE if the parameters are valid and FALSE otherwise.
## File Seek Functions
```c
sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ;
```
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.
like lseek(), the whence parameter can be any one of the following three values:
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.
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.
Note that the frames offset can be negative and in fact should be when SEEK_END
is used for the whence parameter.
sf_seek will return the offset in (multichannel) frames from the start of the
audio data or -1 if an error occurred (ie an attempt is made to seek beyond the
start or end of the file).
## Error Reporting Functions {#error}
```c
int sf_error (SNDFILE *sndfile) ;
```
This function returns the current error number for the given SNDFILE.
The error number may be one of the following:
| Name | Value |
|:----------------------------|:------|
| SF_ERR_NO_ERROR | 0 |
| SF_ERR_UNRECOGNISED_FORMAT | 1 |
| SF_ERR_SYSTEM | 2 |
| SF_ERR_MALFORMED_FILE | 3 |
| SF_ERR_UNSUPPORTED_ENCODING | 4 |
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.
```c
const char* sf_strerror (SNDFILE *sndfile) ;
const char* sf_error_number (int errnum) ;
```
The error functions sf_strerror () and sf_error_number () convert the library's
internal error enumerations into text strings.
```c
int sf_perror (SNDFILE *sndfile) ;
int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ;
```
The functions sf_perror() and sf_error_str() are deprecated and will be dropped
from the library at some later date.
## File Close Function {#close}
```c
int sf_close (SNDFILE *sndfile) ;
```
The close function closes the file, deallocates its internal buffers and returns
0 on success or an error value otherwise.
## Write Sync Function {#write_sync}
```c
void sf_write_sync (SNDFILE *sndfile) ;
```
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.
## File Read Functions {#read}
```c
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) ;
```
{: #readf}
```c
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) ;
```
The file read functions fill the array pointed to by ptr with the requested
number of items or frames.
For the frames-count functions, the frames parameter specifies the number of
frames. A frame is just a block of samples, one for each channel.
**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).**
For the items-count functions, the items parameter must be an integer product
of the number of channels or an error will occur. Here, an item is just a
sample.
Note: The only difference between the "items" and "frames" versions of each read
function is the units in which the object count is specified - calling
sf_readf_short() with a count argument of N, on a SNDFILE with C channels, is
the same as calling sf_read_short with a count argument of N\*C. The buffer
pointed to by "ptr" should be the same number of bytes in each case.
Note: 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 [Note 1](#note-1).
The sf_read_XXXX and sf_readf_XXXX functions return the number of items or
frames read, respectively. Unless the end of the file was reached during the
read, the return value should equal the number of objects requested. Attempts to
read beyond the end of the file will not result in an error but will cause the
read functions to return less than the number of objects requested or 0 if
already at the end of the file. When the buffer is not is not completely filled,
unused buffer space is filled by zeroes.
## File Write Functions {#write}
```c
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) ;
```
{: #writef}
```c
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) ;
```
The file write functions write the data in the array pointed to by ptr to the
file.
For items-count functions, the items parameter specifies the size of the array
and must be an integer product of the number of channels or an error will occur.
For the frames-count functions, the array is expected to be large enough to hold
a number of items equal to the product of frames and the number of channels.
As with the read functions [above](#read), the only difference in the items and
frames version of each write function is the units in which the buffer size is
specified. Again, the data type used by the calling program and the data format
of the file do not need to be the same ([Note 1](#note-1)).
The sf_write_XXXX and sf_writef_XXXX functions respectively return the number of
items or frames written (which should be the same as the items or frames
parameter).
## Raw File Read and Write Functions {#raw}
```c
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) ;
```
**Note:** Unless you are writing an external decoder/encode that uses libsndfile
to handle the file headers, you should not be using these functions.
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.
The raw read and write functions return the number of bytes read or written
(which should be the same as the bytes parameter).
**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.**
See also : [SFC_RAW_NEEDS_ENDSWAP](command.md#sfc_raw_needs_endswap).
## Functions for Reading and Writing String Data {#string}
```c
const char* sf_get_string (SNDFILE *sndfile, int str_type) ;
int sf_set_string (SNDFILE *sndfile, int str_type, const char* str) ;
```
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
**str_type** parameter can be any one of the following string types:
| Name | Value | Description |
|:-------------------|:------|:--------------|
| SF_STR_TITLE | 0x01 | Title. |
| SF_STR_COPYRIGHT | 0x02 | Copyright. |
| SF_STR_SOFTWARE | 0x03 | Software. |
| SF_STR_ARTIST | 0x04 | Artist. |
| SF_STR_COMMENT | 0x05 | Comment. |
| SF_STR_DATE | 0x06 | Date. |
| SF_STR_ALBUM | 0x07 | Album. |
| SF_STR_LICENSE | 0x08 | License. |
| SF_STR_TRACKNUMBER | 0x09 | Track number. |
| SF_STR_GENRE | 0x10 | Genre. |
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.
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().
Strings passed to and retrieved from these two functions are assumed to be
utf-8. However, while formats like Ogg/Vorbis and FLAC fully support utf-8,
others like WAV and AIFF officially only support ASCII. Writing utf-8 strings to
WAV and AIF files with libsndfile will work when read back with libsndfile, but
may not work with other programs.
The suggested method of dealing with tags retrieved using sf_get_string() is to
assume they are utf-8. Similarly if you have a string in some exotic format like
utf-16, it should be encoded to utf-8 before being written using libsndfile.
## Function for retrieving library version {#version_string}
```c
const char *sf_version_string (void) ;
```
Return the library version string.
## Function for retrieving current byterate {#current_byterate}
```c
int sf_current_byterate (SNDFILE *sndfile) ;
```
Return the current byterate at this point in the file. The byte rate in this
case is the number of bytes per second of audio data. For instance, for a
stereo, 18 bit PCM encoded file with an 16kHz sample rate, the byte rate
would be 2 (stereo) \* 2 (two bytes per sample) * 16000 => 64000 bytes/sec.
For some file formats the returned value will be accurate and exact, for some
it will be a close approximation, for some it will be the average bitrate for
the whole file and for some it will be a time varying value that was accurate
when the file was most recently read or written.
To get the bitrate, multiple this value by 8.
`sf_current_byterate` returns byte per second or -1 if byterate is
unknown.
## Functions to get and set chunks from within a sound file
These functions allow the getting and setting of chunks within a sound file (for
those formats which allow it).
These functions fail safely. Specifically, they will not allow you to overwrite
existing chunks or add extra versions of format specific reserved chunks but
should allow you to retrieve any and all chunks (may not be implemented for all
chunks or all file formats).
### sf_set_chunk
```c
int sf_set_chunk (SNDFILE *sndfile, const SF_CHUNK_INFO *chunk_info) ;
```
Set the specified chunk info (must be done before any audio data is written to
the file). This will fail for format specific reserved chunks. The
`chunk_info->data` pointer must be valid until the file is closed.
The `SF_CHUNK_INFO` struct is documented as follows:
```c
struct SF_CHUNK_INFO
{ char id [64] ; /* The chunk identifier. */
unsigned id_size ; /* The size of the chunk identifier. */
unsigned datalen ; /* The size of that data. */
void *data ; /* Pointer to the data. */
} ;
typedef struct SF_CHUNK_INFO SF_CHUNK_INFO ;
```
`sf_set_chunk` returns `SF_ERR_NO_ERROR` on success or non-zero on failure.
### sf_get_chunk_iterator
```c
SF_CHUNK_ITERATOR *
sf_get_chunk_iterator (SNDFILE *sndfile, const SF_CHUNK_INFO *chunk_info) ;
```
Get an iterator for all chunks matching `chunk_info`.
`SF_CHUNK_ITERATOR` is an opaque structure to an iterator over the all chunks of
a given id and defined as follows:
```c
typedef struct SF_CHUNK_ITERATOR SF_CHUNK_ITERATOR ;
```
The iterator will point to the first chunk matching `chunk_info`. Chunks are
matching, if (`chunk_info->id`) matches the first (`chunk_info->id_size`) bytes
of a chunk found in the `SNDFILE*` handle. If `chunk_info` is `NULL`, an
iterator to all chunks in the `SNDFILE*` handle is returned. The values of
`chunk_info->datalen` and `chunk_info->data` are ignored. If no matching chunks
are found in the sndfile, `NULL` is returned.
The returned iterator will stay valid until one of the following occurs:
* The sndfile is closed.
* A new chunk is added using [`sf_set_chunk()`](#sf_set_chunk).
* Another chunk iterator function is called on the same `SNDFILE*`
handle that causes the iterator to be modified.
The memory for the iterator belongs to the SNDFILE* handle and is freed when
[sf_close](#close) is called.
### sf_next_chunk_iterator
```c
sf_next_chunk_iterator (SF_CHUNK_ITERATOR * iterator) ;
```
Iterate through chunks by incrementing the iterator.
Increments the iterator and returns a handle to the new one. After this call,
iterator will no longer be valid, and you must use the newly returned handle
from now on. The returned handle can be used to access the next chunk matching
the criteria as defined in [sf_get_chunk_iterator](#sf_get_chunk_iterator).
If iterator points to the last chunk, this will free all resources associated
with iterator and return `NULL`. The returned iterator will stay valid until
`sf_get_next_chunk_iterator` is called again, the sndfile is closed or a new
chunk us added.
### sf_get_chunk_size
```c
int
sf_get_chunk_size (const SF_CHUNK_ITERATOR * it, SF_CHUNK_INFO * chunk_info) ;
```
Get the size of the specified chunk.
If the specified chunk exists, the size will be returned in the `datalen` field
of the `SF_CHUNK_INFO` struct. Additionally, the id of the chunk will be copied
to the `id` field of the `SF_CHUNK_INFO` struct and it's `id_size` field will be
updated accordingly.
If the chunk doesn't exist `chunk_info->datalen` will be zero, and the `id` and
`id_size` fields will be undefined.
The function will return `SF_ERR_NO_ERROR` on success or non-zero on failure.
### sf_get_chunk_data
```c
int
sf_get_chunk_data (const SF_CHUNK_ITERATOR *it, SF_CHUNK_INFO *chunk_info) ;
```
Get the specified chunk data.
If the specified chunk exists, up to `chunk_info->datalen` bytes of the chunk
data will be copied into the `chunk_info->data` buffer (allocated by the caller)
and the `chunk_info->datalen` field updated to reflect the size of the data. The
`id` and `id_size` field will be updated according to the retrieved chunk. If
the chunk doesn't exist `chunk_info->datalen` will be zero, and the `id` and
`id_size` fields will be undefined.
The function will return `SF_ERR_NO_ERROR` on success or non-zero on failure.
## Note 1
When converting between integer PCM formats of differing size (e.g. using
sf_read_int() to read a 16 bit PCM encoded WAV file) libsndfile obeys one simple
rule:
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.
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 [sf_command](command.md)
interface.
## Note 2
Reading a file containing 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 &lt; 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
[sf_command](command.md) interface, a command of
[SFC_SET_SCALE_FLOAT_INT_READ](command.md#sfc_set_scale_float_int_read) and a
parameter of SF_TRUE to force correct scaling.

47
Engine/lib/libsndfile/docs/bugs.md Normal file
View file

@ -0,0 +1,47 @@
---
layout: page
---
# Reporting Bugs in libsndfile
Before even attempting to report a bug in libsndfile please make sure you have
read the [Frequently Asked Questions](FAQ.md). If you are having a problem
writing code using libsndfile make sure you read the
[Application Programming Interface](api.md) documentation.
That said, I am interested in finding and fixing all genuine bugs in libsndfile.
Bugs I want to fix include any of the following problems (and probably others):
- Compilation problems on new platforms.
- Errors being detected during the `make check` process.
- Segmentation faults occurring inside libsndfile.
- libsndfile hanging when opening a file.
- Supported sound file types being incorrectly read or written.
- Omissions, errors or spelling mistakes in the documentation.
When submitting a bug report you must include:
- Your system (CPU and memory size should be enough).
- The operating system you are using.
- Whether you are using a package provided by your distribution or you compiled
it yourself.
- If you compiled it yourself, the compiler you are using. (Also make sure to
run `make check`.)
- A description of the problem.
- Information generated by the sndfile-info program (see next paragraph).
- If you are having problems with sndfile-play and ALSA on Linux, I will need
information about your kernel, ALSA version, compiler version, whether you
compiled the kernel/ALSA your self or installed from a package etc.
If libsndfile compiles and installs correctly but has difficulty reading a
particular file or type of file you should run the **sndfile-info** program
(from the examples directory of the libsndfile distribution) on the file. See
[here](sndfile_info.md) for an example of the use of the **sndfile-info**
program.
Please do not send me a sound file which fails to open under libsndfile unless
I specifically ask you to. The above information should usually suffice for most
problems.
Once you have the above information you should submit a ticket on the libsndfile
[GitHub issue tracker](https://github.com/libsndfile/libsndfile/issues).

2016
Engine/lib/libsndfile/docs/command.md Normal file
View file

File diff suppressed because it is too large Load diff

18
Engine/lib/libsndfile/docs/development.md Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
---
# libsndfile Development
libsndfile is being developed by a small community of users and hackers. People
interested in helping can raise an issue on Github.
The main repository can be found on Github:
<https://github.com/libsndfile/libsndfile/>
and includes [instructions](https://github.com/libsndfile/libsndfile/blob/master/README.md)
on how to build libsndfile from the Git repo.
If you are interested in how to add a new format to a libsndfile, you may find
this [FAQ](new_file_type_howto.md) helpful.

60
Engine/lib/libsndfile/docs/donate.md Normal file
View file

@ -0,0 +1,60 @@
---
layout: page
title: libsndfile : donate.
---
{% include logo.html %}
Dear libsndfile user,
This library was developed on Linux for Linux. I am not a Windows user and
maintaining this library for Windows costs me significant amounts of time above
and beyond the time taken to make it work on Linux and Unix-like systems.
I therefore ask Windows users of libsndfile to donate to ensure that
libsndfile's support for Windows continues. As long as donations continue to
flow in at a decentrate, I will continue to release precompiled Windows binaries
in sync with the Linux/Unix version. If donations are poor, support for windows
will fall behind.
You are free to donate any amount you chose. As a guideline:
* If you are simply a user of libsndfile that would like to ensure that the
development of libsndfile continues, a donation of $10US would be more than
adequate.
* If you are shareware author that distributes libsndfile with your app and
makes more than $1000 a year from your shareware, a one off donation of $50
would be appropriate.
* If your company is a commercial software house that distributes one or more
products that ship with libsndfile, a donation of $100 every second or third
year would be appropriate.
Donations can be made in Bitcoin to the Bitcoin address
**15hVWemFiH6DLJ22SBYPk9b4fgWtxBEvfQ** which can be verified by checking the
following GPG signature.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
libsndfile Bitcoin address : 15hVWemFiH6DLJ22SBYPk9b4fgWtxBEvfQ
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)
iQIcBAEBCAAGBQJSK7MUAAoJEEXYQ7zIiotIgXEP/R8hy65tlV7TiPw9bY9BklXS
/Vl8FU2RhDkBt61ZmxbfDTybyQ5Vce/3wWph15L4RvpoX1OyeintQFmwwuPjOGiq
eIz0nT9vDorG37Xdo5NZNBu9Tp1Od9MNtxFaAsRWFrDfvKEKljBHrcfM972cYrAp
DaFd0Ik+bHKom9iQXFB7TFd0w2V4uszVMQDUGqb/vRNeRURZS7ypeMNwc8tZyTKR
waEGMTa5sxxRjs7MqGRxSovnFT7JV3TNfdkBInUliIR/XvrudFR9J4Fiv+8Dk9P8
WNjm6uFxvgIqiu1G9bjrwwr+DsBju93ljGNcZoayAKw5vwbX6KTcCbc31k9dP8Hf
p6YdmPlZVKZmva+P3nLSJBTlxNu24Jm+ha+ZM/svDXTaPFWC8l5FP17kK0Bj8wCq
N7pDz6RchEn10u+HdhfT1XiUjxj0zNXrr0GGj9apjl0RlT0O49eBttV0oXIdBRLi
nTEaOWITpCgu7ggw1kWXHIWEncuiaSuJy/iH8PgNepWVj/6PxQRMrTqG4ux2Snk8
Ua4vO8YHLMZX/XvSUS7eMtgfM7AO6YjJ/ac9bQif9bh6LsYEVVklysMUin6ZRS7Z
Cms23FnqeQKtJOzdvqSJiV06lK6fP+tYdM4WSYn+AfL4IfYl2v48xXVU8XOOK9BH
bJPKMDcz1ZvfYtX5mSW1
=WXGB
-----END PGP SIGNATURE-----
Thanks and regards,
Erik de Castro Lopo
Main libsndfile author and maintainer

21
Engine/lib/libsndfile/docs/embedded_files.md Normal file
View file

@ -0,0 +1,21 @@
---
layout: page
---
# Embedded Sound Files
By using the open SNDFILE with a file descriptor function:
SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ;
it is possible to open sound files embedded within larger files. There are
however a couple of caveats:
* Read/Write mode (SFM_RDWR) is not supported.
* Writing of embedded files is only supported at the end of the file.
* Reading of embedded files is only supported at file offsets greater than zero.
* Not all file formats are supported (currently only WAV, AIFF and AU).
The test program **multi_file_test.c** in the **tests/** directory of the source
code tarball shows how this functionality is used to read and write embedded
files.

53
Engine/lib/libsndfile/docs/formats.md Normal file
View file

@ -0,0 +1,53 @@
---
layout: page
title: libsndfile: Supported formats
---
# libsndfile : Supported formats
The following table lists the file formats and encodings that libsndfile can
read and write. The file formats are arranged across the top and encodings along
the left edge.
{:.formats-table}
| | Microsoft WAV | SGI / Apple AIFF / AIFC |Sun / DEC / NeXT AU / SND | Headerless RAW | Paris Audio File PAF | Commodore Amiga IFF / SVX | Sphere Nist WAV | IRCAM SF | Creative VOC | Soundforge W64 | GNU Octave 2.0 MAT4 | GNU Octave 2.1 MAT5 | Portable Voice Format PVF | Fasttracker 2 XI | HMM Tool Kit HTK | Apple CAF | Sound Designer II SD2 | Free Lossless Audio Codec FLAC |
|:-------------------|:-------------:|:-----------------------:|:------------------------:|:--------------:|:--------------------:|:-------------------------:|:---------------:|:--------:|:------------:|:--------------:|:-------------------:|:-------------------:|:-------------------------:|:----------------:|:----------------:|:---------:|:---------------------:|:------------------------------:|
| Unsigned 8 bit PCM | R/W | R/W | | R/W | | | | | R/W | R/W | | R/W | | | | | | |
| Signed 8 bit PCM | | R/W | R/W | R/W | R/W | R/W | R/W | | | | | | R/W | | | R/W | R/W | R/W |
| Signed 16 bit PCM | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | | R/W | R/W | R/W | R/W |
| Signed 24 bit PCM | R/W | R/W | R/W | R/W | R/W | | R/W | | | R/W | | | | | | R/W | R/W | R/W |
| Signed 32 bit PCM | R/W | R/W | R/W | R/W | | | R/W | R/W | | R/W | R/W | R/W | R/W | | | R/W | | |
| 32 bit float | R/W | R/W | R/W | R/W | | | | R/W | | R/W | R/W | R/W | | | | R/W | | |
| 64 bit double | R/W | R/W | R/W | R/W | | | | | | R/W | R/W | R/W | | | | R/W | | |
| u-law encoding | R/W | R/W | R/W | R/W | | | R/W | R/W | R/W | R/W | | | | | | R/W | | |
| A-law encoding | R/W | R/W | R/W | R/W | | | R/W | R/W | R/W | R/W | | | | | | R/W | | |
| IMA ADPCM | R/W | | | | | | | | | R/W | | | | | | | | |
| MS ADPCM | R/W | | | | | | | | | R/W | | | | | | | | |
| GSM 6.10 | R/W | R/W | | R/W | | | | | | R/W | | | | | | | | |
| G721 ADPCM 32kbps | R/W | | R/W | | | | | | | | | | | | | | | |
| G723 ADPCM 24kbps | | | R/W | | | | | | | | | | | | | | | |
| G723 ADPCM 40kbps | | | R/W | | | | | | | | | | | | | | | |
| 12 bit DWVW | | R/W | | R/W | | | | | | | | | | | | | | |
| 16 bit DWVW | | R/W | | R/W | | | | | | | | | | | | | | |
| 24 bit DWVW | | R/W | | R/W | | | | | | | | | | | | | | |
| Ok Dialogic ADPCM | | | | R/W | | | | | | | | | | | | | | |
| 8 bit DPCM | | | | | | | | | | | | | | R/W | | | | |
| 16 bit DPCM | | | | | | | | | | | | | | R/W | | | | |
From version 1.0.18, libsndfile also reads and writes
[FLAC](https://xiph.org/flac/) and [Ogg/Vorbis](https://xiph.org/vorbis/).
From version 1.0.29, libsndfile can read and write
[Ogg/Opus](https://opus-codec.org/).
From version 1.1.0, libsndfile can read and write MP3.
Some of the file formats I am also interested in adding are:
- Kurzweil K2000 sampler files.
- Ogg Speex.
Other file formats may also be added on request.
If you are interested in how to add a new format to a libsndfile, you may find
this [FAQ](new_file_type_howto.md) helpful.

322
Engine/lib/libsndfile/docs/index.md Normal file
View file

@ -0,0 +1,322 @@
---
layout: home
title: The libsndfile Home Page
---
Libsndfile is a C library for reading and writing files containing sampled sound
(such as MS Windows WAV and the Apple/SGI AIFF format) through one standard
library interface. It is released in source code format under the
[Gnu Lesser General Public License](http://www.gnu.org/copyleft/lesser.html).
The library was written to compile and run on a Linux system but should compile
and run on just about any Unix (including MacOS X).
There are also pre-compiled binaries available for 32 and 64 bit windows.
It was designed to handle both little-endian (such as WAV) and big-endian (such
as AIFF) data, and to compile and run correctly on little-endian (such as Intel
and DEC/Compaq Alpha) processor systems as well as big-endian processor systems
such as Motorola 68k, Power PC, MIPS and Sparc. Hopefully the design of the
library will also make it easy to extend for reading and writing new sound file
formats.
It has been compiled and tested (at one time or another) on the following
systems:
* Every platform supported by Debian GNU/Linux including x86_64-linux-gnu,
i486-linux-gnu, powerpc-linux-gnu, sparc-linux-gnu, alpha-linux-gnu,
mips-linux-gnu and armel-linux-gnu.
* powerpc-apple-darwin7.0 (Mac OS X 10.3)
* sparc-sun-solaris2.8 (using gcc)
* mips-sgi-irix5.3 (using gcc)
* QNX 6.0
* i386-unknown-openbsd2.9
* Microsoft Windows
At the moment, each new release is being tested on i386 Linux, x86_64 Linux,
PowerPC Linux, Win32 and Win64.
## Features
libsndfile has the following main features :
* Ability to read and write a large number of [file formats](formats.html).
* A simple, elegant and easy to use Applications Programming Interface.
* Usable on Unix, Win32, MacOS and others.
* On the fly format conversion, including endian-ness swapping, type conversion
and bitwidth scaling.
* Optional normalisation when reading floating point data from files containing
integer data.
* Ability to open files in read/write mode.
* The ability to write the file header without closing the file (only on files
open for write or read/write).
* Ability to query the library about all supported formats and retrieve text
strings describing each format.
libsndfile has a comprehensive test suite so that each release is as bug free
as possible.
When new bugs are found, new tests are added to the test suite to ensure that
these bugs don't creep back into the code.
When new features are added, tests are added to the test suite to make sure that
these features continue to work correctly even when they are old features.
## History
My first attempt at reading and writing WAV files was in 1990 or so under
Windows 3.1. I started using Linux in early 1995 and contributed some code to
the [wavplay](http://www.vaxxine.com/ve3wwg/gnuwave.html) program. That
contributed code would eventually mutate into this library. As one of my
interests is Digital Signal Processing (DSP) I decided that as well as reading
data from an audio file in the native format (typically 16 bit short integers)
it would also be useful to be able to have the library do the conversion to
floating point numbers for DSP applications. It then dawned on me that whatever
file format (anything from 8 bit unsigned chars, to 32 bit floating point
numbers) the library should be able to convert the data to whatever format the
library user wishes to use it in. For example, in a sound playback program, the
library caller typically wants the sound data in 16 bit short integers to dump
into a sound card even though the data in the file may be 32 bit floating point
numbers (ie Microsoft's WAVE_FORMAT_IEEE_FLOAT format). Another example would be
someone doing speech recognition research who has recorded some speech as a 16
bit WAV file but wants to process it as double precision floating point numbers.
Here is the release history for libsndfile:
* Version 0.0.8 (Feb 15 1999) First official release.
* Version 0.0.28 (Apr 26 2002) Final release of version 0 of libsndfile.
* Version 1.0.0rc1 (Jun 24 2002) Release candidate 1 of version 1 of libsndfile.
* Version 1.0.0rc6 (Aug 14 2002) MacOS 9 fixes.
* Version 1.0.0 (Aug 16 2002) First 1.0.X release.
* Version 1.0.1 (Sep 14 2002) Added MAT4 and MAT5 file formats.
* Version 1.0.2 (Nov 24 2002) Added VOX ADPCM format.
* Version 1.0.3 (Dec 09 2002) Fixes for Linux on ia64 CPUs.
* Version 1.0.4 (Feb 02 2003) New file formats and functionality.
* Version 1.0.5 (May 03 2003) One new file format and new functionality.
* Version 1.0.6 (Feb 08 2004) Large file fix for Linux/Solaris, new
functionality and Win32 improvements.
* Version 1.0.7 (Feb 24 2004) Fix build problems on MacOS X and fix ia64/MIPS
etc clip mode detection.
* Version 1.0.8 (Mar 14 2004) Minor bug fixes.
* Version 1.0.9 (Mar 30 2004) Add AVR format. Improve handling of some WAV
files.
* Version 1.0.10 (Jun 15 2004) Minor bug fixes. Fix support for Win32 MinGW
compiler.
* Version 1.0.11 (Nov 15 2004) Add SD2 file support, reading of loop data in WAV
and AIFF. Minor bug fixes.
* Version 1.0.12 (Sep 30 2005) Add FLAC and CAF file support, virtual I/O
interface. Minor bug fixes and cleanups.
* Version 1.0.13 (Jan 21 2006) Add read/write of instrument chunks. Minor bug
fixes.
* Version 1.0.14 (Feb 19 2006) Minor bug fixes. Start shipping windows
binary/source ZIP.
* Version 1.0.15 (Mar 16 2006) Minor bug fixes.
* Version 1.0.16 (Apr 30 2006) Add support for RIFX. Other minor feature
enhancements and bug fixes.
* Version 1.0.17 (Aug 31 2006) Add C++ wrapper sndfile.hh. Minor bug fixes and
cleanups.
* Version 1.0.18 (Feb 07 2009) Add Ogg/Vorbis support, remove captive
libraries, many new features and bug fixes. Generate Win32 and Win64
pre-compiled binaries.
* Version 1.0.19 (Mar 02 2009) Fix for CVE-2009-0186. Huge number of minor fixes
as a result of static analysis.
* Version 1.0.20 (May 14 2009) Fix for potential heap overflow.
* Version 1.0.21 (December 13 2009) Bunch of minor bug fixes.
* Version 1.0.22 (October 04 2010) Bunch of minor bug fixes.
* Version 1.0.23 (October 10 2010) Minor bug fixes.
* Version 1.0.24 (March 23 2011) Minor bug fixes.
* Version 1.0.25 (July 13 2011) Fix for Secunia Advisory SA45125. Minor bug
fixes and improvements.
* Version 1.0.26 (November 22 2015) Fix for CVE-2014-9496, CVE-2014-9756 and
CVE-2015-7805. Add ALAC/CAF support. Minor bug fixes and improvements.
* Version 1.0.27 (June 19 2016) Fix a seek regression in 1.0.26. Add metadata
read/write for CAF and RF64. FIx PAF endian-ness issue.
* Version 1.0.28 (April 2 2017) Fix buffer overruns in FLAC and ID3 handling
code. Reduce default header memory requirements. Fix detection of Large File
Support for 32 bit systems.
* Version 1.0.29 (August 15 2020) Opus support, build system improvements and
bug fixes.
* Version 1.0.30 (September 19 2020) Bugfix release. Fix file descriptor leaks
in sf_open_fd () function. Fix critical CMake bug leading to broken ABI on
Linux platforms. Other numerous fixes to CMake build system, consider it
stable now. Fix some memory leaks. Fix handling of some SD2 files. Update
documentation. Integrate GitHub Actions for faster test builds and Oss-Fuzz
for fuzzing tests. Move sndfile.h.in from src/ to include/ directory. To avoid
problems, delete old generated sndfile.h from $(top_builddir)/src.
* Version 1.0.31 (January 24 2021) Bugfix release. Fix multiple memory leaks
reported by OSS-Fuzz. More SSE2-optimized functions for x86 and amd64.
* Version 1.1.0 (March 27 2022) Minor release, backward compatible with previous
releases. Added long-awaited MP3 support. Numerous improvements and bugfixes.
* Version 1.2.0 (December 25 2022) Various bugfixes,
removed artificial samplerate limit
* Version 1.2.1 (August 12 2023) Patch release, various bugfixes.
* Version 1.2.2 (August 13 2023) Patch release, various bugfixes.
## Similar or Related Projects
* [SoX](http://sox.sourceforge.net/) is a program for converting between sound
file formats.
* [Wavplay](http://www.hitsquad.com/smm/programs/WavPlay/) started out as a
minimal WAV file player under Linux and has mutated into Gnuwave, a
client/server application for more general multimedia and games sound
playback.
* [Audiofile](http://www.68k.org/~michael/audiofile/) (libaudiofile) is a
library similar to libsndfile but with a different programming interface. The
author Michael Pruett has set out to clone (and fix some bugs in) the
libaudiofile library which ships with SGI's IRIX OS.
* [sndlib.tar.gz](ftp://ccrma-ftp.stanford.edu/pub/Lisp/sndlib.tar.gz) is
another library written by Bill Schottstaedt of CCRMA.
## Licensing
libsndfile is released under the terms of the GNU Lesser General Public License,
of which there are two versions;
[version 2.1](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html)
and
[version 3](http://www.gnu.org/copyleft/lesser.html).
To maximise the compatibility of libsndfile, the user may choose to use
libsndfile under either of the above two licenses.
You can also read a simple explanation of the ideas behind the GPL and the LGPL
[here](http://www.gnu.org/copyleft/lesser.html).
You can use libsndfile with
[Free Software](http://www.gnu.org/),
[Open Source](http://www.opensource.org/),
proprietary, shareware or other closed source applications as long as libsndfile
is used as a dynamically loaded library and you abide by a small number of other
conditions (read the LGPL for more info).
With applications released under the GNU GPL you can also use libsndfile
statically linked to your application.
I would like to see libsndfile used as widely as possible but I would prefer it
if you released software that uses libsndfile as
[Free Software](http://www.gnu.org/)
or
[Open Source](http://www.opensource.org/).
However, if you put in a great deal of effort building a significant application
which simply uses libsndfile for file I/O, then I have no problem with you
releasing that as closed source and charging as much money as you want for it as
long as you abide by [the license](http://www.gnu.org/copyleft/lesser.html).
## Download
Check latest version on
[GitHub Releases page](https://github.com/libsndfile/libsndfile/releases/).
Binaries and source packages are signed by current releaser David Seifert aka
@SoapGentoo. You can verify signatures with his public GPG key:
```
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v2
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
=K3x+
-----END PGP PUBLIC KEY BLOCK-----
```
## See Also
* [sndfile-tools](https://github.com/libsndfile/sndfile-tools): a small
collection of programs which use libsndfile.

101
Engine/lib/libsndfile/docs/libsndfile.css Normal file
View file

@ -0,0 +1,101 @@
body {
background : black ;
color : white ;
font-family : arial, helvetica, sans-serif ;
line-height: 1.5 ;
margin-left: 6%;
margin-right: 6%;
}
td {
font-family : arial, helvetica, sans-serif ;
background : black ;
color : white ;
}
center {
font-family : arial, helvetica, sans-serif ;
}
p {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
}
.indent_block {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
}
br {
font-family : arial, helvetica, sans-serif ;
}
form {
font-family : arial, helvetica, sans-serif ;
}
ul {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
}
ol {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
}
dl {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
}
h1 {
font-size : xx-large ;
background : black ;
color : #5050FF ;
text-align : left ;
}
h2 {
font-size : x-large ;
background : black ;
color : #5050FF ;
text-align : left ;
}
h3 {
font-size : large ;
background : black ;
color : #5050FF ;
text-align : left ;
}
h4 {
font-size : medium ;
background : black ;
color : #5050FF ;
text-align : left ;
}
pre {
font-family : courier, monospace ;
font-size : medium ;
}
code,
kbd,
samp,
var {
font-family: "Courier New", monospace, serif;
font-size: 1em;
}
a:link { color : #9090FF ; }
a:visited { color : #5050FF ; }
a:active { color : #FF00FF ; }
a:hover { background-color : #202080 ; }
table.formats-table {
text-align: center;
font-size: small;
border-collapse: collapse;
}
table.formats-table, table.formats-table th, table.formats-table td {
border: 1px solid white;
}
.image-logo {
display: block;
margin-left: auto;
margin-right: auto;
}
nav {
text-align: center;
}

BIN
Engine/lib/libsndfile/docs/libsndfile.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 22 KiB

434
Engine/lib/libsndfile/docs/linux_games_programming.txt Normal file
View file

@ -0,0 +1,434 @@
# Here are some some emails I exchanged with a guy trying to use
# libsndfile version 1 with code from the book "Linux Games Programming"
# by John Hall. The email addresses have been changed to foil the spam
# bots.
Date: Tue, 20 Jul 2004 22:49:21 +0100
From: Paul <paul@fake-domain-name.co.uk>
To: erikd@fake-domain-name.com
Subject: Can you help with a problem?
Date: Tue, 20 Jul 2004 22:49:21 +0100
Hi,
I'm trying to get the source examples in the "Programming Linux Games"
(NoStarch, Loki Software + John R. Hall) which use sndfile.h/libsndfile.
While I can guess some of the newer versions of function calls and
enumerations, there are some which I cannot guess.
Would you be able to translate them to the current version of
enumeration and function calls so that I can update the source?
These are the three currently failing me:
sf_open_read(filename, SF_INFO *sfinfo) (guess: sf_open(filename,SFM_READ, &sfinfo))
SF_FORMAT_PCM (guess: either SF_FORMAT_PCM_U8 or _RAW)
SF_INFO.pcmbitwidth (guess: no idea!)
There are probably more. I'm happy to send you the source files for
sound calls, scan the pages or anything else. Failing that, is there
somewhere with the changes listed so I can try and fix the code for myself?
Thanks
TTFN
Paul
================================================================================
Date: Wed, 21 Jul 2004 17:38:08 +1000
From: Erik de Castro Lopo <erikd@fake-domain-name.com>
To: Paul <paul@fake-domain-name.co.uk>
Subject: Re: Can you help with a problem?
On Tue, 20 Jul 2004 22:49:21 +0100
Paul <paul@fake-domain-name.co.uk> wrote:
> Hi,
>
> I'm trying to get the source examples in the "Programming Linux Games"
> (NoStarch, Loki Software + John R. Hall) which use sndfile.h/libsndfile.
>
> While I can guess some of the newer versions of function calls and
> enumerations, there are some which I cannot guess.
>
> Would you be able to translate them to the current version of
> enumeration and function calls so that I can update the source?
>
> These are the three currently failing me:
>
> sf_open_read(filename, SF_INFO *sfinfo) (guess: sf_open(filename,
> SFM_READ, &sfinfo))
yes.
> SF_FORMAT_PCM (guess: either SF_FORMAT_PCM_U8 or _RAW)
Actually this list:
SF_FORMAT_PCM_U8
SF_FORMAT_PCM_S8
SF_FORMAT_PCM_16
SF_FORMAT_PCM_24
SF_FORMAT_PCM_32
> SF_INFO.pcmbitwidth (guess: no idea!)
WIth the above change, pcmbitwidth becomes redundant.
> There are probably more. I'm happy to send you the source files for
> sound calls, scan the pages or anything else. Failing that, is there
> somewhere with the changes listed so I can try and fix the code for
> myself?
Version 1.0.0 came out some time ago, but I think this:
http://www.mega-nerd.com/libsndfile/version-1.html
lists most of the changes. You should also look at the API docs:
http://www.mega-nerd.com/libsndfile/api.html
HTH,
Erik
--
+-----------------------------------------------------------+
Erik de Castro Lopo nospam@fake-domain-name.com
+-----------------------------------------------------------+
"There is no reason why anyone would want a computer in their home"
Ken Olson, DEC, 1977
================================================================================
From: PFJ <paul@fake-domain-name.co.uk>
To: Erik de Castro Lopo <erikd@fake-domain-name.com>
Subject: Re: Can you help with a problem?
Date: Wed, 21 Jul 2004 09:07:39 +0100
Hi Erik,
Thanks for getting back to me.
> > sf_open_read(filename, SF_INFO *sfinfo) (guess: sf_open(filename, SFM_READ, &sfinfo))
>
> yes.
Yay!
> > SF_FORMAT_PCM (guess: either SF_FORMAT_PCM_U8 or _RAW)
>
> Actually this list:
>
> SF_FORMAT_PCM_U8
> SF_FORMAT_PCM_S8
> SF_FORMAT_PCM_16
> SF_FORMAT_PCM_24
> SF_FORMAT_PCM_32
I know, but the source code explicitly has SF_FORMAT_PCM which given the
code afterwards would equate to one of the above, but given that PCM
files can have a varied bitwidth the author probably wanted to cover all
bases.
> Version 1.0.0 came out some time ago, but I think this:
>
> http://www.mega-nerd.com/libsndfile/version-1.html
>
> lists most of the changes. You should also look at the API docs:
>
> http://www.mega-nerd.com/libsndfile/api.html
I'll download them and see what I can gleen.
Thanks again for getting back to me
TTFN
Paul
================================================================================
Date: Wed, 21 Jul 2004 18:20:29 +1000
From: Erik de Castro Lopo <erikd@fake-domain-name.com>
To: PFJ <paul@fake-domain-name.co.uk>
Subject: Re: Can you help with a problem?
On Wed, 21 Jul 2004 09:07:39 +0100
PFJ <paul@fake-domain-name.co.uk> wrote:
> I know, but the source code explicitly has SF_FORMAT_PCM which given the
> code afterwards would equate to one of the above, but given that PCM
> files can have a varied bitwidth the author probably wanted to cover all
> bases.
But surely the existing code does something like:
sfinfo.format = SF_FORMAT_WAV | SF_FORMAT_PCM;
sfinfo.pcmbitwidth = 16;
which can be directly translated to:
sfinfo.format = SF_FORMAT_WAV | SF_FORMAT_PCM_16;
and the same for pcmbitwitdhs of 24 and 32. For pcmbitwidth of 8
you need to know that WAV files use SF_FORMAT_PCM_U8 and AIFF
files use SF_FORMAT_PCM_S8. That's all there is to it.
Erik
--
+-----------------------------------------------------------+
Erik de Castro Lopo nospam@fake-domain-name.com
+-----------------------------------------------------------+
"Python addresses true pseudocode's two major failings: that it
isn't standardized, and it isn't executable."
- Grant R. Griffin in comp.dsp
================================================================================
Subject: Re: Can you help with a problem?
From: PFJ <paul@fake-domain-name.co.uk>
To: Erik de Castro Lopo <erikd@fake-domain-name.com>
Date: Wed, 21 Jul 2004 09:50:55 +0100
Hi Erik,
> > I know, but the source code explicitly has SF_FORMAT_PCM which given the
> > code afterwards would equate to one of the above, but given that PCM
> > files can have a varied bitwidth the author probably wanted to cover all
> > bases.
>
> But surely the existing code does something like:
>
> sfinfo.format = SF_FORMAT_WAV | SF_FORMAT_PCM;
> sfinfo.pcmbitwidth = 16;
If only!
The actual code is this
int LoadSoundFile(char *filename, sound_p sound)
{
SNDFILE *file;
SF_INFO file_info;
short *buffer_short = NULL;
u_int8_t *buffer_8 = NULL;
int16_t *buffer_16 = NULL;
unsigned int i;
/* Open the file and retrieve sample information. */
file = sf_open_read(filename, &file_info);
// I've sorted this one already - PFJ
/* Make sure the format is acceptable. */
if ((file_info.format & 0x0F) != SF_FORMAT_PCM) {
printf("'%s' is not a PCM-based audio file.\n", filename);
sf_close(file);
return -1;
}
if ((file_info.pcmbitwidth == 8) && (file_info.channels == 1)) {
sound->format = AL_FORMAT_MONO8;
} else if ((file_info.pcmbitwidth == 8) && (file_info.channels == 2)) {
sound->format = AL_FORMAT_STEREO8;
} else if ((file_info.pcmbitwidth == 16) && (file_info.channels == 1)) {
sound->format = AL_FORMAT_MONO16;
} else if ((file_info.pcmbitwidth == 16) && (file_info.channels == 2)) {
sound->format = AL_FORMAT_STEREO16;
} else {
printf("Unknown sample format in %s.\n", filename);
sf_close(file);
return -1;
}
/* Allocate buffers. */
buffer_short = (short *)malloc(file_info.samples * file_info.channels * sizeof (short));
buffer_8 = (u_int8_t *)malloc(file_info.samples * file_info.channels * file_info.pcmbitwidth / 8);
buffer_16 = (int16_t *)buffer_8;
if (buffer_short == NULL || buffer_8 == NULL) {
printf("Unable to allocate enough memory for '%s'.\n", filename);
goto error_cleanup;
}
/* Read the entire sound file. */
if (sf_readf_short(file,buffer_short,file_info.samples) == (size_t)-1) {
printf("Error while reading samples from '%s'.\n", filename);
goto error_cleanup;
}
<minor snip>
/* Fill in the sound data structure. */
sound->freq = file_info.samplerate;
sound->size = file_info.samples * file_info.channels * file_info.pcmbitwidth / 8;
/* Give our sound data to OpenAL. */
alGenBuffers(1, &sound->name);
if (alGetError() != AL_NO_ERROR) {
printf("Error creating an AL buffer name for %s.\n", filename);
goto error_cleanup;
}
alBufferData(sound->name, sound->format, buffer_8, sound->size,sound->freq);
if (alGetError() != AL_NO_ERROR) {
printf("Error sending buffer data to OpenAL for %s.\n", filename);
goto error_cleanup;
}
/* Close the file and return success. */
sf_close(file);
free(buffer_short);
free(buffer_8);
return 0;
error_cleanup:
if (file != NULL) fclose(file);
free(buffer_short);
free(buffer_8);
return -1;
}
As you can see, the PCM material in the listing will not currently
compile and for the other sndfile material, it probably won't either.
Any help would be appreciated.
TTFN
Paul
================================================================================
From: Erik de Castro Lopo <erikd@fake-domain-name.com>
To: PFJ <paul@fake-domain-name.co.uk>
Subject: Re: Can you help with a problem?
Date: Wed, 21 Jul 2004 19:36:46 +1000
On Wed, 21 Jul 2004 09:50:55 +0100
PFJ <paul@fake-domain-name.co.uk> wrote:
> Hi Erik,
>
> > > I know, but the source code explicitly has SF_FORMAT_PCM which given the
> > > code afterwards would equate to one of the above, but given that PCM
> > > files can have a varied bitwidth the author probably wanted to cover all
> > > bases.
> >
> > But surely the existing code does something like:
> >
> > sfinfo.format = SF_FORMAT_WAV | SF_FORMAT_PCM;
> > sfinfo.pcmbitwidth = 16;
>
> If only!
No, really.
Drop this completely:
> /* Make sure the format is acceptable. */
> if ((file_info.format & 0x0F) != SF_FORMAT_PCM) {
> printf("'%s' is not a PCM-based audio file.\n", filename);
> sf_close(file);
> return -1;
> }
Replace this block:
> if ((file_info.pcmbitwidth == 8) && (file_info.channels == 1)) {
> sound->format = AL_FORMAT_MONO8;
> } else if ((file_info.pcmbitwidth == 8) && (file_info.channels == 2)) {
> sound->format = AL_FORMAT_STEREO8;
> } else if ((file_info.pcmbitwidth == 16) && (file_info.channels == 1)) {
> sound->format = AL_FORMAT_MONO16;
> } else if ((file_info.pcmbitwidth == 16) && (file_info.channels == 2)) {
> sound->format = AL_FORMAT_STEREO16;
> } else {
> printf("Unknown sample format in %s.\n", filename);
> sf_close(file);
> return -1;
> }
with:
int pcmbitwidth = 0;
if (file_info.format & SF_FORMAT_SUBMASK != SF_FORMAT_PCM_16)
{ printf("'%s' is not a PCM-based audio file.\n", filename);
sf_close(file);
return -1;
}
if (file_info.channels < 1 || file_info.channels > 2)
{ printf("'%s' bad channel count.\n", filename);
sf_close(file);
return -1;
}
switch (file_info.format & SF_FORMAT_SUBMASK + file_info.channels << 16)
{ case (SF_FORMAT_PCM_U8 + 1 << 16):
sound->format = AL_FORMAT_MONO8;
pcmbitwidth = 8;
break;
case (SF_FORMAT_PCM_U8 + 2 << 16):
sound->format = AL_FORMAT_STEREO8;
pcmbitwidth = 8;
break;
case (SF_FORMAT_PCM_16 + 1 << 16):
sound->format = AL_FORMAT_MONO16;
pcmbitwidth = 16;
break;
case (SF_FORMAT_PCM_16 + 2 << 16):
sound->format = AL_FORMAT_STEREO16;
pcmbitwidth = 16;
break;
default:
printf("Unknown sample format in %s.\n", filename);
sf_close(file);
return -1;
}
> /* Allocate buffers. */
> buffer_short = (short *)malloc(file_info.samples *
> file_info.channels *
> sizeof (short));
>
> buffer_8 = (u_int8_t *)malloc(file_info.samples *
> file_info.channels *
> file_info.pcmbitwidth / 8);
Use pcmbitwidth as calculated above.
> buffer_16 = (int16_t *)buffer_8;
>
> if (buffer_short == NULL || buffer_8 == NULL) {
> printf("Unable to allocate enough memory for '%s'.\n", filename);
> goto error_cleanup;
> }
>
> /* Read the entire sound file. */
> if (sf_readf_short(file,buffer_short,file_info.samples) == (size_t)- 1) {
Replace "(size_t) - 1" with " < 0".
> As you can see, the PCM material in the listing will not currently
> compile and for the other sndfile material, it probably won't either.
None of the changes above should have been very difficult to figure
out.
Erik
--
+-----------------------------------------------------------+
Erik de Castro Lopo nospam@fake-domain-name.com
+-----------------------------------------------------------+
Microsoft is finally bringing all of its Windows operating system families
under one roof. It will combine all of the features of CE, stability and
support of ME and the speed of NT.
It will be called Windows CEMENT...

27
Engine/lib/libsndfile/docs/lists.md Normal file
View file

@ -0,0 +1,27 @@
---
layout: page
title: libsndfile Mailing Lists
---
# libsndfile Mailing Lists
**Note**: These mailing lists are not maintained by the libsndfile team anymore.
Use [GitHub issues and pull requests instead](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests).
There are three mailing lists for libsndfile:
- **libsndfile-announce@mega-nerd.com**  
[Subscribe](mailto:libsndfile-announce-request@mega-nerd.com?subject=subscribe)
A list which will announce each new release of libsndfile. No one can
post to this list except the author.
- **libsndfile-devel@mega-nerd.com**  
[Subscribe](mailto:libsndfile-devel-request@mega-nerd.com?subject=subscribe)
A list for discussing bugs, porting issues and feature requests.
Posting is restricted to subscribers.
- **libsndfile-users@mega-nerd.com**  
[Subscribe](mailto:libsndfile-users-request@mega-nerd.com?subject=subscribe)
A list for discussing the use of libsndfile in other programs.
Posting is restricted to subscribers.
The libsndfile-devel and libsndfile-users list will automatically receive a copy
of all emails to the libsndfile-announce list.

134
Engine/lib/libsndfile/docs/new_file_type_howto.md Normal file
View file

@ -0,0 +1,134 @@
---
layout: page
---
# How to add new file format
Original : Wed May 23 19:05:07 EST 2001
Update 1 : Fri Jul 11 22:12:38 EST 2003
This document will attempt to explain as fully as possible how to add code to
libsndfile to allow the reading and writing of new file types. By new file
type I particularly mean a new header type rather than a new encoding method
for an existing file type.
This HOWTO will take the form of a step by step guide. It will assume that you
have all required tools including :
- gcc
- make (should really be the GNU version)
- autoconf
- automake
- libtool
These should all be available on the GNU ftp site: <ftp://ftp.gnu.org/pub/gnu/>.
To help make these steps clearer let's suppose we are adding support for the
Whacky file format whose files contain 'W','A','C' and 'K' as the first four
bytes of the file format. Lets also assume that Whacky files contain PCM encoded
data.
## Step 1
Create a new .c file in the src/ directory of the libsndfile source tree. The
file name should be reasonable descriptive so that is is obvious that files of
the new type are handled by this file. In this particular case the file might
be named 'whacky.c'.
## Step 2
Add your new source code file to the build process.
Edit the file src/Makefile.am and add the name of your file handler to the
FILESPECIFIC list of handlers. This list looks something like this:
FILESPECIFIC = aiff.c au.c au_g72x.c nist.c paf.c raw.c samplitude.c \
svx.c wav.c wav_float.c wav_gsm610.c wav_ima_adpcm.c \
wav_ms_adpcm.c
Then, run the script named 'reconf' in the libsndfile top level directory,
which will run autoconf and other associated tools. Finally run "./configure"
in the top level directory. You may want to use the "--disable-gcc-opt" option
to disable gcc optimisations and make debugging with gdb/ddd easier.
## Step 3
Add a unique identifier for the new file type.
Edit src/sndfile.h and find the enum containing the SF_FORMAT_XXX identifiers.
Since you will be adding a major file type you should add your identifier to the
top part of the list where the values are above 0x10000 in value. The easiest
way to do this is to find the largest value in the list, add 0x10000 to it and
make that your new identifier value. The identifier should be something like
SF_FORMAT_WACK.
## Step 4
Add code to the file type recogniser function.
Edit src/sndfile.c and find the function guess_file_type (). This function
reads the first 3 ints of the file and from that makes a guess at the file
type. In our case we would add:
if (buffer [0] == MAKE_MARKER ('W','A','C','K'))
return SF_FORMAT_WACK ;
The use of the MAKE_MARKER macro should be pretty obvious and it is defined at
the top of file should you need to have a look at it.
## Step 5
Add a call to your open function from psf_open_file ().
Edit src/sndfile.c and find the switch statement in psf_open_file (). It starts
like this:
switch (filetype)
{ case SF_FORMAT_WAV :
error = wav_open (psf) ;
break ;
case SF_FORMAT_AIFF :
error = aiff_open (psf) ;
break ;
Towards the bottom of this switch statement your should add one for the new file
type. Something like:
case SF_FORMAT_WACK :
sf_errno = whacky_open (psf) ;
break ;
## Step 6
Add prototypes for new open read and open write functions.
Edit src/common.h, go to the bottom of the file and add something like
int whacky_open (SF_PRIVATE *psf) ;
## Step 7
Implement your open read function. The best way to do this is by coding
something much like one of the other file formats. The file src/au.c might be a
good place to start.
In src/whacky.c you should now implement the function whacky_open() which
was prototyped in src/common.h. This function should return 0 on success and
a non-zero number on error.
Error values are defined in src/common.h in a enum which starts at SFE_NO_ERROR.
When adding a new error value, you also need to add an error string to the
SndfileErrors array in src/sndfile.c.
To parse the header of your new file type you should avoid using standard read/
write/seek functions (and the fread/fwrite/fseek etc) and instead use
psf_binheader_readf () which is implemented and documented in src/common.h.
During the parsing process, you should also print logging information to
libsndfile's internal log buffer using the psf_log_printf() function.
At the end of the open read process, you should have set a number of fields in
the SF_PRIVATE structure pointed to by psf.
**THIS FILE IS INCOMPLETE**

71
Engine/lib/libsndfile/docs/octave.md Normal file
View file

@ -0,0 +1,71 @@
---
layout: page
---
# libsndfile and GNU Octave
[GNU Octave](http://www.octave.org/) is a high-level interactive language for
numerical computations. There are currently two development streams, a stable
2.0.X series and a development 2.1.X series. Octave reads and writes data in
binary formats that were originally developed for
[MATLAB](http://www.mathworks.com/). Version 2.0.X of Octave uses binary data
files compatible with MATLAB version 4.2 while Octave 2.1.X uses binary data
files compatible with MATLAB version 5.0 as well as being able to read the older
MATLAB 4.2 format.
From version 1.0.1 of libsndfile onwards, libsndfile has the ability of reading
and writing a small subset of the binary data files used by both versions of GNU
Octave. This gives people using GNU Octave for audio based work an easy method
of moving audio data between GNU Octave and other programs which use libsndfile.
For instance it is now possible to do the following:
* Load a WAV file into a sound file editor such as
[Sweep](http://www.metadecks.org/software/sweep/).
* Save it as a MAT4 file.
* Load the data into Octave for manipulation.
* Save the modified data.
* Reload it in Sweep.
Another example would be using the MAT4 or MAT5 file formats as a format which
can be easily loaded into Octave for viewing/analyzing as well as a format which
can be played with command line players such as the one included with
libsndfile.
## Details
Octave, like most programming languages, uses variables to store data, and
Octave variables can contain both arrays and matrices. It is also able to store
one or more of these variables in a file. When reading Octave files, libsndfile
expects a file to contain two variables and their associated data. The first
variable should contain a variable holding the file sample rate while the second
variable contains the audio data.
For example, to generate a sine wave and store it as a binary file which is
compatible with libsndfile, do the following:
octave:1 > samplerate = 44100 ;
octave:2 > wavedata = sin ((0:1023)*2*pi/1024) ;
octave:3 > save sine.mat samplerate wavedata
The process of reading and writing files compatible with libsndfile can be made
easier by use of two Octave script files:
octave:4 > [data fs] = sndfile_load ("sine.mat") ;
octave:5 > sndfile_save ("sine2.mat", data, fs) ;
In addition, libsndfile contains a command line program which which is able to
play the correct types of Octave files. Using this command line player
**sndfile-play** and a third Octave script file allows Octave data to be played
from within Octave on any of the platforms which **sndfile-play** supports (at
the moment: Linux, MacOS X, Solaris and Win32).
octave:6 > sndfile_play (data, fs) ;
These three Octave scripts are installed automatically in Octave's site script
directory when libsndfile is installed (except on Win32) ie when libsndfile is
being installed into /usr/local, the Octave scripts will be installed in
/usr/local/share/octave/site/m/.
There are some other Octave scripts for audio to be found
[here](http://octave.sourceforge.net/audio/index.html).

14
Engine/lib/libsndfile/docs/print.css Normal file
View file

@ -0,0 +1,14 @@
body {
background:white;
color:black;
}
h1{
background:white;
color:black;
}
h2 {
background:white;
color:#666;
}

36
Engine/lib/libsndfile/docs/sndfile_info.md Normal file
View file

@ -0,0 +1,36 @@
---
layout: page
title: sndfile-info
---
Here is an example of the output from the **sndfile-info** program
distributed with libsndfile.
This file was opened and parsed correctly but had been truncated so that
the values in the **FORM** and **SSND** chunks were incorrect.
```
erikd@hendrix > examples/sndfile-info truncated.aiff
truncated.aiff
size : 200000
FORM : 307474 (should be 199992)
AIFF
COMM : 18
Sample Rate : 16000
Samples : 76857
Channels : 2
Sample Size : 16
SSND : 307436 (should be 199946)
Offset : 0
Block Size : 0
--------------------------------
Sample Rate : 16000
Frames : 76857
Channels : 2
Bit Width : 16
Format : 0x00020001
Sections : 1
Seekable : TRUE
Signal Max : 32766
```

10
Engine/lib/libsndfile/docs/tutorial.md Normal file
View file

@ -0,0 +1,10 @@
---
layout: page
---
# libsndfile Tutorial
**More coming soon.**
For now, the best place to look for example code is the `examples/` directory of the source code distribution and the
libsndfile test suite which is located in the `tests/` directory of the source code distribution.

18
Engine/lib/libsndfile/docs/win32.md Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
---
# Building libsndfile on Win32
**Note : For pre-compiled binaries for windows, both for win32 and win64, see
the main web page.**
There are currently two build systems; the official GNU autotool based one and
a more limited and experimental CMake based build system.
libsndfile is written to be compiled by a compiler which supports large chunks
of the 1999 ISO C Standard (tested with GCC, Clang and Visual Studio 2015).
It is recommended to use CMake and Visual Studio to build libsndfile on Windows
but you can try the [MinGW](http://www.mingw.org/) compiler suite with Autotools
or CMake buildsystem.