FS-11091: [mod_sndfile] Remove libsndfile from the code base, use pre-compiled binaries on Windows, update to libsndfile 1.0.28

This commit is contained in:
Andrey Volk committed 2018-04-05 01:56:04 +03:00
1 parent 58e4992494
commit a71ede5f57
359 files changed
+100 -119233

No files matched your search

-851
View File
@@ -1,851 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile : Frequently Asked Questions.
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<META NAME="Description" CONTENT="The libsndfile FAQ.">
<META NAME="Keywords" CONTENT="WAV AIFF AU libsndfile sound audio dsp Linux">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<H1><B>libsndfile : Frequently Asked Questions.</B></H1>
<P>
<A HREF="#Q001">Q1 : Do you plan to support XYZ codec in libsndfile?</A><BR/>
<A HREF="#Q002">Q2 : In version 0 the SF_INFO struct had a pcmbitwidth field
but version 1 does not. Why?</A><BR/>
<A HREF="#Q003">Q3 : Compiling is really slow on MacOS X. Why?</A><BR/>
<A HREF="#Q004">Q4 : When trying to compile libsndfile on Solaris I get a "bad
substitution" error during linking. What can I do to fix this?</A><BR/>
<A HREF="#Q005">Q5 : Why doesn't libsndfile do interleaving/de-interleaving?</A><BR/>
<A HREF="#Q006">Q6 : What's the best format for storing temporary files?</A><BR/>
<A HREF="#Q007">Q7 : On Linux/Unix/MacOS X, what's the best way of detecting the
presence of libsndfile?</A><BR/>
<A HREF="#Q008">Q8 : I have libsndfile installed and now I want to use it. I
just want a simple Makefile! What do I do?</A><BR/>
<A HREF="#Q009">Q9 : How about adding the ability to write/read sound files to/from
memory buffers?</A><BR/>
<A HREF="#Q010">Q10 : Reading a 16 bit PCM file as normalised floats and then
writing them back changes some sample values. Why?</A><BR/>
<A HREF="#Q011">Q11 : I'm having problems with u-law encoded WAV files generated by
libsndfile in Winamp. Why?</A><BR/>
<A HREF="#Q012">Q12 : I'm looking at sf_read*. What are items? What are frames?</A><BR/>
<A HREF="#Q013">Q13 : Why can't libsndfile open this Sound Designer II (SD2)
file?</A><BR/>
<A HREF="#Q014">Q14 : I'd like to statically link libsndfile to my closed source
application. Can I buy a license so that this is possible?</A><BR/>
<A HREF="#Q015">Q15 : My program is crashing during a call to a function in libsndfile.
Is this a bug in libsndfile?</A><BR/>
<A HREF="#Q016">Q16 : Will you accept a fix for compiling libsndfile with compiler X?
</A><BR/>
<A HREF="#Q017">Q17 : Can libsndfile read/write files from/to UNIX pipes?
</A><BR/>
<A HREF="#Q018">Q18 : Is it possible to build a Universal Binary on Mac OS X?
</A><BR/>
<A HREF="#Q019">Q19 : I have project files for Visual Studio / XCode / Whatever. Why
don't you distribute them with libsndfile?
</A><BR/>
<A HREF="#Q020">Q20 : Why doesn't libsndfile support MP3? Lots of other Open Source
projects support it!
</A><BR/>
<A HREF="#Q021">Q21 : How do I use libsndfile in a closed source or commercial program
and comply with the license?
</A><BR/>
<A HREF="#Q022">Q22 : What versions of windows does libsndfile work on?
</A><BR/>
<A HREF="#Q023">Q23 : I'm cross compiling libsndfile for another platform. How can I
run the test suite?
</A><BR/>
<HR>
<!-- ========================================================================= -->
<A NAME="Q001"></A>
<H2><BR/><B>Q1 : Do you plan to support XYZ codec in libsndfile?</B></H2>
<P>
If source code for XYZ codec is available under a suitable license (LGPL, BSD,
MIT etc) then yes, I'd like to add it.
</P>
<P>
If suitable documentation is available on how to decode and encode the format
then maybe, depending on how much work is involved.
</P>
<P>
If XYZ is some proprietary codec where no source code or documentation is
available then no.
</P>
<P>
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.
</P>
<!-- ========================================================================= -->
<A NAME="Q002"></A>
<H2><BR/><B>Q2 : In version 0 the SF_INFO struct had a pcmbitwidth field
but version 1 does not. Why?</B></H2>
<P>
This was dropped for a number of reasons:
</P>
<UL>
<LI> pcmbitwidth makes little sense on compressed or floating point formats
<LI> with the new API you really don't need to know it
</UL>
<P>
As documented
<A HREF="api.html#note1">here</A>
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.
</P>
<!-- ========================================================================= -->
<A NAME="Q003"></A>
<H2><BR/><B>Q3 : Compiling is really slow on MacOS X. Why?</B></H2>
<P>
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 <b>really</b> slow compiles.
Newer version of OS X ship GNU Bash as /bin/sh and this answer doesn't apply in that
case.
</P>
<P>
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 is is called as /bin/sh.
</P>
<P>
When I did this on my iBook running MacOS X, compile times dropped from 13 minutes
to 3 minutes.
</P>
<!-- ========================================================================= -->
<A NAME="Q004"></A>
<H2><BR/><B>Q4 : When trying to compile libsndfile on Solaris I get a "bad
substitution" error on linking. Why?</B></H2>
<P>
It seems that the Solaris Bourne shell disagrees with GNU libtool.
</P>
<P>
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 is is called as /bin/sh.
</P>
<!-- ========================================================================= -->
<A NAME="Q005"></A>
<H2><BR/><B>Q5 : Why doesn't libsndfile do interleaving/de-interleaving?</B></H2>
<P>
This problem is bigger than it may seem at first.
</P>
<P>
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.
</P>
<P>
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.
</P>
<!-- ========================================================================= -->
<A NAME="Q006"></A>
<H2><BR/><B>Q6 : What's the best format for storing temporary files?</B></H2>
<P>
When you want to store temporary data there are a number of requirements;
</P>
<UL>
<LI> A simple, easy to parse header.
<LI> The format must provide the fastest possible read and write rates (ie
avoid conversions and encoding/decoding).
<LI> The file format must be reasonably common and playable by most players.
<LI> Able to store data in either endian-ness.
</UL>
<P>
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.
</P>
<P>
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.
</P>
<!-- ========================================================================= -->
<A NAME="Q007"></A>
<H2><BR/><B>Q7 : On Linux/Unix/MaxOS X, what's the best way of detecting the presence
of libsndfile using autoconf?</B></H2>
<P>
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):
</P>
<PRE>
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)
</PRE>
<P>
This will automatically set the <B>SNDFILE_CFLAGS</B> and <B>SNDFILE_LIBS</B>
variables which can be used in Makefile.am like this:
</P>
<PRE>
SNDFILE_CFLAGS = @SNDFILE_CFLAGS@
SNDFILE_LIBS = @SNDFILE_LIBS@
</PRE>
<P>
If you install libsndfile from source, you will probably need to set the
<B>PKG_CONFIG_PATH</B> environment variable as suggested at the end of the
libsndfile configure process. For instance on my system I get this:
</P>
<PRE>
-=-=-=-=-=-=-=-=-=-= 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.
</PRE>
<!-- ========================================================================= -->
<A NAME="Q008"></A>
<H2><BR/><B>Q8 : I have libsndfile installed and now I want to use it. I just want
a simple Makefile! What do I do?</B></H2>
<P>
The <B>pkg-config</B> program makes finding the correct compiler flag values and
library location far easier.
During the installation of libsndfile, a file named <B>sndfile.pc</B> is installed
in the directory <B>${libdir}/pkgconfig</B> (ie if libsndfile is installed in
<B>/usr/local/lib</B>, <B>sndfile.pc</B> will be installed in
<B>/usr/local/lib/pkgconfig/</B>).
</P>
<P>
In order for pkg-config to find sndfile.pc it may be necessary to point the
environment variable <B>PKG_CONFIG_PATH</B> in the right direction.
</P>
<PRE>
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
</PRE>
<P>
Then, to compile a C file into an object file, the command would be:
</P>
<PRE>
gcc `pkg-config --cflags sndfile` -c somefile.c
</PRE>
<P>
and to link a number of objects into an executable that links against libsndfile,
the command would be:
</P>
<PRE>
gcc `pkg-config --libs sndfile` obj1.o obj2.o -o program
</PRE>
<!-- ========================================================================= -->
<A NAME="Q009"></A>
<H2><BR/><B>Q9 : How about adding the ability to write/read sound files to/from
memory buffers?</B></H2>
<P>
This has been added for version 1.0.13.
</P>
<!-- ========================================================================= -->
<A NAME="Q010"></A>
<H2><BR/><B>Q10 : Reading a 16 bit PCM file as normalised floats and then
writing them back changes some sample values. Why?</B></H2>
<P>
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.
</P>
<P>
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 <B>lrintf</B> and <B>lrint</B> (or a replacement has
been supplied) then the maximum possible error is 1 in 16369 or about 0.006%.
</P>
<P>
Regardless of the size of the error, the reason why this is done is rather
subtle.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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 <b>short</b> and <b>int</b> data
types (ie using sf_read_short or sf_read_int) or using un-normalized floats
(see
<a href="command.html#SFC_SET_NORM_FLOAT">
SFC_SET_NORM_FLOAT</a>).
</P>
<P>
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).
</P>
<!-- ========================================================================= -->
<A NAME="Q011"></A>
<H2><BR/><B>Q11 : I'm having problems with u-law encoded WAV files generated by
libsndfile in Winamp. Why?
</B></H2>
<P>
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.
</P>
<P>
Michael Lee did some experimenting and found that:
</P>
<PRE>
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.
</PRE>
<P>
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.
</P>
<!-- ========================================================================= -->
<A NAME="Q012"></A>
<H2><BR/><B>Q12 : I'm looking at sf_read*. What are items? What are frames?
</B></H2>
<P>
An <tt>item</tt> is a single sample of the data type you are reading; ie a
single <tt>short</tt> value for <tt>sf_read_short</tt> or a single <tt>float</tt>
for <tt>sf_read_float</tt>.
</P>
<P>
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.
</P>
<P>
Here are two simple, correct examples, both of which are assumed to be working
on a stereo file, first using items:
</P>
<PRE>
#define CHANNELS 2
short data [CHANNELS * 100] ;
sf_count items_read = sf_read_short (file, data, 200) ;
assert (items_read == 200) ;
</PRE>
<P>
and now readng the exact same amount of data using frames:
</P>
<PRE>
#define CHANNELS 2
short data [CHANNELS * 100] ;
sf_count frames_read = sf_readf_short (file, data, 100) ;
assert (frames_read == 100) ;
</PRE>
<!-- ========================================================================= -->
<A NAME="Q013"></A>
<H2><BR/><B>Q13 : Why can't libsndfile open this Sound Designer II (SD2) file?
</B></H2>
<P>
This is somewhat complicated.
First some background.
</P>
<P>
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:
</P>
<PRE>
-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
</PRE>
<P>
Notice how the file itself looks like a directory containing a single file
named <B>rsrc</B>.
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.
</P>
<P>
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.
</P>
<P>
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:
</P>
<PRE>
-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
</PRE>
<P>
Regardless of what platform it is running on, when libsndfile is asked to
open a file named <B>"foo"</B> 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 <B>"._foo"</B> 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.
</P>
<P>
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.
</P>
<P>
Occasionally, when SD2 files are moved to other systems, the file is
<A HREF="http://www.macdisk.com/binhexen.php3">BinHexed</A>
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.
</P>
<!-- ========================================================================= -->
<A NAME="Q014"></A>
<H2><BR/><B>Q14 : I'd like to statically link libsndfile to my closed source
application. Can I buy a license so that this is possible?
</B></H2>
<P>
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.
</P>
<P>
The <B>only</B> way you can legally use libsndfile as a statically linked
library is if your application is released under the GNU GPL or LGPL.
</P>
<!-- ========================================================================= -->
<A NAME="Q015"></A>
<H2><BR/><B>Q15 : My program is crashing during a call to a function in libsndfile.
Is this a bug in libsndfile?
</B></H2>
<P>
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.
</P>
<P>
To figure out whether it is your code or libsndfile you should do the
following:
</P>
<UL>
<LI>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
<B>-W -Wall -Werror</B> which will force you to fix all warnings
before you can run the code.
<LI>Try using a memory debugger.
<A HREF="http://valgrind.kde.org/">Valgrind</A> on x86 Linux is excellent.
<A HREF="http://www.ibm.com/software/awdtools/purify/">Purify</A> also
has a good reputation.
<LI>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.
</UL>
<!-- ========================================================================= -->
<A NAME="Q016"></A>
<H2><BR/><B>Q16 : Will you accept a fix for compiling libsndfile with compiler X?
</B></H2>
<P>
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.
</P>
<P>
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.
</P>
<!-- ========================================================================= -->
<A NAME="Q017"></A>
<H2><BR/><B>Q17 : Can libsndfile read/write files from/to UNIX pipes?
</B></H2>
<P>
Yes, libsndfile can read files from pipes.
Unfortunately, the write case is much more complicated.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
See also <A HREF="#Q006">FAQ Q6</A>.
</P>
<!-- ========================================================================= -->
<A NAME="Q018"></A>
<H2><BR/><B>Q18 : Is it possible to build a Universal Binary on Mac OS X?
</B></H2>
<P>
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.
</P>
<P>
It is <b>not</b> possible to build a working universal binary via a single
compile/build run on a single CPU.
</P>
<P>
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.
</P>
<P>
Part of the problem is the 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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</p>
<!-- ========================================================================= -->
<A NAME="Q019"></A>
<H2><BR/><B>Q19 : I have project files for Visual Studio / XCode / Whatever. Why
don't you distribute them with libsndfile?
</B></H2>
<P>
There's a very good reason for this.
I will only distribute things that I actually have an ability to test and
maintain.
Project files for a bunch of different compilers and Integrated Development
Environments are simply too difficult to maintain.
</P>
<P>
The problem is that every time I add a new file to libsndfile or rename an
existing file I would have to modify all the project files and then test that
libsndfile still built with all the different compilers.
</P>
<P>
Maintaining these project files is also rather difficult if I don't have access
to the required compiler/IDE.
If I just edit the project files without testing them I will almost certainly
get it wrong.
If I release a version of libsndfile with broken project files, I'll get a bunch
of emails from people complaining about it not building and have no way of
fixing or even testing it.
</P>
<P>
I currently release sources that I personally test on Win32, Linux and
MacOS X (PowerPC) using the compiler I trust (GNU GCC).
Supporting one compiler on three (actually much more because GCC is available
almost everywhere) platforms is doable without too much pain.
I also release binaries for Win32 with instructions on how to use those
binaries with Visual Studio.
As a guy who is mainly interested in Linux, I'm not to keen to jump through
a bunch of hoops to support compilers and operating systems I don't use.
</P>
<P>
So, I hear you want to volunteer to maintain the project files for Some Crappy
Compiler 2007?
Well sorry, that won't work either.
I have had numerous people over the years offer to maintaining the project
files for Microsoft's Visual Studio.
Every single time that happened, they maintained it for a release or two and
then disappeared off the face of the earth.
Hence, I'm not willing to enter into an arrangement like that again.
</P>
<!-- ========================================================================= -->
<A NAME="Q020"></A>
<H2><BR/><B>Q20 : Why doesn't libsndfile support MP3? Lots of other Open Source
projects support it!
</B></H2>
<P>
MP3 is not supported for one very good reason; doing so requires the payment
of licensing fees.
As can be seen from
<a href="http://www.mp3licensing.com/royalty/software.html">
mp3licensing.com</a>
the required royalty payments are not cheap.
</P>
<p>
Yes, I know other libraries ignore the licensing requirements, but their legal
status is extremely dubious.
At any time, the body selling the licenses could go after the authors of those
libraries.
Some of those authors may be students and hence wouldn't be worth pursuing.
</P>
<p>
However, libsndfile is released under the name of a company, Mega Nerd Pty Ltd;
a company which has income from from libsamplerate licensing, libsndfile based
consulting income and other unrelated consulting income.
Adding MP3 support to libsndfile could place that income under legal threat.
</p>
<p>
Fortunately, Ogg Vorbis exists as an alternative to MP3.
Support for Ogg Vorbis was added to libsndfile (mostly due to the efforts of
John ffitch of the Csound project) in version 1.0.18.
</p>
<!-- ========================================================================= -->
<A NAME="Q021"></A>
<H2><BR/><B>Q21 : How do I use libsndfile in a closed source or commercial program
and comply with the license?
</B></H2>
<p>
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):
</p>
<ul>
<li>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.
<li>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
<a href="http://www.gnu.org/licenses/lgpl-2.1.txt">version 2.1</a>
or optionally
<a href="http://www.gnu.org/licenses/lgpl.txt">version 3</a>.
<li>Include the text for both versions of the license, possibly as separate
files named libsndfile_lgpl_v2_1.txt and libsndfile_lgpl_v3.txt.
</ul>
<!-- ========================================================================= -->
<A NAME="Q022"></A>
<H2><BR/><B>Q22 : What versions of Windows does libsndfile work on?
</B></H2>
<p>
Currently the precompiled windows binaries are thoroughly tested on Windows XP.
As such, they should also work on Win2k and Windows Vista.
They may also work on earlier versions of Windows.
</p>
<p>
Since version 0.1.18 I have also been releasing precompiled binaries for Win64,
the 64 bit version of Windows.
These binaries have received much less testing than the 32 bit versions, but
should work as expected.
I'd be very interested in receiving feedback on these binaries.
</p>
<!-- ========================================================================= -->
<A NAME="Q023"></A>
<H2><BR/><B>Q23 : I'm cross compiling libsndfile for another platform. How can I
run the test suite?
</B></H2>
<p>
</p>
<p>
Since version 1.0.21 the top level Makefile has an extra make target,
'test-tarball'.
Building this target creates a tarball called called:
</p>
<center><tt>
libsndfile-testsuite-${host_triplet}-${version}.tar.gz
</tt></center>
<p>
in the top level directory.
This tarball can then be copied to the target platform.
Once untarred and test script <tt>test_wrapper.sh</tt> can be run from
the top level of the extracted tarball.
</p>
<!-- ========================================================================= -->
<HR>
<P>
The libsndfile home page is here :
<A HREF="http://www.mega-nerd.com/libsndfile/">
http://www.mega-nerd.com/libsndfile/</A>.
<BR/>
Version : 1.0.25
</P>
</BODY>
</HTML>
-9
View File
@@ -1,9 +0,0 @@
## Process this file with automake to produce Makefile.in
html_DATA = index.html libsndfile.jpg libsndfile.css api.html command.html \
bugs.html sndfile_info.html new_file_type.HOWTO \
win32.html FAQ.html lists.html embedded_files.html octave.html \
dither.html tutorial.html
EXTRA_DIST = $(html_DATA)
-781
View File
@@ -1,781 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
The libsndfile API
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<META NAME="Description" CONTENT="The libsndfile API.">
<META NAME="Keywords" CONTENT="WAV AIFF AU libsndfile sound audio dsp Linux">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<BR>
<H1><B>libsndfile</B></H1>
<P>
Libsndfile is a library designed to allow the reading and writing of many
different sampled sound file formats (such as MS Windows WAV and the Apple/SGI
AIFF format) through one standard library interface.
</P>
<!-- pepper -->
<P>
During read and write operations, formats are seamlessly converted between the
format the application program has requested or supplied and the file's data
format. The application programmer can remain blissfully unaware of issues
such as file endian-ness and data format. See <A HREF="#note1">Note 1</A> and
<A HREF="#note2">Note 2</A>.
</P>
<!-- pepper -->
<P>
Every effort is made to keep these documents up-to-date, error free and
unambiguous.
However, since maintaining the documentation is the least fun part of working
on libsndfile, these docs can and do fall behind the behaviour of library.
If any errors, omissions or ambiguities are found, please notify me (erikd)
at mega-nerd dot com.
</P>
<!-- pepper -->
<P>
To supplement this reference documentation, there are simple example programs
included in the source code tarball.
The test suite which is also part of the source code tarball is also a good
place to look for the correct usage of the library functions.
</P>
<!-- pepper -->
<P>
<B> Finally, if you think there is some feature missing from libsndfile, check that
it isn't already implemented (and documented)
<A HREF="command.html">here</A>.
</B>
</P>
<H2><B>Synopsis</B></H2>
<P>
The functions of libsndfile are defined as follows:
</P>
<!-- pepper -->
<PRE>
#include &lt;stdio.h&gt;
#include &lt;sndfile.h&gt;
SNDFILE* <A HREF="#open">sf_open</A> (const char *path, int mode, SF_INFO *sfinfo) ;
SNDFILE* <A HREF="#open_fd">sf_open_fd</A> (int fd, int mode, SF_INFO *sfinfo, int close_desc) ;
SNDFILE* <A HREF="#open_virtual">sf_open_virtual</A> (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ;
int <A HREF="#check">sf_format_check</A> (const SF_INFO *info) ;
sf_count_t <A HREF="#seek">sf_seek</A> (SNDFILE *sndfile, sf_count_t frames, int whence) ;
int <A HREF="command.html">sf_command</A> (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
int <A HREF="#error">sf_error</A> (SNDFILE *sndfile) ;
const char* <A HREF="#error">sf_strerror</A> (SNDFILE *sndfile) ;
const char* <A HREF="#error">sf_error_number</A> (int errnum) ;
int <A HREF="#error">sf_perror</A> (SNDFILE *sndfile) ;
int <A HREF="#error">sf_error_str</A> (SNDFILE *sndfile, char* str, size_t len) ;
int <A HREF="#close">sf_close</A> (SNDFILE *sndfile) ;
void <A HREF="#write_sync">sf_write_sync</A> (SNDFILE *sndfile) ;
sf_count_t <A HREF="#read">sf_read_short</A> (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t <A HREF="#read">sf_read_int</A> (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t <A HREF="#read">sf_read_float</A> (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t <A HREF="#read">sf_read_double</A> (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
sf_count_t <A HREF="#readf">sf_readf_short</A> (SNDFILE *sndfile, short *ptr, sf_count_t frames) ;
sf_count_t <A HREF="#readf">sf_readf_int</A> (SNDFILE *sndfile, int *ptr, sf_count_t frames) ;
sf_count_t <A HREF="#readf">sf_readf_float</A> (SNDFILE *sndfile, float *ptr, sf_count_t frames) ;
sf_count_t <A HREF="#readf">sf_readf_double</A> (SNDFILE *sndfile, double *ptr, sf_count_t frames) ;
sf_count_t <A HREF="#write">sf_write_short</A> (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t <A HREF="#write">sf_write_int</A> (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t <A HREF="#write">sf_write_float</A> (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t <A HREF="#write">sf_write_double</A> (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
sf_count_t <A HREF="#writef">sf_writef_short</A> (SNDFILE *sndfile, short *ptr, sf_count_t frames) ;
sf_count_t <A HREF="#writef">sf_writef_int</A> (SNDFILE *sndfile, int *ptr, sf_count_t frames) ;
sf_count_t <A HREF="#writef">sf_writef_float</A> (SNDFILE *sndfile, float *ptr, sf_count_t frames) ;
sf_count_t <A HREF="#writef">sf_writef_double</A> (SNDFILE *sndfile, double *ptr, sf_count_t frames) ;
sf_count_t <A HREF="#raw">sf_read_raw</A> (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
sf_count_t <A HREF="#raw">sf_write_raw</A> (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
const char* <A HREF="#string">sf_get_string</A> (SNDFILE *sndfile, int str_type) ;
int <A HREF="#string">sf_set_string</A> (SNDFILE *sndfile, int str_type, const char* str) ;
</PRE>
<!-- pepper -->
<P>
SNDFILE* is an anonymous pointer to data which is private to the library.
</P>
<A NAME="open"></A>
<H2><B>File Open Function</B></H2>
<PRE>
SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ;
</PRE>
<P>
The SF_INFO structure is for passing data between the calling function and the library
when opening a file for reading or writing. It is defined in sndfile.h as follows:
</P>
<!-- pepper -->
<PRE>
typedef struct
{ sf_count_t frames ; /* Used to be called samples. */
int samplerate ;
int channels ;
int format ;
int sections ;
int seekable ;
} SF_INFO ;
</PRE>
<P>
The mode parameter for this function can be any one of the following three values:
</P>
<!-- pepper -->
<PRE>
SFM_READ - read only mode
SFM_WRITE - write only mode
SFM_RDWR - read/write mode
</PRE>
<P>
When opening a file for read, the <b>format</B> field should be set to zero before
calling sf_open().
The only exception to this is the case of RAW files where the caller has to set
the samplerate, channels and format fields to valid values.
All other fields of the structure are filled in by the library.
</P>
<!-- pepper -->
<P>
When opening a file for write, the caller must fill in structure members samplerate,
channels, and format.
</P>
<!-- pepper -->
<P>
The format field in the above SF_INFO structure is made up of the bit-wise OR of a
major format type (values between 0x10000 and 0x08000000), a minor format type
(with values less than 0x10000) and an optional endian-ness value.
The currently understood formats are listed in sndfile.h as follows and also include
bitmasks for separating major and minor file types.
Not all combinations of endian-ness and major and minor file types are valid.
</P>
<!-- pepper -->
<PRE>
enum
{ /* Major formats. */
SF_FORMAT_WAV = 0x010000, /* Microsoft WAV format (little endian). */
SF_FORMAT_AIFF = 0x020000, /* Apple/SGI AIFF format (big endian). */
SF_FORMAT_AU = 0x030000, /* Sun/NeXT AU format (big endian). */
SF_FORMAT_RAW = 0x040000, /* RAW PCM data. */
SF_FORMAT_PAF = 0x050000, /* Ensoniq PARIS file format. */
SF_FORMAT_SVX = 0x060000, /* Amiga IFF / SVX8 / SV16 format. */
SF_FORMAT_NIST = 0x070000, /* Sphere NIST format. */
SF_FORMAT_VOC = 0x080000, /* VOC files. */
SF_FORMAT_IRCAM = 0x0A0000, /* Berkeley/IRCAM/CARL */
SF_FORMAT_W64 = 0x0B0000, /* Sonic Foundry's 64 bit RIFF/WAV */
SF_FORMAT_MAT4 = 0x0C0000, /* Matlab (tm) V4.2 / GNU Octave 2.0 */
SF_FORMAT_MAT5 = 0x0D0000, /* Matlab (tm) V5.0 / GNU Octave 2.1 */
SF_FORMAT_PVF = 0x0E0000, /* Portable Voice Format */
SF_FORMAT_XI = 0x0F0000, /* Fasttracker 2 Extended Instrument */
SF_FORMAT_HTK = 0x100000, /* HMM Tool Kit format */
SF_FORMAT_SDS = 0x110000, /* Midi Sample Dump Standard */
SF_FORMAT_AVR = 0x120000, /* Audio Visual Research */
SF_FORMAT_WAVEX = 0x130000, /* MS WAVE with WAVEFORMATEX */
SF_FORMAT_SD2 = 0x160000, /* Sound Designer 2 */
SF_FORMAT_FLAC = 0x170000, /* FLAC lossless file format */
SF_FORMAT_CAF = 0x180000, /* Core Audio File format */
SF_FORMAT_WVE = 0x190000, /* Psion WVE format */
SF_FORMAT_OGG = 0x200000, /* Xiph OGG container */
SF_FORMAT_MPC2K = 0x210000, /* Akai MPC 2000 sampler */
SF_FORMAT_RF64 = 0x220000, /* RF64 WAV file */
/* Subtypes from here on. */
SF_FORMAT_PCM_S8 = 0x0001, /* Signed 8 bit data */
SF_FORMAT_PCM_16 = 0x0002, /* Signed 16 bit data */
SF_FORMAT_PCM_24 = 0x0003, /* Signed 24 bit data */
SF_FORMAT_PCM_32 = 0x0004, /* Signed 32 bit data */
SF_FORMAT_PCM_U8 = 0x0005, /* Unsigned 8 bit data (WAV and RAW only) */
SF_FORMAT_FLOAT = 0x0006, /* 32 bit float data */
SF_FORMAT_DOUBLE = 0x0007, /* 64 bit float data */
SF_FORMAT_ULAW = 0x0010, /* U-Law encoded. */
SF_FORMAT_ALAW = 0x0011, /* A-Law encoded. */
SF_FORMAT_IMA_ADPCM = 0x0012, /* IMA ADPCM. */
SF_FORMAT_MS_ADPCM = 0x0013, /* Microsoft ADPCM. */
SF_FORMAT_GSM610 = 0x0020, /* GSM 6.10 encoding. */
SF_FORMAT_VOX_ADPCM = 0x0021, /* Oki Dialogic ADPCM encoding. */
SF_FORMAT_G721_32 = 0x0030, /* 32kbs G721 ADPCM encoding. */
SF_FORMAT_G723_24 = 0x0031, /* 24kbs G723 ADPCM encoding. */
SF_FORMAT_G723_40 = 0x0032, /* 40kbs G723 ADPCM encoding. */
SF_FORMAT_DWVW_12 = 0x0040, /* 12 bit Delta Width Variable Word encoding. */
SF_FORMAT_DWVW_16 = 0x0041, /* 16 bit Delta Width Variable Word encoding. */
SF_FORMAT_DWVW_24 = 0x0042, /* 24 bit Delta Width Variable Word encoding. */
SF_FORMAT_DWVW_N = 0x0043, /* N bit Delta Width Variable Word encoding. */
SF_FORMAT_DPCM_8 = 0x0050, /* 8 bit differential PCM (XI only) */
SF_FORMAT_DPCM_16 = 0x0051, /* 16 bit differential PCM (XI only) */
SF_FORMAT_VORBIS = 0x0060, /* Xiph Vorbis encoding. */
/* Endian-ness options. */
SF_ENDIAN_FILE = 0x00000000, /* Default file endian-ness. */
SF_ENDIAN_LITTLE = 0x10000000, /* Force little endian-ness. */
SF_ENDIAN_BIG = 0x20000000, /* Force big endian-ness. */
SF_ENDIAN_CPU = 0x30000000, /* Force CPU endian-ness. */
SF_FORMAT_SUBMASK = 0x0000FFFF,
SF_FORMAT_TYPEMASK = 0x0FFF0000,
SF_FORMAT_ENDMASK = 0x30000000
} ;
</PRE>
<!-- pepper -->
<P>
Every call to sf_open() should be matched with a call to sf_close() to free up
memory allocated during the call to sf_open().
</P>
<!-- pepper -->
<P>
On success, the sf_open function returns a non-NULL pointer which should be
passed as the first parameter to all subsequent libsndfile calls dealing with
that audio file.
On fail, the sf_open function returns a NULL pointer.
An explanation of the error can obtained by passing NULL to
<A HREF="#error">sf_strerror</A>.
</P>
<A NAME="open_fd"></A>
<H3><B>File Descriptor Open</B></H3>
<PRE>
SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ;
</PRE>
<P>
<b>Note:</b> On Microsoft Windows, this function does not work if the
application and the libsndfile DLL are linked to different versions of the
Microsoft C runtime DLL.
</P>
<P>
The second open function takes a file descriptor of a file that has already been
opened.
Care should be taken to ensure that the mode of the file represented by the
descriptor matches the mode argument.
This function is useful in the following circumstances:
</P>
<UL>
<LI>Opening temporary files securely (ie use the tmpfile() to return a
FILE* pointer and then using fileno() to retrieve the file descriptor
which is then passed to libsndfile).
<LI>Opening files with file names using OS specific character encodings
and then passing the file descriptor to sf_open_fd().
<LI>Opening sound files embedded within larger files.
<A HREF="embedded_files.html">More info</A>.
</UL>
<P>
Every call to sf_open_fd() should be matched with a call to sf_close() to free up
memory allocated during the call to sf_open().
</P>
<P>
When sf_close() is called, the file descriptor is only closed if the <B>close_desc</B>
parameter was TRUE when the sf_open_fd() function was called.
</P>
<P>
On success, the sf_open_fd function returns a non-NULL pointer which should be
passed as the first parameter to all subsequent libsndfile calls dealing with
that audio file.
On fail, the sf_open_fd function returns a NULL pointer.
</P>
<A NAME="open_virtual"></A>
<h3><b>Virtual File Open Function</b></h3>
<pre>
SNDFILE* sf_open_virtual (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ;
</pre>
<p>
Opens a soundfile from a virtual file I/O context which is provided
by the caller. This is usually used to interface libsndfile to a stream or buffer
based system. Apart from the sfvirtual and the user_data parameters this function behaves
like <a href="#open">sf_open</a>.
</p>
<pre>
typedef struct
{ sf_vio_get_filelen get_filelen ;
sf_vio_seek seek ;
sf_vio_read read ;
sf_vio_write write ;
sf_vio_tell tell ;
} SF_VIRTUAL_IO ;
</pre>
<p>
Libsndfile calls the callbacks provided by the SF_VIRTUAL_IO structure when opening, reading
and writing to the virtual file context. The user_data pointer is a user defined context which
will be available in the callbacks.
</p>
<pre>
typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ;
typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ;
typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ;
typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ;
typedef sf_count_t (*sf_vio_tell) (void *user_data) ;
</pre>
<h4>sf_vio_get_filelen</h4>
<pre>
typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ;
</pre>
<p>
The virtual file contex must return the length of the virtual file in bytes.<br>
</p>
<h4>sf_vio_seek</h4>
<pre>
typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ;
</pre>
<p>
The virtual file context must seek to offset using the seek mode provided by whence which is one of<br>
</p>
<pre>
SEEK_CUR
SEEK_SET
SEEK_END
</pre>
<p>
The return value must contain the new offset in the file.
</p>
<h4>sf_vio_read</h4>
<pre>
typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ;
</pre>
<p>
The virtual file context must copy ("read") "count" bytes into the
buffer provided by ptr and return the count of actually copied bytes.
</p>
<h4>sf_vio_write</h4>
<pre>
typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ;
</pre>
<p>
The virtual file context must process "count" bytes stored in the
buffer passed with ptr and return the count of actually processed bytes.<br>
</p>
<h4>sf_vio_tell</h4>
<pre>
typedef sf_count_t (*sf_vio_tell) (void *user_data) ;
</pre>
<p>
Return the current position of the virtual file context.<br>
</p>
<A NAME="check"></A>
<BR><H2><B>Format Check Function</B></H2>
<PRE>
int sf_format_check (const SF_INFO *info) ;
</PRE>
<!-- pepper -->
<P>
This function allows the caller to check if a set of parameters in the SF_INFO struct
is valid before calling sf_open (SFM_WRITE).
</P>
<P>
sf_format_check returns TRUE if the parameters are valid and FALSE otherwise.
</P>
<A NAME="seek"></A>
<BR><H2><B>File Seek Functions</B></H2>
<PRE>
sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ;
</PRE>
<P>
The file seek functions work much like lseek in unistd.h with the exception that
the non-audio data is ignored and the seek only moves within the audio data section of
the file.
In addition, seeks are defined in number of (multichannel) frames.
Therefore, a seek in a stereo file from the current position forward with an offset
of 1 would skip forward by one sample of both channels.
</P>
<P>
like lseek(), the whence parameter can be any one of the following three values:
</P>
<PRE>
SEEK_SET - The offset is set to the start of the audio data plus offset (multichannel) frames.
SEEK_CUR - The offset is set to its current location plus offset (multichannel) frames.
SEEK_END - The offset is set to the end of the data plus offset (multichannel) frames.
</PRE>
<!-- pepper -->
<P>
Internally, libsndfile keeps track of the read and write locations using separate
read and write pointers.
If a file has been opened with a mode of SFM_RDWR, bitwise OR-ing the standard whence
values above with either SFM_READ or SFM_WRITE allows the read and write pointers to
be modified separately.
If the SEEK_* values are used on their own, the read and write pointers are
both modified.
</P>
<P>
Note that the frames offset can be negative and in fact should be when SEEK_END is used for the
whence parameter.
</P>
<P>
sf_seek will return the offset in (multichannel) frames from the start of the audio data
or -1 if an error occured (ie an attempt is made to seek beyond the start or end of the file).
</P>
<A NAME="error"></A>
<H2><BR><B>Error Reporting Functions</B></H2>
<PRE>
int sf_error (SNDFILE *sndfile) ;
</PRE>
<P>
This function returns the current error number for the given SNDFILE.
The error number may be one of the following:
</P>
<PRE>
enum
{ SF_ERR_NO_ERROR = 0,
SF_ERR_UNRECOGNISED_FORMAT = 1,
SF_ERR_SYSTEM = 2,
SF_ERR_MALFORMED_FILE = 3,
SF_ERR_UNSUPPORTED_ENCODING = 4
} ;
</PRE>
<!-- pepper -->
<P>
or any one of many other internal error values.
Applications should only test the return value against error values defined in
&lt;sndfile.h&gt; as the internal error values are subject to change at any
time.
For errors not in the above list, the function sf_error_number() can be used to
convert it to an error string.
</P>
<PRE>
const char* sf_strerror (SNDFILE *sndfile) ;
const char* sf_error_number (int errnum) ;
</PRE>
<P>
The error functions sf_strerror() and sf_error_number() convert the library's internal
error enumerations into text strings.
</P>
<PRE>
int sf_perror (SNDFILE *sndfile) ;
int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ;
</PRE>
<P>
The functions sf_perror() and sf_error_str() are deprecated and will be dropped
from the library at some later date.
</P>
<A NAME="close"></A>
<H2><BR><B>File Close Function</B></H2>
<PRE>
int sf_close (SNDFILE *sndfile) ;
</PRE>
<!-- pepper -->
<P>
The close function closes the file, deallocates its internal buffers and returns
0 on success or an error value otherwise.
</P>
<BR>
<A NAME="write_sync"></A>
<H2><BR><B>Write Sync Function</B></H2>
<PRE>
void sf_write_sync (SNDFILE *sndfile) ;
</PRE>
<!-- pepper -->
<P>
If the file is opened SFM_WRITE or SFM_RDWR, call the operating system's function
to force the writing of all file cache buffers to disk. If the file is opened
SFM_READ no action is taken.
</P>
<BR>
<A NAME="read"></A>
<H2><BR><B>File Read Functions (Items)</B></H2>
<PRE>
sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
</PRE>
<P>
The file read items functions fill the array pointed to by ptr with the requested
number of items. The items parameter must be an integer product of the number
of channels or an error will occur.
</P>
<!-- pepper -->
<P>
It is important to note that the data type used by the calling program and the data
format of the file do not need to be the same. For instance, it is possible to open
a 16 bit PCM encoded WAV file and read the data using sf_read_float(). The library
seamlessly converts between the two formats on-the-fly. See
<A HREF="#note1">Note 1</A>.
</P>
<!-- pepper -->
<P>
The sf_read_XXXX functions return the number of items read.
Unless the end of the file was reached during the read, the return value should
equal the number of items requested.
Attempts to read beyond the end of the file will not result in an error but will
cause the sf_read_XXXX functions to return less than the number of items requested
or 0 if already at the end of the file.
</P>
<A NAME="readf"></A>
<H2><BR><B>File Read Functions (Frames)</B></H2>
<PRE>
sf_count_t sf_readf_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ;
sf_count_t sf_readf_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ;
sf_count_t sf_readf_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ;
sf_count_t sf_readf_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ;
</PRE>
<!-- pepper -->
<P>
The file read frames functions fill the array pointed to by ptr with the requested
number of frames of data. The array must be large enough to hold the product of
frames and the number of channels.
</P>
<P><B>
Care must be taken to ensure that there is enough space in the array pointed to by
ptr, to take (frames * channels) number of items (shorts, ints, floats or doubles).
</B></P>
<P>
The sf_readf_XXXX functions return the number of frames read.
Unless the end of the file was reached during the read, the return value should equal
the number of frames requested.
Attempts to read beyond the end of the file will not result in an error but will cause
the sf_readf_XXXX functions to return less than the number of frames requested or 0 if
already at the end of the file.
</P>
<A NAME="write"></A>
<H2><BR><B>File Write Functions (Items)</B></H2>
<PRE>
sf_count_t sf_write_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t sf_write_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t sf_write_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t sf_write_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
</PRE>
<P>
The file write items functions write the data in the array pointed to by ptr to the file.
The items parameter must be an integer product of the number of channels or an error
will occur.
</P>
<!-- pepper -->
<P>
It is important to note that the data type used by the calling program and the data
format of the file do not need to be the same. For instance, it is possible to open
a 16 bit PCM encoded WAV file and write the data using sf_write_float(). The library
seamlessly converts between the two formats on-the-fly. See
<A HREF="#note1">Note 1</A>.
</P>
<P>
The sf_write_XXXX functions return the number of items written (which should be the
same as the items parameter).
</P>
<A NAME="writef"></A>
<H2><BR><B>File Write Functions (Frames)</B></H2>
<PRE>
sf_count_t sf_writef_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ;
sf_count_t sf_writef_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ;
sf_count_t sf_writef_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ;
sf_count_t sf_writef_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ;
</PRE>
<P>
The file write frames functions write the data in the array pointed to by ptr to the file.
The array must be large enough to hold the product of frames and the number of channels.
</P>
<P>
The sf_writef_XXXX functions return the number of frames written (which should be the
same as the frames parameter).
</P>
<A NAME="raw"></A>
<H2><BR><B>Raw File Read and Write Functions</B></H2>
<!-- pepper -->
<PRE>
sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
sf_count_t sf_write_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
</PRE>
<P>
<b>Note:</b> Unless you are writing an external decoder/encode that uses
libsndfile to handle the file headers, you should not be using these
functions.
</P>
<P>
The raw read and write functions read raw audio data from the audio file (not to be
confused with reading RAW header-less PCM files). The number of bytes read or written
must always be an integer multiple of the number of channels multiplied by the number
of bytes required to represent one sample from one channel.
</P>
<!-- pepper -->
<P>
The raw read and write functions return the number of bytes read or written (which
should be the same as the bytes parameter).
</P>
<P>
<B>
Note : The result of using of both regular reads/writes and raw reads/writes on
compressed file formats other than SF_FORMAT_ALAW and SF_FORMAT_ULAW is undefined.
</B>
</P>
<p>
See also : <a href="command.html#SFC_RAW_NEEDS_ENDSWAP">SFC_RAW_NEEDS_ENDSWAP</a>
</p>
<A NAME="string"></A>
<H2><BR><B>Functions for Reading and Writing String Data</B></H2>
<PRE>
const char* sf_get_string (SNDFILE *sndfile, int str_type) ;
int sf_set_string (SNDFILE *sndfile, int str_type, const char* str) ;
</PRE>
<P>
These functions allow strings to be set on files opened for write and to be
retrieved from files opened for read where supported by the given file type.
The <B>str_type</B> parameter can be any one of the following string types:
</P>
<PRE>
enum
{ SF_STR_TITLE,
SF_STR_COPYRIGHT,
SF_STR_SOFTWARE,
SF_STR_ARTIST,
SF_STR_COMMENT,
SF_STR_DATE,
SF_STR_ALBUM,
SF_STR_LICENSE,
SF_STR_TRACKNUMBER,
SF_STR_GENRE
} ;
</PRE>
<P>
The sf_get_string() function returns the specified string if it exists and a
NULL pointer otherwise.
In addition to the string ids above, SF_STR_FIRST (== SF_STR_TITLE) and
SF_STR_LAST (always the same as the highest numbers string id) are also
available to allow iteration over all the available string ids.
</P>
<P>
The sf_set_string() function sets the string data.
It returns zero on success and non-zero on error.
The error code can be converted to a string using sf_error_number().
</P>
<P>
</P>
<HR>
<A NAME="note1"></A>
<H2><BR><B>Note 1</B></H2>
<!-- pepper -->
<P>
When converting between integer PCM formats of differing size (ie using sf_read_int()
to read a 16 bit PCM encoded WAV file) libsndfile obeys one simple rule:
</P>
<P CLASS=indent_block>
Whenever integer data is moved from one sized container to another sized container,
the most significant bit in the source container will become the most significant bit
in the destination container.
</P>
<P>
When converting between integer data and floating point data, different rules apply.
The default behaviour when reading floating point data (sf_read_float() or
sf_read_double ()) from a file with integer data is normalisation. Regardless of
whether data in the file is 8, 16, 24 or 32 bit wide, the data will be read as
floating point data in the range [-1.0, 1.0]. Similarly, data in the range [-1.0, 1.0]
will be written to an integer PCM file so that a data value of 1.0 will be the largest
allowable integer for the given bit width. This normalisation can be turned on or off
using the <A HREF="command.html">sf_command</A> interface.
</P>
<A NAME="note2"></A>
<H2><BR><B>Note 2</B></H2>
<P>
Reading a file containg floating point data (allowable with WAV, AIFF, AU and other
file formats) using integer read methods (sf_read_short() or sf_read_int()) can
produce unexpected results.
For instance the data in the file may have a maximum absolute value &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
<A HREF="command.html">sf_command</A>
interface, a command of
<A HREF="command.html#SFC_SET_SCALE_FLOAT_INT_READ">SFC_SET_SCALE_FLOAT_INT_READ</A>
and a parameter of SF_TRUE to force correct scaling.
</P>
<!-- pepper -->
<HR>
<!-- pepper -->
<P>
The libsndfile home page is
<A HREF="http://www.mega-nerd.com/libsndfile/">here</A>.
</P>
<P>
Version : 1.0.25
</P>
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
</BODY>
</HTML>
-76
View File
@@ -1,76 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
Bug Reporting
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<CENTER>
<H1><B>Reporting Bugs in libsndfile</B></H1>
</CENTER>
<P>
Before even attempting to report a bug in libsndfile please make sure you have
read the
<A HREF="FAQ.html">Frequently Asked Questions</A>.
If you are having a problem writing code using libsndfile make sure you read
the
<A HREF="api.html">Application Programming Interface</A>
documentation.
</P>
<P>
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) :
</P>
<UL>
<LI> Compilation problems on new platforms.
<LI> Errors being detected during the `make check' process.
<LI> Segmentation faults occuring inside libsndfile.
<LI> libsndfile hanging when opening a file.
<LI> Supported sound file types being incorrectly read or written.
<LI> Omissions, errors or spelling mistakes in the documentation.
</UL>
<P>
When submitting a bug report you must include :
</P>
<UL>
<LI> Your system (CPU and memory size should be enough).
<LI> The operating system you are using.
<LI> Whether you are using a package provided by your distribution or you
compiled it youself.
<LI> If you compiled it yourself, the compiler you are using. (Also make
sure to run 'make check'.)
<LI> A description of the problem.
<LI> Information generated by the sndfile-info program (see next paragraph).
<LI> 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.
</UL>
<P>
If libsndfile compiles and installs correctly but has difficulty reading a particular
file or type of file you should run the <B>sndfile-info</B> program (from the examples
directory of the libsndfile distribution) on the file. See
<A HREF="sndfile_info.html">here</A>
for an example of the use of the <B>sndfile-info</B> program.
</P>
<P>
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.
</P>
<P>
Once you have the above information you should submit a ticket on the libsnfile
<A HREF="https://github.com/erikd/libsndfile/issues">github issue tracker</A>.
</P>
</BODY>
</HTML>
File diff suppressed because it is too large. Load diff
-43
View File
@@ -1,43 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile Development
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<!-- pepper -->
<H1><BR>libsndfile Development</H1>
<!-- pepper -->
<P>
libsndfile is being developed by a small but growing community of users
and hackers led by Erik de Castro Lopo.
People interested in helping should join the libsndfile-devel
<A HREF="lists.html">mailing list</A>
where most of the discussion about new features takes place.
</P>
<!-- pepper -->
<P>
The main repository can be found on Github:
</P>
<!-- pepper -->
<center>
<A HREF="https://github.com/erikd/libsndfile/">
https://github.com/erikd/libsndfile/</A>
</center>
<!-- pepper -->
<P>
and includes
<a href="https://github.com/erikd/libsndfile/blob/master/README.md">
instuctions</a>
on how to build libsndfilefrom the Git repo.
</P>
<!-- pepper -->
</BODY>
</HTML>
File diff suppressed because it is too large. Load diff
-112
View File
@@ -1,112 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile : donate.
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<!-- Another version at the bottom of the page. -->
<META NAME="Description" CONTENT="The libsndfile API.">
<META NAME="Keywords" CONTENT="WAV AIFF AU libsndfile sound audio dsp Linux">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<br/>
<!-- pepper -->
<center>
<IMG SRC="libsndfile.jpg" HEIGHT=98 WIDTH=367 ALT="libsndfile.jpg">
</center>
<!-- pepper -->
<br/>
<p>
Dear libsndfile user,
</p>
<!-- pepper -->
<p>
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.
</p>
<!-- pepper -->
<p>
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 decent
rate, 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.
</p>
<!-- pepper -->
<p>
You are free to donate any amount you chose.
As a guideline:
</p>
<!-- pepper -->
<ul>
<li>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.
</li>
<li>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.
</li>
<li>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.
</li>
</ul>
<!-- pepper -->
<p>
Donations can be made in Bitcoin to the Bitcoin address
<b>15hVWemFiH6DLJ22SBYPk9b4fgWtxBEvfQ</b>
which can be verified by checking the following GPG signature.
</p>
<pre>
-----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-----
</pre>
<p>
Thanks and regards,
<br/>
Erik de Castro Lopo
<br/>
Main libsndfile author and maintainer
</p>
<!-- pepper -->
<img src=
"/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|trgb=0;0;0|wxh=15;20|md=6|dd=B|st=1|sh=1|df=libsndfile-donate.dat"
HEIGHT=0 WIDTH=0 ALT="">
</BODY>
</HTML>
-47
View File
@@ -1,47 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile : Embedded Sound Files.
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<META NAME="Description" CONTENT="The libsndfile API.">
<META NAME="Keywords" CONTENT="WAV AIFF AU libsndfile sound audio dsp Linux">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<!-- pepper -->
<BODY>
<!-- pepper -->
<H1><B>Embedded Sound Files.</B></H1>
<P>
By using the open SNDFILE with a file descriptor function:
</P>
<!-- pepper -->
<PRE>
SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ;
</PRE>
<!-- pepper -->
<P>
it is possible to open sound files embedded within larger files.
There are however a couple of caveats:
<P>
<!-- pepper -->
<UL>
<LI> Read/Write mode (SFM_RDWR) is not supported.
<LI> Writing of embedded files is only supported at the end of the file.
<LI> Reading of embedded files is only supported at file offsets greater
than zero.
<LI> Not all file formats are supported (currently only WAV, AIFF and AU).
</UL>
<!-- pepper -->
<P>
The test program <B>multi_file_test.c</B> in the <B>tests/</B> directory of the
source code tarball shows how this functionality is used to read and write
embedded files.
</P>
<!-- pepper -->
</BODY>
</HTML>
-493
View File
@@ -1,493 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<META NAME="Version" CONTENT="libsndfile-1.0.25">
<META NAME="Description" CONTENT="The libsndfile Home Page">
<META NAME="Keywords" CONTENT="WAV AIFF AU SVX PAF NIST W64 libsndfile sound audio dsp Linux">
<META NAME="ROBOTS" CONTENT="NOFOLLOW">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<!-- pepper -->
<CENTER>
<IMG SRC="libsndfile.jpg" HEIGHT=98 WIDTH=367 ALT="libsndfile.jpg">
</CENTER>
<!-- pepper -->
<CENTER>
<A HREF="#History">History</A> -+-
<A HREF="#Features">Features</A> -+-
<A HREF="#Similar">Similar or Related Projects</A> -+-
<A HREF="NEWS">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="ChangeLog">Change Log</A> -+-
<A HREF="#Licensing">Licensing Information</A> -+-
<A HREF="#SeeAlso">See Also</A>
</CENTER>
<br><br>
<P>
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
<A HREF="http://www.gnu.org/copyleft/lesser.html">Gnu Lesser General Public License</A>.
</P>
<!-- pepper -->
<P>
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.
</P>
<P>
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.
</P>
<!-- pepper -->
<P>
It has been compiled and tested (at one time or another) on the following systems:
</P>
<!-- pepper -->
<UL>
<LI>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.</LI>
<LI>powerpc-apple-darwin7.0 (Mac OS X 10.3)</LI>
<LI>sparc-sun-solaris2.8 (using gcc)</LI>
<LI>mips-sgi-irix5.3 (using gcc)</LI>
<LI>QNX 6.0</LI>
<LI>i386-unknown-openbsd2.9</LI>
</UL>
<!-- pepper -->
<P>
At the moment, each new release is being tested on i386 Linux, x86_64 Linux,
PowerPC Linux, Win32 and Win64.
</P>
<!-- pepper -->
<A NAME="Capabilities"></A>
<A NAME="Features"></A>
<H1><B>Features</B></H1>
<P>
libsndfile has the following main features :
</P>
<UL>
<lI> Ability to read and write a large number of file formats.
<LI> A simple, elegant and easy to use Applications Programming Interface.
<LI> Usable on Unix, Win32, MacOS and others.
<LI> On the fly format conversion, including endian-ness swapping, type conversion
and bitwidth scaling.
<LI> Optional normalisation when reading floating point data from files containing
integer data.
<LI> Ability to open files in read/write mode.
<LI> The ability to write the file header without closing the file (only on files
open for write or read/write).
<LI> Ability to query the library about all supported formats and retrieve text
strings describing each format.
</UL>
<P>
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.
</P>
<P>
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.
</P>
<br>
<TABLE BORDER="1" cellpadding="2">
<TR><TD>&nbsp;</TD>
<TD ALIGN="center">Micro- soft<br>WAV</TD>
<TD ALIGN="center">SGI / Apple<br>AIFF / AIFC</TD>
<TD ALIGN="center">Sun / DEC /<br>NeXT<br>AU / SND</TD>
<TD ALIGN="center">Header- less<br>RAW</TD>
<TD ALIGN="center">Paris Audio<br>File<br>PAF</TD>
<TD ALIGN="center">Commo- dore<br>Amiga<br>IFF / SVX</TD>
<TD ALIGN="center">Sphere<br>Nist<br>WAV</TD>
<TD ALIGN="center">IRCAM<br>SF</TD>
<TD ALIGN="center">Creative<br>VOC</TD>
<TD ALIGN="center">Sound forge<br>W64</TD>
<TD ALIGN="center"><A HREF="octave.html">GNU Octave 2.0</A><br>MAT4</TD>
<TD ALIGN="center"><A HREF="octave.html">GNU Octave 2.1</A><br>MAT5</TD>
<TD ALIGN="center">Portable Voice Format<br>PVF</TD>
<TD ALIGN="center">Fasttracker 2<br>XI</TD>
<TD ALIGN="center">HMM Tool Kit<br>HTK</TD>
<TD ALIGN="center">Apple<br>CAF</TD>
<TD ALIGN="center">Sound<br>Designer II<br>SD2</TD>
<TD ALIGN="center">Free Lossless Audio Codec<br>FLAC</TD>
</TR>
<TR><TD>Unsigned 8 bit PCM</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>Signed 8 bit PCM</TD>
<TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
</TR>
<TR><TD>Signed 16 bit PCM</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
</TR>
<TR><TD>Signed 24 bit PCM</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
</TR>
<TR><TD>Signed 32 bit PCM</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>32 bit float</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>64 bit double</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>u-law encoding</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>A-law encoding</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>IMA ADPCM</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>MS ADPCM</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>GSM 6.10</TD>
<TD ALIGN="center">R/W</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>G721 ADPCM 32kbps</TD>
<TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>G723 ADPCM 24kbps</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>G723 ADPCM 40kbps</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>12 bit DWVW</TD>
<TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>16 bit DWVW</TD>
<TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>24 bit DWVW</TD>
<TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>Ok Dialogic ADPCM</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>8 bit DPCM</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR><TD>16 bit DPCM</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
<TD>&nbsp;</TD><TD ALIGN="center">R/W</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
</TABLE>
<p>
From version 1.0.18, libsndfile also reads and writes
<a href="http://flac.sourceforge.net/">FLAC</a>
and
<a href="http://www.vorbis.com/">Ogg/Vorbis</a>.
</p>
<!-- pepper -->
<P>
Some of the file formats I am also interested in adding are:
</P>
<UL>
<LI> Kurzweil K2000 sampler files.
<LI> Ogg Speex.
</UL>
<P>
I have decided that I will not be adding support for MPEG Layer 3 (commonly
known as MP3) due to the patent issues surrounding this file format.
See
<a href="FAQ.html#Q020">
the FAQ</a>
for more.
</P>
<P>
Other file formats may also be added on request.
</P>
<!-- pepper -->
<A NAME="History"></A>
<H1><B>History</B></H1>
<P>
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
<A HREF="http://www.vaxxine.com/ve3wwg/gnuwave.html">wavplay</A>
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.
</P>
<P>
Here is the release history for libsndfile :
</P>
<UL>
<LI>Version 0.0.8 (Feb 15 1999) First official release.
<LI>Version 0.0.28 (Apr 26 2002) Final release of version 0 of libsndfile.
<LI>Version 1.0.0rc1 (Jun 24 2002) Release candidate 1 of version 1 of libsndfile.
<LI>Version 1.0.0rc6 (Aug 14 2002) MacOS 9 fixes.
<LI>Version 1.0.0 (Aug 16 2002) First 1.0.X release.
<LI>Version 1.0.1 (Sep 14 2002) Added MAT4 and MAT5 file formats.
<LI>Version 1.0.2 (Nov 24 2002) Added VOX ADPCM format.
<LI>Version 1.0.3 (Dec 09 2002) Fixes for Linux on ia64 CPUs.
<LI>Version 1.0.4 (Feb 02 2003) New file formats and functionality.
<LI>Version 1.0.5 (May 03 2003) One new file format and new functionality.
<LI>Version 1.0.6 (Feb 08 2004) Large file fix for Linux/Solaris, new functionality
and Win32 improvements.
<LI>Version 1.0.7 (Feb 24 2004) Fix build problems on MacOS X and fix ia64/MIPS etc
clip mode detction.
<LI>Version 1.0.8 (Mar 14 2004) Minor bug fixes.
<LI>Version 1.0.9 (Mar 30 2004) Add AVR format. Improve handling of some WAV files.
<LI>Version 1.0.10 (Jun 15 2004) Minor bug fixes. Fix support for Win32 MinGW compiler.
<LI>Version 1.0.11 (Nov 15 2004) Add SD2 file support, reading of loop data in WAV and AIFF.
Minor bug fixes.
<LI>Version 1.0.12 (Sep 30 2005) Add FLAC and CAF file support, virtual I/O interface.
Minor bug fixes and cleanups.
<LI>Version 1.0.13 (Jan 21 2006) Add read/write of instrument chunks. Minor bug fixes.
<LI>Version 1.0.14 (Feb 19 2006) Minor bug fixes. Start shipping windows binary/source ZIP.
<LI>Version 1.0.15 (Mar 16 2006) Minor bug fixes.
<LI>Version 1.0.16 (Apr 30 2006) Add support for RIFX. Other minor feature enhancements and
bug fixes.
<LI>Version 1.0.17 (Aug 31 2006) Add C++ wrapper sndfile.hh. Minor bug fixes and cleanups.
<LI>Version 1.0.18 (Feb 07 2009) Add Ogg/Vorbis suppport, remove captive libraries, many
new features and bug fixes. Generate Win32 and Win64 pre-compiled binaries.
<LI>Version 1.0.19 (Mar 02 2009) Fix for CVE-2009-0186. Huge number of minor fixes as a
result of static analysis.
<LI>Version 1.0.20 (May 14 2009) Fix for potential heap overflow.
<LI>Version 1.0.21 (December 13 2009) Bunch of minor bug fixes.
<LI>Version 1.0.22 (October 04 2010) Bunch of minor bug fixes.
<LI>Version 1.0.23 (October 10 2010) Minor bug fixes.
<LI>Version 1.0.24 (March 23 2011) Minor bug fixes.
<LI>Version 1.0.25 (July 13 2011) Fix for Secunia Advisory SA45125. Minor bug fixes and
improvements.
</UL>
<A NAME="Similar"></A>
<H1><B>Similar or Related Projects</B></H1>
<UL>
<LI><A HREF="http://sox.sourceforge.net/">SoX</A> is a program for
converting between sound file formats.
<LI><A HREF="http://www.hitsquad.com/smm/programs/WavPlay/">Wavplay</A> 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.
<LI><A HREF="http://www.68k.org/~michael/audiofile/">Audiofile</A> (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.
<LI><A HREF="ftp://ccrma-ftp.stanford.edu/pub/Lisp/sndlib.tar.gz">sndlib.tar.gz</A> is
another library written by Bill Schottstaedt of CCRMA.
</UL>
<A NAME="Licensing"></A>
<H1><B>Licensing</B></H1>
<P>
libsndfile is released under the terms of the GNU Lesser General Public License,
of which there are two versions;
<a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">version 2.1</a>
and
<a href="http://www.gnu.org/copyleft/lesser.html">version 3</a>.
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
<A HREF="http://www.gnu.org/copyleft/copyleft.html">here</A>.
</P>
<P>
You can use libsndfile with
<A HREF="http://www.gnu.org/">Free Software</A>,
<A HREF="http://www.opensource.org/">Open Source</A>,
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.
</P>
<P>
I would like to see libsndfile used as widely as possible but I would prefer it
if you released software that uses libsndfile as
<A HREF="http://www.gnu.org/">Free Software</A>
or
<A HREF="http://www.opensource.org/">Open Source</A>.
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 <A HREF="http://www.gnu.org/copyleft/lesser.html">the license</A>.
</P>
<A NAME="Download"></A>
<H1><B>Download</B></H1>
<P>
Here is the latest version. It is available in the following formats:
</P>
<UL>
<LI>Source code as a .tar.gz :
<A HREF="files/libsndfile-1.0.25.tar.gz">libsndfile-1.0.25.tar.gz</A>
and
<A HREF="files/libsndfile-1.0.25.tar.gz.asc">(GPG signature)</A>.
<LI>Win32 installer:
<A HREF="files/libsndfile-1.0.25-w32-setup.exe">
libsndfile-1.0.25-w32-setup.exe</A> (thoroughly tested under
<a href="http://www.winehq.com/">Wine</a> and Windows XP).
<LI>Win64 installer:
<A HREF="files/libsndfile-1.0.25-w64-setup.exe">
libsndfile-1.0.25-w64-setup.exe</A>
(thoroughly tested on 64 bit Windows 7).
</UL>
<P>
The Win32 installer was compiled for Windows XP but should also work on Windows
2000, Vista and Windows 7.
</p>
<P>
Pre-release versions of libsndfile are available
<A HREF="http://www.mega-nerd.com/tmp/">here</A>
and are announced on the
<A HREF="lists.html">libsndfile-devel</A>
mailing list.
</P>
<A NAME="SeeAlso"></A>
<H1><B>See Also</B></H1>
<UL>
<LI><a href="http://www.mega-nerd.com/libsndfile/tools/">
sndfile-tools</a>
: a small collection of programs which use libsndfile.
</UL>
<br><br>
<hr>
<P>
The latest version of this document can be found
<A HREF="http://www.mega-nerd.com/libsndfile/">here</A>.
</P>
<P>
Author :
<A HREF="m&#97;ilt&#111;:&#101;rikd&#64;&#109;eg&#97;-&#110;erd.&#99;om">
Erik de Castro Lopo</a>
</P>
<!-- pepper -->
<P>
This page has been accessed
<IMG SRC=
"/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|trgb=0;0;0|wxh=15;20|md=7|dd=B|st=1|sh=1|df=libsndfile.dat"
HEIGHT=30 WIDTH=100 ALT="counter.gif">
times.
</P>
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
<br><br>
</BODY>
</HTML>
-92
View File
@@ -1,92 +0,0 @@
body {
background : @HTML_BGCOLOUR@ ;
color : @HTML_FGCOLOUR@ ;
font-family : arial, helvetica, sans-serif ;
line-height: 1.5 ;
}
td {
font-family : arial, helvetica, sans-serif ;
background : @HTML_BGCOLOUR@ ;
color : @HTML_FGCOLOUR@ ;
}
center {
font-family : arial, helvetica, sans-serif ;
}
p {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
margin-left : 3% ;
margin-right : 3% ;
}
.indent_block {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
margin-left : 10% ;
margin-right : 10% ;
}
br {
font-family : arial, helvetica, sans-serif ;
}
form {
font-family : arial, helvetica, sans-serif ;
}
ul {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
margin-left : 3% ;
margin-right : 6% ;
}
ol {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
margin-left : 3% ;
margin-right : 6% ;
}
dl {
font-family : arial, helvetica, sans-serif ;
text-align : left ;
margin-left : 3% ;
margin-right : 3% ;
}
h1 {
font-size : xx-large ;
background : @HTML_BGCOLOUR@ ;
color : #5050FF ;
text-align : left ;
margin-left : 3% ;
margin-right : 3% ;
}
h2 {
font-size : x-large ;
background : @HTML_BGCOLOUR@ ;
color : #5050FF ;
text-align : left ;
margin-left : 3% ;
margin-right : 3% ;
}
h3 {
font-size : large ;
background : @HTML_BGCOLOUR@ ;
color : #5050FF ;
text-align : left ;
margin-left : 3% ;
margin-right : 3% ;
}
h4 {
font-size : medium ;
background : @HTML_BGCOLOUR@ ;
color : #5050FF ;
text-align : left ;
margin-left : 3% ;
margin-right : 3% ;
}
pre {
font-family : courier, monospace ;
font-size : medium ;
margin-left : 6% ;
margin-right : 6% ;
}
a:link { color : #9090FF ; }
a:visited { color : #5050FF ; }
a:active { color : #FF00FF ; }
a:hover { background-color : #202080 ; }
@@ -1,434 +0,0 @@
# 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. Thats 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...
-52
View File
@@ -1,52 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile Mailing Lists
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<!-- pepper -->
<H1><BR>libsndfile Mailing Lists</H1>
<!-- pepper -->
<P>
There are three mailing lists for libsndfile:
</P>
<!-- pepper -->
<UL>
<LI> <B>libsndfile-announce&#64;mega-nerd.com</B>&nbsp;&nbsp;<!-- pepper -->
<A HREF="m&#97;ilt&#111;:li&#98;sndfile-announce-request@meg&#97;-nerd.&#99;om?subject=subscribe">Subscribe</A>
<BR>
A list which will announce each new release of libsndfile.
Noone can post to this list except the author.
<BR><BR>
<LI> <B>libsndfile-devel&#64;mega-nerd.com</B>&nbsp;&nbsp;<!-- pepper -->
<A HREF="m&#97;ilt&#111;:li&#98;sndfile-devel-request@meg&#97;-nerd.&#99;om?subject=subscribe">Subscribe</A>
<BR>
A list for discussing bugs, porting issues and feature requests.
Posting is restricted to subscribers.
<BR><BR>
<LI> <B>libsndfile-users&#64;mega-nerd.com</B>&nbsp;&nbsp;<!-- pepper -->
<A HREF="m&#97;ilt&#111;:li&#98;sndfile-users-request@meg&#97;-nerd.&#99;om?subject=subscribe">Subscribe</A>
<BR>
A list for discussing the use of libsndfile in other programs.
Posting is restricted to subscribers.
<!-- pepper -->
<BR><BR>
</UL>
<!-- pepper -->
<P>
The libsndfile-devel and libsndfile-users list will automatically receive a
copy of all emails to the libsndfile-announce list.
</P>
<BR>
<!-- pepper -->
</BODY>
</HTML>
-135
View File
@@ -1,135 +0,0 @@
new_file_type.HOWTO
===================
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.in 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 ;
Setp 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 ***
-118
View File
@@ -1,118 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile and GNU Octave
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<BR>
<H1><B>libsndfile and GNU Octave</B></H1>
<P>
<A HREF="http://www.octave.org/">GNU Octave</A> 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
<A HREF="http://www.mathworks.com/">MATLAB</A>.
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.
</P>
<P>
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.
</P>
<P>
For instance it is now possible to do the following:
</P>
<UL>
<LI> Load a WAV file into a sound file editor such as
<A HREF="http://www.metadecks.org/software/sweep/">Sweep</A>.
<LI> Save it as a MAT4 file.
<LI> Load the data into Octave for manipulation.
<LI> Save the modified data.
<LI> Reload it in Sweep.
</UL>
<P>
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.
</P>
<H2><B>Details</B></H2>
<P>
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.
</P>
<P>
For example, to generate a sine wave and store it as a binary file which
is compatible with libsndfile, do the following:
</P>
<PRE>
octave:1 > samplerate = 44100 ;
octave:2 > wavedata = sin ((0:1023)*2*pi/1024) ;
octave:3 > save sine.mat samplerate wavedata
</PRE>
<P>
The process of reading and writing files compatible with libsndfile can be
made easier by use of two Octave script files :
</P>
<PRE>
octave:4 > [data fs] = sndfile_load ("sine.mat") ;
octave:5 > sndfile_save ("sine2.mat", data, fs) ;
</PRE>
<P>
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 <B>sndfile-play</B> and a third Octave script
file allows Octave data to be played from within Octave on any of the platforms
which <B>sndfile-play</B> supports (at the moment: Linux, MacOS X, Solaris and
Win32).
</P>
<PRE>
octave:6 > sndfile_play (data, fs) ;
</PRE>
<P>
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/.
</P>
<P>
There are some other Octave scripts for audio to be found
<A HREF="http://octave.sourceforge.net/audio/index.html">here</A>.
</P>
<BR>
<!-- ========================================================================= -->
<HR>
<P>
The libsndfile home page is here :
<A HREF="http://www.mega-nerd.com/libsndfile/">
http://www.mega-nerd.com/libsndfile/</A>.
</P>
</BODY>
</HTML>
-71
View File
@@ -1,71 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile : pkg-config
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<BR>
<H1>libsndfile and pkg-config</H1>
<P>
From version 1.0.0 libsndfile has had the ability to read and write files of
greater than 2 Gig in size on most OSes even if sizeof (long) == 4.
OSes which support this feature include Linux (2.4 kernel, glibc6) on x86, PPC and
probably others, Win32, MacOS X, *BSD, Solaris and probably others.
OSes on 64 bit processors where the default compile environment is LP64 (longs and
pointers are 64 bit ie Linux on DEC/Compaq/HP Alpha processors) automatically
support large file access.
</P>
<P>
Other OSes including Linux on 32 bit processors, 32 bit Solaris and others require
special compiler flags to add large file support.
This applies to both the compilation of the library itself and the compilation of
programs which link to the library.
</P>
<P>
Note : People using Win32, MacOS (both OS X and pre-OS X) or *BSD can disregard the
rest of this document as it does not apply to either of these OSes.
</P>
<P>
The <B>pkg-config</B> program makes finding the correct compiler flag values and
library location far easier.
During the installation of libsndfile, a file named <B>sndfile.pc</B> is installed
in the directory <B>${libdir}/pkgconfig</B> (ie if libsndfile is installed in
<B>/usr/local/lib</B>, <B>sndfile.pc</B> will be installed in
<B>/usr/local/lib/pkgconfig/</B>).
</P>
<P>
In order for pkg-config to find sndfile.pc it may be necessary to point the
environment variable <B>PKG_CONFIG_PATH</B> in the right direction.
</P>
<PRE>
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
</PRE>
<P>
Then, to compile a C file into an object file, the command would be:
</P>
<PRE>
gcc `pkg-config --cflags sndfile` -c somefile.c
</PRE>
<P>
and to link a number of objects into an executable that links against libsndfile,
the command would be:
</P>
<PRE>
gcc `pkg-config --libs sndfile` obj1.o obj2.o -o program
</PRE>
<P>
Obviously all this can be rolled into a Makefile for easier maintenance.
</P>
</BODY>
</HTML>
-14
View File
@@ -1,14 +0,0 @@
body {
background:white;
color:black;
}
h1{
background:white;
color:black;
}
h2 {
background:white;
color:#666;
}
-53
View File
@@ -1,53 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
sndfile-info
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<P>
Here is an example of the output from the <B>sndfile-info</B> program distributed with
libsndfile.
</P>
<P>
This file was opened and parsed correctly but had been truncated so that the values
in the <B>FORM</B> and <B>SSND</B> chunks were incorrect.
</P>
<PRE>
<B>erikd@hendrix ></B> 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
</PRE>
</BODY>
</HTML>
-34
View File
@@ -1,34 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
libsndfile Tutorial
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<!-- pepper -->
<H1><BR>libsndfile Tutorial</H1>
<!-- pepper -->
<P>
<b>More coming soon.</b>
</P>
<!-- pepper -->
<P>
For now, the best place to look for example code is the <tt>examples/</tt>
directory of the source code distribution and the libsndfile test suite which
is located in the <tt>tests/</tt> directory of the source code distribution.
</P>
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
</BODY>
</HTML>
-53
View File
@@ -1,53 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>
Building libsndfile on Win32
</TITLE>
<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
<LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
<LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
</HEAD>
<BODY>
<!-- pepper -->
<H1><BR>Building libsndfile on Win32</H1>
<P><B>
Note : For pre-compiled binaries for windows, both for win32 and win64, see the
main web page.
</B></P>
<P>
There is currently only one way of building libsndfile for Win32 and Win64;
cross compiling from Linux using the MinGW cross compiler.
</P>
<P>
libsndfile is written to be compiled by a compiler which supports large
chunks of the 1999 ISO C Standard.
Unfortunately, the microsoft compiler supports close to nothing of this
standard and hence is not suitable for libsndfile.
</P>
<P>
It <b>may</b> be possible to compile libsndfile on windows using the
<a href="http://www.mingw.org/">MinGW</a>
compiler suite, but I haven't tested that and have no interest in supporting
that.
</P>
<!--===========================================================================-->
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
<BR>
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
<!-- pepper -->
</BODY>
</HTML>