diff --git a/.gitignore b/.gitignore index 9e07eaf3..3cc7c5d5 100644 --- a/.gitignore +++ b/.gitignore @@ -25,7 +25,7 @@ configure depcomp doc/Doxyfile doc/FLAC.tag -doc/html/api/ +doc/api/ examples/c/decode/file/example_c_decode_file examples/c/encode/file/example_c_encode_file examples/cpp/decode/file/example_cpp_decode_file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4c6ae799 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,74 @@ +Thanks for considering contributing to the FLAC project! + +Contributing to FLAC is possible in many ways. Among them are + +- Reporting bugs or other issues at https://github.com/xiph/flac/issues +- Submitting patches at https://github.com/xiph/flac/pulls +- Testing FLAC playing devices and software at + https://wiki.hydrogenaud.io/index.php?title=FLAC_decoder_testbench + +General communication not specific to issues is generally done through +the FLAC mailing lists: + +- For user questions and discussions: + https://lists.xiph.org/mailman/listinfo/flac +- For developer questions and discussions: + https://lists.xiph.org/mailman/listinfo/flac-dev + +## Goals + +Since FLAC is an open-source project, it's important to have a set of +goals that everyone works to. They may change slightly from time to time +but they're a good guideline. Changes should be in line with the goals +and should not attempt to embrace any of the anti-goals. + +**Goals** + +- FLAC should be and stay an open format with an open-source reference + implementation. +- FLAC should be lossless. This seems obvious but lossy compression + seems to creep into every audio codec. This goal also means that flac + should stay archival quality and be truly lossless for all input. + Testing of releases should be thorough. +- FLAC should yield respectable compression, on par or better than other + lossless codecs. +- FLAC should allow at least realtime decoding on even modest hardware. +- FLAC should support fast sample-accurate seeking. +- FLAC should allow gapless playback of consecutive streams. This follows from the lossless goal. +- The FLAC project owes a lot to the many people who have advanced the + audio compression field so freely, and aims also to contribute through + the open-source development of new ideas. + +**Anti-goals** + +- Lossy compression. There are already many suitable lossy formats (Ogg + Vorbis, MP3, etc.). +- Copy prevention, DRM, etc. There is no intention to add any copy + prevention methods. Of course, we can't stop someone from encrypting a + FLAC stream in another container (e.g. the way Apple encrypts AAC in + MP4 with FairPlay), that is the choice of the user. + + +## Contributing patches + +Contributions to FLAC should be licensed with the same license as the +part of the FLAC project the contribution belongs to. These are + +- libFLAC and libFLAC++ are licensed under Xiph.org's + BSD-like license (see COPYING.Xiph), so contributions to these + libraries should also be licensed under this license, otherwise they + cannot be accepted +- the flac and metaflac command line programs are licensed under GPLv2, + see COPYING.GPL +- the helper libraries for flac and metaflac (which are in src/share) + are licensed under varying licenses, see the license preamble for each + file to see how they are licensed + +Patches can be contributed through GitHub as a Pull Request. +Alternatively you can supply patches through the mailing list. + +## Code style + +FLAC does have its own peculiar coding style that does not seem to fit +general categories. You can use `git clang-format` to have your patch +auto-formatted similar to the rest of the code. diff --git a/Makefile.am b/Makefile.am index 392a3c19..ae8cb006 100644 --- a/Makefile.am +++ b/Makefile.am @@ -56,6 +56,7 @@ EXTRA_DIST = \ COPYING.GPL \ COPYING.LGPL \ COPYING.Xiph \ + README.md \ autogen.sh \ config.rpath \ depcomp \ diff --git a/README b/README deleted file mode 100644 index d7cb9382..00000000 --- a/README +++ /dev/null @@ -1,291 +0,0 @@ -/* FLAC - Free Lossless Audio Codec - * Copyright (C) 2001-2009 Josh Coalson - * Copyright (C) 2011-2022 Xiph.Org Foundation - * - * This file is part the FLAC project. FLAC is comprised of several - * components distributed under different 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 LGPL or GPL (see COPYING.LGPL and - * 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 is an Open Source lossless audio codec developed by Josh Coalson from 2001 -to 2009. From 2012 to 2021 it was maintained by Erik de Castro Lopo. It continues -to be maintained by various volunteers under the auspices of the Xiph.org Foundation. - -FLAC is comprised of - * `libFLAC', a library which implements reference encoders and - decoders for native FLAC and Ogg FLAC, and a metadata interface - * `libFLAC++', a C++ object wrapper library around libFLAC - * `flac', a command-line program for encoding and decoding files - * `metaflac', a command-line program for viewing and editing FLAC - metadata - * player plugin for XMMS - * user and API documentation - -The libraries (libFLAC, libFLAC++) 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.3.4 - Contents -=============================================================================== - -- Introduction -- Prerequisites -- Note to embedded developers -- Building in a GNU environment -- Building with MSVC -- Building on Mac OS X -- Building with CMake - - -=============================================================================== -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 - examples/ example programs demonstrating the use of libFLAC and libFLAC++ - include/ public include files for libFLAC and libFLAC++ - man/ the man pages for `flac' and `metaflac' - src/ the source code and private headers - test/ the test scripts - -If you have questions about building FLAC that this document does not answer, -please submit them at the following tracker so this document can be improved: - - https://sourceforge.net/p/flac/support-requests/ - - -=============================================================================== -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. - - -=============================================================================== -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.ac and src/libFLAC/Makefile.am; the following dependency -graph shows which modules may be pruned without breaking things -further down: - -metadata.h - stream_decoder.h - format.h - -stream_encoder.h - stream_decoder.h - format.h - -stream_decoder.h - format.h - -In other words, for pure decoding applications, both the stream encoder -and metadata editing interfaces can be safely removed. - -There is a section dedicated to embedded use in the libFLAC API -HTML documentation (see doc/html/api/index.html). - -Also, there are several places in the libFLAC code with comments marked -with "OPT:" where a #define can be changed to enable code that might be -faster on a specific platform. Experimenting with these can yield faster -binaries. - - -=============================================================================== -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. May be necessary for building on OS X (Intel). - ---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.ac 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 Microsoft Visual Studio -=============================================================================== - -FLAC used to provide Visual Studio specific build files, but as this was rather -hard to maintain, CMake has replaced these files. See Building with CMake for -more information. - -=============================================================================== -Building on Mac OS X -=============================================================================== - -If you have Fink or a recent version of OS X with the proper autotools, -the GNU flow above should work. - - -=============================================================================== -Building with CMake -=============================================================================== - -CMake is a cross-platform build system. FLAC can be built on Windows, Linux, Mac -OS X using CMake. - -You can use either CMake's CLI or GUI. We recommend you to have a separate build -folder outside the repository in order to not spoil it with generated files. It is -possible however to do a so-called in-tree build, in that case /path/to/flac-build -in the following examples is equal to /path/to/flac-source. - -CLI ---- - Go to your build folder and run something like this: - - /path/to/flac-build$ cmake /path/to/flac-source - - or e.g. in Windows shell - - C:\path\to\flac-build> cmake \path\to\flac-source - (provided that cmake is in your %PATH% variable) - - That will generate build scripts for the default build system (e.g. Makefiles - for UNIX). After that you start build with a command like this: - - /path/to/flac-build$ make - - And afterwards you can run tests or install the built libraries and headers - - /path/to/flac-build$ make test - /path/to/flac-build$ make install - - If you want use a build system other than default add -G flag to cmake, e.g.: - - /path/to/flac-build$ cmake /path/to/flac-source -GNinja - /path/to/flac-build$ ninja - - or: - - /path/to/flac-build$ cmake /path/to/flac-source -GXcode - - Use cmake --help to see the list of available generators. - - By default CMake will search for OGG. If CMake fails to find it you can help - CMake by specifying the exact path: - - /path/to/flac-build$ cmake /path/to/flac-source -DOGG_ROOT=/path/to/ogg - - If you would like CMake to build OGG alongside FLAC, you can place the ogg - sources directly in the flac source directory as a subdirectory with the name - ogg, for example - - /path/to/flac-source/ogg - - If you don't want to build flac with OGG support you can tell CMake not to - look for OGG: - - /path/to/flac-build$ cmake /path/to/flac-source -DWITH_OGG=OFF - - Other FLAC's options (e.g. building C++ lib or docs) can also be put to cmake - through -D flag. - -GUI ---- - It is likely that you would prefer to use the CMake GUI if you use Visual - Studio to build FLAC. It's in essence the same process as building using CLI. - - Open cmake-gui. In the window select a source directory (the repository's - root), a build directory (some other directory outside the repository). Then - press button "Configure". CMake will ask you which build system you prefer. - Choose that version of Visual Studio which you have on your system, choose - whether you want to build for Win32 or x64. Press OK. After CMake finishes - you can change the configuration to your liking and if you change anything, - run Configure again. With the "Generate" button, CMake creates Visual Studio - files, which can be opened from Visual Studio. With the button "Open Project" - CMake will launch Visual Studio and open the generated solution. You can use - the project files as usual but remember that they were generated by CMake. - That means that your changes (e.g. some additional compile flags) will be - lost when you run CMake next time. - - CMake searches by default for OGG on your system and returns an error if it - cannot find it. If you want to build OGG alongside FLAC, you can download the - OGG sources and extract them in a subdirectory of the FLAC source directory - with the name ogg (i.e. /path/to/flac-source/ogg) before running CMake. If - you don't want to build FLAC with OGG support, untick the box following - WITH_OGG flag in the list of variables in cmake-gui window and run - "Configure" again. - - If CMake fails to find MSVC compiler then running cmake-gui from MS Developer - comand prompt should help. diff --git a/README.md b/README.md new file mode 100644 index 00000000..1c616434 --- /dev/null +++ b/README.md @@ -0,0 +1,279 @@ + + +# Free Lossless Audio Codec (FLAC) + +FLAC is open source software that can reduce the amount of storage space +needed to store digital audio signals without needing to remove +information in doing so. + +The files read and produced by this software are called FLAC files. As +these files (which follow the [FLAC format](https://xiph.org/flac/format.html)) +can be read from and written to by other software as well, this software +is often referred to as the FLAC reference implementation. + +FLAC has been developed by volunteers. If you want to help out, see +CONTRIBUTING.md for more information. + +## Components + +FLAC is comprised of + * libFLAC, a library which implements reference encoders and + decoders for native FLAC and Ogg FLAC, and a metadata interface + * libFLAC++, a C++ object wrapper library around libFLAC + * `flac`, a command-line program for encoding and decoding files + * `metaflac`, a command-line program for viewing and editing FLAC + metadata + * player plugin for XMMS + * user and API documentation + +The libraries (libFLAC, libFLAC++) 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). + +## Documentation + +For documentation of the `flac` and `metaflac` command line tools, see +the directory man, which contains the files flac.md and metaflac.md + +The API documentation is in html and is generated by Doxygen. It can be +found in the directory doc/html/api. It is included in a release tarball +and must be build with Doxygen when the source is taken directly from +git. + +The directory examples contains example source code on using libFLAC and +libFLAC++. + +Documentation concerning the FLAC format itself (which can be used to +create software reading and writing FLAC software independent from +libFLAC) was included in previous releases, but can now be found on +https://datatracker.ietf.org/doc/draft-ietf-cellar-flac/ Additionally +a set of files for conformance testing called the FLAC decoder testbench +can be found at https://github.com/ietf-wg-cellar/flac-test-files + +If you have questions about FLAC that this document does not answer, +please submit them at the following tracker so this document can be +improved: + +https://github.com/xiph/flac/issues + +## Building FLAC + +All components of the FLAC project can be build with a variety of +compilers (including GCC, Clang, Visual Studio, Intel C++ Compiler) on +many architectures (inluding x86, x86_64, ARMv7, ARMv8 and PowerPC) +for many different operating systems. + +To do this, FLAC provides two build systems: one using GNU's autotools +and one with CMake. Both differ slighly in configuration options, but +should be considered equivalent for most use cases. + +FLAC used to provide files specifically for building with Visual Studio, +but these have been removed in favor of using CMake. + +## Building with CMake + +CMake is a cross-platform build system. FLAC can be built on Windows, +Linux, Mac OS X using CMake. + +You can use either CMake's CLI or GUI. We recommend you to have a +separate build folder outside the repository in order to not spoil it +with generated files. It is possible however to do a so-called in-tree +build, in that case /path/to/flac-build in the following examples is +equal to /path/to/flac-source. + +### CMake CLI + +Go to your build folder and run something like this: + +``` +/path/to/flac-build$ cmake /path/to/flac-source +``` + +or e.g. in Windows shell + +``` +C:\path\to\flac-build> cmake \path\to\flac-source +``` + +(provided that cmake is in your %PATH% variable) + +That will generate build scripts for the default build system (e.g. +Makefiles for UNIX). After that you start build with a command like +this: + +``` +/path/to/flac-build$ make +``` + +And afterwards you can run tests or install the built libraries and +headers + +``` +/path/to/flac-build$ make test +/path/to/flac-build$ make install +``` + +If you want use a build system other than default add -G flag to cmake, +e.g.: + +``` +/path/to/flac-build$ cmake /path/to/flac-source -GNinja +/path/to/flac-build$ ninja +``` + +or: + +``` +/path/to/flac-build$ cmake /path/to/flac-source -GXcode +``` + +Use cmake --help to see the list of available generators. + +By default CMake will search for OGG. If CMake fails to find it you can +help CMake by specifying the exact path: + +``` +/path/to/flac-build$ cmake /path/to/flac-source -DOGG_ROOT=/path/to/ogg +``` + +If you would like CMake to build OGG alongside FLAC, you can place the +ogg sources directly in the flac source directory as a subdirectory with +the name ogg, for example: + +``` +/path/to/flac-source/ogg +``` + +If you don't want to build flac with OGG support you can tell CMake not +to look for OGG: + +``` +/path/to/flac-build$ cmake /path/to/flac-source -DWITH_OGG=OFF +``` + +Other FLAC's options (e.g. building C++ lib or docs) can also be put to +cmake through -D flag. If you want to know what options are available, +use -LH: + +``` +/path/to/flac-build$ cmake /path/to/flac-source -LH +``` + +### CMake GUI (for Visual Studio) +It is likely that you would prefer to use the CMake GUI if you use +Visual Studio to build FLAC. It's in essence the same process as +building using CLI. + +Open cmake-gui. In the window select a source directory (the +repository's root), a build directory (some other directory outside the +repository). Then press button "Configure". CMake will ask you which +build system you prefer. Choose that version of Visual Studio which you +have on your system, choose whether you want to build for Win32 or x64. +Press OK. + +After CMake finishes you can change the configuration to your liking and +if you change anything, run Configure again. With the "Generate" button, +CMake creates Visual Studio files, which can be opened from Visual +Studio. With the button "Open Project" CMake will launch Visual Studio +and open the generated solution. You can use the project files as usual +but remember that they were generated by CMake. That means that your +changes (e.g. some additional compile flags) will be lost when you run +CMake next time. + +CMake searches by default for OGG on your system and returns an error +if it cannot find it. If you want to build OGG alongside FLAC, you can +download the OGG sources and extract them in a subdirectory of the FLAC +source directory with the name ogg (i.e. /path/to/flac-source/ogg) +before running CMake. If you don't want to build FLAC with OGG support, +untick the box following WITH_OGG flag in the list of variables in +cmake-gui window and run "Configure" again. + +If CMake fails to find MSVC compiler then running cmake-gui from MS +Developer comand prompt should help. + +## Building with GNU autotools + +FLAC uses autoconf and libtool for configuring and building. To +configure a build, open a commmand line/terminal and run `./configure` +You can provide options to this command, which are listed by running +`./configure --help`. + +In case the configure script is not present (for example when building +from git and not from a release tarball), it can be generated by running +`./autogen.sh`. This may require a libtool development package though. + +After configuration, build with `make`, verify the build with +`make check` and install with `make install`. Installation might require +administrator priviledged, i.e. `sudo make install`. + +The 'make check' step is optional; omit it to skip all the tests, which +can take about an hour to complete. 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. + +Summarizing: + +``` +./configure +make && make check +sudo make install +``` + +## 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.ac and src/libFLAC/Makefile.am; the following dependency +graph shows which modules may be pruned without breaking things +further down: + +``` +metadata.h + stream_decoder.h + format.h + +stream_encoder.h + stream_decoder.h + format.h + +stream_decoder.h + format.h +``` + +In other words, for pure decoding applications, both the stream encoder +and metadata editing interfaces can be safely removed. Note that this +is specific to building the libraries for embedded use. The command line +tools do not provide such compartmentalization, and require a complete +libFLAC build to function. + +There is a section dedicated to embedded use in the libFLAC API +HTML documentation (see doc/html/api/index.html). + +Also, there are several places in the libFLAC code with comments marked +with "OPT:" where a #define can be changed to enable code that might be +faster on a specific platform. Experimenting with these can yield +faster binaries. diff --git a/configure.ac b/configure.ac index 3a20cdb3..2ef1f925 100644 --- a/configure.ac +++ b/configure.ac @@ -659,8 +659,7 @@ AC_CONFIG_FILES([ \ include/test_libs_common/Makefile \ doc/Doxyfile \ doc/Makefile \ - doc/html/Makefile \ - doc/html/images/Makefile \ + doc/images/Makefile \ m4/Makefile \ man/Makefile \ test/common.sh \ diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 1f001707..df1f2775 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -12,43 +12,15 @@ if (NOT BUILD_DOXYGEN) return() endif() -set(DOXYGEN_HTML_FOOTER doxygen.footer.html) -set(DOXYGEN_GENERATE_TAGFILE FLAC.tag) +set(top_srcdir "${PROJECT_SOURCE_DIR}") +configure_file(Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY) -if(CMAKE_VERSION VERSION_LESS 3.12) - doxygen_add_docs(FLAC-doxygen - ALL - "${PROJECT_SOURCE_DIR}/include/FLAC" - "${PROJECT_SOURCE_DIR}/include/FLAC++") -else() - doxygen_add_docs(FLAC-doxygen - "${PROJECT_SOURCE_DIR}/include/FLAC" - "${PROJECT_SOURCE_DIR}/include/FLAC++") - install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/html/" - DESTINATION "${CMAKE_INSTALL_DOCDIR}/html/api") +add_custom_target(FLAC-doxygen ALL + COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Generating API documentation with Doxygen" + VERBATIM ) -endif() - -install(FILES - html/images/logo.svg - html/images/logo130.gif - html/changelog.html - html/developers.html - html/documentation.html - html/documentation_bugs.html - html/documentation_example_code.html - html/documentation_format_overview.html - html/documentation_tools.html - html/documentation_tools_flac.html - html/documentation_tools_metaflac.html - html/faq.html - html/favicon.ico - html/features.html - html/flac.css - html/format.html - html/id.html - html/index.html - html/license.html - html/ogg_mapping.html -DESTINATION "${CMAKE_INSTALL_DOCDIR}/html") +install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/api/" + DESTINATION "${CMAKE_INSTALL_DOCDIR}/api") diff --git a/doc/Makefile.am b/doc/Makefile.am index 8cc79c98..cb0df6f8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -16,26 +16,26 @@ # with this program; if not, write to the Free Software Foundation, Inc., # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. -SUBDIRS = . html +SUBDIRS = . images if FLaC__HAS_DOXYGEN all-local: Doxyfile FLAC.tag: Doxyfile doxygen Doxyfile - rm -rf html/api - mv doxytmp/html html/api + rm -rf api + mv doxytmp/html api rm -rf doxytmp else FLAC.tag: touch $@ - mkdir -p html/api + mkdir -p api endif doc_DATA = \ FLAC.tag -EXTRA_DIST = Doxyfile.in doxygen.footer.html doxygen.header.html \ +EXTRA_DIST = Doxyfile.in doxygen.footer.html \ isoflac.txt $(doc_DATA) CMakeLists.txt distclean-local: - rm -rf FLAC.tag html/api doxytmp + rm -rf FLAC.tag api doxytmp diff --git a/doc/doxygen.header.html b/doc/doxygen.header.html deleted file mode 100644 index 4e917936..00000000 --- a/doc/doxygen.header.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - - - - diff --git a/doc/html/Makefile.am b/doc/html/Makefile.am deleted file mode 100644 index e5e1f952..00000000 --- a/doc/html/Makefile.am +++ /dev/null @@ -1,50 +0,0 @@ -# FLAC - Free Lossless Audio Codec -# Copyright (C) 2001-2009 Josh Coalson -# Copyright (C) 2011-2022 Xiph.Org Foundation -# -# This file is part the FLAC project. FLAC is comprised of several -# components distributed under different 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. - -SUBDIRS = images - -html_DATA = \ - developers.html \ - documentation.html \ - documentation_bugs.html \ - documentation_example_code.html \ - documentation_format_overview.html \ - documentation_tools.html \ - faq.html \ - favicon.ico \ - features.html \ - flac.css \ - format.html \ - id.html \ - index.html \ - license.html \ - ogg_mapping.html - -EXTRA_DIST = $(html_DATA) api - -if FLaC__HAS_DOXYGEN -# The install targets don't copy whole directories so we have to -# handle 'api/' specially: -install-data-local: - $(mkinstalldirs) $(DESTDIR)$(htmldir)/api - (cd $(builddir)/api && $(INSTALL_DATA) * $(DESTDIR)$(htmldir)/api) -uninstall-local: - rm -rf $(DESTDIR)$(htmldir)/api -distclean-local: - -rm -rf api -endif diff --git a/doc/html/developers.html b/doc/html/developers.html deleted file mode 100644 index df768b6f..00000000 --- a/doc/html/developers.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - developers - - - - - - -
- - - -
- -
-
- developers -
-
-
- FLAC is an open source project and we are happy to enlist the help of anyone who wants to contribute, or to help with FLAC support in other programs and devices. The preferred method of communication is the developer mailing list (you must subscribe to post).
-
- FLAC is open to third-party developers who want to add support for FLAC into their programs. All the necessary functionality is contained in the libFLAC libraries which are licensed under Xiph.org's BSD license.
-
- Some pointers to developer documentation and code:
- -
- -
- -
- -
-
- goals -
-
-
- Since FLAC is an open-source project, it's important to have a set of goals that everyone works to. They may change slightly from time to time but they're a good guideline. Changes should be in line with the goals and should not attempt to embrace any of the anti-goals.
-
- Goals - - Anti-goals
- -
- -
- - - - - - diff --git a/doc/html/documentation.html b/doc/html/documentation.html deleted file mode 100644 index 985d0aa9..00000000 --- a/doc/html/documentation.html +++ /dev/null @@ -1,91 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - documentation - - - - - - -
- - - -
- -
-
- documentation -
-
-
- FLAC is a general purpose audio format supported by many programs. Most of the documentation here is about the FLAC format itself and the tools we provide, but there is also information on using other programs that support FLAC. - - In more detail: - - For developers who want to add FLAC support to their programs: - - Keep in mind that the online version of the documentation will always apply to the latest release. For older releases, check the documentation included with the release package. -
- -
- - - - - - diff --git a/doc/html/documentation_bugs.html b/doc/html/documentation_bugs.html deleted file mode 100644 index 21caa49c..00000000 --- a/doc/html/documentation_bugs.html +++ /dev/null @@ -1,85 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - documentation - - - - - - -
- - - -
- -
-
- known bugs -
-
-
- The following are major known bugs in the current (1.3.4) release: - -
- -
- -
- -
-
- reporting bugs -
-
-
- To report a bug, please go to the FLAC bug tracker (or appropriately the feature request tracker, patch page, or support page).
-
- First check that there is not already an existing request. If you do submit a new request, make sure and provide an email contact and use the Monitor feature. -
- -
- - - - - - diff --git a/doc/html/documentation_example_code.html b/doc/html/documentation_example_code.html deleted file mode 100644 index 189cd349..00000000 --- a/doc/html/documentation_example_code.html +++ /dev/null @@ -1,67 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - developers - - - - - - -
- - - -
- -
-
- example code -
-
-
- The FLAC source code has several small example programs that demonstrate how to use the libraries. The source is available on the download page, or can be checked out from git. The examples complement the API documentation.
-
- Currently the examples show how to encode WAV files to FLAC and vice-versa using both libFLAC and libFLAC++. Over time we'll be adding more examples. -
- -
- - - - - - diff --git a/doc/html/documentation_format_overview.html b/doc/html/documentation_format_overview.html deleted file mode 100644 index 9f457073..00000000 --- a/doc/html/documentation_format_overview.html +++ /dev/null @@ -1,116 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - documentation - - - - - - -
- - - -
- -
-
- format -
-
-
- The basic structure of a FLAC stream is: - - The first four bytes are to identify the FLAC stream. The metadata that follows contains all the information about the stream except for the audio data itself. After the metadata comes the encoded audio data.
-
- METADATA
-
- FLAC defines several types of metadata blocks (see the format page for the complete list). Metadata blocks can be any length and new ones can be defined. A decoder is allowed to skip any metadata types it does not understand. Only one is mandatory: the STREAMINFO block. This block has information like the sample rate, number of channels, etc., and data that can help the decoder manage its buffers, like the minimum and maximum data rate and minimum and maximum block size. Also included in the STREAMINFO block is the MD5 signature of the unencoded audio data. This is useful for checking an entire stream for transmission errors.
-
- Other blocks allow for padding, seek tables, tags, cuesheets, and application-specific data. There are flac options for adding PADDING blocks or specifying seek points. FLAC does not require seek points for seeking but they can speed up seeks, or be used for cueing in editing applications.
-
- Also, if you have a need of a custom metadata block, you can define your own and request an ID here. Then you can reserve a PADDING block of the correct size when encoding, and overwrite the padding block with your APPLICATION block after encoding. The resulting stream will be FLAC compatible; decoders that are aware of your metadata can use it and the rest will safely ignore it.
-
- AUDIO DATA
-
- After the metadata comes the encoded audio data. Audio data and metadata are not interleaved. Like most audio codecs, FLAC splits the unencoded audio data into blocks, and encodes each block separately. The encoded block is packed into a frame and appended to the stream. The reference encoder uses a single block size for the whole stream but the FLAC format does not require it.
-
- BLOCKING
-
- The block size is an important parameter to encoding. If it is too small, the frame overhead will lower the compression. If it is too large, the modeling stage of the compressor will not be able to generate an efficient model. Understanding FLAC's modeling will help you to improve compression for some kinds of input by varying the block size. In the most general case, using linear prediction on 44.1kHz audio, the optimal block size will be between 2-6 ksamples. flac defaults to a block size of 4096 in this case. Using the fast fixed predictors, a smaller block size is usually preferable because of the smaller frame header.
-
- INTER-CHANNEL DECORRELATION
-
- In the case of stereo input, once the data is blocked it is optionally passed through an inter-channel decorrelation stage. The left and right channels are converted to center and side channels through the following transformation: mid = (left + right) / 2, side = left - right. This is a lossless process, unlike joint stereo. For normal CD audio this can result in significant extra compression. flac has two options for this: -m always compresses both the left-right and mid-side versions of the block and takes the smallest frame, and -M, which adaptively switches between left-right and mid-side.
-
- MODELING
-
- In the next stage, the encoder tries to approximate the signal with a function in such a way that when the approximation is subtracted, the result (called the residual, residue, or error) requires fewer bits-per-sample to encode. The function's parameters also have to be transmitted so they should not be so complex as to eat up the savings. FLAC has two methods of forming approximations: 1) fitting a simple polynomial to the signal; and 2) general linear predictive coding (LPC). I will not go into the details here, only some generalities that involve the encoding options.
-
- First, fixed polynomial prediction (specified with -l 0) is much faster, but less accurate than LPC. The higher the maximum LPC order, the slower, but more accurate, the model will be. However, there are diminishing returns with increasing orders. Also, at some point (usually around order 9) the part of the encoder that guesses what is the best order to use will start to get it wrong and the compression will actually decrease slightly; at that point you will have to you will have to use the exhaustive search option -e to overcome this, which is significantly slower.
-
- Second, the parameters for the fixed predictors can be transmitted in 3 bits whereas the parameters for the LPC model depend on the bits-per-sample and LPC order. This means the frame header length varies depending on the method and order you choose and can affect the optimal block size.
-
- RESIDUAL CODING
-
- Once the model is generated, the encoder subracts the approximation from the original signal to get the residual (error) signal. The error signal is then losslessly coded. To do this, FLAC takes advantage of the fact that the error signal generally has a Laplacian (two-sided geometric) distribution, and that there are a set of special Huffman codes called Rice codes that can be used to efficiently encode these kind of signals quickly and without needing a dictionary.
-
- Rice coding involves finding a single parameter that matches a signal's distribution, then using that parameter to generate the codes. As the distribution changes, the optimal parameter changes, so FLAC supports a method that allows the parameter to change as needed. The residual can be broken into several contexts or partitions, each with it's own Rice parameter. flac allows you to specify how the partitioning is done with the -r option. The residual can be broken into 2^n partitions, by using the option -r n,n. The parameter n is called the partition order. Furthermore, the encoder can be made to search through m to n partition orders, taking the best one, by specifying -r m,n. Generally, the choice of n does not affect encoding speed but m,n does. The larger the difference between m and n, the more time it will take the encoder to search for the best order. The block size will also affect the optimal order.
-
- FRAMING
-
- An audio frame is preceded by a frame header and trailed by a frame footer. The header starts with a sync code, and contains the minimum information necessary for a decoder to play the stream, like sample rate, bits per sample, etc. It also contains the block or sample number and an 8-bit CRC of the frame header. The sync code, frame header CRC, and block/sample number allow resynchronization and seeking even in the absence of seek points. The frame footer contains a 16-bit CRC of the entire encoded frame for error detection. If the reference decoder detects a CRC error it will generate a silent block.
-
- MISCELLANEOUS
-
- As a convenience, the reference decoder knows how to skip ID3v1 and ID3v2 tags. Note however that the FLAC specification does not require compliant implementations to support ID3 in any form and their use is strongly discouraged.
-
- flac has a verify option -V that verifies the output while encoding. With this option, a decoder is run in parallel to the encoder and its output is compared against the original input. If a difference is found flac will stop with an error. -
- -
- - - - - - diff --git a/doc/html/documentation_tools.html b/doc/html/documentation_tools.html deleted file mode 100644 index 8c9f32c2..00000000 --- a/doc/html/documentation_tools.html +++ /dev/null @@ -1,77 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - documentation - - - - - - -
- - - -
- -
-
- tools -
-
-
- FLAC is a general purpose audio format supported by many programs, but in this section we are concentrating on just the official tools provided by the FLAC project: - - Other resources: - -
- See Getting FLAC for instructions on downloading and installing the official FLAC tools, or Using FLAC for instructions and guides on playing FLAC files, ripping CDs to FLAC, etc. -
- -
- - - - - - diff --git a/doc/html/faq.html b/doc/html/faq.html deleted file mode 100644 index ace2fa72..00000000 --- a/doc/html/faq.html +++ /dev/null @@ -1,390 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - faq - - - - - - -
- - - -
- -
-
- faq -
-
-
- General - - Tools - - API - - Project - - -

