Mercurial > hg > sv-dependency-builds

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