diff options
Diffstat (limited to 'apps/codecs/libFLAC/README')
-rw-r--r-- | apps/codecs/libFLAC/README | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/apps/codecs/libFLAC/README b/apps/codecs/libFLAC/README new file mode 100644 index 0000000000..e135601037 --- /dev/null +++ b/apps/codecs/libFLAC/README | |||
@@ -0,0 +1,257 @@ | |||
1 | /* FLAC - Free Lossless Audio Codec | ||
2 | * Copyright (C) 2001,2002,2003,2004,2005 Josh Coalson | ||
3 | * | ||
4 | * This file is part the FLAC project. FLAC is comprised of several | ||
5 | * components distributed under difference licenses. The codec libraries | ||
6 | * are distributed under Xiph.Org's BSD-like license (see the file | ||
7 | * COPYING.Xiph in this distribution). All other programs, libraries, and | ||
8 | * plugins are distributed under the GPL (see COPYING.GPL). The documentation | ||
9 | * is distributed under the Gnu FDL (see COPYING.FDL). Each file in the | ||
10 | * FLAC distribution contains at the top the terms under which it may be | ||
11 | * distributed. | ||
12 | * | ||
13 | * Since this particular file is relevant to all components of FLAC, | ||
14 | * it may be distributed under the Xiph.Org license, which is the least | ||
15 | * restrictive of those mentioned above. See the file COPYING.Xiph in this | ||
16 | * distribution. | ||
17 | */ | ||
18 | |||
19 | |||
20 | FLAC (http://flac.sourceforge.net/) is an Open Source lossless audio | ||
21 | codec developed by Josh Coalson. | ||
22 | |||
23 | FLAC is comprised of | ||
24 | * `libFLAC', a library which implements reference encoders and | ||
25 | decoders, and a metadata interface | ||
26 | * `libFLAC++', a C++ object wrapper library around libFLAC | ||
27 | * `libOggFLAC' and `libOggFLAC++', which provide encoders and | ||
28 | decoders for FLAC streams in an Ogg container | ||
29 | * `flac', a command-line program for encoding and decoding files | ||
30 | * `metaflac', a command-line program for viewing and editing FLAC | ||
31 | metadata | ||
32 | * player plugins for XMMS and Winamp | ||
33 | * user and API documentation | ||
34 | |||
35 | The libraries (libFLAC, libFLAC++, libOggFLAC, and libOggFLAC++) are | ||
36 | licensed under Xiph.org's BSD-like license (see COPYING.Xiph). All other | ||
37 | programs and plugins are licensed under the GNU General Public License | ||
38 | (see COPYING.GPL). The documentation is licensed under the GNU Free | ||
39 | Documentation License (see COPYING.FDL). | ||
40 | |||
41 | |||
42 | =============================================================================== | ||
43 | FLAC - 1.1.2 - Contents | ||
44 | =============================================================================== | ||
45 | |||
46 | - Introduction | ||
47 | - Prerequisites | ||
48 | - Building in a GNU environment | ||
49 | - Building with Makefile.lite | ||
50 | - Building with MSVC | ||
51 | - Building on Mac OS X | ||
52 | - Note to embedded developers | ||
53 | |||
54 | |||
55 | =============================================================================== | ||
56 | Introduction | ||
57 | =============================================================================== | ||
58 | |||
59 | This is the source release for the FLAC project. See | ||
60 | |||
61 | doc/html/index.html | ||
62 | |||
63 | for full documentation. | ||
64 | |||
65 | A brief description of the directory tree: | ||
66 | |||
67 | doc/ the HTML documentation | ||
68 | flac.pbproj/ the Mac OS X Project Builder project | ||
69 | include/ public include files for libFLAC and libFLAC++ | ||
70 | man/ the man page for `flac' | ||
71 | src/ the source code and private headers | ||
72 | test/ the test scripts | ||
73 | |||
74 | |||
75 | =============================================================================== | ||
76 | Prerequisites | ||
77 | =============================================================================== | ||
78 | |||
79 | To build FLAC with support for Ogg FLAC you must have built and installed | ||
80 | libogg according to the specific instructions below. You must have | ||
81 | libogg 1.1.2 or greater, or there will be seeking problems with Ogg FLAC. | ||
82 | |||
83 | If you are building on x86 and want the assembly optimizations, you will | ||
84 | need to have NASM >= 0.98.30 installed according to the specific instructions | ||
85 | below. | ||
86 | |||
87 | |||
88 | =============================================================================== | ||
89 | Building in a GNU environment | ||
90 | =============================================================================== | ||
91 | |||
92 | FLAC uses autoconf and libtool for configuring and building. | ||
93 | Better documentation for these will be forthcoming, but in | ||
94 | general, this should work: | ||
95 | |||
96 | ./configure && make && make check && make install | ||
97 | |||
98 | The 'make check' step is optional; omit it to skip all the tests, | ||
99 | which can take several hours and use around 70-80 megs of disk space. | ||
100 | Even though it will stop with an explicit message on any failure, it | ||
101 | does print out a lot of stuff so you might want to capture the output | ||
102 | to a file if you're having a problem. Also, don't run 'make check' | ||
103 | as root because it confuses some of the tests. | ||
104 | |||
105 | NOTE: Despite our best efforts it's entirely possible to have | ||
106 | problems when using older versions of autoconf, automake, or | ||
107 | libtool. If you have the latest versions and still can't get it | ||
108 | to work, see the next section on Makefile.lite. | ||
109 | |||
110 | There are a few FLAC-specific arguments you can give to | ||
111 | `configure': | ||
112 | |||
113 | --enable-debug : Builds everything with debug symbols and some | ||
114 | extra (and more verbose) error checking. | ||
115 | |||
116 | --disable-asm-optimizations : Disables the compilation of the | ||
117 | assembly routines. Many routines have assembly versions for | ||
118 | speed and `configure' is pretty good about knowing what is | ||
119 | supported, but you can use this option to build only from the | ||
120 | C sources. | ||
121 | |||
122 | --enable-sse : If you are building for an x86 CPU that supports | ||
123 | SSE instructions, you can enable some of the faster routines | ||
124 | if your operating system also supports SSE instructions. flac | ||
125 | can tell if the CPU supports the instructions but currently has | ||
126 | no way to test if the OS does, so if it does, you must pass | ||
127 | this argument to configure to use the SSE routines. If flac | ||
128 | crashes when built with this option you will have to go back and | ||
129 | configure without --enable-sse. Note that | ||
130 | --disable-asm-optimizations implies --disable-sse. | ||
131 | |||
132 | --enable-local-xmms-plugin : Installs the FLAC XMMS plugin in | ||
133 | $HOME/.xmms/Plugins, instead of the global XMMS plugin area | ||
134 | (usually /usr/lib/xmms/Input). | ||
135 | |||
136 | --with-ogg= | ||
137 | --with-xmms-prefix= | ||
138 | --with-libiconv-prefix= | ||
139 | Use these if you have these packages but configure can't find them. | ||
140 | |||
141 | If you want to build completely from scratch (i.e. starting with just | ||
142 | configure.in and Makefile.am) you should be able to just run 'autogen.sh' | ||
143 | but make sure and read the comments in that file first. | ||
144 | |||
145 | |||
146 | =============================================================================== | ||
147 | Building with Makefile.lite | ||
148 | =============================================================================== | ||
149 | |||
150 | There is a more lightweight build system for do-it-yourself-ers. | ||
151 | It is also useful if configure isn't working, which may be the | ||
152 | case since lately we've had some problems with different versions | ||
153 | of automake and libtool. The Makefile.lite system should work | ||
154 | on GNU systems with few or no adjustments. | ||
155 | |||
156 | From the top level just 'make -f Makefile.lite'. You can | ||
157 | specify zero or one optional target from 'release', 'debug', | ||
158 | 'test', or 'clean'. The default is 'release'. There is no | ||
159 | 'install' target but everything you need will end up in the | ||
160 | obj/ directory. | ||
161 | |||
162 | If you are not on an x86 system or you don't have nasm, you | ||
163 | may have to change the DEFINES in src/libFLAC/Makefile.lite. If | ||
164 | you don't have nasm, remove -DFLAC__HAS_NASM. If your target is | ||
165 | not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN. | ||
166 | |||
167 | |||
168 | =============================================================================== | ||
169 | Building with MSVC | ||
170 | =============================================================================== | ||
171 | |||
172 | There are now .dsp projects and a master FLAC.dsw workspace to build | ||
173 | all the libraries and executables. | ||
174 | |||
175 | Prerequisite: you must have the Ogg libraries installed as described | ||
176 | later. | ||
177 | |||
178 | Prerequisite: you must have nasm installed, and nasmw.exe must be in | ||
179 | your PATH, or the path to nasmw.exe must be added to the list of | ||
180 | directories for executable files in the MSVC global options. | ||
181 | |||
182 | To build everything, run Developer Studio, do File|Open Workspace, | ||
183 | and open FLAC.dsw. Select "Build | Set active configuration..." | ||
184 | from the menu, then in the dialog, select "All - Win32 Release" (or | ||
185 | Debug if you prefer). Click "Ok" then hit F7 to build. This will build | ||
186 | all libraries both statically (e.g. obj\release\lib\libFLAC_static.lib) | ||
187 | and as DLLs (e.g. obj\release\bin\libFLAC.dll), and it will build all | ||
188 | binaries, statically linked (e.g. obj\release\bin\flac.exe). | ||
189 | |||
190 | Everything will end up in the "obj" directory. DLLs and .exe files | ||
191 | are all that are needed and can be copied to an installation area and | ||
192 | added to the PATH. The plugins have to be copied to their appropriate | ||
193 | place in the player area. For Winamp2 this is <winamp2-dir>\Plugins. | ||
194 | |||
195 | By default the code is configured with Ogg support. Before building FLAC | ||
196 | you will need to get the Ogg source distribution | ||
197 | (see http://xiph.org/ogg/vorbis/download/), build ogg_static.lib (load and | ||
198 | build win32\ogg_static.dsp), copy ogg_static.lib into FLAC's | ||
199 | 'obj\release\lib' directory, and copy the entire include\ogg tree into | ||
200 | FLAC's 'include' directory (so that there is an 'ogg' directory in FLAC's | ||
201 | 'include' directory with the files ogg.h, os_types.h and config_types.h). | ||
202 | |||
203 | |||
204 | =============================================================================== | ||
205 | Building on Mac OS X | ||
206 | =============================================================================== | ||
207 | |||
208 | If you have Fink, the GNU flow above should work. Otherwise, | ||
209 | there is a Project Builder project in the top-level source | ||
210 | directory to build libFLAC and the command-line utilities on | ||
211 | Mac OS X. In a terminal, cd to the top-level directory (the | ||
212 | one that contains this README file) and type: | ||
213 | |||
214 | pbxbuild -alltargets | ||
215 | |||
216 | This will create everything and leave it in the build/ directory. | ||
217 | Don't worry about the rest of the stuff that is in build/ or | ||
218 | the stuff that was already there before building. | ||
219 | |||
220 | The Project Builder project requires that you have libiconv and | ||
221 | libogg in /sw, ala fink. If you don't, you'll need to install | ||
222 | them somewhere and change the path to them in the Library Paths | ||
223 | section of several targets. | ||
224 | |||
225 | It also assumes the CPU supports Altivec instructions. If it does | ||
226 | not, you will also have to add -DFLAC__NO_ASM to the CFLAGS in the | ||
227 | libFLAC target. | ||
228 | |||
229 | There currently is no install procedure; you will have to | ||
230 | manually copy the tools to wherever you need them. | ||
231 | |||
232 | |||
233 | =============================================================================== | ||
234 | Note to embedded developers | ||
235 | =============================================================================== | ||
236 | |||
237 | libFLAC has grown larger over time as more functionality has been | ||
238 | included, but much of it may be unnecessary for a particular embedded | ||
239 | implementation. Unused parts may be pruned by some simple editing of | ||
240 | configure.in and src/libFLAC/Makefile.am; the following dependency | ||
241 | graph shows which modules may be pruned without breaking things | ||
242 | further down: | ||
243 | |||
244 | file_encoder.h | ||
245 | stream_encoder.h | ||
246 | format.h | ||
247 | |||
248 | file_decoder.h | ||
249 | seekable_stream_decoder.h | ||
250 | stream_decoder.h | ||
251 | format.h | ||
252 | |||
253 | metadata.h | ||
254 | format.h | ||
255 | |||
256 | There is a section dedicated to embedded use in the libFLAC API | ||
257 | HTML documentation (see doc/html/api/index.html). | ||