- General -

- - What is FLAC?
-
- FLAC stands for Free Lossless Audio Codec, an audio format similar to MP3, but lossless, meaning that audio is compressed in FLAC without any loss in quality. This is similar to how Zip works, except with FLAC you will get much better compression because it is designed specifically for audio, and you can play back compressed FLAC files in your favorite player (or your car or home stereo, see supported devices) just like you would an MP3 file.
-
- For more details, see What is FLAC?
-
- I have a FLAC file, how do I play it?
- How can I create FLAC files?
-
- See Using FLAC or a list of hardware that supports FLAC.
-
- What licensing applies to the FLAC format and software?
-
- See the license page.
-
- What kinds of tags does FLAC support?
-
- FLAC has it's own native tagging system which is identical to that of Vorbis. They are called alternately "FLAC tags" and "Vorbis comments". It is the only tagging system required and guaranteed to be supported by FLAC implementations.
-
- Out of convenience, the reference decoder knows how to skip ID3 tags so that they don't interfere with decoding. But you should not expect any tags beside FLAC tags to be supported in applications; some implementations may not even be able to decode a FLAC file with ID3 tags.
-
- What software support FLAC?
-
- This list is so large now it is difficult to maintain and keep up-to-date. For a partial list of open-source software that supports FLAC, see the software section of the links page. For a partial list of the most popular software used to encode, decode, play, tag, and rip FLAC files, see the download page.
-
- How can I play FLAC in Windows Media Player?
-
- The easiest way is to use the Xiph.org Directshow Filters, download them here
-
- What hardware products support FLAC?
-
- See the hardware section of the links page.
-
- What is the difference between (native) FLAC and Ogg FLAC?
-
- You can think of an audio codec as having two layers. The inside layer is the raw compressed data, and the outside layer is the "container" or "transport layer" that splits and arranges the compressed data in pieces so it can be seeked through, edited, etc.
-
- "Native" FLAC is the compressed FLAC data stored in a very minimalist container, designed to be very efficient at storing single audio streams.
-
- Ogg FLAC is the compressed FLAC data stored in an Ogg container. Ogg is a much more powerful transport layer that enables mixing several kinds of different streams (audio, data, metadata, etc). The overhead is slightly higher than with native FLAC.
-
- In either case, the compressed FLAC data is the same and one can be converted to the other without re-encoding.
-
- Which should I use, (native) FLAC or Ogg FLAC?
-
- The short answer right now is probably "native FLAC". If all you are doing is compressing audio to be played back later, native FLAC will do everything you need, is more widely supported, and will yield smaller files. If you plan to edit the compressed audio, or want to multiplex the audio with video later in an Ogg container, Ogg FLAC is a better choice.
-
- Why aren't PERFORMER/TITLE/etc tags stored in the FLAC CUESHEET block?
-
- This has turned out to be a pretty polarizing issue and requires a long explanation.
-
- The original purpose of a cue sheet in CD authoring software was to lay out the disc, essentially specifying how the audio will be organized on the disc; some of the information ends up as the CD table of contents: the track numbers and locations, and the index points. Later CD-TEXT was added. But CD-TEXT is a very complex spec, and actually goes in the CD subcode data. It is internationalized, not through Unicode, but with several different character sets, some of them multi-byte. It even allows for graphics. In cue sheets, the TITLE/PERFORMER/etc tags are just a limited shorthand for authoring CD-TEXT, but when you rip, you almost never parse the CD-TEXT, you get it from another database, and it doesn't really belong in the FLAC CUESHEET block.
-
- For FLAC the intention is that applications can calculate the CDDB or CDindex ID from the CUESHEET block and look it up in an online or local database just like CD rippers and players do. But if you really want it in the file itself, the track metadata should be stored separate from the CUESHEET, and already can be because of FLAC's metadata system. There just isn't a method specified yet because as soon as it is, people will say that it's not flexible enough. From experience (and you can see this come up time and time again in many lists), anyone who is going to the trouble of keeping a lossless collection in the first place will already be picky about metadata, and it is hard to come up with a standard that will please even the majority. That is the big problem with metadata and is why Xiph has deferred on it, waiting for someone to come up with a good metadata spec that can be multiplexed together with data.
-
- Some players (for example Foobar2000) allow you to store the CDDB data as FLAC tags and can parse that.
-
- Why doesn't FLAC store all WAVE metadata?
- If flac compresses WAVE files, why isn't it technically a WAVE file compressor?
-
- (By default, flac does not store WAVE metadata, but it can with the --keep-foreign-metadata option described below.)
-
- FLAC is a general-purpose audio format, not just a compressed WAVE file format. There's a subtle difference. WAVE is a complicated standard; many kinds of data besides audio data can be put in it. FLAC's purpose is not to reproduce a WAVE file, including all the non-audio data that is in it, it is to losslessly compress the audio.
-
- However, if you really need to store the non-audio parts of a WAVE or AIFF file, you can use the --keep-foreign-metadata option to flac when encoding to store it in FLAC metadata, then use the option again when decoding to restore in to the decoded WAVE/AIFF file.
-
- Why do some lossless comparisons say FLAC does not support RIFF chunks?
-
- This is a limitation that no longer exists with FLAC (see above).
-
- Why do the encoder settings have a big effect on the encoding time but not the decoding time?
-
- It's hard to explain without going into the codec design, but to oversimplify, the encoder is looking for functions that approximate the signal. Higher settings make the encoder search more to find better approximations. The functions are themselves encoded in the FLAC file. Decoding only requires computing the one chosen function, and the complexity of the function is very stable. This is by design, to make decoding easier, and is one of the things that makes FLAC easy to implement in hardware.
-
- Why use FLAC instead of other codecs that compress more?
-
- For most users, a small difference in filesize is usually far outweighed by FLAC's advantages: open patent free codec, portable open source (BSD) reference implementation, documented API, multi-platform support, hardware support, multi-channel support, etc. Improving FLAC to get a little more compression is not worth making it more complex and more compute-intensive to decode, and hence, less likely to be supported in hardware.
-
- Why can't you make FLAC encode faster?
-
- FLAC already encodes pretty fast. It is faster than real-time even on weak systems and is not much slower than even the fastest codecs. And it is faster than the CD ripping process with which it is usually paired, meaning even if it went faster, it would not speed up the ripping-encoding process anyway.
-
- Part of the reason is that FLAC is asymmetric (see also). That means that it is optimized for decoding speed at the expense of encoding speed, because it makes it easier to decode on low-powered hardware, and because you only encode once but you decode many times.
-
- How can I be sure FLAC is lossless?
- How much testing has been done on FLAC?
-
- First, FLAC is probably the only lossless compressor that has a published and comprehensive test suite. With the others you rely on the author's personal testing or the longevity of the program. But with FLAC you can download the whole test suite and run it on any version you like, or alter it to test your own data. The test suite checks every function in the API, as well as running many thousands of streams through an encode-decode-verify process, to test every nook and cranny of the system. Even on a fast machine the full test suite takes hours. The full test suite must pass on several platforms before a release is made.
-
- Second, you can always use the -V option with flac (also supported by most GUI frontends) to verify while encoding. With this option, a decoder is run in parallel to the encoder and its output is compared against the original input. If a difference is found flac will stop with an error.
-
- Finally, FLAC is used by many people and has been judged stable enough by many software and hardware makers to be incorporated into their products.
-
- What is the lowest bitrate (or highest compression) achievable with FLAC?
-
- With FLAC you do not specify a bitrate like with some lossy codecs. It's more like specifying a quality with Vorbis or MPC, except with FLAC the quality is always "lossless" and the resulting bitrate is roughly proportional to the amount of information in the original signal. You cannot control the bitrate much and the result can be from around 100% of the input rate (if you are encoding noise), down to almost 0 (encoding silence).
-
- How many channels does FLAC support?
-
- FLAC supports from 1 to 8 channels per stream. Channels are only grouped in FLAC to take advantage of interchannel correlation and to define common channel assignments (like stereo L/R, 5.1 surround, et cetera). When encoding a large number of independent channels it is expected that they are coded separately and if required, multiplexed together in a suitable container like Ogg or Matroska.
-
- What kind of audio samples does FLAC support?
-
- FLAC supports linear PCM samples with a resolution between 4 and 32 bits per sample. FLAC does not support floating point samples. In some cases it is possible to losslessly transform samples from an incompatible range to a FLAC-compatible range before encoding.
-
- FLAC supports linear sample rates from 1Hz - 1048575Hz in 1Hz increments.
-
- Will FLAC ever support floating-point samples?
-
- It's unlikely FLAC will ever support floating-point samples natively. The main application for floating-point is audio engineering, which demands easy editing and very high speed for both encoding and decoding above everything else.
-
- FLAC is designed as a consumer audio format. It trades ease of editing for a featureful, robust transport layer more suited for playback, and encoding speed for more compression and faster decompression. - -

