Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.27/doc/FAQ.html @ 40:1df64224f5ac

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