Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 1 | /* FLAC - Free Lossless Audio Codec |
Erik de Castro Lopo | b1982fb | 2013-05-25 17:11:19 +1000 | [diff] [blame] | 2 | * Copyright (C) 2001-2009 Josh Coalson |
Erik de Castro Lopo | 1437391 | 2014-11-24 22:07:15 +1100 | [diff] [blame^] | 3 | * Copyright (C) 2011-2014 Xiph.Org Foundation |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 4 | * |
Josh Coalson | e8a7601 | 2003-02-07 00:14:32 +0000 | [diff] [blame] | 5 | * This file is part the FLAC project. FLAC is comprised of several |
Ulrich Klauer | cd4ddab | 2013-05-26 22:53:43 +0200 | [diff] [blame] | 6 | * components distributed under different licenses. The codec libraries |
Josh Coalson | e8a7601 | 2003-02-07 00:14:32 +0000 | [diff] [blame] | 7 | * are distributed under Xiph.Org's BSD-like license (see the file |
| 8 | * COPYING.Xiph in this distribution). All other programs, libraries, and |
Josh Coalson | f37520b | 2006-11-20 06:46:07 +0000 | [diff] [blame] | 9 | * plugins are distributed under the LGPL or GPL (see COPYING.LGPL and |
| 10 | * COPYING.GPL). The documentation is distributed under the Gnu FDL (see |
| 11 | * COPYING.FDL). Each file in the FLAC distribution contains at the top the |
| 12 | * terms under which it may be distributed. |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 13 | * |
Josh Coalson | e8a7601 | 2003-02-07 00:14:32 +0000 | [diff] [blame] | 14 | * Since this particular file is relevant to all components of FLAC, |
| 15 | * it may be distributed under the Xiph.Org license, which is the least |
| 16 | * restrictive of those mentioned above. See the file COPYING.Xiph in this |
| 17 | * distribution. |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 18 | */ |
| 19 | |
| 20 | |
Erik de Castro Lopo | f84287e | 2012-01-31 19:28:14 +1100 | [diff] [blame] | 21 | FLAC is an Open Source lossless audio codec developed by Josh Coalson from 2001 |
| 22 | to 2009. |
| 23 | |
| 24 | From January 2012 FLAC is being maintained by Erik de Castro Lopo under the |
| 25 | auspices of the Xiph.org Foundation. |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 26 | |
Josh Coalson | bc86950 | 2002-06-14 06:36:16 +0000 | [diff] [blame] | 27 | FLAC is comprised of |
| 28 | * `libFLAC', a library which implements reference encoders and |
Josh Coalson | 8da98c8 | 2006-10-15 04:24:05 +0000 | [diff] [blame] | 29 | decoders for native FLAC and Ogg FLAC, and a metadata interface |
Josh Coalson | bc86950 | 2002-06-14 06:36:16 +0000 | [diff] [blame] | 30 | * `libFLAC++', a C++ object wrapper library around libFLAC |
Josh Coalson | 0c3524c | 2002-08-22 04:21:54 +0000 | [diff] [blame] | 31 | * `flac', a command-line program for encoding and decoding files |
Josh Coalson | cf3f338 | 2003-09-24 04:36:57 +0000 | [diff] [blame] | 32 | * `metaflac', a command-line program for viewing and editing FLAC |
| 33 | metadata |
Erik de Castro Lopo | 0854575 | 2014-06-28 09:21:05 +1000 | [diff] [blame] | 34 | * player plugin for XMMS |
Josh Coalson | 0c3524c | 2002-08-22 04:21:54 +0000 | [diff] [blame] | 35 | * user and API documentation |
| 36 | |
Josh Coalson | 8da98c8 | 2006-10-15 04:24:05 +0000 | [diff] [blame] | 37 | The libraries (libFLAC, libFLAC++) are |
Josh Coalson | afd8107 | 2003-01-31 23:34:56 +0000 | [diff] [blame] | 38 | licensed under Xiph.org's BSD-like license (see COPYING.Xiph). All other |
Josh Coalson | 0c3524c | 2002-08-22 04:21:54 +0000 | [diff] [blame] | 39 | programs and plugins are licensed under the GNU General Public License |
Josh Coalson | afd8107 | 2003-01-31 23:34:56 +0000 | [diff] [blame] | 40 | (see COPYING.GPL). The documentation is licensed under the GNU Free |
| 41 | Documentation License (see COPYING.FDL). |
Josh Coalson | 0c3524c | 2002-08-22 04:21:54 +0000 | [diff] [blame] | 42 | |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 43 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 44 | =============================================================================== |
Ulrich Klauer | bd4af7e | 2013-05-27 00:49:58 +0200 | [diff] [blame] | 45 | FLAC - 1.3.0 - Contents |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 46 | =============================================================================== |
| 47 | |
| 48 | - Introduction |
Josh Coalson | b445ebe | 2004-09-26 00:54:28 +0000 | [diff] [blame] | 49 | - Prerequisites |
Josh Coalson | 8c8eb71 | 2007-09-12 01:03:20 +0000 | [diff] [blame] | 50 | - Note to embedded developers |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 51 | - Building in a GNU environment |
| 52 | - Building with Makefile.lite |
| 53 | - Building with MSVC |
| 54 | - Building on Mac OS X |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 55 | |
| 56 | |
| 57 | =============================================================================== |
| 58 | Introduction |
| 59 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 60 | |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 61 | This is the source release for the FLAC project. See |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 62 | |
Josh Coalson | c28ec32 | 2004-09-10 00:20:04 +0000 | [diff] [blame] | 63 | doc/html/index.html |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 64 | |
| 65 | for full documentation. |
| 66 | |
| 67 | A brief description of the directory tree: |
| 68 | |
Josh Coalson | 917df86 | 2002-07-03 07:39:05 +0000 | [diff] [blame] | 69 | doc/ the HTML documentation |
Erik de Castro Lopo | 0854575 | 2014-06-28 09:21:05 +1000 | [diff] [blame] | 70 | examples/ example programs demonstrating the use of libFLAC and libFLAC++ |
Josh Coalson | 917df86 | 2002-07-03 07:39:05 +0000 | [diff] [blame] | 71 | include/ public include files for libFLAC and libFLAC++ |
Erik de Castro Lopo | 0854575 | 2014-06-28 09:21:05 +1000 | [diff] [blame] | 72 | man/ the man pages for `flac' and `metaflac' |
Josh Coalson | 917df86 | 2002-07-03 07:39:05 +0000 | [diff] [blame] | 73 | src/ the source code and private headers |
| 74 | test/ the test scripts |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 75 | |
Erik de Castro Lopo | 0854575 | 2014-06-28 09:21:05 +1000 | [diff] [blame] | 76 | If you have questions about building FLAC that this document does not answer, |
| 77 | please submit them at the following tracker so this document can be improved: |
| 78 | |
| 79 | https://sourceforge.net/p/flac/support-requests/ |
| 80 | |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 81 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 82 | =============================================================================== |
Josh Coalson | b445ebe | 2004-09-26 00:54:28 +0000 | [diff] [blame] | 83 | Prerequisites |
| 84 | =============================================================================== |
| 85 | |
| 86 | To build FLAC with support for Ogg FLAC you must have built and installed |
| 87 | libogg according to the specific instructions below. You must have |
| 88 | libogg 1.1.2 or greater, or there will be seeking problems with Ogg FLAC. |
| 89 | |
| 90 | If you are building on x86 and want the assembly optimizations, you will |
Josh Coalson | df8e732 | 2005-01-21 01:25:43 +0000 | [diff] [blame] | 91 | need to have NASM >= 0.98.30 installed according to the specific instructions |
| 92 | below. |
Josh Coalson | b445ebe | 2004-09-26 00:54:28 +0000 | [diff] [blame] | 93 | |
| 94 | |
| 95 | =============================================================================== |
Josh Coalson | 8c8eb71 | 2007-09-12 01:03:20 +0000 | [diff] [blame] | 96 | Note to embedded developers |
| 97 | =============================================================================== |
| 98 | |
| 99 | libFLAC has grown larger over time as more functionality has been |
| 100 | included, but much of it may be unnecessary for a particular embedded |
| 101 | implementation. Unused parts may be pruned by some simple editing of |
Ulrich Klauer | eaae8e0 | 2013-04-30 23:10:11 +0200 | [diff] [blame] | 102 | configure.ac and src/libFLAC/Makefile.am; the following dependency |
Josh Coalson | 8c8eb71 | 2007-09-12 01:03:20 +0000 | [diff] [blame] | 103 | graph shows which modules may be pruned without breaking things |
| 104 | further down: |
| 105 | |
| 106 | metadata.h |
| 107 | stream_decoder.h |
| 108 | format.h |
| 109 | |
| 110 | stream_encoder.h |
| 111 | stream_decoder.h |
| 112 | format.h |
| 113 | |
| 114 | stream_decoder.h |
| 115 | format.h |
| 116 | |
| 117 | In other words, for pure decoding applications, both the stream encoder |
| 118 | and metadata editing interfaces can be safely removed. |
| 119 | |
| 120 | There is a section dedicated to embedded use in the libFLAC API |
| 121 | HTML documentation (see doc/html/api/index.html). |
| 122 | |
| 123 | Also, there are several places in the libFLAC code with comments marked |
| 124 | with "OPT:" where a #define can be changed to enable code that might be |
| 125 | faster on a specific platform. Experimenting with these can yield faster |
| 126 | binaries. |
| 127 | |
| 128 | |
| 129 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 130 | Building in a GNU environment |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 131 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 132 | |
Josh Coalson | 172ac00 | 2001-10-31 18:30:19 +0000 | [diff] [blame] | 133 | FLAC uses autoconf and libtool for configuring and building. |
| 134 | Better documentation for these will be forthcoming, but in |
| 135 | general, this should work: |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 136 | |
Josh Coalson | c220cf4 | 2002-08-23 06:41:31 +0000 | [diff] [blame] | 137 | ./configure && make && make check && make install |
| 138 | |
| 139 | The 'make check' step is optional; omit it to skip all the tests, |
Josh Coalson | ccea6aa | 2002-12-17 08:14:42 +0000 | [diff] [blame] | 140 | which can take several hours and use around 70-80 megs of disk space. |
Josh Coalson | 9d260d8 | 2003-08-28 23:47:15 +0000 | [diff] [blame] | 141 | Even though it will stop with an explicit message on any failure, it |
| 142 | does print out a lot of stuff so you might want to capture the output |
| 143 | to a file if you're having a problem. Also, don't run 'make check' |
| 144 | as root because it confuses some of the tests. |
Josh Coalson | bfe42f1 | 2000-12-22 22:42:25 +0000 | [diff] [blame] | 145 | |
Josh Coalson | 917df86 | 2002-07-03 07:39:05 +0000 | [diff] [blame] | 146 | NOTE: Despite our best efforts it's entirely possible to have |
| 147 | problems when using older versions of autoconf, automake, or |
| 148 | libtool. If you have the latest versions and still can't get it |
| 149 | to work, see the next section on Makefile.lite. |
Josh Coalson | 0403256 | 2001-07-20 23:43:15 +0000 | [diff] [blame] | 150 | |
Josh Coalson | 3643db3 | 2001-07-18 00:23:06 +0000 | [diff] [blame] | 151 | There are a few FLAC-specific arguments you can give to |
| 152 | `configure': |
| 153 | |
| 154 | --enable-debug : Builds everything with debug symbols and some |
| 155 | extra (and more verbose) error checking. |
| 156 | |
| 157 | --disable-asm-optimizations : Disables the compilation of the |
| 158 | assembly routines. Many routines have assembly versions for |
| 159 | speed and `configure' is pretty good about knowing what is |
| 160 | supported, but you can use this option to build only from the |
Erik de Castro Lopo | 0854575 | 2014-06-28 09:21:05 +1000 | [diff] [blame] | 161 | C sources. May be necessary for building on OS X (Intel). |
Josh Coalson | 3643db3 | 2001-07-18 00:23:06 +0000 | [diff] [blame] | 162 | |
Josh Coalson | e326848 | 2001-12-04 06:46:12 +0000 | [diff] [blame] | 163 | --enable-sse : If you are building for an x86 CPU that supports |
Josh Coalson | 3643db3 | 2001-07-18 00:23:06 +0000 | [diff] [blame] | 164 | SSE instructions, you can enable some of the faster routines |
| 165 | if your operating system also supports SSE instructions. flac |
| 166 | can tell if the CPU supports the instructions but currently has |
| 167 | no way to test if the OS does, so if it does, you must pass |
| 168 | this argument to configure to use the SSE routines. If flac |
| 169 | crashes when built with this option you will have to go back and |
Josh Coalson | e326848 | 2001-12-04 06:46:12 +0000 | [diff] [blame] | 170 | configure without --enable-sse. Note that |
| 171 | --disable-asm-optimizations implies --disable-sse. |
Josh Coalson | 9e6efb6 | 2001-05-29 18:48:42 +0000 | [diff] [blame] | 172 | |
Josh Coalson | 3d73072 | 2003-01-14 06:59:50 +0000 | [diff] [blame] | 173 | --enable-local-xmms-plugin : Installs the FLAC XMMS plugin in |
| 174 | $HOME/.xmms/Plugins, instead of the global XMMS plugin area |
| 175 | (usually /usr/lib/xmms/Input). |
Josh Coalson | c69f878 | 2001-11-13 23:08:22 +0000 | [diff] [blame] | 176 | |
Josh Coalson | 822eef6 | 2002-09-12 06:40:44 +0000 | [diff] [blame] | 177 | --with-ogg= |
Josh Coalson | 822eef6 | 2002-09-12 06:40:44 +0000 | [diff] [blame] | 178 | --with-xmms-prefix= |
| 179 | --with-libiconv-prefix= |
| 180 | Use these if you have these packages but configure can't find them. |
| 181 | |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 182 | If you want to build completely from scratch (i.e. starting with just |
Ulrich Klauer | eaae8e0 | 2013-04-30 23:10:11 +0200 | [diff] [blame] | 183 | configure.ac and Makefile.am) you should be able to just run 'autogen.sh' |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 184 | but make sure and read the comments in that file first. |
| 185 | |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 186 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 187 | =============================================================================== |
Josh Coalson | 0403256 | 2001-07-20 23:43:15 +0000 | [diff] [blame] | 188 | Building with Makefile.lite |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 189 | =============================================================================== |
Josh Coalson | 0403256 | 2001-07-20 23:43:15 +0000 | [diff] [blame] | 190 | |
| 191 | There is a more lightweight build system for do-it-yourself-ers. |
| 192 | It is also useful if configure isn't working, which may be the |
| 193 | case since lately we've had some problems with different versions |
| 194 | of automake and libtool. The Makefile.lite system should work |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 195 | on GNU systems with few or no adjustments. |
Josh Coalson | 0403256 | 2001-07-20 23:43:15 +0000 | [diff] [blame] | 196 | |
| 197 | From the top level just 'make -f Makefile.lite'. You can |
| 198 | specify zero or one optional target from 'release', 'debug', |
| 199 | 'test', or 'clean'. The default is 'release'. There is no |
| 200 | 'install' target but everything you need will end up in the |
| 201 | obj/ directory. |
| 202 | |
| 203 | If you are not on an x86 system or you don't have nasm, you |
| 204 | may have to change the DEFINES in src/libFLAC/Makefile.lite. If |
| 205 | you don't have nasm, remove -DFLAC__HAS_NASM. If your target is |
| 206 | not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN. |
| 207 | |
| 208 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 209 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 210 | Building with MSVC |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 211 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 212 | |
Erik de Castro Lopo | c152d1a | 2013-03-18 06:22:51 +1100 | [diff] [blame] | 213 | There are .vcproj projects and a master FLAC.sln solution to build all |
| 214 | the libraries and executables with MSVC 2005 or newer. |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 215 | |
Josh Coalson | 630d22e | 2003-01-25 18:32:56 +0000 | [diff] [blame] | 216 | Prerequisite: you must have the Ogg libraries installed as described |
| 217 | later. |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 218 | |
Erik de Castro Lopo | c152d1a | 2013-03-18 06:22:51 +1100 | [diff] [blame] | 219 | Prerequisite: you must have nasm installed, and nasm.exe must be in |
| 220 | your PATH, or the path to nasm.exe must be added to the list of |
Josh Coalson | 64fbc8f | 2004-09-10 00:57:17 +0000 | [diff] [blame] | 221 | directories for executable files in the MSVC global options. |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 222 | |
Josh Coalson | 32821c0 | 2007-02-22 02:56:16 +0000 | [diff] [blame] | 223 | To build everything, run Visual Studio, do File|Open and open FLAC.sln. |
| 224 | From the dropdown in the toolbar, select "Release" instead of "Debug", |
Erik de Castro Lopo | 0854575 | 2014-06-28 09:21:05 +1000 | [diff] [blame] | 225 | then do Build|Build Solution. |
Josh Coalson | 32821c0 | 2007-02-22 02:56:16 +0000 | [diff] [blame] | 226 | |
Erik de Castro Lopo | c152d1a | 2013-03-18 06:22:51 +1100 | [diff] [blame] | 227 | This will build all libraries both statically (e.g. |
Erik de Castro Lopo | f67928d | 2013-01-02 22:48:59 +1100 | [diff] [blame] | 228 | objs\release\lib\libFLAC_static.lib) and as DLLs (e.g. |
| 229 | objs\release\lib\libFLAC.dll), and it will build all binaries, statically |
| 230 | linked (e.g. objs\release\bin\flac.exe). |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 231 | |
Erik de Castro Lopo | c152d1a | 2013-03-18 06:22:51 +1100 | [diff] [blame] | 232 | Everything will end up in the "objs" directory. DLLs and .exe files |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 233 | are all that are needed and can be copied to an installation area and |
Erik de Castro Lopo | c152d1a | 2013-03-18 06:22:51 +1100 | [diff] [blame] | 234 | added to the PATH. |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 235 | |
Erik de Castro Lopo | c152d1a | 2013-03-18 06:22:51 +1100 | [diff] [blame] | 236 | By default the code is configured with Ogg support. Before building FLAC |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 237 | you will need to get the Ogg source distribution |
Erik de Castro Lopo | c152d1a | 2013-03-18 06:22:51 +1100 | [diff] [blame] | 238 | (see http://xiph.org/downloads/), build libogg_static.lib (load |
| 239 | win32\libogg_static.sln, change solution configuration to "Release" and |
| 240 | code generation to "Multi-threaded (/MT)", then build), copy libogg_static.lib |
| 241 | into FLAC's 'objs\release\lib' directory, and copy the entire include\ogg tree |
| 242 | into FLAC's 'include' directory (so that there is an 'ogg' directory in FLAC's |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 243 | 'include' directory with the files ogg.h, os_types.h and config_types.h). |
| 244 | |
Erik de Castro Lopo | c152d1a | 2013-03-18 06:22:51 +1100 | [diff] [blame] | 245 | If you want to build without Ogg support, instead edit all .vcproj files |
| 246 | and remove any "FLAC__HAS_OGG" definitions. |
Josh Coalson | 32821c0 | 2007-02-22 02:56:16 +0000 | [diff] [blame] | 247 | |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 248 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 249 | =============================================================================== |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 250 | Building on Mac OS X |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 251 | =============================================================================== |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 252 | |
Ulrich Klauer | eaae8e0 | 2013-04-30 23:10:11 +0200 | [diff] [blame] | 253 | If you have Fink or a recent version of OS X with the proper autotools, |
Erik de Castro Lopo | 4ff213b | 2013-05-01 08:08:11 +1000 | [diff] [blame] | 254 | the GNU flow above should work. |