- Tools -

- - How do I set up EAC to rip directly to FLAC?
-
- See Case's excellent EAC configuration page. Or use AutoFLAC or MAREO to rip to FLAC or multiple formats at once.
-
- Why am I getting "Run-time error '75': Path/File access error" with FLAC Frontend?
-
- You are probably using an old version of FLAC Frontend. Try downloading a new version from this sourceforge page
-
- How do I encode a file that starts with a dash?
-
- When using flac to encode on the command-line, a file that starts with a dash will be treated as an option, but there is a simple workaround. Use -- to signal the end of options and the beginning of filenames, like so:
-
- flac -V -- -01-name.wav
-
- Why does it take so long to edit some FLAC files with metaflac?
-
- Since metadata is stored at the beginning of a FLAC file, changing the length of it can sometimes cause the whole file to be rewritten. You can avoid this by adding padding with flac when you encode, or with metaflac after encoding. By default, flac adds 8k of padding; you can change this amount if you need more or less.
-
- Why don't wildcards for file names like *.flac or *.wav work with flac/metaflac on Windows?
-
- The Windows command shells (cmd.exe, command.com) implement wildcard handling differently than most other shells, leaving it up to the program to do everything including difficult and ambiguous cases. For an explanation of why wildcards on cmd.exe/command.com are dangerous, see here. Better command shells for Windows exist, e.g. from Cygwin. A workaround with the Windows shells is to do something like:
-
- for %F in (*.wav) do flac "%F"
-
- but care must still be taken that the command will execute as intended.
-
- I compressed a file to FLAC with verify on, and flac said "Verify FAILED!" Why?
-
- The only known cause of verify errors is faulty hardware. The dead giveaway is that if you repeat the exact same command, the error occurs in a different place or not at all. This can also happen when decoding or testing a FLAC file. If this is happening it is your hardware and not a FLAC bug.
-
- The problem is usually caused by overclocking/overheating the CPU or bad RAM. Try one of the many free programs available for testing hardware (e.g. Memtest).
-
- If you ever have a verify error that fails at the same place every time, please file a bug, uploading a sample according to the instructions found at the bottom of this bug report.
-
- I compressed a WAVE file to FLAC, then decompressed to WAVE, and the two weren't identical. Why?
- I compressed a WAVE file to FLAC and it said "warning: skipping unknown sub-chunk LIST". Why?
-
- WAVE is a complicated standard; many kinds of data besides audio data can be put in it. Most likely what has happened is that the application that created the original WAVE file also added some extra information for it's own use, which FLAC does not store or recreate by default (but can with the --keep-foreign-metadata option) (see also). The audio data in the two WAVE files will be identical. There are other tools to compare just the audio content of two WAVE files; ExactAudioCopy has such a feature.
-
- For the more technically inclined, by default FLAC only stores what is in the 'fmt ' and 'data' sub-chunks of a WAVE file. (see also)
-
- I decoded a FLAC file and the WAVE is 2 bytes shorter than the original. Why?
-
- The difference is probably that between an 18-byte 'fmt ' subchunk in the original WAVE vs. a 16-byte one in the decoded WAVE. With WAVE there is more than one way to write identical formatting information, but FLAC always writes the most common legal form. (see also)
-
- Why did I get "ERROR initializing encoder, state = FLAC__STREAM_ENCODER_NOT_STREAMABLE"?
-
- You specified encoding options that are outside the Streamable subset. If that is what you really wanted and you understand the consequences, you can use flac --lax to generate a non-Subset stream. The resulting file may not be streamable or play in all players.
-
- Why doesn't the same file compressed on different machines with the same options yield the same FLAC file?
-
- It's not supposed to, and neither does it mean either encoding was bad. There are many variations between different machines or even different builds of flac on the same machine that can lead to small differences in the FLAC file, even if they have the exact same final size. This is normal. - -

