1<!--- 2/* FLAC - Free Lossless Audio Codec 3 * Copyright (C) 2001-2009 Josh Coalson 4 * Copyright (C) 2011-2022 Xiph.Org Foundation 5 * 6 * This file is part the FLAC project. FLAC is comprised of several 7 * components distributed under different licenses. The codec libraries 8 * are distributed under Xiph.Org's BSD-like license (see the file 9 * COPYING.Xiph in this distribution). All other programs, libraries, and 10 * plugins are distributed under the LGPL or GPL (see COPYING.LGPL and 11 * COPYING.GPL). The documentation is distributed under the Gnu FDL (see 12 * COPYING.FDL). Each file in the FLAC distribution contains at the top the 13 * terms under which it may be distributed. 14 * 15 * Since this particular file is relevant to all components of FLAC, 16 * it may be distributed under the Xiph.Org license, which is the least 17 * restrictive of those mentioned above. See the file COPYING.Xiph in this 18 * distribution. 19 */ 20---> 21 22# Free Lossless Audio Codec (FLAC) 23 24FLAC is open source software that can reduce the amount of storage space 25needed to store digital audio signals without needing to remove 26information in doing so. 27 28The files read and produced by this software are called FLAC files. As 29these files (which follow the [FLAC format](https://xiph.org/flac/format.html)) 30can be read from and written to by other software as well, this software 31is often referred to as the FLAC reference implementation. 32 33FLAC has been developed by volunteers. If you want to help out, see 34CONTRIBUTING.md for more information. 35 36## Components 37 38FLAC is comprised of 39 * libFLAC, a library which implements reference encoders and 40 decoders for native FLAC and Ogg FLAC, and a metadata interface 41 * libFLAC++, a C++ object wrapper library around libFLAC 42 * `flac`, a command-line program for encoding and decoding files 43 * `metaflac`, a command-line program for viewing and editing FLAC 44 metadata 45 * user and API documentation 46 47The libraries (libFLAC, libFLAC++) are licensed under Xiph.org's 48BSD-like license (see COPYING.Xiph). All other programs and plugins are 49licensed under the GNU General Public License (see COPYING.GPL). The 50documentation is licensed under the GNU Free Documentation License 51(see COPYING.FDL). 52 53## Documentation 54 55For documentation of the `flac` and `metaflac` command line tools, see 56the directory man, which contains the files flac.md and metaflac.md 57 58The API documentation is in html and is generated by Doxygen. It can be 59found in the directory doc/html/api. It is included in a release tarball 60and must be build with Doxygen when the source is taken directly from 61git. 62 63The directory examples contains example source code on using libFLAC and 64libFLAC++. 65 66Documentation concerning the FLAC format itself (which can be used to 67create software reading and writing FLAC software independent from 68libFLAC) was included in previous releases, but can now be found on 69https://datatracker.ietf.org/doc/draft-ietf-cellar-flac/ Additionally 70a set of files for conformance testing called the FLAC decoder testbench 71can be found at https://github.com/ietf-wg-cellar/flac-test-files 72 73If you have questions about FLAC that this document does not answer, 74please submit them at the following tracker so this document can be 75improved: 76 77https://github.com/xiph/flac/issues 78 79## Building FLAC 80 81All components of the FLAC project can be build with a variety of 82compilers (including GCC, Clang, Visual Studio, Intel C++ Compiler) on 83many architectures (inluding x86, x86_64, ARMv7, ARMv8 and PowerPC) 84for many different operating systems. 85 86To do this, FLAC provides two build systems: one using GNU's autotools 87and one with CMake. Both differ slighly in configuration options, but 88should be considered equivalent for most use cases. 89 90FLAC used to provide files specifically for building with Visual Studio, 91but these have been removed in favor of using CMake. 92 93## Building with CMake 94 95CMake is a cross-platform build system. FLAC can be built on Windows, 96Linux, Mac OS X using CMake. 97 98You can use either CMake's CLI or GUI. We recommend you to have a 99separate build folder outside the repository in order to not spoil it 100with generated files. It is possible however to do a so-called in-tree 101build, in that case /path/to/flac-build in the following examples is 102equal to /path/to/flac-source. 103 104### CMake CLI 105 106Go to your build folder and run something like this: 107 108``` 109/path/to/flac-build$ cmake /path/to/flac-source 110``` 111 112or e.g. in Windows shell 113 114``` 115C:\path\to\flac-build> cmake \path\to\flac-source 116``` 117 118(provided that cmake is in your %PATH% variable) 119 120That will generate build scripts for the default build system (e.g. 121Makefiles for UNIX). After that you start build with a command like 122this: 123 124``` 125/path/to/flac-build$ make 126``` 127 128And afterwards you can run tests or install the built libraries and 129headers 130 131``` 132/path/to/flac-build$ make test 133/path/to/flac-build$ make install 134``` 135 136If you want use a build system other than default add -G flag to cmake, 137e.g.: 138 139``` 140/path/to/flac-build$ cmake /path/to/flac-source -GNinja 141/path/to/flac-build$ ninja 142``` 143 144or: 145 146``` 147/path/to/flac-build$ cmake /path/to/flac-source -GXcode 148``` 149 150Use cmake --help to see the list of available generators. 151 152By default CMake will search for OGG. If CMake fails to find it you can 153help CMake by specifying the exact path: 154 155``` 156/path/to/flac-build$ cmake /path/to/flac-source -DOGG_ROOT=/path/to/ogg 157``` 158 159If you would like CMake to build OGG alongside FLAC, you can place the 160ogg sources directly in the flac source directory as a subdirectory with 161the name ogg, for example: 162 163``` 164/path/to/flac-source/ogg 165``` 166 167If you don't want to build flac with OGG support you can tell CMake not 168to look for OGG: 169 170``` 171/path/to/flac-build$ cmake /path/to/flac-source -DWITH_OGG=OFF 172``` 173 174Other FLAC's options (e.g. building C++ lib or docs) can also be put to 175cmake through -D flag. If you want to know what options are available, 176use -LH: 177 178``` 179/path/to/flac-build$ cmake /path/to/flac-source -LH 180``` 181 182### CMake GUI (for Visual Studio) 183It is likely that you would prefer to use the CMake GUI if you use 184Visual Studio to build FLAC. It's in essence the same process as 185building using CLI. 186 187Open cmake-gui. In the window select a source directory (the 188repository's root), a build directory (some other directory outside the 189repository). Then press button "Configure". CMake will ask you which 190build system you prefer. Choose that version of Visual Studio which you 191have on your system, choose whether you want to build for Win32 or x64. 192Press OK. 193 194After CMake finishes you can change the configuration to your liking and 195if you change anything, run Configure again. With the "Generate" button, 196CMake creates Visual Studio files, which can be opened from Visual 197Studio. With the button "Open Project" CMake will launch Visual Studio 198and open the generated solution. You can use the project files as usual 199but remember that they were generated by CMake. That means that your 200changes (e.g. some additional compile flags) will be lost when you run 201CMake next time. 202 203CMake searches by default for OGG on your system and returns an error 204if it cannot find it. If you want to build OGG alongside FLAC, you can 205download the OGG sources and extract them in a subdirectory of the FLAC 206source directory with the name ogg (i.e. /path/to/flac-source/ogg) 207before running CMake. If you don't want to build FLAC with OGG support, 208untick the box following WITH_OGG flag in the list of variables in 209cmake-gui window and run "Configure" again. 210 211If CMake fails to find MSVC compiler then running cmake-gui from MS 212Developer comand prompt should help. 213 214## Building with GNU autotools 215 216FLAC uses autoconf and libtool for configuring and building. To 217configure a build, open a commmand line/terminal and run `./configure` 218You can provide options to this command, which are listed by running 219`./configure --help`. 220 221In case the configure script is not present (for example when building 222from git and not from a release tarball), it can be generated by running 223`./autogen.sh`. This may require a libtool development package though. 224 225After configuration, build with `make`, verify the build with 226`make check` and install with `make install`. Installation might require 227administrator priviledged, i.e. `sudo make install`. 228 229The 'make check' step is optional; omit it to skip all the tests, which 230can take about an hour to complete. Even though it will stop with an 231explicit message on any failure, it does print out a lot of stuff so you 232might want to capture the output to a file if you're having a problem. 233Also, don't run 'make check' as root because it confuses some of the 234tests. 235 236Summarizing: 237 238``` 239./configure 240make && make check 241sudo make install 242``` 243 244## Note to embedded developers 245 246libFLAC has grown larger over time as more functionality has been 247included, but much of it may be unnecessary for a particular embedded 248implementation. Unused parts may be pruned by some simple editing of 249configure.ac and src/libFLAC/Makefile.am; the following dependency 250graph shows which modules may be pruned without breaking things 251further down: 252 253``` 254metadata.h 255 stream_decoder.h 256 format.h 257 258stream_encoder.h 259 stream_decoder.h 260 format.h 261 262stream_decoder.h 263 format.h 264``` 265 266In other words, for pure decoding applications, both the stream encoder 267and metadata editing interfaces can be safely removed. Note that this 268is specific to building the libraries for embedded use. The command line 269tools do not provide such compartmentalization, and require a complete 270libFLAC build to function. 271 272There is a section dedicated to embedded use in the libFLAC API 273HTML documentation (see doc/html/api/index.html). 274 275Also, there are several places in the libFLAC code with comments marked 276with "OPT:" where a #define can be changed to enable code that might be 277faster on a specific platform. Experimenting with these can yield 278faster binaries. 279