| /* FLAC - Free Lossless Audio Codec |
| * Copyright (C) 2001,2002,2003,2004,2005 Josh Coalson |
| * |
| * This file is part the FLAC project. FLAC is comprised of several |
| * components distributed under difference licenses. The codec libraries |
| * are distributed under Xiph.Org's BSD-like license (see the file |
| * COPYING.Xiph in this distribution). All other programs, libraries, and |
| * plugins are distributed under the GPL (see COPYING.GPL). The documentation |
| * is distributed under the Gnu FDL (see COPYING.FDL). Each file in the |
| * FLAC distribution contains at the top the terms under which it may be |
| * distributed. |
| * |
| * Since this particular file is relevant to all components of FLAC, |
| * it may be distributed under the Xiph.Org license, which is the least |
| * restrictive of those mentioned above. See the file COPYING.Xiph in this |
| * distribution. |
| */ |
| |
| |
| FLAC (http://flac.sourceforge.net/) is an Open Source lossless audio |
| codec developed by Josh Coalson. |
| |
| FLAC is comprised of |
| * `libFLAC', a library which implements reference encoders and |
| decoders, and a metadata interface |
| * `libFLAC++', a C++ object wrapper library around libFLAC |
| * `libOggFLAC' and `libOggFLAC++', which provide encoders and |
| decoders for FLAC streams in an Ogg container |
| * `flac', a command-line program for encoding and decoding files |
| * `metaflac', a command-line program for viewing and editing FLAC |
| metadata |
| * player plugins for XMMS and Winamp |
| * user and API documentation |
| |
| The libraries (libFLAC, libFLAC++, libOggFLAC, and libOggFLAC++) are |
| licensed under Xiph.org's BSD-like license (see COPYING.Xiph). All other |
| programs and plugins are licensed under the GNU General Public License |
| (see COPYING.GPL). The documentation is licensed under the GNU Free |
| Documentation License (see COPYING.FDL). |
| |
| |
| =============================================================================== |
| FLAC - 1.1.2-beta - Contents |
| =============================================================================== |
| |
| - Introduction |
| - Prerequisites |
| - Building in a GNU environment |
| - Building with Makefile.lite |
| - Building with MSVC |
| - Building on Mac OS X |
| - Note to embedded developers |
| |
| |
| =============================================================================== |
| Introduction |
| =============================================================================== |
| |
| This is the source release for the FLAC project. See |
| |
| doc/html/index.html |
| |
| for full documentation. |
| |
| A brief description of the directory tree: |
| |
| doc/ the HTML documentation |
| flac.pbproj/ the Mac OS X Project Builder project |
| include/ public include files for libFLAC and libFLAC++ |
| man/ the man page for `flac' |
| src/ the source code and private headers |
| test/ the test scripts |
| |
| |
| =============================================================================== |
| Prerequisites |
| =============================================================================== |
| |
| To build FLAC with support for Ogg FLAC you must have built and installed |
| libogg according to the specific instructions below. You must have |
| libogg 1.1.2 or greater, or there will be seeking problems with Ogg FLAC. |
| |
| If you are building on x86 and want the assembly optimizations, you will |
| need to have NASM >= 0.98.30 installed according to the specific instructions |
| below. |
| |
| |
| =============================================================================== |
| Building in a GNU environment |
| =============================================================================== |
| |
| FLAC uses autoconf and libtool for configuring and building. |
| Better documentation for these will be forthcoming, but in |
| general, this should work: |
| |
| ./configure && make && make check && make install |
| |
| The 'make check' step is optional; omit it to skip all the tests, |
| which can take several hours and use around 70-80 megs of disk space. |
| Even though it will stop with an explicit message on any failure, it |
| does print out a lot of stuff so you might want to capture the output |
| to a file if you're having a problem. Also, don't run 'make check' |
| as root because it confuses some of the tests. |
| |
| NOTE: Despite our best efforts it's entirely possible to have |
| problems when using older versions of autoconf, automake, or |
| libtool. If you have the latest versions and still can't get it |
| to work, see the next section on Makefile.lite. |
| |
| There are a few FLAC-specific arguments you can give to |
| `configure': |
| |
| --enable-debug : Builds everything with debug symbols and some |
| extra (and more verbose) error checking. |
| |
| --disable-asm-optimizations : Disables the compilation of the |
| assembly routines. Many routines have assembly versions for |
| speed and `configure' is pretty good about knowing what is |
| supported, but you can use this option to build only from the |
| C sources. |
| |
| --enable-sse : If you are building for an x86 CPU that supports |
| SSE instructions, you can enable some of the faster routines |
| if your operating system also supports SSE instructions. flac |
| can tell if the CPU supports the instructions but currently has |
| no way to test if the OS does, so if it does, you must pass |
| this argument to configure to use the SSE routines. If flac |
| crashes when built with this option you will have to go back and |
| configure without --enable-sse. Note that |
| --disable-asm-optimizations implies --disable-sse. |
| |
| --enable-local-xmms-plugin : Installs the FLAC XMMS plugin in |
| $HOME/.xmms/Plugins, instead of the global XMMS plugin area |
| (usually /usr/lib/xmms/Input). |
| |
| --with-ogg= |
| --with-xmms-prefix= |
| --with-libiconv-prefix= |
| Use these if you have these packages but configure can't find them. |
| |
| If you want to build completely from scratch (i.e. starting with just |
| configure.in and Makefile.am) you should be able to just run 'autogen.sh' |
| but make sure and read the comments in that file first. |
| |
| |
| =============================================================================== |
| Building with Makefile.lite |
| =============================================================================== |
| |
| There is a more lightweight build system for do-it-yourself-ers. |
| It is also useful if configure isn't working, which may be the |
| case since lately we've had some problems with different versions |
| of automake and libtool. The Makefile.lite system should work |
| on GNU systems with few or no adjustments. |
| |
| From the top level just 'make -f Makefile.lite'. You can |
| specify zero or one optional target from 'release', 'debug', |
| 'test', or 'clean'. The default is 'release'. There is no |
| 'install' target but everything you need will end up in the |
| obj/ directory. |
| |
| If you are not on an x86 system or you don't have nasm, you |
| may have to change the DEFINES in src/libFLAC/Makefile.lite. If |
| you don't have nasm, remove -DFLAC__HAS_NASM. If your target is |
| not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN. |
| |
| |
| =============================================================================== |
| Building with MSVC |
| =============================================================================== |
| |
| There are now .dsp projects and a master FLAC.dsw workspace to build |
| all the libraries and executables. |
| |
| Prerequisite: you must have the Ogg libraries installed as described |
| later. |
| |
| Prerequisite: you must have nasm installed, and nasmw.exe must be in |
| your PATH, or the path to nasmw.exe must be added to the list of |
| directories for executable files in the MSVC global options. |
| |
| To build everything, run Developer Studio, do File|Open Workspace, |
| and open FLAC.dsw. Select "Build | Set active configuration..." |
| from the menu, then in the dialog, select "All - Win32 Release" (or |
| Debug if you prefer). Click "Ok" then hit F7 to build. This will build |
| all libraries both statically (e.g. obj\release\lib\libFLAC_static.lib) |
| and as DLLs (e.g. obj\release\bin\libFLAC.dll), and it will build all |
| binaries, statically linked (e.g. obj\release\bin\flac.exe). |
| |
| Everything will end up in the "obj" directory. DLLs and .exe files |
| are all that are needed and can be copied to an installation area and |
| added to the PATH. The plugins have to be copied to their appropriate |
| place in the player area. For Winamp2 this is <winamp2-dir>\Plugins. |
| |
| By default the code is configured with Ogg support. Before building FLAC |
| you will need to get the Ogg source distribution |
| (see http://xiph.org/ogg/vorbis/download/), build ogg_static.lib (load and |
| build win32\ogg_static.dsp), copy ogg_static.lib into FLAC's |
| 'obj\release\lib' directory, and copy the entire include\ogg tree into |
| FLAC's 'include' directory (so that there is an 'ogg' directory in FLAC's |
| 'include' directory with the files ogg.h, os_types.h and config_types.h). |
| |
| |
| =============================================================================== |
| Building on Mac OS X |
| =============================================================================== |
| |
| If you have Fink, the GNU flow above should work. Otherwise, |
| there is a Project Builder project in the top-level source |
| directory to build libFLAC and the command-line utilities on |
| Mac OS X. In a terminal, cd to the top-level directory (the |
| one that contains this README file) and type: |
| |
| pbxbuild -alltargets |
| |
| This will create everything and leave it in the build/ directory. |
| Don't worry about the rest of the stuff that is in build/ or |
| the stuff that was already there before building. |
| |
| The Project Builder project requires that you have libiconv and |
| libogg in /sw, ala fink. If you don't, you'll need to install |
| them somewhere and change the path to them in the Library Paths |
| section of several targets. |
| |
| It also assumes the CPU supports Altivec instructions. If it does |
| not, you will also have to add -DFLAC__NO_ASM to the CFLAGS in the |
| libFLAC target. |
| |
| There currently is no install procedure; you will have to |
| manually copy the tools to wherever you need them. |
| |
| |
| =============================================================================== |
| Note to embedded developers |
| =============================================================================== |
| |
| libFLAC has grown larger over time as more functionality has been |
| included, but much of it may be unnecessary for a particular embedded |
| implementation. Unused parts may be pruned by some simple editing of |
| configure.in and src/libFLAC/Makefile.am; the following dependency |
| graph shows which modules may be pruned without breaking things |
| further down: |
| |
| file_encoder.h |
| stream_encoder.h |
| format.h |
| |
| file_decoder.h |
| seekable_stream_decoder.h |
| stream_decoder.h |
| format.h |
| |
| metadata.h |
| format.h |
| |
| There is a section dedicated to embedded use in the libFLAC API |
| HTML documentation (see doc/html/api/index.html). |