- API -

- - Why does your API change for point releases?
-
- The FLAC release numbering scheme of MAJOR.MINOR.MICRO reflects the state of the FLAC format, not the API. This is most intuitive for users, at the expense of flustering developers. The shared library number (derived from the libtool current:revision:age number) is the indicator of binary API compatibility. As of FLAC 1.1.3, the current, revision, and age numbers are also #defined in the library headers to make porting easier; see the porting guide.
-
- How can I determine the encoded frame length?
-
- With native FLAC, it is not possible to determine the frame length without decoding. Probably if I had it all to do again I would have constrained the possible block sizes, which would have made it more practical to put the frame length in the frame header. For an example of how to find the frame boundaries in a stream, see the source code to metaflac, in the functionality that adds seek points.
-
- With Ogg FLAC, it can be calculated from the Ogg page header. - -

- Project -

- - Where are the mailing lists, forums, discussion areas, etc.?
-
- There are a few places. The main discussions happen on the official FLAC mailing lists (you must subscribe to post). Also, there is a lot of discussion relating to FLAC on Hydrogen Audio.
-
- How do I submit a bug report?
-
- First, visit the bug tracking page and do a little searching of both open and closed bugs to see if yours is already there. If you have something truly new submit a new bug there. Make sure to monitor the bug or include your email address in the description. Include as much information as possible: the version of FLAC that you are running, the name and version of any frontend you are running, your operating system and version, your CPU type and speed, the amount of memory you have, where you downloaded FLAC from, the exact error message (if any) copied from the console, and anything else you may think will help. -
- -
- - - - - - diff --git a/doc/html/favicon.ico b/doc/html/favicon.ico deleted file mode 100644 index 594fe38a..00000000 Binary files a/doc/html/favicon.ico and /dev/null differ diff --git a/doc/html/features.html b/doc/html/features.html deleted file mode 100644 index bbc7b6d0..00000000 --- a/doc/html/features.html +++ /dev/null @@ -1,113 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - features - - - - - - -
- - - -
- -
-
- introduction -
-
-
- FLAC stands for Free Lossless Audio Codec, an audio format similar to MP3, but lossless, meaning that audio is compressed in FLAC without any loss in quality. This is similar to how Zip works, except with FLAC you will get much better compression because it is designed specifically for audio, and you can play back compressed FLAC files in your favorite player (or your car or home stereo, see supported devices) just like you would an MP3 file.
-
- FLAC stands out as the fastest and most widely supported lossless audio codec, and the only one that at once is non-proprietary, is unencumbered by patents, has an open-source reference implementation, has a well documented format and API, and has several other independent implementations.
-
- FLAC supports tagging, cover art, and fast seeking. FLAC is freely available and supported on most operating systems, including Windows, "unix" (Linux, *BSD, Solaris, OS X, IRIX), BeOS, OS/2, and Amiga.
-
- There are many programs and devices that support FLAC, but the core FLAC project here maintains the format and provides programs and libraries for working with FLAC files. See Getting FLAC for instructions on downloading and installing the official FLAC tools, or Using FLAC for instructions and guides on playing FLAC files, ripping CDs to FLAC, etc.
-
- When we say that FLAC is "Free" it means more than just that it is available at no cost. It means that the specification of the format is fully open to the public to be used for any purpose (the FLAC project reserves the right to set the FLAC specification and certify compliance), and that neither the FLAC format nor any of the implemented encoding/decoding methods are covered by any known patent. It also means that all the source code is available under open-source licenses. It is the first truly open and free lossless audio format. (For more information, see the license page.)
-
- Notable features of FLAC: - - What FLAC is not: - -
- -
- - - - - - diff --git a/doc/html/flac.css b/doc/html/flac.css deleted file mode 100644 index a4e57926..00000000 --- a/doc/html/flac.css +++ /dev/null @@ -1,194 +0,0 @@ -/* - * Copyright (c) 2005,2006,2007 Josh Coalson - * Permission is granted to copy, distribute and/or modify this document - * under the terms of the GNU Free Documentation License, Version 1.1 - * or any later version published by the Free Software Foundation; - * with no invariant sections. - * A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html - */ - -body -{ - background-color: #9a9; - color: black; - margin: 0 auto; - padding: 0px; - max-width: 1200px; -} - -/*div -{ - background-color: #99CC99; - margin: 0px; - padding: 0px; -}*/ - -div.logo -{ - background-color: black; - padding: 1px; - text-align: center; -} - -div.navbar -{ - border-width: 2px 0px 2px 0px; - border-style: solid; - border-color: black; - background-color: #D3D4C5; - padding: 3px; - text-align: center; -} - - -div.above_nav -{ - height: 25px; -} - -div.below_nav -{ - height: 25px; -} - -div.body_with_sidebar -{ -/* text-align: left; */ -} - -div.box -{ - text-align: left; - margin: 0; - background-color: #EEEED4; -} - -div.box_title -{ - border-width: 1px 0px 0px 0px; - border-style: solid; - border-color: black; - background-color: #D3D4C5; - padding: 3px 6px; - font-family: lucida, verdana, helvetica, arial, sans-serif; - font-weight: bold; - font-size: 150%; -} - -div.box_header -{ - border-width: 1px 0px 0px 0px; - border-style: solid; - border-color: black; - background-color: #EEEED4; - padding: 3px; -} - -div.box_footer -{ - border-width: 0px 0px 1px 0px; - border-style: solid; - border-color: black; - background-color: #EEEED4; - padding: 3px; -} - -div.box_body -{ - background-color: #EEEED4; - padding: 0px 6px; - font-family: lucida, verdana, helvetica, arial, sans-serif; - font-weight: normal; - font-size: 100%; -} - -#newsbox h3 -{ - margin: 5px 0 0 0; - font-size: 0.9em; -} - -#newsbox p -{ - margin: 0; -} - -div.smallbox -{ - text-align: left; - margin: 0 0 0 8px; - background-color: #EEEED4; -} - -div.smallbox_title -{ - text-align: center; - border-width: 1px 0px 0px 0px; - border-style: solid; - border-color: black; - background-color: #D3D4C5; - padding: 3px; - font-family: lucida, verdana, helvetica, arial, sans-serif; - font-weight: bold; - font-size: 100%; -} - -div.smallbox_header -{ - border-width: 1px 0px 0px 0px; - border-style: solid; - border-color: black; - background-color: #EEEED4; - padding: 3px; -} - -div.smallbox_footer -{ - border-width: 0px 0px 1px 0px; - border-style: solid; - border-color: black; - background-color: #EEEED4; - padding: 3px; -} - -div.smallbox_body -{ - background-color: #EEEED4; - padding: 0px 3px 0px 3px; - font-family: lucida, verdana, helvetica, arial, sans-serif; - font-weight: normal; - font-size: 80%; -} - -div.copyright -{ - text-align: left; - margin: 10px; -} - -span.commandname -{ - font-family: monospace; - font-weight: bold; -} - -span.command -{ - font-family: monospace; - font-weight: bold; -} - -span.argument -{ - font-family: monospace; -} - -span.code -{ - font-family: monospace; -} - -a:link {color:#336699; background-color:transparent} -a:visited {color:#336699; background-color:transparent} -a:active {color:#336699; background-color:transparent} -a:hover {color:#336699; background-color:transparent} diff --git a/doc/html/format.html b/doc/html/format.html deleted file mode 100644 index 68195cbb..00000000 --- a/doc/html/format.html +++ /dev/null @@ -1,1849 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - format - - - - - - -
- - - -
- -
-
- format -
-
-
- This is a detailed description of the FLAC format. There is also a companion document that describes FLAC-to-Ogg mapping.
-
- For a user-oriented overview, see About the FLAC Format.
-
- Table of Contents - - Acknowledgments
-
- FLAC owes much to the many people who have advanced the audio compression field so freely. For instance: - - Scope
-
- It is a known fact that no algorithm can losslessly compress all possible input, so most compressors restrict themselves to a useful domain and try to work as well as possible within that domain. FLAC's domain is audio data. Though it can losslessly code any input, only certain kinds of input will get smaller. FLAC exploits the fact that audio data typically has a high degree of sample-to-sample correlation.
-
- Within the audio domain, there are many possible subdomains. For example: low bitrate speech, high-bitrate multi-channel music, etc. FLAC itself does not target a specific subdomain but many of the default parameters of the reference encoder are tuned to CD-quality music data (i.e. 44.1kHz, 2 channel, 16 bits per sample). The effect of the encoding parameters on different kinds of audio data will be examined later.
-
- Architecture
-
- Similar to many audio coders, a FLAC encoder has the following stages: - - In addition, FLAC specifies a metadata system, which allows arbitrary information about the stream to be included at the beginning of the stream.
-
- Definitions
-
- Many terms like "block" and "frame" are used to mean different things in different encoding schemes. For example, a frame in MP3 corresponds to many samples across several channels, whereas an S/PDIF frame represents just one sample for each channel. The definitions we use for FLAC follow. Note that when we talk about blocks and subblocks we are referring to the raw unencoded audio data that is the input to the encoder, and when we talk about frames and subframes, we are referring to the FLAC-encoded data. - - Blocking
-
- The size used for blocking the audio data has a direct effect on the compression ratio. If the block size is too small, the resulting large number of frames mean that excess bits will be wasted on frame headers. If the block size is too large, the characteristics of the signal may vary so much that the encoder will be unable to find a good predictor. In order to simplify encoder/decoder design, FLAC imposes a minimum block size of 16 samples, and a maximum block size of 65535 samples. This range covers the optimal size for all of the audio data FLAC supports.
-
- Currently the reference encoder uses a fixed block size, optimized on the sample rate of the input. Future versions may vary the block size depending on the characteristics of the signal.
-
- Blocked data is passed to the predictor stage one subblock (channel) at a time. Each subblock is independently coded into a subframe, and the subframes are concatenated into a frame. Because each channel is coded separately, it means that one channel of a stereo frame may be encoded as a constant subframe, and the other an LPC subframe.
-
- Interchannel Decorrelation
-
- In stereo streams, many times there is an exploitable amount of correlation between the left and right channels. FLAC allows the frames of stereo streams to have different channel assignments, and an encoder may choose to use the best representation on a frame-by-frame basis. - - Surprisingly, the left-side and right-side forms can be the most efficient in many frames, even though the raw number of bits per sample needed for the original signal is slightly more than that needed for independent or mid-side coding.
-
- Prediction
-
- FLAC uses four methods for modeling the input signal: - - Residual Coding
-
- FLAC currently defines two similar methods for the coding of the error signal from the prediction stage. The error signal is coded using Rice codes in one of two ways: 1) the encoder estimates a single Rice parameter based on the variance of the residual and Rice codes the entire residual using this parameter; 2) the residual is partitioned into several equal-length regions of contiguous samples, and each region is coded with its own Rice parameter based on the region's mean. (Note that the first method is a special case of the second method with one partition, except the Rice parameter is based on the residual variance instead of the mean.)
-
- The FLAC format has reserved space for other coding methods. Some possibilities for volunteers would be to explore better context-modeling of the Rice parameter, or Huffman coding. See LOCO-I and pucrunch for descriptions of several universal codes.
-
- Format
-
- This section specifies the FLAC bitstream format. FLAC has no format version information, but it does contain reserved space in several places. Future versions of the format may use this reserved space safely without breaking the format of older streams. Older decoders may choose to abort decoding or skip data encoded with newer methods. Apart from reserved patterns, in places the format specifies invalid patterns, meaning that the patterns may never appear in any valid bitstream, in any prior, present, or future versions of the format. These invalid patterns are usually used to make the synchronization mechanism more robust.
-
- All numbers used in a FLAC bitstream are integers; there are no floating-point representations. All numbers are big-endian coded. All numbers are unsigned unless otherwise specified.
-
- Before the formal description of the stream, an overview might be helpful. - - - The following tables constitute a formal description of the FLAC format. Numbers in angle brackets indicate how many bits are used for a given field.
-
- -
- -
- -
-
- - - - - - - - - - - - - - - - - - - - -
- STREAM -
- <32> - - "fLaC", the FLAC stream marker in ASCII, meaning byte 0 of the stream is 0x66, followed by 0x4C 0x61 0x43 -
- METADATA_BLOCK - - This is the mandatory STREAMINFO metadata block that has the basic properties of the stream -
- METADATA_BLOCK* - - Zero or more metadata blocks -
- FRAME+ - - One or more audio frames -
-
-
- -
- -
-
- - - - - - - - - - - - -
- METADATA_BLOCK -
- METADATA_BLOCK_HEADER - - A block header that specifies the type and size of the metadata block data. -
- METADATA_BLOCK_DATA - -   -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - -
- METADATA_BLOCK_HEADER -
- <1> - - Last-metadata-block flag: '1' if this block is the last metadata block before the audio blocks, '0' otherwise. -
- <7> - - BLOCK_TYPE
-
    -
  • - 0 : STREAMINFO -
  • -
  • - 1 : PADDING -
  • -
  • - 2 : APPLICATION -
  • -
  • - 3 : SEEKTABLE -
  • -
  • - 4 : VORBIS_COMMENT -
  • -
  • - 5 : CUESHEET -
  • -
  • - 6 : PICTURE -
  • -
  • - 7-126 : reserved -
  • -
  • - 127 : invalid, to avoid confusion with a frame sync code -
  • -
