Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.25/doc/FAQ.html @ 169:223a55898ab9 tip default

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add null config files
author Chris Cannam <cannam@all-day-breakfast.com>
date Mon, 02 Mar 2020 14:03:47 +0000
parents 545efbb81310
children
rev   line source
cannam@85 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
cannam@85 2 <HTML>
cannam@85 3
cannam@85 4 <HEAD>
cannam@85 5 <TITLE>
cannam@85 6 libsndfile : Frequently Asked Questions.
cannam@85 7 </TITLE>
cannam@85 8 <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
cannam@85 9 <META NAME="Description" CONTENT="The libsndfile FAQ.">
cannam@85 10 <META NAME="Keywords" CONTENT="WAV AIFF AU libsndfile sound audio dsp Linux">
cannam@85 11 <LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
cannam@85 12 <LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
cannam@85 13 </HEAD>
cannam@85 14
cannam@85 15 <BODY>
cannam@85 16
cannam@85 17 <H1><B>libsndfile : Frequently Asked Questions.</B></H1>
cannam@85 18 <P>
cannam@85 19 <A HREF="#Q001">Q1 : Do you plan to support XYZ codec in libsndfile?</A><BR/>
cannam@85 20 <A HREF="#Q002">Q2 : In version 0 the SF_INFO struct had a pcmbitwidth field
cannam@85 21 but version 1 does not. Why?</A><BR/>
cannam@85 22 <A HREF="#Q003">Q3 : Compiling is really slow on MacOS X. Why?</A><BR/>
cannam@85 23 <A HREF="#Q004">Q4 : When trying to compile libsndfile on Solaris I get a "bad
cannam@85 24 substitution" error during linking. What can I do to fix this?</A><BR/>
cannam@85 25 <A HREF="#Q005">Q5 : Why doesn't libsndfile do interleaving/de-interleaving?</A><BR/>
cannam@85 26 <A HREF="#Q006">Q6 : What's the best format for storing temporary files?</A><BR/>
cannam@85 27 <A HREF="#Q007">Q7 : On Linux/Unix/MacOS X, what's the best way of detecting the
cannam@85 28 presence of libsndfile?</A><BR/>
cannam@85 29 <A HREF="#Q008">Q8 : But I just want a simple Makefile! What do I do?</A><BR/>
cannam@85 30 <A HREF="#Q009">Q9 : How about adding the ability to write/read sound files to/from
cannam@85 31 memory buffers?</A><BR/>
cannam@85 32 <A HREF="#Q010">Q10 : Reading a 16 bit PCM file as normalised floats and then
cannam@85 33 writing them back changes some sample values. Why?</A><BR/>
cannam@85 34 <A HREF="#Q011">Q11 : I'm having problems with u-law encoded WAV files generated by
cannam@85 35 libsndfile in Winamp. Why?</A><BR/>
cannam@85 36 <A HREF="#Q012">Q12 : I'm looking at sf_read*. What are items? What are frames?</A><BR/>
cannam@85 37 <A HREF="#Q013">Q13 : Why can't libsndfile open this Sound Designer II (SD2)
cannam@85 38 file?</A><BR/>
cannam@85 39 <A HREF="#Q014">Q14 : I'd like to statically link libsndfile to my closed source
cannam@85 40 application. Can I buy a license so that this is possible?</A><BR/>
cannam@85 41 <A HREF="#Q015">Q15 : My program is crashing during a call to a function in libsndfile.
cannam@85 42 Is this a bug in libsndfile?</A><BR/>
cannam@85 43 <A HREF="#Q016">Q16 : Will you accept a fix for compiling libsndfile with compiler X?
cannam@85 44 </A><BR/>
cannam@85 45 <A HREF="#Q017">Q17 : Can libsndfile read/write files from/to UNIX pipes?
cannam@85 46 </A><BR/>
cannam@85 47 <A HREF="#Q018">Q18 : Is it possible to build a Universal Binary on Mac OS X?
cannam@85 48 </A><BR/>
cannam@85 49 <A HREF="#Q019">Q19 : I have project files for Visual Studio / XCode / Whatever. Why
cannam@85 50 don't you distribute them with libsndfile?
cannam@85 51 </A><BR/>
cannam@85 52 <A HREF="#Q020">Q20 : Why doesn't libsndfile support MP3? Lots of other Open Source
cannam@85 53 projects support it!
cannam@85 54 </A><BR/>
cannam@85 55 <A HREF="#Q021">Q21 : How do I use libsndfile in a closed source or commercial program
cannam@85 56 and comply with the license?
cannam@85 57 </A><BR/>
cannam@85 58 <A HREF="#Q022">Q22 : What versions of windows does libsndfile work on?
cannam@85 59 </A><BR/>
cannam@85 60 <A HREF="#Q023">Q23 : I'm cross compiling libsndfile for another platform. How can I
cannam@85 61 run the test suite?
cannam@85 62 </A><BR/>
cannam@85 63 <HR>
cannam@85 64
cannam@85 65 <!-- ========================================================================= -->
cannam@85 66 <A NAME="Q001"></A>
cannam@85 67 <H2><BR/><B>Q1 : Do you plan to support XYZ codec in libsndfile?</B></H2>
cannam@85 68 <P>
cannam@85 69 If source code for XYZ codec is available under a suitable license (LGPL, BSD,
cannam@85 70 MIT etc) then yes, I'd like to add it.
cannam@85 71 </P>
cannam@85 72 <P>
cannam@85 73 If suitable documentation is available on how to decode and encode the format
cannam@85 74 then maybe, depending on how much work is involved.
cannam@85 75 </P>
cannam@85 76 <P>
cannam@85 77 If XYZ is some proprietary codec where no source code or documentation is
cannam@85 78 available then no.
cannam@85 79 </P>
cannam@85 80 <P>
cannam@85 81 So if you want support for XYZ codec, first find existing source code or
cannam@85 82 documentation.
cannam@85 83 If you can't find either then the answer is no.
cannam@85 84 </P>
cannam@85 85 <!-- ========================================================================= -->
cannam@85 86 <A NAME="Q002"></A>
cannam@85 87 <H2><BR/><B>Q2 : In version 0 the SF_INFO struct had a pcmbitwidth field
cannam@85 88 but version 1 does not. Why?</B></H2>
cannam@85 89 <P>
cannam@85 90 This was dropped for a number of reasons:
cannam@85 91 </P>
cannam@85 92 <UL>
cannam@85 93 <LI> pcmbitwidth makes little sense on compressed or floating point formats
cannam@85 94 <LI> with the new API you really don't need to know it
cannam@85 95 </UL>
cannam@85 96 <P>
cannam@85 97 As documented
cannam@85 98 <A HREF="http://www.mega-nerd.com/libsndfile/api.html#note1">here</A>
cannam@85 99 there is now a well defined behaviour which ensures that no matter what the
cannam@85 100 bit width of the source file, the scaling always does something sensible.
cannam@85 101 This makes it safe to read 8, 16, 24 and 32 bit PCM files using sf_read_short()
cannam@85 102 and always have the optimal behaviour.
cannam@85 103 </P>
cannam@85 104
cannam@85 105 <!-- ========================================================================= -->
cannam@85 106 <A NAME="Q003"></A>
cannam@85 107 <H2><BR/><B>Q3 : Compiling is really slow on MacOS X. Why?</B></H2>
cannam@85 108 <P>
cannam@85 109 When you configure and compile libsndfile, it uses the /bin/sh shell for a number
cannam@85 110 of tasks (ie configure script and libtool).
cannam@85 111 Older versions of OS X (10.2?) shipped a really crappy Bourne shell as /bin/sh
cannam@85 112 which resulted in <b>really</b> slow compiles.
cannam@85 113 Newer version of OS X ship GNU Bash as /bin/sh and this answer doesn't apply in that
cannam@85 114 case.
cannam@85 115 </P>
cannam@85 116 <P>
cannam@85 117 To fix this I suggest that you install the GNU Bash shell, rename /bin/sh to
cannam@85 118 /bin/sh.old and make a symlink from /bin/sh to the bash shell.
cannam@85 119 Bash is designed to behave as a Bourne shell when is is called as /bin/sh.
cannam@85 120 </P>
cannam@85 121 <P>
cannam@85 122 When I did this on my iBook running MacOS X, compile times dropped from 13 minutes
cannam@85 123 to 3 minutes.
cannam@85 124 </P>
cannam@85 125
cannam@85 126 <!-- ========================================================================= -->
cannam@85 127 <A NAME="Q004"></A>
cannam@85 128 <H2><BR/><B>Q4 : When trying to compile libsndfile on Solaris I get a "bad
cannam@85 129 substitution" error on linking. Why?</B></H2>
cannam@85 130 <P>
cannam@85 131 It seems that the Solaris Bourne shell disagrees with GNU libtool.
cannam@85 132 </P>
cannam@85 133 <P>
cannam@85 134 To fix this I suggest that you install the GNU Bash shell, rename /bin/sh to
cannam@85 135 /bin/sh.old and make a symlink from /bin/sh to the bash shell.
cannam@85 136 Bash is designed to behave as a Bourne shell when is is called as /bin/sh.
cannam@85 137 </P>
cannam@85 138
cannam@85 139 <!-- ========================================================================= -->
cannam@85 140 <A NAME="Q005"></A>
cannam@85 141 <H2><BR/><B>Q5 : Why doesn't libsndfile do interleaving/de-interleaving?</B></H2>
cannam@85 142 <P>
cannam@85 143 This problem is bigger than it may seem at first.
cannam@85 144 </P>
cannam@85 145 <P>
cannam@85 146 For a stereo file, it is a pretty safe bet that a simple interleaving/de-interleaving
cannam@85 147 could satisfy most users.
cannam@85 148 However, for files with more than 2 channels this is unlikely to be the case.
cannam@85 149 If the user has a 4 channel file and want to play that file on a stereo output
cannam@85 150 sound card they either want the first 2 channels or they want some mixed combination
cannam@85 151 of the 4 channels.
cannam@85 152 </P>
cannam@85 153 <P>
cannam@85 154 When you add more channels, the combinations grow exponentially and it becomes
cannam@85 155 increasingly difficult to cover even a sensible subset of the possible combinations.
cannam@85 156 On top of that, coding any one style of interleaver/de-interleaver is trivial, while
cannam@85 157 coding one that can cover all combinations is far from trivial.
cannam@85 158 This means that this feature will not be added any time soon.
cannam@85 159 </P>
cannam@85 160
cannam@85 161 <!-- ========================================================================= -->
cannam@85 162 <A NAME="Q006"></A>
cannam@85 163 <H2><BR/><B>Q6 : What's the best format for storing temporary files?</B></H2>
cannam@85 164
cannam@85 165 <P>
cannam@85 166 When you want to store temporary data there are a number of requirements;
cannam@85 167 </P>
cannam@85 168 <UL>
cannam@85 169 <LI> A simple, easy to parse header.
cannam@85 170 <LI> The format must provide the fastest possible read and write rates (ie
cannam@85 171 avoid conversions and encoding/decoding).
cannam@85 172 <LI> The file format must be reasonably common and playable by most players.
cannam@85 173 <LI> Able to store data in either endian-ness.
cannam@85 174 </UL>
cannam@85 175 <P>
cannam@85 176 The format which best meets these requirements is AU, which allows data to be
cannam@85 177 stored in any one of short, int, float and double (among others) formats.
cannam@85 178 </P>
cannam@85 179 <P>
cannam@85 180 For instance, if an application uses float data internally, its temporary files
cannam@85 181 should use a format of (SF_ENDIAN_CPU | SF_FORMAT_AU | SF_FORMAT_FLOAT) which
cannam@85 182 will store big endian float data in big endian CPUs and little endian float data
cannam@85 183 on little endian CPUs.
cannam@85 184 Reading and writing this format will not require any conversions or byte swapping
cannam@85 185 regardless of the host CPU.
cannam@85 186 </P>
cannam@85 187
cannam@85 188 <!-- ========================================================================= -->
cannam@85 189
cannam@85 190 <A NAME="Q007"></A>
cannam@85 191 <H2><BR/><B>Q7 : On Linux/Unix/MaxOS X, what's the best way of detecting the presence
cannam@85 192 of libsndfile using autoconf?</B></H2>
cannam@85 193
cannam@85 194 <P>
cannam@85 195 libsndfile uses the pkg-config (man pkg-config) method of registering itself with the
cannam@85 196 host system.
cannam@85 197 The best way of detecting its presence is using something like this in configure.ac
cannam@85 198 (or configure.in):
cannam@85 199 </P>
cannam@85 200 <PRE>
cannam@85 201 PKG_CHECK_MODULES(SNDFILE, sndfile >= 1.0.2, ac_cv_sndfile=1, ac_cv_sndfile=0)
cannam@85 202
cannam@85 203 AC_DEFINE_UNQUOTED([HAVE_SNDFILE],${ac_cv_sndfile},
cannam@85 204 [Set to 1 if you have libsndfile.])
cannam@85 205
cannam@85 206 AC_SUBST(SNDFILE_CFLAGS)
cannam@85 207 AC_SUBST(SNDFILE_LIBS)
cannam@85 208 </PRE>
cannam@85 209 <P>
cannam@85 210 This will automatically set the <B>SNDFILE_CFLAGS</B> and <B>SNDFILE_LIBS</B>
cannam@85 211 variables which can be used in Makefile.am like this:
cannam@85 212 </P>
cannam@85 213 <PRE>
cannam@85 214 SNDFILE_CFLAGS = @SNDFILE_CFLAGS@
cannam@85 215 SNDFILE_LIBS = @SNDFILE_LIBS@
cannam@85 216 </PRE>
cannam@85 217 <P>
cannam@85 218 If you install libsndfile from source, you will probably need to set the
cannam@85 219 <B>PKG_CONFIG_PATH</B> environment variable as suggested at the end of the
cannam@85 220 libsndfile configure process. For instance on my system I get this:
cannam@85 221 </P>
cannam@85 222 <PRE>
cannam@85 223 -=-=-=-=-=-=-=-=-=-= Configuration Complete =-=-=-=-=-=-=-=-=-=-
cannam@85 224
cannam@85 225 Configuration summary :
cannam@85 226
cannam@85 227 Version : ..................... 1.0.5
cannam@85 228 Experimental code : ........... no
cannam@85 229
cannam@85 230 Tools :
cannam@85 231
cannam@85 232 Compiler is GCC : ............. yes
cannam@85 233 GCC major version : ........... 3
cannam@85 234
cannam@85 235 Installation directories :
cannam@85 236
cannam@85 237 Library directory : ........... /usr/local/lib
cannam@85 238 Program directory : ........... /usr/local/bin
cannam@85 239 Pkgconfig directory : ......... /usr/local/lib/pkgconfig
cannam@85 240
cannam@85 241 Compiling some other packages against libsndfile may require
cannam@85 242 the addition of "/usr/local/lib/pkgconfig" to the
cannam@85 243 PKG_CONFIG_PATH environment variable.
cannam@85 244 </PRE>
cannam@85 245
cannam@85 246 <!-- ========================================================================= -->
cannam@85 247
cannam@85 248 <A NAME="Q008"></A>
cannam@85 249 <H2><BR/><B>Q8 : But I just want a simple Makefile! What do I do?</B></H2>
cannam@85 250
cannam@85 251 <P>
cannam@85 252 The <B>pkg-config</B> program makes finding the correct compiler flag values and
cannam@85 253 library location far easier.
cannam@85 254 During the installation of libsndfile, a file named <B>sndfile.pc</B> is installed
cannam@85 255 in the directory <B>${libdir}/pkgconfig</B> (ie if libsndfile is installed in
cannam@85 256 <B>/usr/local/lib</B>, <B>sndfile.pc</B> will be installed in
cannam@85 257 <B>/usr/local/lib/pkgconfig/</B>).
cannam@85 258 </P>
cannam@85 259 <P>
cannam@85 260 In order for pkg-config to find sndfile.pc it may be necessary to point the
cannam@85 261 environment variable <B>PKG_CONFIG_PATH</B> in the right direction.
cannam@85 262 </P>
cannam@85 263 <PRE>
cannam@85 264 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
cannam@85 265 </PRE>
cannam@85 266
cannam@85 267 <P>
cannam@85 268 Then, to compile a C file into an object file, the command would be:
cannam@85 269 </P>
cannam@85 270 <PRE>
cannam@85 271 gcc `pkg-config --cflags sndfile` -c somefile.c
cannam@85 272 </PRE>
cannam@85 273 <P>
cannam@85 274 and to link a number of objects into an executable that links against libsndfile,
cannam@85 275 the command would be:
cannam@85 276 </P>
cannam@85 277 <PRE>
cannam@85 278 gcc `pkg-config --libs sndfile` obj1.o obj2.o -o program
cannam@85 279 </PRE>
cannam@85 280
cannam@85 281 <!-- ========================================================================= -->
cannam@85 282
cannam@85 283 <A NAME="Q009"></A>
cannam@85 284 <H2><BR/><B>Q9 : How about adding the ability to write/read sound files to/from
cannam@85 285 memory buffers?</B></H2>
cannam@85 286
cannam@85 287 <P>
cannam@85 288 This has been added for version 1.0.13.
cannam@85 289 </P>
cannam@85 290
cannam@85 291 <!-- ========================================================================= -->
cannam@85 292
cannam@85 293 <A NAME="Q010"></A>
cannam@85 294 <H2><BR/><B>Q10 : Reading a 16 bit PCM file as normalised floats and then
cannam@85 295 writing them back changes some sample values. Why?</B></H2>
cannam@85 296
cannam@85 297 <P>
cannam@85 298 This is caused by the fact that the conversion from 16 bit short to float is
cannam@85 299 done by dividing by 32768 (0x8000 in hexadecimal) while the conversion from
cannam@85 300 float to 16 bit short is done by multiplying by 32767 (0x7FFF in hex).
cannam@85 301 So for instance, a value in a 16 bit PCM file of 20000 gets read as a floating
cannam@85 302 point number of 0.6103515625 (20000.0 / 0x8000).
cannam@85 303 Converting that back to a 16 bit short results in a value of 19999.3896484375
cannam@85 304 (0.6103515625 * 0x7FFF) which then gets rounded down to 19999.
cannam@85 305 </P>
cannam@85 306 <P>
cannam@85 307 You will notice that for this particular case, the error is 1 in 20000 or
cannam@85 308 0.005%.
cannam@85 309 Interestingly, for values of less than 16369, dividing by 0x8000 followed
cannam@85 310 by multiplying by 0x7FFF and then rounding the result, gives back the
cannam@85 311 original value.
cannam@85 312 It turns out that as long as the host operating system supplies the 1999 ISO
cannam@85 313 C Standard functions <B>lrintf</B> and <B>lrint</B> (or a replacement has
cannam@85 314 been supplied) then the maximum possible error is 1 in 16369 or about 0.006%.
cannam@85 315 </P>
cannam@85 316 <P>
cannam@85 317 Regardless of the size of the error, the reason why this is done is rather
cannam@85 318 subtle.
cannam@85 319 </P>
cannam@85 320 <P>
cannam@85 321 In a file containing 16 bit PCM samples, the values are restricted to the range
cannam@85 322 [-32768, 32767] while we want floating point values in the range [-1.0, 1.0].
cannam@85 323 The only way to do this conversion is to do a floating point division by a value
cannam@85 324 of 0x8000.
cannam@85 325 Converting the other way, the only way to ensure that floating point values in
cannam@85 326 the range [-1.0, 1.0] are within the valid range allowed by a 16 bit short is
cannam@85 327 to multiply by 0x7FFF.
cannam@85 328 </P>
cannam@85 329 <P>
cannam@85 330 Some people would say that this is a severe short-coming of libsndfile.
cannam@85 331 I would counter that anybody who is constantly converting back and forth
cannam@85 332 between 16 bit shorts and normalised floats is going to suffer other losses
cannam@85 333 in audio quality that they should also be concerned about.
cannam@85 334 </P>
cannam@85 335 <P>
cannam@85 336 Since this problem only occurs when converting between integer data on disk and
cannam@85 337 normalized floats in the application, it can be avoided by using something
cannam@85 338 other than normalized floats in the application.
cannam@85 339 Alternatives to normalized floats are the <b>short</b> and <b>int</b> data
cannam@85 340 types (ie using sf_read_short or sf_read_int) or using un-normalized floats
cannam@85 341 (see
cannam@85 342 <a href="http://www.mega-nerd.com/libsndfile/command.html#SFC_SET_NORM_FLOAT">
cannam@85 343 SFC_SET_NORM_FLOAT</a>).
cannam@85 344 </P>
cannam@85 345 <P>
cannam@85 346 Another way to deal with this problem is to consider 16 bit short data as a
cannam@85 347 final destination format only, not as an intermediate storage format.
cannam@85 348 All intermediate data (ie which is going to be processed further) should be
cannam@85 349 stored in floating point format which is supported by all of the most common
cannam@85 350 file formats.
cannam@85 351 If floating point files are considered too large (2 times the size of a 16 bit
cannam@85 352 PCM file), it would also be possible to use 24 bit PCM as an intermediate
cannam@85 353 storage format (and which is also supported by most common file types).
cannam@85 354 </P>
cannam@85 355
cannam@85 356 <!-- ========================================================================= -->
cannam@85 357
cannam@85 358 <A NAME="Q011"></A>
cannam@85 359 <H2><BR/><B>Q11 : I'm having problems with u-law encoded WAV files generated by
cannam@85 360 libsndfile in Winamp. Why?
cannam@85 361 </B></H2>
cannam@85 362
cannam@85 363 <P>
cannam@85 364 This is actually a Winamp problem.
cannam@85 365 The official Microsoft spec suggests that the 'fmt ' chunk should be 18 bytes.
cannam@85 366 Unfortunately at least one of Microsoft's own applications (Sound Recorder on
cannam@85 367 Win98 I believe) did not accept 18 bytes 'fmt ' chunks.
cannam@85 368 </P>
cannam@85 369 <P>
cannam@85 370 Michael Lee did some experimenting and found that:
cannam@85 371 </P>
cannam@85 372 <PRE>
cannam@85 373 I have checked that Windows Media Player 9, QuickTime Player 6.4,
cannam@85 374 RealOne Player 2.0 and GoldWave 5.06 can all play u-law files with
cannam@85 375 16-byte or 18-byte 'fmt ' chunk. Only Winamp (2.91) and foobar2000
cannam@85 376 are unable to play u-law files with 16-byte 'fmt ' chunk.
cannam@85 377 </PRE>
cannam@85 378
cannam@85 379 <P>
cannam@85 380 Even this is a very small sampling of all the players out there.
cannam@85 381 For that reason it is probably not a good idea to change this now because there
cannam@85 382 is the risk of breaking something that currently works.
cannam@85 383 </P>
cannam@85 384
cannam@85 385 <!-- ========================================================================= -->
cannam@85 386
cannam@85 387 <A NAME="Q012"></A>
cannam@85 388 <H2><BR/><B>Q12 : I'm looking at sf_read*. What are items? What are frames?
cannam@85 389 </B></H2>
cannam@85 390
cannam@85 391 <P>
cannam@85 392 An <tt>item</tt>tt> is a single sample of the data type you are reading; ie a
cannam@85 393 single <tt>short</tt> value for <tt>sf_read_short</tt> or a single <tt>float</tt>
cannam@85 394 for <tt>sf_read_float</tt>.
cannam@85 395 </P>
cannam@85 396
cannam@85 397 For a sound file with only one channel, a frame is the same as a item (ie a
cannam@85 398 single sample) while for multi channel sound files, a single frame contains a
cannam@85 399 single item for each channel.
cannam@85 400 </P>
cannam@85 401
cannam@85 402 <P>
cannam@85 403 Here are two simple, correct examples, both of which are assumed to be working
cannam@85 404 on a stereo file, first using items:
cannam@85 405 </P>
cannam@85 406
cannam@85 407 <PRE>
cannam@85 408 #define CHANNELS 2
cannam@85 409 short data [CHANNELS * 100] ;
cannam@85 410 sf_count items_read = sf_read_short (file, data, 200) ;
cannam@85 411 assert (items_read == 200) ;
cannam@85 412 </PRE>
cannam@85 413
cannam@85 414 <P>
cannam@85 415 and now readng the exact same amount of data using frames:
cannam@85 416 </P>
cannam@85 417
cannam@85 418 <PRE>
cannam@85 419 #define CHANNELS 2
cannam@85 420 short data [CHANNELS * 100] ;
cannam@85 421 sf_count frames_read = sf_readf_short (file, data, 100) ;
cannam@85 422 assert (frames_read == 100) ;
cannam@85 423 </PRE>
cannam@85 424
cannam@85 425 <!-- ========================================================================= -->
cannam@85 426
cannam@85 427 <A NAME="Q013"></A>
cannam@85 428 <H2><BR/><B>Q13 : Why can't libsndfile open this Sound Designer II (SD2) file?
cannam@85 429 </B></H2>
cannam@85 430
cannam@85 431 <P>
cannam@85 432 This is somewhat complicated.
cannam@85 433 First some background.
cannam@85 434 </P>
cannam@85 435
cannam@85 436 <P>
cannam@85 437 SD2 files are native to the Apple Macintosh platform and use features of
cannam@85 438 the Mac filesystem (file resource forks) to store the file's sample rate,
cannam@85 439 number of channels, sample width and more.
cannam@85 440 When you look at a file and its resource fork on Mac OS X it looks like
cannam@85 441 this:
cannam@85 442 </P>
cannam@85 443
cannam@85 444 <PRE>
cannam@85 445 -rw-r--r-- 1 erikd erikd 46512 Oct 18 22:57 file.sd2
cannam@85 446 -rw-r--r-- 1 erikd erikd 538 Oct 18 22:57 file.sd2/rsrc
cannam@85 447 </PRE>
cannam@85 448
cannam@85 449 <P>
cannam@85 450 Notice how the file itself looks like a directory containing a single file
cannam@85 451 named <B>rsrc</B>.
cannam@85 452 When libsndfile is compiled for MacOS X, it should open (for write and read)
cannam@85 453 SD2 file with resource forks like this without any problems.
cannam@85 454 It will also handle files with the resource fork in a separate file as
cannam@85 455 described below.
cannam@85 456 </P>
cannam@85 457
cannam@85 458 <P>
cannam@85 459 When SD2 files are moved to other platforms, the resource fork of the file
cannam@85 460 can sometimes be dropped altogether.
cannam@85 461 All that remains is the raw audio data and no information about the number
cannam@85 462 of channels, sample rate or bit width which makes it a little difficult for
cannam@85 463 libsndfile to open the file.
cannam@85 464 </P>
cannam@85 465
cannam@85 466 <P>
cannam@85 467 However, it is possible to safely move an SD2 file to a Linux or Windows
cannam@85 468 machine.
cannam@85 469 For instance, when an SD2 file is copied from inside MacOS X to a windows
cannam@85 470 shared directory or a Samba share (ie Linux), MacOS X is clever enough to
cannam@85 471 store the resource fork of the file in a separate hidden file in the
cannam@85 472 same directory like this:
cannam@85 473 </P>
cannam@85 474 <PRE>
cannam@85 475 -rw-r--r-- 1 erikd erikd 538 Oct 18 22:57 ._file.sd2
cannam@85 476 -rw-r--r-- 1 erikd erikd 46512 Oct 18 22:57 file.sd2
cannam@85 477 </PRE>
cannam@85 478
cannam@85 479 <P>
cannam@85 480 Regardless of what platform it is running on, when libsndfile is asked to
cannam@85 481 open a file named <B>"foo"</B> and it can't recognize the file type from
cannam@85 482 the data in the file, it will attempt to open the resource fork and if
cannam@85 483 that fails, it then tries to open a file named <B>"._foo"</B> to see if
cannam@85 484 the file has a valid resource fork.
cannam@85 485 This is the same regardless of whether the file is being opened for read
cannam@85 486 or write.
cannam@85 487 </P>
cannam@85 488
cannam@85 489 <P>
cannam@85 490 In short, libsndfile should open SD2 files with a valid resource fork on
cannam@85 491 all of the platforms that libsndfile supports.
cannam@85 492 If a file has lost its resource fork, the only option is the open the file
cannam@85 493 using the SF_FORMAT_RAW option and guessing its sample rate, channel count
cannam@85 494 and bit width.
cannam@85 495 </P>
cannam@85 496
cannam@85 497 <P>
cannam@85 498 Occasionally, when SD2 files are moved to other systems, the file is
cannam@85 499 <A HREF="http://www.macdisk.com/binhexen.php3">BinHexed</A>
cannam@85 500 which wraps the resource fork and the data fork together.
cannam@85 501 For these files, it would be possible to write a BinHex parser but
cannam@85 502 there is not a lot to gain considering how rare these BinHexed SD2
cannam@85 503 files are.
cannam@85 504 </P>
cannam@85 505
cannam@85 506 <!-- ========================================================================= -->
cannam@85 507 <A NAME="Q014"></A>
cannam@85 508 <H2><BR/><B>Q14 : I'd like to statically link libsndfile to my closed source
cannam@85 509 application. Can I buy a license so that this is possible?
cannam@85 510 </B></H2>
cannam@85 511
cannam@85 512 <P>
cannam@85 513 Unfortunately no.
cannam@85 514 libsndfile contains code written by other people who have agreed that their
cannam@85 515 code be used under the GNU LGPL but no more.
cannam@85 516 Even if they were to agree, there would be significant difficulties in
cannam@85 517 dividing up the payments fairly.
cannam@85 518 </P>
cannam@85 519
cannam@85 520 <P>
cannam@85 521 The <B>only</B> way you can legally use libsndfile as a statically linked
cannam@85 522 library is if your application is released under the GNU GPL or LGPL.
cannam@85 523 </P>
cannam@85 524
cannam@85 525 <!-- ========================================================================= -->
cannam@85 526 <A NAME="Q015"></A>
cannam@85 527 <H2><BR/><B>Q15 : My program is crashing during a call to a function in libsndfile.
cannam@85 528 Is this a bug in libsndfile?
cannam@85 529 </B></H2>
cannam@85 530
cannam@85 531 <P>
cannam@85 532 libsndfile is being used by large numbers of people all over the world
cannam@85 533 without any problems like this. That means that it is much more likely
cannam@85 534 that your code has a bug than libsndfile. However, it is still possible
cannam@85 535 that there is a bug in libsndfile.
cannam@85 536 </P>
cannam@85 537 <P>
cannam@85 538 To figure out whether it is your code or libsndfile you should do the
cannam@85 539 following:
cannam@85 540 </P>
cannam@85 541 <UL>
cannam@85 542 <LI>Make sure you are compiling your code with warnings switched on and
cannam@85 543 that you fix as many warnings as possible.
cannam@85 544 With the GNU compiler (gcc) I would recommend at least
cannam@85 545 <B>-W -Wall -Werror</B> which will force you to fix all warnings
cannam@85 546 before you can run the code.
cannam@85 547 <LI>Try using a memory debugger.
cannam@85 548 <A HREF="http://valgrind.kde.org/">Valgrind</A> on x86 Linux is excellent.
cannam@85 549 <A HREF="http://www.ibm.com/software/awdtools/purify/">Purify</A> also
cannam@85 550 has a good reputation.
cannam@85 551 <LI>If the code is clean after the above two steps and you still get
cannam@85 552 a crash in libsndfile, then send me a small snippet of code (no
cannam@85 553 more than 30-40 lines) which includes the call to sf_open() and
cannam@85 554 also shows how all variables passed to/returned from sf_open()
cannam@85 555 are defined.
cannam@85 556 </UL>
cannam@85 557
cannam@85 558 <!-- ========================================================================= -->
cannam@85 559 <A NAME="Q016"></A>
cannam@85 560 <H2><BR/><B>Q16 : Will you accept a fix for compiling libsndfile with compiler X?
cannam@85 561 </B></H2>
cannam@85 562
cannam@85 563 <P>
cannam@85 564 If compiler X is a C++ compiler then no.
cannam@85 565 C and C++ are different enough to make writing code that compiles as valid C
cannam@85 566 and valid C++ too difficult.
cannam@85 567 I would rather spend my time fixing bugs and adding features.
cannam@85 568 </P>
cannam@85 569
cannam@85 570 <P>
cannam@85 571 If compiler X is a C compiler then I will do what I can as long as that does
cannam@85 572 not hamper the correctness, portability and maintainability of the existing
cannam@85 573 code.
cannam@85 574 It should be noted however that libsndfile uses features specified by the 1999
cannam@85 575 ISO C Standard.
cannam@85 576 This can make compiling libsndfile with some older compilers difficult.
cannam@85 577 </P>
cannam@85 578
cannam@85 579 <!-- ========================================================================= -->
cannam@85 580 <A NAME="Q017"></A>
cannam@85 581 <H2><BR/><B>Q17 : Can libsndfile read/write files from/to UNIX pipes?
cannam@85 582 </B></H2>
cannam@85 583
cannam@85 584 <P>
cannam@85 585 Yes, libsndfile can read files from pipes.
cannam@85 586 Unfortunately, the write case is much more complicated.
cannam@85 587 </P>
cannam@85 588
cannam@85 589 <P>
cannam@85 590 File formats like AIFF and WAV have information at the start of the file (the
cannam@85 591 file header) which states the length of the file, the number of sample frames
cannam@85 592 etc.
cannam@85 593 This information must be filled in correctly when the file header is written,
cannam@85 594 but this information is not reliably known until the file is closed.
cannam@85 595 This means that libsndfile cannot write AIFF, WAV and many other file types
cannam@85 596 to a pipe.
cannam@85 597 </P>
cannam@85 598
cannam@85 599 <P>
cannam@85 600 However, there is at least one file format (AU) which is specifically designed
cannam@85 601 to be written to a pipe.
cannam@85 602 Like AIFF and WAV, AU has a header with a sample frames field, but it is
cannam@85 603 specifically allowable to set that frames field to 0x7FFFFFFF if the file
cannam@85 604 length is not known when the header is written.
cannam@85 605 The AU file format can also hold data in many of the standard formats (ie
cannam@85 606 SF_FORMAT_PCM_16, SF_FORMAT_PCM_24, SF_FORMAT_FLOAT etc) as well as allowing
cannam@85 607 data in both big and little endian format.
cannam@85 608 </P>
cannam@85 609
cannam@85 610 <P>
cannam@85 611 See also <A HREF="#Q006">FAQ Q6</A>.
cannam@85 612 </P>
cannam@85 613
cannam@85 614 <!-- ========================================================================= -->
cannam@85 615 <A NAME="Q018"></A>
cannam@85 616 <H2><BR/><B>Q18 : Is it possible to build a Universal Binary on Mac OS X?
cannam@85 617 </B></H2>
cannam@85 618
cannam@85 619 <P>
cannam@85 620 Yes, but you must do two separate configure/build/test runs; one on PowerPC
cannam@85 621 and one on Intel.
cannam@85 622 It is then possible to merge the binaries into a single universal binary using
cannam@85 623 one of the programs in the Apple tool chain.
cannam@85 624 </P>
cannam@85 625
cannam@85 626 <P>
cannam@85 627 It is <b>not</b> possible to build a working universal binary via a single
cannam@85 628 compile/build run on a single CPU.
cannam@85 629 </P>
cannam@85 630
cannam@85 631 <P>
cannam@85 632 The problem is that the libsndfile build process detects features of the CPU its
cannam@85 633 being built for during the configure process and when building a universal binary,
cannam@85 634 configure is only run once and that data is then used for both CPUs.
cannam@85 635 That configure data will be wrong for one of those CPUs.
cannam@85 636 You will still be able to compile libsndfile, and the test suite will pass on
cannam@85 637 the machine you compiled it on.
cannam@85 638 However, if you take the universal binary test suite programs compiled on one
cannam@85 639 CPU and run them on the other, the test suite will fail.
cannam@85 640 </P>
cannam@85 641
cannam@85 642 <P>
cannam@85 643 Part of the problem is the the CPU endian-ness is detected at configure time.
cannam@85 644 Yes, I know the Apple compiler defines one of the macros __LITTLE_ENDIAN__
cannam@85 645 and __BIG_ENDIAN__, but those macros are not part of the 1999 ISO C Standard
cannam@85 646 and they are not portable.
cannam@85 647 </P>
cannam@85 648
cannam@85 649 <P>
cannam@85 650 Endian issues are not the only reason why the cross compiled binary will fail.
cannam@85 651 The configure script also detects other CPU specific idiosyncrasies to provide
cannam@85 652 more optimized code.
cannam@85 653 </P>
cannam@85 654
cannam@85 655 <P>
cannam@85 656 Finally, the real show stopper problem with universal binaries is the problem
cannam@85 657 with the test suite.
cannam@85 658 libsndfile contains a huge, comprehensive test suite.
cannam@85 659 When you compile a universal binary and run the test suite, you only test the
cannam@85 660 native compile.
cannam@85 661 The cross compiled binary (the one with the much higher chance of having
cannam@85 662 problems) cannot be tested.
cannam@85 663 </P>
cannam@85 664
cannam@85 665 <P>
cannam@85 666 Now, if you have read this far you're probably thinking there must be a way
cannam@85 667 to fix this and there probably is.
cannam@85 668 The problem is that its a hell of a lot of work and would require significant
cannam@85 669 changes to the configure process, the internal code and the test suite.
cannam@85 670 In addition, these changes must not break compilation on any of the platforms
cannam@85 671 libsndfile is currently working on.
cannam@85 672 </p>
cannam@85 673
cannam@85 674
cannam@85 675 <!-- ========================================================================= -->
cannam@85 676 <A NAME="Q019"></A>
cannam@85 677 <H2><BR/><B>Q19 : I have project files for Visual Studio / XCode / Whatever. Why
cannam@85 678 don't you distribute them with libsndfile?
cannam@85 679 </B></H2>
cannam@85 680
cannam@85 681 <P>
cannam@85 682 There's a very good reason for this.
cannam@85 683 I will only distribute things that I actually have an ability to test and
cannam@85 684 maintain.
cannam@85 685 Project files for a bunch of different compilers and Integrated Development
cannam@85 686 Environments are simply too difficult to maintain.
cannam@85 687 </P>
cannam@85 688
cannam@85 689 <P>
cannam@85 690 The problem is that every time I add a new file to libsndfile or rename an
cannam@85 691 existing file I would have to modify all the project files and then test that
cannam@85 692 libsndfile still built with all the different compilers.
cannam@85 693 </P>
cannam@85 694
cannam@85 695 <P>
cannam@85 696 Maintaining these project files is also rather difficult if I don't have access
cannam@85 697 to the required compiler/IDE.
cannam@85 698 If I just edit the project files without testing them I will almost certainly
cannam@85 699 get it wrong.
cannam@85 700 If I release a version of libsndfile with broken project files, I'll get a bunch
cannam@85 701 of emails from people complaining about it not building and have no way of
cannam@85 702 fixing or even testing it.
cannam@85 703 </P>
cannam@85 704
cannam@85 705 <P>
cannam@85 706 I currently release sources that I personally test on Win32, Linux and
cannam@85 707 MacOS X (PowerPC) using the compiler I trust (GNU GCC).
cannam@85 708 Supporting one compiler on three (actually much more because GCC is available
cannam@85 709 almost everywhere) platforms is doable without too much pain.
cannam@85 710 I also release binaries for Win32 with instructions on how to use those
cannam@85 711 binaries with Visual Studio.
cannam@85 712 As a guy who is mainly interested in Linux, I'm not to keen to jump through
cannam@85 713 a bunch of hoops to support compilers and operating systems I don't use.
cannam@85 714 </P>
cannam@85 715
cannam@85 716 <P>
cannam@85 717 So, I hear you want to volunteer to maintain the project files for Some Crappy
cannam@85 718 Compiler 2007?
cannam@85 719 Well sorry, that won't work either.
cannam@85 720 I have had numerous people over the years offer to maintaining the project
cannam@85 721 files for Microsoft's Visual Studio.
cannam@85 722 Every single time that happened, they maintained it for a release or two and
cannam@85 723 then disappeared off the face of the earth.
cannam@85 724 Hence, I'm not willing to enter into an arrangement like that again.
cannam@85 725 </P>
cannam@85 726
cannam@85 727 <!-- ========================================================================= -->
cannam@85 728 <A NAME="Q020"></A>
cannam@85 729 <H2><BR/><B>Q20 : Why doesn't libsndfile support MP3? Lots of other Open Source
cannam@85 730 projects support it!
cannam@85 731 </B></H2>
cannam@85 732
cannam@85 733 <P>
cannam@85 734 MP3 is not supported for one very good reason; doing so requires the payment
cannam@85 735 of licensing fees.
cannam@85 736 As can be seen from
cannam@85 737 <a href="http://www.mp3licensing.com/royalty/software.html">
cannam@85 738 mp3licensing.com</a>
cannam@85 739 the required royalty payments are not cheap.
cannam@85 740 </P>
cannam@85 741
cannam@85 742 <p>
cannam@85 743 Yes, I know other libraries ignore the licensing requirements, but their legal
cannam@85 744 status is extremely dubious.
cannam@85 745 At any time, the body selling the licenses could go after the authors of those
cannam@85 746 libraries.
cannam@85 747 Some of those authors may be students and hence wouldn't be worth pursuing.
cannam@85 748 </P>
cannam@85 749
cannam@85 750 <p>
cannam@85 751 However, libsndfile is released under the name of a company, Mega Nerd Pty Ltd;
cannam@85 752 a company which has income from from libsamplerate licensing, libsndfile based
cannam@85 753 consulting income and other unrelated consulting income.
cannam@85 754 Adding MP3 support to libsndfile could place that income would be under legal
cannam@85 755 threat.
cannam@85 756 </p>
cannam@85 757
cannam@85 758 <p>
cannam@85 759 Fortunately, Ogg Vorbis exists as an alternative to MP3.
cannam@85 760 Support for Ogg Vorbis was added to libsndfile (mostly due to the efforts of
cannam@85 761 John ffitch of the Csound project) in version 1.0.18.
cannam@85 762 </p>
cannam@85 763
cannam@85 764
cannam@85 765 <!-- ========================================================================= -->
cannam@85 766 <A NAME="Q021"></A>
cannam@85 767 <H2><BR/><B>Q21 : How do I use libsndfile in a closed source or commercial program
cannam@85 768 and comply with the license?
cannam@85 769 </B></H2>
cannam@85 770
cannam@85 771 <p>
cannam@85 772 Here is a checklist of things you need to do to make sure your use of libsndfile
cannam@85 773 in a closed source or commercial project complies with the license libsndfile is
cannam@85 774 released under, the GNU Lesser General Public License (LGPL):
cannam@85 775 </p>
cannam@85 776
cannam@85 777 <ul>
cannam@85 778 <li>Make sure you are linking to libsndfile as a shared library (Linux and Unix
cannam@85 779 systems), Dynamic Link Library (Microsoft Windows) or dynlib (Mac OS X).
cannam@85 780 If you are using some other operating system that doesn't allow dynamically
cannam@85 781 linked libraries, you will not be able to use libsndfile unless you release
cannam@85 782 the source code to your program.
cannam@85 783 <li>In the licensing documentation for your program, add a statement that your
cannam@85 784 software depends on libsndfile and that libsndfile is released under the GNU
cannam@85 785 Lesser General Public License, either
cannam@85 786 <a href="http://www.gnu.org/licenses/lgpl-2.1.txt">version 2.1</a>
cannam@85 787 or optionally
cannam@85 788 <a href="http://www.gnu.org/licenses/lgpl.txt">version 3</a>.
cannam@85 789 <li>Include the text for both versions of the license, possibly as separate
cannam@85 790 files named libsndfile_lgpl_v2_1.txt and libsndfile_lgpl_v3.txt.
cannam@85 791 </ul>
cannam@85 792
cannam@85 793 <!-- ========================================================================= -->
cannam@85 794 <A NAME="Q022"></A>
cannam@85 795 <H2><BR/><B>Q22 : What versions of Windows does libsndfile work on?
cannam@85 796 </B></H2>
cannam@85 797
cannam@85 798 <p>
cannam@85 799 Currently the precompiled windows binaries are thoroughly tested on Windows XP.
cannam@85 800 As such, they should also work on Win2k and Windows Vista.
cannam@85 801 They may also work on earlier versions of Windows.
cannam@85 802 </p>
cannam@85 803
cannam@85 804 <p>
cannam@85 805 Since version 0.1.18 I have also been releasing precompiled binaries for Win64,
cannam@85 806 the 64 bit version of Windows.
cannam@85 807 These binaries have received much less testing than the 32 bit versions, but
cannam@85 808 should work as expected.
cannam@85 809 I'd be very interested in receiving feedback on these binaries.
cannam@85 810 </p>
cannam@85 811
cannam@85 812 <!-- ========================================================================= -->
cannam@85 813 <A NAME="Q023"></A>
cannam@85 814 <H2><BR/><B>Q23 : I'm cross compiling libsndfile for another platform. How can I
cannam@85 815 run the test suite?
cannam@85 816 </B></H2>
cannam@85 817
cannam@85 818 <p>
cannam@85 819 </p>
cannam@85 820
cannam@85 821 <p>
cannam@85 822 Since version 1.0.21 the top level Makefile has an extra make target,
cannam@85 823 'test-tarball'.
cannam@85 824 Building this target creates a tarball called called:
cannam@85 825 </p>
cannam@85 826
cannam@85 827 <center><tt>
cannam@85 828 libsndfile-testsuite-${host_triplet}-${version}.tar.gz
cannam@85 829 </tt></center>
cannam@85 830
cannam@85 831 <p>
cannam@85 832 in the top level directory.
cannam@85 833 This tarball can then be copied to the target platform.
cannam@85 834 Once untarred and test script <tt>test_wrapper.sh</tt> can be run from
cannam@85 835 the top level of the extracted tarball.
cannam@85 836 </p>
cannam@85 837
cannam@85 838 <!-- ========================================================================= -->
cannam@85 839 <HR>
cannam@85 840 <P>
cannam@85 841 The libsndfile home page is here :
cannam@85 842 <A HREF="http://www.mega-nerd.com/libsndfile/">
cannam@85 843 http://www.mega-nerd.com/libsndfile/</A>.
cannam@85 844 <BR/>
cannam@85 845 Version : 1.0.25
cannam@85 846 </P>
cannam@85 847
cannam@85 848 </BODY>
cannam@85 849 </HTML>