-
- <24> - - Length (in bytes) of metadata to follow (does not include the size of the METADATA_BLOCK_HEADER) -
-
-
- -
- -
-
- - - - - - - - -
- METADATA_BLOCK_DATA -
- METADATA_BLOCK_STREAMINFO
- || METADATA_BLOCK_PADDING
- || METADATA_BLOCK_APPLICATION
- || METADATA_BLOCK_SEEKTABLE
- || METADATA_BLOCK_VORBIS_COMMENT
- || METADATA_BLOCK_CUESHEET
- || METADATA_BLOCK_PICTURE -
- The block data must match the block type in the block header. -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- METADATA_BLOCK_STREAMINFO -
- <16> - - The minimum block size (in samples) used in the stream. -
- <16> - - The maximum block size (in samples) used in the stream. (Minimum blocksize == maximum blocksize) implies a fixed-blocksize stream. -
- <24> - - The minimum frame size (in bytes) used in the stream. May be 0 to imply the value is not known. -
- <24> - - The maximum frame size (in bytes) used in the stream. May be 0 to imply the value is not known. -
- <20> - - Sample rate in Hz. 20 bits are available, the maximum sample rate being 1048575Hz. Also, a value of 0 is invalid. -
- <3> - - (number of channels)-1. FLAC supports from 1 to 8 channels -
- <5> - - (bits per sample)-1. FLAC supports from 4 to 32 bits per sample. Currently the reference encoder and decoders only support up to 24 bits per sample. -
- <36> - - Total samples in stream. 'Samples' means inter-channel sample, i.e. one second of 44.1Khz audio will have 44100 samples regardless of the number of channels. A value of zero here means the number of total samples is unknown. -
- <128> - - MD5 signature of the unencoded audio data. This allows the decoder to determine if an error exists in the audio data even when the error does not result in an invalid bitstream. -
- - NOTES
-
    -
  • - FLAC specifies a minimum block size of 16 and a maximum block size of 65535, meaning the bit patterns corresponding to the numbers 0-15 in the minimum blocksize and maximum blocksize fields are invalid. -
  • -
-
-
-
- -
- -
-
- - - - - - - - -
- METADATA_BLOCK_PADDING -
- <n> - - n '0' bits (n must be a multiple of 8) -
-
-
- -
- -
-
- - - - - - - - - - - - -
- METADATA_BLOCK_APPLICATION -
- <32> - - Registered application ID. (Visit the registration page to register an ID with FLAC.) -
- <n> - - Application data (n must be a multiple of 8) -
-
-
- -
- -
-
- - - - - - - - - - - - -
- METADATA_BLOCK_SEEKTABLE -
- SEEKPOINT+ - - One or more seek points. -
- - NOTE
-
    -
  • - The number of seek points is implied by the metadata header 'length' field, i.e. equal to length / 18. -
  • -
-
-
-
- -
- -
-
- - - - - - - - - - - - - - - - - - - - -
- SEEKPOINT -
- <64> - - Sample number of first sample in the target frame, or 0xFFFFFFFFFFFFFFFF for a placeholder point. -
- <64> - - Offset (in bytes) from the first byte of the first frame header to the first byte of the target frame's header. -
- <16> - - Number of samples in the target frame. -
- - NOTES
-
    -
  • - For placeholder points, the second and third field values are undefined. -
  • -
  • - Seek points within a table must be sorted in ascending order by sample number. -
  • -
  • - Seek points within a table must be unique by sample number, with the exception of placeholder points. -
  • -
  • - The previous two notes imply that there may be any number of placeholder points, but they must all occur at the end of the table. -
  • -
-
-
-
- -
- -
-
- - - - - - - - -
- METADATA_BLOCK_VORBIS_COMMENT -
- <n> - - Also known as FLAC tags, the contents of a vorbis comment packet as specified here (without the framing bit). Note that the vorbis comment spec allows for on the order of 2 ^ 64 bytes of data where as the FLAC metadata block is limited to 2 ^ 24 bytes. Given the stated purpose of vorbis comments, i.e. human-readable textual information, this limit is unlikely to be restrictive. Also note that the 32-bit field lengths are little-endian coded according to the vorbis spec, as opposed to the usual big-endian coding of fixed-length integers in the rest of FLAC. -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- METADATA_BLOCK_CUESHEET -
- <128*8> - - Media catalog number, in ASCII printable characters 0x20-0x7e. In general, the media catalog number may be 0 to 128 bytes long; any unused characters should be right-padded with NUL characters. For CD-DA, this is a thirteen digit number, followed by 115 NUL bytes. -
- <64> - - The number of lead-in samples. This field has meaning only for CD-DA cuesheets; for other uses it should be 0. For CD-DA, the lead-in is the TRACK 00 area where the table of contents is stored; more precisely, it is the number of samples from the first sample of the media to the first sample of the first index point of the first track. According to the Red Book, the lead-in must be silence and CD grabbing software does not usually store it; additionally, the lead-in must be at least two seconds but may be longer. For these reasons the lead-in length is stored here so that the absolute position of the first track can be computed. Note that the lead-in stored here is the number of samples up to the first index point of the first track, not necessarily to INDEX 01 of the first track; even the first track may have INDEX 00 data. -
- <1> - - 1 if the CUESHEET corresponds to a Compact Disc, else 0. -
- <7+258*8> - - Reserved. All bits must be set to zero. -
- <8> - - The number of tracks. Must be at least 1 (because of the requisite lead-out track). For CD-DA, this number must be no more than 100 (99 regular tracks and one lead-out track). -
- CUESHEET_TRACK+ - - One or more tracks. A CUESHEET block is required to have a lead-out track; it is always the last track in the CUESHEET. For CD-DA, the lead-out track number must be 170 as specified by the Red Book, otherwise is must be 255. -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- CUESHEET_TRACK -
- <64> - - Track offset in samples, relative to the beginning of the FLAC audio stream. It is the offset to the first index point of the track. (Note how this differs from CD-DA, where the track's offset in the TOC is that of the track's INDEX 01 even if there is an INDEX 00.) For CD-DA, the offset must be evenly divisible by 588 samples (588 samples = 44100 samples/sec * 1/75th of a sec). -
- <8> - - Track number. A track number of 0 is not allowed to avoid conflicting with the CD-DA spec, which reserves this for the lead-in. For CD-DA the number must be 1-99, or 170 for the lead-out; for non-CD-DA, the track number must for 255 for the lead-out. It is not required but encouraged to start with track 1 and increase sequentially. Track numbers must be unique within a CUESHEET. -
- <12*8> - - Track ISRC. This is a 12-digit alphanumeric code; see here and here. A value of 12 ASCII NUL characters may be used to denote absence of an ISRC. -
- <1> - - The track type: 0 for audio, 1 for non-audio. This corresponds to the CD-DA Q-channel control bit 3. -
- <1> - - The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. This corresponds to the CD-DA Q-channel control bit 5; see here. -
- <6+13*8> - - Reserved. All bits must be set to zero. -
- <8> - - The number of track index points. There must be at least one index in every track in a CUESHEET except for the lead-out track, which must have zero. For CD-DA, this number may be no more than 100. -
- CUESHEET_TRACK_INDEX+ - - For all tracks except the lead-out track, one or more track index points. -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - -
- CUESHEET_TRACK_INDEX -
- <64> - - Offset in samples, relative to the track offset, of the index point. For CD-DA, the offset must be evenly divisible by 588 samples (588 samples = 44100 samples/sec * 1/75th of a sec). Note that the offset is from the beginning of the track, not the beginning of the audio data. -
- <8> - - The index point number. For CD-DA, an index number of 0 corresponds to the track pre-gap. The first index in a track must have a number of 0 or 1, and subsequently, index numbers must increase by 1. Index numbers must be unique within a track. -
- <3*8> - - Reserved. All bits must be set to zero. -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- METADATA_BLOCK_PICTURE -
- <32> - - The picture type according to the ID3v2 APIC frame:
-
    -
  • 0 - Other
  • -
  • 1 - 32x32 pixels 'file icon' (PNG only)
  • -
  • 2 - Other file icon
  • -
  • 3 - Cover (front)
  • -
  • 4 - Cover (back)
  • -
  • 5 - Leaflet page
  • -
  • 6 - Media (e.g. label side of CD)
  • -
  • 7 - Lead artist/lead performer/soloist
  • -
  • 8 - Artist/performer
  • -
  • 9 - Conductor
  • -
  • 10 - Band/Orchestra
  • -
  • 11 - Composer
  • -
  • 12 - Lyricist/text writer
  • -
  • 13 - Recording Location
  • -
  • 14 - During recording
  • -
  • 15 - During performance
  • -
  • 16 - Movie/video screen capture
  • -
  • 17 - A bright coloured fish
  • -
  • 18 - Illustration
  • -
  • 19 - Band/artist logotype
  • -
  • 20 - Publisher/Studio logotype
  • -
- Others are reserved and should not be used. There may only be one each of picture type 1 and 2 in a file. -
- <32> - - The length of the MIME type string in bytes. -
- <n*8> - - The MIME type string, in printable ASCII characters 0x20-0x7e. The MIME type may also be --> to signify that the data part is a URL of the picture instead of the picture data itself. -
- <32> - - The length of the description string in bytes. -
- <n*8> - - The description of the picture, in UTF-8. -
- <32> - - The width of the picture in pixels. -
- <32> - - The height of the picture in pixels. -
- <32> - - The color depth of the picture in bits-per-pixel. -
- <32> - - For indexed-color pictures (e.g. GIF), the number of colors used, or 0 for non-indexed pictures. -
- <32> - - The length of the picture data in bytes. -
- <n*8> - - The binary picture data. -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - - - - - -
- FRAME -
- FRAME_HEADER - -   -
- SUBFRAME+ - - One SUBFRAME per channel. -
- <?> - - Zero-padding to byte alignment. -
- FRAME_FOOTER - -   -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- FRAME_HEADER -
- <14> - - Sync code '11111111111110' -
- <1> - - Reserved: [1]
-
    -
  • - 0 : mandatory value -
  • -
  • - 1 : reserved for future use -
  • -
-
- <1> - - Blocking strategy: [2] [3]
-
    -
  • - 0 : fixed-blocksize stream; frame header encodes the frame number -
  • -
  • - 1 : variable-blocksize stream; frame header encodes the sample number -
  • -
-
- <4> - - Block size in inter-channel samples:
-
    -
  • - 0000 : reserved -
  • -
  • - 0001 : 192 samples -
  • -
  • - 0010-0101 : 576 * (2^(n-2)) samples, i.e. 576/1152/2304/4608 -
  • -
  • - 0110 : get 8 bit (blocksize-1) from end of header -
  • -
  • - 0111 : get 16 bit (blocksize-1) from end of header -
  • -
  • - 1000-1111 : 256 * (2^(n-8)) samples, i.e. 256/512/1024/2048/4096/8192/16384/32768 -
  • -
-
- <4> - - Sample rate:
-
    -
  • - 0000 : get from STREAMINFO metadata block -
  • -
  • - 0001 : 88.2kHz -
  • -
  • - 0010 : 176.4kHz -
  • -
  • - 0011 : 192kHz -
  • -
  • - 0100 : 8kHz -
  • -
  • - 0101 : 16kHz -
  • -
  • - 0110 : 22.05kHz -
  • -
  • - 0111 : 24kHz -
  • -
  • - 1000 : 32kHz -
  • -
  • - 1001 : 44.1kHz -
  • -
  • - 1010 : 48kHz -
  • -
  • - 1011 : 96kHz -
  • -
  • - 1100 : get 8 bit sample rate (in kHz) from end of header -
  • -
  • - 1101 : get 16 bit sample rate (in Hz) from end of header -
  • -
  • - 1110 : get 16 bit sample rate (in tens of Hz) from end of header -
  • -
  • - 1111 : invalid, to prevent sync-fooling string of 1s -
  • -
-
- <4> - - Channel assignment -
    -
  • - 0000-0111 : (number of independent channels)-1. Where defined, the channel order follows SMPTE/ITU-R recommendations. The assignments are as follows: -
      -
    • 1 channel: mono
    • -
    • 2 channels: left, right
    • -
    • 3 channels: left, right, center
    • -
    • 4 channels: front left, front right, back left, back right
    • -
    • 5 channels: front left, front right, front center, back/surround left, back/surround right
    • -
    • 6 channels: front left, front right, front center, LFE, back/surround left, back/surround right
    • -
    • 7 channels: front left, front right, front center, LFE, back center, side left, side right
    • -
    • 8 channels: front left, front right, front center, LFE, back left, back right, side left, side right
    • -
    -
  • -
  • - 1000 : left/side stereo: channel 0 is the left channel, channel 1 is the side(difference) channel -
  • -
  • - 1001 : right/side stereo: channel 0 is the side(difference) channel, channel 1 is the right channel -
  • -
  • - 1010 : mid/side stereo: channel 0 is the mid(average) channel, channel 1 is the side(difference) channel -
  • -
  • - 1011-1111 : reserved -
  • -
-
- <3> - - Sample size in bits: [5]
-
    -
  • - 000 : get from STREAMINFO metadata block -
  • -
  • - 001 : 8 bits per sample -
  • -
  • - 010 : 12 bits per sample -
  • -
  • - 011 : reserved -
  • -
  • - 100 : 16 bits per sample -
  • -
  • - 101 : 20 bits per sample -
  • -
  • - 110 : 24 bits per sample -
  • -
  • - 111 : reserved -
  • -
-
- <1> - - Reserved:
-
    -
  • - 0 : mandatory value -
  • -
  • - 1 : reserved for future use -
  • -
-
- <?> - - if(variable blocksize)
-    <8-56>:"UTF-8" coded sample number (decoded number is 36 bits) [4]
- else
-    <8-48>:"UTF-8" coded frame number (decoded number is 31 bits) [4] -
- <?> - - if(blocksize bits == 011x)
-    8/16 bit (blocksize-1) -
- <?> - - if(sample rate bits == 11xx)
-    8/16 bit sample rate -
- <8> - - CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0) of everything before the crc, including the sync code -
- - NOTES
-
    -
  1. - This bit must remain reserved for 0 in order for a FLAC frame's initial 15 bits to be distinguishable from the start of an MPEG audio frame (see also). -
  2. -
  3. - The "blocking strategy" bit must be the same throughout the entire stream. -
  4. -
  5. - The "blocking strategy" bit determines how to calculate the sample number of the first sample in the frame. If the bit is 0 (fixed-blocksize), the frame header encodes the frame number as above, and the frame's starting sample number will be the frame number times the blocksize. If it is 1 (variable-blocksize), the frame header encodes the frame's starting sample number itself. (In the case of a fixed-blocksize stream, only the last block may be shorter than the stream blocksize; its starting sample number will be calculated as the frame number times the previous frame's blocksize, or zero if it is the first frame). -
  6. -
  7. - The "UTF-8" coding used for the sample/frame number is the same variable length code used to store compressed UCS-2, extended to handle larger input. -
  8. -
  9. - For subframes that encode a difference channel, - the sample size is one bit larger than the sample size of the frame, - in order to be able to encode the difference between extreme values. -
  10. -
-
-
-
- -
- -
-
- - - - - - - - -
- FRAME_FOOTER -
- <16> - - CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with 0) of everything before the crc, back to and including the frame header sync code -
-
-
- -
- -
-
- - - - - - - - - - - - -
- SUBFRAME -
- SUBFRAME_HEADER - -   -
- SUBFRAME_CONSTANT
|| SUBFRAME_FIXED
|| SUBFRAME_LPC
|| SUBFRAME_VERBATIM -
- The SUBFRAME_HEADER specifies which one. -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - -
- SUBFRAME_HEADER -
- <1> - - Zero bit padding, to prevent sync-fooling string of 1s -
- <6> - - Subframe type: - -
- <1+k> - - 'Wasted bits-per-sample' flag: -
    -
  • - 0 : no wasted bits-per-sample in source subblock, k=0 -
  • -
  • - 1 : k wasted bits-per-sample in source subblock, k-1 follows, unary coded; e.g. k=3 => 001 follows, k=7 => 0000001 follows. -
  • -
- The size of the samples stored in the subframe is the subframe sample size reduced by k bits. - Decoded samples must be shifted left by k bits. -
-
-
- -
- -
-
- - - - - - - - -
- SUBFRAME_CONSTANT -
- <n> - - Unencoded constant value of the subblock, n = frame's bits-per-sample. -
-
-
- -
- -
-
- - - - - - - - - - - - -
- SUBFRAME_FIXED -
- <n> - - Unencoded warm-up samples (n = frame's bits-per-sample * predictor order). -
- RESIDUAL - - Encoded residual -
-
-
- -
- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
- SUBFRAME_LPC -
- <n> - - Unencoded warm-up samples (n = frame's bits-per-sample * lpc order). -
- <4> - - (Quantized linear predictor coefficients' precision in bits)-1 (1111 = invalid). -
- <5> - - Quantized linear predictor coefficient shift needed in bits (NOTE: this number is signed two's-complement; - but, due to implementation details, must be non-negative). -
- <n> - - Unencoded predictor coefficients (n = qlp coeff precision * lpc order) (NOTE: the coefficients are signed two's-complement). -
- RESIDUAL - - Encoded residual -
-
-
- -
- -
-
- - - - - - - - -
- SUBFRAME_VERBATIM -
- <n*i> - - Unencoded subblock; n = frame's bits-per-sample, i = frame's blocksize. -
-
-
- -
- -
-
- - - - - - - - - - - - -
- RESIDUAL -
- <2> - - Residual coding method:
-
    -
  • - 00 : partitioned Rice coding with 4-bit Rice parameter; RESIDUAL_CODING_METHOD_PARTITIONED_RICE follows -
  • -
  • - 01 : partitioned Rice coding with 5-bit Rice parameter; RESIDUAL_CODING_METHOD_PARTITIONED_RICE2 follows -
  • -
  • - 10-11 : reserved -
  • -
-
- RESIDUAL_CODING_METHOD_PARTITIONED_RICE ||
- RESIDUAL_CODING_METHOD_PARTITIONED_RICE2 -
-   -
-
-
- -
- -
-
- - - - - - - - - - - - -
- RESIDUAL_CODING_METHOD_PARTITIONED_RICE -
- <4> - - Partition order. -
- RICE_PARTITION+ - - There will be 2^order partitions. -
-
-
- -
- -
-
- - - - - - - - - - - - -
- RICE_PARTITION -
- <4(+5)> - - Encoding parameter:
-
    -
  • - 0000-1110 : Rice parameter. -
  • -
  • - 1111 : Escape code, meaning the partition is in unencoded binary form using n bits per sample; n follows as a 5-bit number. -
  • -
-
- <?> - - Encoded residual. The number of samples (n) in the partition is determined as follows:
-
    -
  • - partition size = (frame's blocksize / (2^partition order)) -
  • -
  • - for first partition of the subframe, n = partition size - predictor -
  • -
  • - for remaining partitions, n = partition size -
  • -
-
-
-
- -
- -
-
- - - - - - - - - - - - -
- RESIDUAL_CODING_METHOD_PARTITIONED_RICE2 -
- <4> - - Partition order. -
- RICE2_PARTITION+ - - There will be 2^order partitions. -
-
-
- -
- -
-
- - - - - - - - - - - - -
- RICE2_PARTITION -
- <5(+5)> - - Encoding parameter:
-
    -
  • - 00000-11110 : Rice parameter. -
  • -
  • - 11111 : Escape code, meaning the partition is in unencoded binary form using n bits per sample; n follows as a 5-bit number. -
  • -
-
- <?> - - Encoded residual. The number of samples (n) in the partition is determined as follows:
-
    -
  • - partition size = (frame's blocksize / (2^partition order)) -
  • -
  • - for first partition of the subframe, n = partition size - predictor -
  • -
  • - for remaining partitions, n = partition size -
  • -
-
-
-
- - - - - - diff --git a/doc/html/id.html b/doc/html/id.html deleted file mode 100644 index f12add15..00000000 --- a/doc/html/id.html +++ /dev/null @@ -1,289 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - id - - - - - - -
- - - -
- -
-
- register -
-
-
- FLAC allows third-party applications to register an ID for use with FLAC APPLICATION metadata blocks. Contact the FLAC-dev mailinglist to register an ID or to change an existing ID. Your request should at least contain the application ID, application name and a contact e-mail address. An application URL and specification URL should be mentioned too, if applicable.
-
- The ID request should be 8 hexadecimal digits and not conflict with any existing IDs (see the table below for all currently registered IDs). This 32-bit number will be stored big-endian in the block.
-
- Information about your application (but not your e-mail address) will show up on this page in the ID directory. You can also provide a URL to your application and a URL reference to the specification of your application's APPLICATION block.
-
- -
- -
- -
-
- id directory -
-
-
- Here is a list of all registered IDs and their applications:
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- ID - - Application -
- 41544348 - "ATCH" - - FlacFile -
- 42534F4C - "BSOL" - - beSolo -
- 42554753 - "BUGS" - - Bugs Player -
- 43756573 - "Cues" - - GoldWave cue points (specification) -
- 46696361 - "Fica" - - CUE Splitter -
- 46746F6C - "Ftol" - - flac-tools -
- 4D4F5442 - "MOTB" - - MOTB MetaCzar -
- 4D505345 - "MPSE" - - MP3 Stream Editor -
- 4D754D4C - "MuML" - - MusicML: Music Metadata Language -
- 52494646 - "RIFF" - - Sound Devices RIFF chunk storage -
- 5346464C - "SFFL" - - Sound Font FLAC -
- 534F4E59 - "SONY" - - Sony Creative Software -
- 5351455A - "SQEZ" - - flacsqueeze -
- 54745776 - "TtWv" - - TwistedWave -
- 55495453 - "UITS" - - UITS Embedding tools -
- 61696666 - "aiff" - - FLAC AIFF chunk storage -
- 696D6167 - "imag" - - flac-image application for storing arbitrary files in APPLICATION metadata blocks -
- 7065656D - "peem" - - Parseable Embedded Extensible Metadata (specification) -
- 71667374 - "qfst" - - QFLAC Studio -
- 72696666 - "riff" - - FLAC RIFF chunk storage -
- 74756E65 - "tune" - - TagTuner -
- 78626174 - "xbat" - - XBAT -
- 786D6364 - "xmcd" - - xmcd -
-
-
- -
- - - - - - diff --git a/doc/html/index.html b/doc/html/index.html deleted file mode 100644 index 09afb9d4..00000000 --- a/doc/html/index.html +++ /dev/null @@ -1,79 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - Free Lossless Audio Codec - - - - - - -
- - - -
- - - - - -
- -
- -
-
- Please note: This is the source-code documentation, for more general information on FLAC, please visit the on-line FLAC homepage
-
- FLAC stands for Free Lossless Audio Codec, an audio format similar to MP3, but lossless, meaning that audio is compressed in FLAC without any loss in quality. This is similar to how Zip works, except with FLAC you will get much better compression because it is designed specifically for audio, and you can play back compressed FLAC files in your favorite player (or your car or home stereo, see supported devices) just like you would an MP3 file.
-
- FLAC stands out as the fastest and most widely supported lossless audio codec, and the only one that at once is non-proprietary, is unencumbered by patents, has an open-source reference implementation, has a well documented format and API, and has several other independent implementations.
-
- See About FLAC for more, or Using FLAC for how to play FLAC files, rip CDs to FLAC, etc. -
- -
- -
- - - - - - diff --git a/doc/html/license.html b/doc/html/license.html deleted file mode 100644 index 5ddcf939..00000000 --- a/doc/html/license.html +++ /dev/null @@ -1,79 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - license - - - - - - -
- - - -
- -
-
- license -
-
-
- FLAC is a free codec in the fullest sense. This page explicitly states all that you may do with the format and software.
-
- The FLAC and Ogg FLAC formats themselves, and their specifications, are fully open to the public to be used for any purpose (the FLAC project reserves the right to set the FLAC specification and certify compliance). They are free for commercial or noncommercial use. That means that commercial developers may independently write FLAC or Ogg FLAC software which is compatible with the specifications for no charge and without restrictions of any kind. There are no licensing fees or royalties of any kind for use of the formats or their specifications, or for distributing, selling, or streaming media in the FLAC or Ogg FLAC formats.
-
- The FLAC project also makes available software that implements the formats, which is distributed according to Open Source licenses as follows:
-
- The reference implementation libraries are licensed under the New BSD License. In simple terms, these libraries may be used by any application, Open or proprietary, linked or incorporated in whole, so long as acknowledgement is made to Xiph.org Foundation when using the source code in whole or in derived works. The Xiph License is free enough that the libraries have been used in commercial products to implement FLAC, including in the firmware of hardware devices where other Open Source licenses can be problematic. In the source code these libraries are called libFLAC and libFLAC++.
-
- The rest of the software that the FLAC project provides is licensed under the GNU General Public License (GPL). This software includes various utilities for converting files to and from FLAC format, plugins for audio players, et cetera. In general, the GPL allows redistribution as long as derived works are also made available in source code form according to compatible terms.
-
- Neither the FLAC nor Ogg FLAC formats nor any of the implemented encoding/decoding methods are covered by any known patent.
-
- FLAC is one of a family of codecs of the Xiph.org Foundation, all created according to the same free ideals. For some other codecs' descriptions of the Xiph License see the Speex and Vorbis license pages.
-
- If you would like to redistribute parts or all of FLAC under different terms, contact the FLAC-dev mailinglist. -
- -
- - - - - - diff --git a/doc/html/ogg_mapping.html b/doc/html/ogg_mapping.html deleted file mode 100644 index 71e04136..00000000 --- a/doc/html/ogg_mapping.html +++ /dev/null @@ -1,124 +0,0 @@ - - - - - - - - - - - - - - - - - FLAC - ogg mapping - - - - - - -
- - - -
- -
-
- ogg mapping -
-
-
- This page specifies the way in which compressed FLAC data is encapsulated in an Ogg transport layer. It assumes basic knowledge of the FLAC format and Ogg structure and framing.
-
- The original FLAC format includes a very thin transport system. This system of compressed FLAC audio data mixed with a thin transport has come to be known as 'native FLAC'. The transport consists of audio frame headers and footers which contain synchronization patterns, timecodes, and checksums (but notably not frame lengths), and a metadata system. It is very lightweight and does not support more elaborate transport mechanisms such as multiple logical streams, but it has served its purpose well.
-
- The native FLAC transport is not a transport "layer" in the way of standard codec design because it cannot be entirely separated from the payload. Though the metadata system can be separated, the frame header includes both data that belongs in the transport (sync pattern, timecode, checksum) and data that belongs in the compressed packets (audio parameters like channel assignments, sample rate, etc).
-
- This presents a problem when trying to encapsulate FLAC in other true transport layers; the choice has to be made between redundancy and complexity. In pursuit of correctness, a mapping could be created that removed from native FLAC the transport data, and merged the remaining frame header information into the audio packets. The disadvantage is that current native FLAC decoder software could not be used to decode because of the tight coupling with the transport. Either a separate decoding implementation would have to be created and maintained, or an Ogg FLAC decoder would have to synthesize native FLAC frames from Ogg FLAC packets and feed them to a native FLAC decoder.
-
- The alternative is to treat native FLAC frames as Ogg packets and accept the transport redundancy. It turns out that this is not much of a penalty; a maximum of 12 bytes per frame will be wasted. Given the common case of stereo CD audio encoded with a blocksize of 4096 samples, a compressed frame will be 4-16 Kbytes. The redundancy amounts to a fraction of a percent.
-
- In the interest of simplicity and expediency, the second method was chosen for the first official FLAC->Ogg mapping. A mapping version is included in the first packet so that a less redundant mapping can be defined in the future.
-
- It should also be noted that support for encapsulating FLAC in Ogg has been present in the FLAC tools since version 1.0.1. However, the mappings used were never formalized and have insurmountable problems. For that reason, Ogg FLAC streams created with flac versions before 1.1.1 should be decoded and re-encoded with flac 1.1.1 or later (flac 1.1.1 can decode all previous Ogg FLAC files, but files made prior to 1.1.0 don't support seeking). Since the support for Ogg FLAC before FLAC 1.1.1 was limited, we hope this will not result in too much inconvenience.
-
- Version 1.0 of the FLAC-to-Ogg mapping then is a simple identifying header followed by pure native FLAC data, as follows: - - It is intended that the first six bytes of any version of FLAC-to-Ogg mapping will share the same structure, namely, the four-byte signature and two-byte version number.
-
- There is an implicit hint to the decoder in the mapping version number; mapping versions which share the same major version number should be decodable by decoders of the same major version number, e.g. a 1.x Ogg FLAC decoder should be able to decode any 1.y Ogg FLAC stream, even when x<y. If a mapping breaks this forward compatibility the major version number will be incremented. -
- -
- - - - - - diff --git a/doc/html/images/Makefile.am b/doc/images/Makefile.am similarity index 100% rename from doc/html/images/Makefile.am rename to doc/images/Makefile.am diff --git a/doc/html/images/logo.svg b/doc/images/logo.svg similarity index 100% rename from doc/html/images/logo.svg rename to doc/images/logo.svg diff --git a/doc/html/images/logo130.gif b/doc/images/logo130.gif similarity index 100% rename from doc/html/images/logo130.gif rename to doc/images/logo130.gif