diff options
| author | Martijn van Beurden <mvanb1@gmail.com> | 2022-09-05 19:11:31 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-09-05 19:11:31 +0200 |
| commit | dd8a264c566292de4d7da8f43688a169ffb431a1 (patch) | |
| tree | c54ea6e27d5367c42836d3b7603376bbc944a4a1 | |
| parent | 5e67c6278eb310e51da23c64862ef83dca8af01b (diff) | |
| download | flac-dd8a264c566292de4d7da8f43688a169ffb431a1.tar.gz | |
Restructure README, API and HTML documentation
Tool documentation has moved to man directory, other dev docs to
README.md and CONTRIBUTING.md. User documentation is already on
the website and doesn't really belong in the source code. Also, fix CMake
so that it uses Doxyfile.in instead of using defaults.
28 files changed, 372 insertions, 4075 deletions
@@ -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 @@ +<!--- +/* 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. + */ +---> + +# 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) - -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") +set(top_srcdir "${PROJECT_SOURCE_DIR}") +configure_file(Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY) -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") +add_custom_target(FLAC-doxygen ALL + COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Generating API documentation with Doxygen" + VERBATIM ) + +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 @@ -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - developers</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - developers | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - developers - </div> - <div class="box_header"></div> - <div class="box_body"> - 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 <a href="http://lists.xiph.org/mailman/listinfo/flac-dev">developer mailing list</a> (you must subscribe to post).<br /> - <br /> - 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 <a href="license.html">Xiph.org's BSD license</a>.<br /> - <br /> - Some pointers to developer documentation and code:<br /> - <ul> - <li><a href="license.html">License</a> - The license under which the official tools are distributed.</li> - <li><a href="api/index.html">libFLAC and libFLAC++ APIs</a> - Complete library documentation.</li> - <li><a href="documentation_example_code.html">Example Code</a> - Some simple example programs demonstrating the use of libFLAC and libFLAC++.</li> - <li><a href="format.html">FLAC Format Specification</a> - The formal specification.</li> - <li><a href="ogg_mapping.html">Ogg FLAC Mapping</a> - How FLAC should be embedded in an Ogg container.</li> - <li><a href="id.html">ID Registration</a> - Register an ID if you need to write custom metadata.</li> - <li><a href="https://github.com/xiph/flac">Git access</a> - for checking out the source code.</li> - <li><a href="https://github.com/xiph/flac/issues">Github Issues</a> - to submit bug reports - <li><a href="https://github.com/xiph/flac/pulls">Github Pulls</a> - to submit patches</li> - </ul> - </div> - <div class="box_footer"></div> -</div> - -<br /> - -<div class="box"> - <div class="box_title"> - goals - </div> - <div class="box_header"></div> - <div class="box_body"> - 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.<br /> - <br /> - <b>Goals</b> - <ul> - <li> - FLAC should be and stay an open format with an open-source reference implementation. - </li> - <li> - FLAC should be lossless. This seems obvious but lossy compression seems to creep into every audio codec. This goal also means that <span class="commandname">flac</span> should stay archival quality and be truly lossless for all input. Testing of releases should be thorough. - </li> - <li> - FLAC should yield respectable compression, on par or better than other lossless codecs. - </li> - <li> - FLAC should allow at least realtime decoding on even modest hardware. - </li> - <li> - FLAC should support fast sample-accurate seeking. - </li> - <li> - FLAC should allow gapless playback of consecutive streams. This follows from the lossless goal. - </li> - <li> - 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. - </li> - </ul> - <b>Anti-goals</b><br /> - <ul> - <li> - Lossy compression. There are already many suitable lossy formats (<a href="http://www.xiph.org/vorbis/">Ogg Vorbis</a>, <a href="http://www.mp3-tech.org/">MP3</a>, etc.). - </li> - <li> - 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. - </li> - </ul> - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - documentation</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - documentation | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - documentation - </div> - <div class="box_header"></div> - <div class="box_body"> - 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. - <ul> - <li><a href="features.html">Introduction</a> - What is FLAC?</li> - <li><a href="http://xiph.org/flac/download.html">Getting FLAC</a> - How to download what you need to play or make FLAC files.</li> - <li><a href="http://xiph.org/flac/documentation_tasks.html">Using FLAC</a> - If you have some FLAC files and want to do something with them, or want to create FLAC files, look here.</li> - <li><a href="faq.html">FAQ</a> - Frequently Asked Questions</li> - </ul> - In more detail: - <ul> - <li><a href="documentation_format_overview.html">About the FLAC Format</a> - An overview of the FLAC format for power users.</li> - <li><a href="documentation_tools.html">Official Tools</a> - How to use the <span class="commandname">flac</span> and <span class="commandname">metaflac</span> command-line tools.</li> - <li><a href="http://xiph.org/flac/comparison.html">Comparison</a> - A comparison of FLAC with other lossless codecs.</li> - <li><a href="documentation_bugs.html">Bugs</a> - How to report bugs and request features, and a list of known bugs in the FLAC tools.</li> - <li><a href="http://sourceforge.net/p/flac/support-requests/">Request Support</a> - Support for the official FLAC tools. For other programs, use <a href="http://www.hydrogenaud.io/">hydrogenaud.io</a></li> - <li><a href="http://lists.xiph.org/mailman/listinfo/flac">FLAC Mailing List</a> - General discussion about FLAC, tools, releases, etc. (You must subscribe to post.)</li> - </ul> - For developers who want to add FLAC support to their programs: - <ul> - <li><a href="documentation_format_overview.html">About the FLAC Format</a> - An overview of the FLAC format for power users.</li> - <li><a href="format.html">FLAC Format Specification</a> - The formal specification.</li> - <li><a href="ogg_mapping.html">Ogg FLAC Mapping</a> - How FLAC should be embedded in an Ogg container.</li> - <li><a href="api/index.html">libFLAC and libFLAC++ APIs</a> - Complete library documentation.</li> - <li><a href="documentation_example_code.html">Example Code</a> - Some simple example programs demonstrating the use of libFLAC and libFLAC++.</li> - <li><a href="license.html">License</a> - The license under which the official tools are distributed.</li> - <li>(see also the <a href="developers.html">developer page</a>)</li> - </ul> - 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. - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - documentation</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - <a name="bugs">known bugs</a> - </div> - <div class="box_header"></div> - <div class="box_body"> - The following are major known bugs in the current (1.3.4) release: - <ul> - <li> - When encoding to Ogg FLAC, the number of seek points is limited to 240. - </li> - </ul> - </div> - <div class="box_footer"></div> -</div> - -<br /> - -<div class="box"> - <div class="box_title"> - <a name="bug_reporting">reporting bugs</a> - </div> - <div class="box_header"></div> - <div class="box_body"> - To report a bug, please go to the <a href="http://sourceforge.net/p/flac/bugs/">FLAC bug tracker</a> (or appropriately the <a href="http://sourceforge.net/p/flac/feature-requests/">feature request tracker</a>, <a href="http://sourceforge.net/p/flac/patches/">patch page</a>, or <a href="http://sourceforge.net/p/flac/support-requests/">support page</a>).<br /> - <br /> - First check that there is not already an existing request. If you do submit a new request, make sure and provide an email contact <b>and</b> use the Monitor feature. - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - developers</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - example code - </div> - <div class="box_header"></div> - <div class="box_body"> - The FLAC source code has several small example programs that demonstrate how to use the libraries. The source is available on the <a href="http://xiph.org/flac/download.html">download page</a>, or can be <a href="https://gitlab.xiph.org/xiph/flac">checked out from git</a>. The examples complement the <a href="api/index.html">API documentation</a>.<br /> - <br /> - 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. - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - documentation</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - <a name="format">format</a> - </div> - <div class="box_header"></div> - <div class="box_body"> - The basic structure of a FLAC stream is: - <ul> - <li>The four byte string "<span class="code">fLaC</span>"</li> - <li>The <a href="format.html#def_STREAMINFO"><span class="code">STREAMINFO</span></a> metadata block</li> - <li>Zero or more other metadata blocks</li> - <li>One or more audio frames</li> - </ul> - 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.<br /> - <br /> - <b>METADATA</b><br /> - <br /> - FLAC defines several types of metadata blocks (see the <a href="format.html">format</a> 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 <span class="code">STREAMINFO</span> 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 <span class="code">STREAMINFO</span> block is the MD5 signature of the <i>unencoded</i> audio data. This is useful for checking an entire stream for transmission errors.<br /> - <br /> - Other blocks allow for padding, seek tables, tags, cuesheets, and application-specific data. There are <a href="documentation_tools_flac.html"><span class="commandname">flac</span> options</a> for adding <span class="code">PADDING</span> 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.<br /> - <br /> - Also, if you have a need of a custom metadata block, you can define your own and request an ID <a href="id.html">here</a>. Then you can reserve a <span class="code">PADDING</span> block of the correct size when encoding, and overwrite the padding block with your <span class="code">APPLICATION</span> 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.<br /> - <br /> - <b>AUDIO DATA</b><br /> - <br /> - 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.<br /> - <br /> - <b>BLOCKING</b><br /> - <br /> - 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. <span class="commandname">flac</span> 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.<br /> - <br /> - <b>INTER-CHANNEL DECORRELATION</b><br /> - <br /> - 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. <span class="commandname">flac</span> has two options for this: <span class="argument">-m</span> always compresses both the left-right and mid-side versions of the block and takes the smallest frame, and <span class="argument">-M</span>, which adaptively switches between left-right and mid-side.<br /> - <br /> - <b>MODELING</b><br /> - <br /> - 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 <i>residual</i>, <i>residue</i>, or <i>error</i>) 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.<br /> - <br /> - First, fixed polynomial prediction (specified with <span class="argument">-l 0</span>) 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 <span class="argument">-e</span> to overcome this, which is significantly slower.<br /> - <br /> - 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.<br /> - <br /> - <b>RESIDUAL CODING</b><br /> - <br /> - 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.<br /> - <br /> - 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 <i>contexts</i> or <i>partitions</i>, each with it's own Rice parameter. <span class="commandname">flac</span> allows you to specify how the partitioning is done with the <span class="argument">-r</span> option. The residual can be broken into 2^<i>n</i> partitions, by using the option <span class="argument">-r n,n</span>. The parameter <i>n</i> is called the <i>partition order</i>. Furthermore, the encoder can be made to search through <i>m</i> to <i>n</i> partition orders, taking the best one, by specifying <span class="argument">-r m,n</span>. 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.<br /> - <br /> - <b>FRAMING</b><br /> - <br /> - 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.<br /> - <br /> - <b>MISCELLANEOUS</b><br /> - <br /> - As a convenience, the reference decoder knows how to skip <a href="http://www.id3.org/">ID3v1 and ID3v2 tags</a>. Note however that the FLAC specification does not require compliant implementations to support ID3 in any form and their use is strongly discouraged.<br /> - <br /> - <span class="commandname">flac</span> has a verify option <span class="argument">-V</span> 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 <span class="commandname">flac</span> will stop with an error. - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - documentation</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - tools - </div> - <div class="box_header"></div> - <div class="box_body"> - 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: - <ul> - <li><a href="documentation_tools_flac.html">flac</a> - The command-line encoder and decoder.</li> - <li><a href="documentation_tools_metaflac.html">metaflac</a> - The command-line metadata editor.</li> - </ul> - Other resources: - <ul> - <li><a href="documentation_bugs.html">Bugs</a> - How to report bugs and request features, and a list of known bugs in the FLAC tools.</li> - <li><a href="http://sourceforge.net/p/flac/support-requests/">Request Support</a> - Support for the official FLAC tools. For other programs, use <a href="http://www.hydrogenaud.io/">hydrogenaud.io</a></li> - <li><a href="http://lists.xiph.org/mailman/listinfo/flac">FLAC Mailing List</a> - General discussion about FLAC, tools, releases, etc. (You must subscribe to post.)</li> - </ul> - <br /> - See <a href="http://xiph.org/flac/download.html">Getting FLAC</a> for instructions on downloading and installing the official FLAC tools, or <a href="http://xiph.org/flac/documentation_tasks.html">Using FLAC</a> for instructions and guides on playing FLAC files, ripping CDs to FLAC, etc. - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - faq</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - faq | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - faq - </div> - <div class="box_header"></div> - <div class="box_body"> - <b>General</b> - <ul> - <li> - <a href="faq.html#general__what_is"><b>What is FLAC?</b></a> - </li> - <li> - <a href="faq.html#general__how_to"><b>I have a FLAC file, how do I play it?</b></a> - </li> - <li> - <a href="faq.html#general__how_to"><b>How can I create FLAC files?</b></a> - </li> - <li> - <a href="faq.html#general__license"><b>What licensing applies to the FLAC format and software?</b></a> - </li> - <li> - <a href="faq.html#general__tagging"><b>What kinds of tags does FLAC support?</b></a> - </li> - <li> - <a href="faq.html#general__software"><b>What software support FLAC?</b></a> - </li> - <li> - <a href="faq.html#general__software_wmp"><b>How can I play FLAC in Windows Media Player?</b></a> - </li> - <li> - <a href="faq.html#general__hardware"><b>What hardware products support FLAC?</b></a> - </li> - <li> - <a href="faq.html#general__native_vs_ogg"><b>What is the difference between (native) FLAC and Ogg FLAC?</b></a> - </li> - <li> - <a href="faq.html#general__native_or_ogg"><b>Which should I use, (native) FLAC or Ogg FLAC?</b></a> - </li> - <li> - <a href="faq.html#general__no_cuesheet_tags"><b>Why aren't PERFORMER/TITLE/etc tags stored in the FLAC CUESHEET block?</b></a> - </li> - <li> - <a href="faq.html#general__no_wave_metadata"><b>Why doesn't FLAC store all WAVE metadata?</b></a> - </li> - <li> - <a href="faq.html#general__not_wave_compressor"><b>If flac compresses WAVE files, why isn't it technically a WAVE file compressor?</b></a> - </li> - <li> - <a href="faq.html#general__no_riff_subchunks"><b>Why do some lossless comparisons say FLAC does not support RIFF chunks?</b></a> - </li> - <li> - <a href="faq.html#general__asymmetry"><b>Why do the encoder settings have a big effect on the encoding time but not the decoding time?</b></a> - </li> - <li> - <a href="faq.html#general__alternatives"><b>Why use FLAC instead of other codecs that compress more?</b></a> - </li> - <li> - <a href="faq.html#general__encode_faster"><b>Why can't you make FLAC encode faster?</b></a> - </li> - <li> - <a href="faq.html#general__lossless_trust"><b>How can I be sure FLAC is lossless?</b></a> - </li> - <li> - <a href="faq.html#general__testing"><b>How much testing has been done on FLAC?</b></a> - </li> - <li> - <a href="faq.html#general__lowest_bitrate"><b>What is the lowest bitrate (or highest compression) achievable with FLAC?</b></a> - </li> - <li> - <a href="faq.html#general__channels"><b>How many channels does FLAC support?</b></a> - </li> - <li> - <a href="faq.html#general__samples"><b>What kind of audio samples does FLAC support?</b></a> - </li> - <li> - <a href="faq.html#general__samples_fp"><b>Will FLAC ever support floating-point samples?</b></a> - </li> - </ul> - <b>Tools</b> - <ul> - <li> - <a href="faq.html#tools__eac_and_flac"><b>How do I set up EAC to rip directly to FLAC?</b></a> - </li> - <li> - <a href="faq.html#tools__runtime75"><b>Why am I getting "Run-time error '75': Path/File access error" with FLAC Frontend?</b></a> - </li> - <li> - <a href="faq.html#tools__option_blocking"><b>How do I encode a file that starts with a dash?</b></a> - </li> - <li> - <a href="faq.html#tools__long_meta_edits"><b>Why does it take so long to edit some FLAC files with metaflac?</b></a> - </li> - <li> - <a href="faq.html#tools__wildcards_on_windows"><b>Why don't wildcards for file names like *.flac or *.wav work with <span class="commandname">flac</span>/<span class="commandname">metaflac</span> on Windows?</b></a> - </li> - <li> - <a href="faq.html#tools__hardware_prob"><b>I compressed a file to FLAC with verify on, and flac said "Verify FAILED!" Why?</b></a> - </li> - <li> - <a href="faq.html#tools__wave_flac_wave"><b>I compressed a WAVE file to FLAC, then decompressed to WAVE, and the two weren't identical. Why?</b></a> - </li> - <li> - <a href="faq.html#tools__skipped_subchunk"><b>I compressed a WAVE file to FLAC and it said "warning: skipping unknown sub-chunk LIST". Why?</b></a> - </li> - <li> - <a href="faq.html#tools__two_bytes_short"><b>I decoded a FLAC file and the WAVE is 2 bytes shorter than the original. Why?</b></a> - </li> - <li> - <a href="faq.html#tools__not_streamable"><b>Why did I get "ERROR initializing encoder, state = FLAC__STREAM_ENCODER_NOT_STREAMABLE"?</b></a> - </li> - <li> - <a href="faq.html#tools__different_sizes"><b>Why doesn't the same file compressed on different machines with the same options yield the same FLAC file?</b></a> - </li> - </ul> - <b>API</b> - <ul> - <li> - <a href="faq.html#api__release_versioning"><b>Why does your API change for point releases?</b></a> - </li> - <li> - <a href="faq.html#api__frame_length"><b>How can I determine the encoded frame length?</b></a> - </li> - </ul> - <b>Project</b> - <ul> - <li> - <a href="faq.html#project__lists"><b>Where are the mailing lists, forums, discussion areas, etc.?</b></a> - </li> - <li> - <a href="faq.html#project__submit_bug"><b>How do I submit a bug report?</b></a> - </li> - </ul> - - <h2> - <b>General</b> - </h2> - - <a name="general__what_is"><b>What is FLAC?</b></a><br /> - <br /> - 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 <a href="http://xiph.org/flac/links.html#hardware">supported devices</a>) just like you would an MP3 file.<br /> - <br /> - For more details, see <a href="features.html">What is FLAC?</a><br /> - <br /> - <a name="general__how_to"><b>I have a FLAC file, how do I play it?</b></a><br /> - <b>How can I create FLAC files?</b><br /> - <br /> - See <a href="http://xiph.org/flac/documentation_tasks.html">Using FLAC</a> or a <a href="http://xiph.org/flac/links.html">list of hardware that supports FLAC</a>.<br /> - <br /> - <a name="general__license"><b>What licensing applies to the FLAC format and software?</b></a><br /> - <br /> - See the <a href="license.html">license page</a>.<br /> - <br /> - <a name="general__tagging"><b>What kinds of tags does FLAC support?</b></a><br /> - <br /> - 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.<br /> - <br /> - 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.<br /> - <br /> - <a name="general__software"><b>What software support FLAC?</b></a><br /> - <br /> - 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 <a href="http://xiph.org/flac/links.html#software">software section</a> 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 <a href="http://xiph.org/flac/download.html">download page</a>.<br /> - <br /> - <a name="general__software_wmp"><b>How can I play FLAC in Windows Media Player?</b></a><br /> - <br /> - The easiest way is to use the Xiph.org Directshow Filters, <a href="http://www.xiph.org/dshow/downloads/">download them here</a><br /> - <br /> - <a name="general__hardware"><b>What hardware products support FLAC?</b></a><br /> - <br /> - See the <a href="http://xiph.org/flac/links.html#hardware">hardware section</a> of the links page.<br /> - <br /> - <a name="general__native_vs_ogg"><b>What is the difference between (native) FLAC and Ogg FLAC?</b></a><br /> - <br /> - 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.<br /> - <br /> - "Native" FLAC is the compressed FLAC data stored in a very minimalist container, designed to be very efficient at storing single audio streams.<br /> - <br /> - Ogg FLAC is the compressed FLAC data stored in an <a href="http://xiph.org/vorbis/doc/oggstream.html">Ogg container</a>. 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.<br /> - <br /> - In either case, the compressed FLAC data is the same and one can be converted to the other without re-encoding.<br /> - <br /> - <a name="general__native_or_ogg"><b>Which should I use, (native) FLAC or Ogg FLAC?</b></a><br /> - <br /> - 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.<br /> - <br /> - <a name="general__no_cuesheet_tags"><b>Why aren't PERFORMER/TITLE/etc tags stored in the FLAC CUESHEET block?</b></a><br /> - <br /> - This has turned out to be a pretty polarizing issue and requires a long explanation.<br /> - <br /> - 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.<br /> - <br /> - 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.<br /> - <br /> - Some players (for example Foobar2000) allow you to store the CDDB data as FLAC tags and can parse that.<br /> - <br /> - <a name="general__no_wave_metadata"><b>Why doesn't FLAC store all WAVE metadata?</b></a><br /> - <a name="general__not_wave_compressor"><b>If flac compresses WAVE files, why isn't it technically a WAVE file compressor?</b></a><br /> - <br /> - (By default, <span class="commandname">flac</span> does not store WAVE metadata, but it can with the <span class="argument"><a href="documentation_tools_flac.html#flac_options_keep_foreign_metadata">--keep-foreign-metadata</a></span> option described below.)<br /> - <br /> - 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.<br /> - <br /> - However, if you really need to store the non-audio parts of a WAVE or AIFF file, you can use the <span class="argument"><a href="documentation_tools_flac.html#flac_options_keep_foreign_metadata">--keep-foreign-metadata</a></span> option to <span class="commandname">flac</span> when encoding to store it in FLAC metadata, then use the option again when decoding to restore in to the decoded WAVE/AIFF file.<br /> - <br /> - <a name="general__no_riff_subchunks"><b>Why do some lossless comparisons say FLAC does not support RIFF chunks?</b></a><br /> - <br /> - This is a limitation that no longer exists with FLAC (<a href="faq.html#general__no_wave_metadata">see above</a>).<br /> - <br /> - <a name="general__asymmetry"><b>Why do the encoder settings have a big effect on the encoding time but not the decoding time?</b></a><br /> - <br /> - 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.<br /> - <br /> - <a name="general__alternatives"><b>Why use FLAC instead of other codecs that compress more?</b></a><br /> - <br /> - 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.<br /> - <br /> - <a name="general__encode_faster"><b>Why can't you make FLAC encode faster?</b></a><br /> - <br /> - 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.<br /> - <br /> - Part of the reason is that FLAC is asymmetric <a href="faq.html#general__asymmetry">(see also)</a>. 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. <br /> - <br /> - <a name="general__lossless_trust"><b>How can I be sure FLAC is lossless?</b></a><br /> - <a name="general__testing"><b>How much testing has been done on FLAC?</b></a><br /> - <br /> - 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.<br /> - <br /> - Second, you can always use the <span class="argument">-V</span> option with <span class="commandname">flac</span> (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 <span class="commandname">flac</span> will stop with an error.<br /> - <br /> - 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.<br /> - <br /> - <a name="general__lowest_bitrate"><b>What is the lowest bitrate (or highest compression) achievable with FLAC?</b></a><br /> - <br /> - 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).<br /> - <br /> - <a name="general__channels"><b>How many channels does FLAC support?</b></a><br /> - <br /> - 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.<br /> - <br /> - <a name="general__samples"><b>What kind of audio samples does FLAC support?</b></a><br /> - <br /> - 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.<br /> - <br /> - FLAC supports linear sample rates from 1Hz - 1048575Hz in 1Hz increments.<br /> - <br /> - <a name="general__samples_fp"><b>Will FLAC ever support floating-point samples?</b></a><br /> - <br /> - 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.<br /> - <br /> - 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. - - <h2> - <b>Tools</b> - </h2> - - <a name="tools__eac_and_flac"><b>How do I set up EAC to rip directly to FLAC?</b></a><br /> - <br /> - See Case's excellent <a href="http://www.saunalahti.fi/cse/EAC/index.html">EAC configuration page</a>. Or use <a href="http://www.legroom.net/software/autoflac">AutoFLAC</a> or <a href="http://mareo.netfirms.com/">MAREO</a> to rip to FLAC or multiple formats at once.<br /> - <br /> - <a name="tools__runtime75"><b>Why am I getting "Run-time error '75': Path/File access error" with FLAC Frontend?</b></a><br /> - <br /> - You are probably using an old version of FLAC Frontend. Try downloading a new version from <a href="http://flacfrontend.sf.net/">this sourceforge page</a><br /> - <br /> - <a name="tools__option_blocking"><b>How do I encode a file that starts with a dash?</b></a><br /> - <br /> - When using <span class="commandname">flac</span> 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 <span class="argument">--</span> to signal the end of options and the beginning of filenames, like so:<br /> - <br /> - <span class="code">flac -V -- -01-name.wav</span><br /> - <br /> - <a name="tools__long_meta_edits"><b>Why does it take so long to edit some FLAC files with metaflac?</b></a><br /> - <br /> - 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 <span class="commandname">flac</span> when you encode, or with <span class="commandname">metaflac</span> after encoding. By default, <span class="commandname">flac</span> adds 8k of padding; you can change this amount if you need more or less.<br /> - <br /> - <a name="tools__wildcards_on_windows"><b>Why don't wildcards for file names like *.flac or *.wav work with <span class="commandname">flac</span>/<span class="commandname">metaflac</span> on Windows?</b></a><br /> - <br /> - 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 <a href="http://www.hydrogenaud.io/forums/index.php?showtopic=50667&st=75&p=466078&#entry466078">here</a>. Better command shells for Windows exist, e.g. from <a href="http://cygwin.com/">Cygwin</a>. A workaround with the Windows shells is to do something like:<br /> - <br /> - <tt>for %F in (*.wav) do flac "%F"</tt><br /> - <br /> - but care must still be taken that the command will execute as intended.<br /> - <br /> - <a name="tools__hardware_prob"><b>I compressed a file to FLAC with verify on, and flac said "Verify FAILED!" Why?</b></a><br /> - <br /> - 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.<br /> - <br /> - 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. <a href="http://www.memtest.org/">Memtest</a>).<br /> - <br /> - If you ever have a verify error that fails at the same place every time, please <a href="faq.html#project__submit_bug">file a bug</a>, uploading a sample according to <a href="http://sourceforge.net/p/flac/bugs/42/">the instructions found at the bottom of this bug report</a>.<br /> - <br /> - <a name="tools__wave_flac_wave"><b>I compressed a WAVE file to FLAC, then decompressed to WAVE, and the two weren't identical. Why?</b></a><br /> - <a name="tools__skipped_subchunk"><b>I compressed a WAVE file to FLAC and it said "warning: skipping unknown sub-chunk LIST". Why?</b></a><br /> - <br /> - 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 <span class="argument"><a href="documentation_tools_flac.html#flac_options_keep_foreign_metadata">--keep-foreign-metadata</a></span> option) (<a href="faq.html#tools__two_bytes_short">see also</a>). 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; <a href="http://www.exactaudiocopy.de/">ExactAudioCopy</a> has such a feature.<br /> - <br /> - For the more technically inclined, by default FLAC only stores what is in the 'fmt ' and 'data' sub-chunks of a WAVE file. <a href="faq.html#general__no_wave_metadata">(see also)</a><br /> - <br /> - <a name="tools__two_bytes_short"><b>I decoded a FLAC file and the WAVE is 2 bytes shorter than the original. Why?</b></a><br /> - <br /> - 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. <a href="faq.html#tools__wave_flac_wave">(see also)</a><br /> - <br /> - <a name="tools__not_streamable"><b>Why did I get "ERROR initializing encoder, state = FLAC__STREAM_ENCODER_NOT_STREAMABLE"?</b></a><br /> - <br /> - You specified encoding options that are outside the <a href="format.html#subset">Streamable subset</a>. If that is what you really wanted and you understand the consequences, you can use <span class="code">flac --lax</span> to generate a non-Subset stream. The resulting file may not be streamable or play in all players.<br /> - <br /> - <a name="tools__different_sizes"><b>Why doesn't the same file compressed on different machines with the same options yield the same FLAC file?</b></a><br /> - <br /> - 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 <span class="commandname">flac</span> 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. - - <h2> - <b>API</b> - </h2> - - <a name="api__release_versioning"><b>Why does your API change for point releases?</b></a><br /> - <br /> - 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 <tt>#define</tt>d in the library headers to make porting easier; see the <a href="api/group__porting.html">porting guide</a>.<br /> - <br /> - <a name="api__frame_length"><b>How can I determine the encoded frame length?</b></a><br /> - <br /> - 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 <span class="commandname">metaflac</span>, in the functionality that adds seek points.<br /> - <br /> - With Ogg FLAC, it can be calculated from the Ogg page header. - - <h2> - <b>Project</b> - </h2> - - <a name="project__lists"><b>Where are the mailing lists, forums, discussion areas, etc.?</b></a><br /> - <br /> - There are a few places. The main discussions happen on <a href="http://lists.xiph.org/mailman/listinfo">the official FLAC mailing lists</a> (you must subscribe to post). Also, there is a lot of discussion relating to FLAC on <a href="http://www.hydrogenaud.io/">Hydrogen Audio</a>.<br /> - <br /> - <a name="project__submit_bug"><b>How do I submit a bug report?</b></a><br /> - <br /> - First, <a href="http://sourceforge.net/p/flac/bugs/">visit the bug tracking page</a> 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. <b>Make sure</b> 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. - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> diff --git a/doc/html/favicon.ico b/doc/html/favicon.ico Binary files differdeleted file mode 100644 index 594fe38a..00000000 --- a/doc/html/favicon.ico +++ /dev/null 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - features</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - <a name="introduction">introduction</a> - </div> - <div class="box_header"></div> - <div class="box_body"> - 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 <a href="http://xiph.org/flac/links.html#hardware">supported devices</a>) just like you would an MP3 file.<br /> - <br /> - FLAC stands out as the <a href="http://xiph.org/flac/comparison.html">fastest and most widely supported lossless audio codec</a>, 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.<br /> - <br /> - 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.<br /> - <br /> - There are <a href="http://xiph.org/flac/links.html">many programs and devices that support FLAC</a>, but the core FLAC project here maintains the format and provides <a href="documentation_tools.html">programs</a> and <a href="developers.html">libraries</a> for working with FLAC files. See <a href="http://xiph.org/flac/download.html">Getting FLAC</a> for instructions on downloading and installing the official FLAC tools, or <a href="http://xiph.org/flac/documentation_tasks.html">Using FLAC</a> for instructions and guides on playing FLAC files, ripping CDs to FLAC, etc.<br /> - <br /> - 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 <a href="license.html">license page</a>.)<br /> - <br /> - Notable features of FLAC: - <ul> - <li> - <b>Lossless</b>: The encoding of audio (PCM) data incurs no loss of information, and the decoded audio is bit-for-bit identical to what went into the encoder. Each frame contains a 16-bit CRC of the frame data for detecting transmission errors. The integrity of the audio data is further insured by storing an <a href="http://userpages.umbc.edu/~mabzug1/cs/md5/md5.html">MD5 signature</a> of the original unencoded audio data in the file header, which can be compared against later during decoding or testing. - </li> - <li> - <b>Fast</b>: FLAC is asymmetric in favor of decode speed. Decoding requires only integer arithmetic, and is much less compute-intensive than for most perceptual codecs. Real-time decode performance is easily achievable on even modest hardware. - </li> - <li> - <b>Hardware support</b>: FLAC is supported by <a href="http://xiph.org/flac/links.html#hardware">dozens of consumer electronic devices</a>, from portable players, to home stereo equipment, to car stereo. - </li> - <li> - <b>Flexible metadata</b>: FLAC's metadata system supports tags, cover art, seek tables, and cue sheets. Applications can write their own <a href="format.html#def_APPLICATION">APPLICATION</a> metadata once they <a href="id.html">register an ID</a>. New metadata blocks can be defined and implemented in future versions of FLAC without breaking older streams or decoders. - </li> - <li> - <b>Seekable</b>: FLAC supports fast sample-accurate seeking. Not only is this useful for playback, it makes FLAC files suitable for use in editing applications. - </li> - <li> - <b>Streamable</b>: Each FLAC frame contains enough data to decode that frame. FLAC does not even rely on previous or following frames. FLAC uses sync codes and CRCs (similar to MPEG and other formats), which, along with framing, allow decoders to pick up in the middle of a stream with a minimum of delay. - </li> - <li> - <b>Suitable for archiving</b>: FLAC is an open format, and there is no generation loss if you need to convert your data to another format in the future. In addition to the frame CRCs and MD5 signature, <span class="commandname">flac</span> has a verify option that decodes the encoded stream in parallel with the encoding process and compares the result to the original, aborting with an error if there is a mismatch. - </li> - <li> - <b>Convenient CD archiving</b>: FLAC has a <a href="format.html#def_CUESHEET">"cue sheet"</a> metadata block for storing a CD table of contents and all track and index points. For instance, you can rip a CD to a single file, then import the CD's extracted cue sheet while encoding to yield a single file representation of the entire CD. If your original CD is damaged, the cue sheet can be exported later in order to burn an exact copy. - </li> - <li> - <b>Error resistant</b>: Because of FLAC's framing, stream errors limit the damage to the frame in which the error occurred, typically a small fraction of a second worth of data. Contrast this with some other lossless codecs, in which a single error destroys the remainder of the stream. - </li> - </ul> - What FLAC is <b>not</b>: - <ul> - <li> - Lossy. FLAC is intended for lossless compression only, as there are many good lossy formats already, such as <a href="http://xiph.org/vorbis">Vorbis</a>, <a href="http://www.musepack.net/">MPC</a>, and <a href="http://www.mp3-tech.org/">MP3</a> (see <a href="http://lame.sourceforge.net/">LAME</a> for an excellent open-source implementation). - </li> - <li> - DRM. 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. - </li> - </ul> - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - format</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - format - </div> - <div class="box_header"></div> - <div class="box_body"> - This is a detailed description of the FLAC format. There is also a companion document that describes <a href="ogg_mapping.html">FLAC-to-Ogg mapping</a>.<br /> - <br /> - For a user-oriented overview, see <a href="documentation_format_overview.html">About the FLAC Format</a>.<br /> - <br /> - <a name="toc"><font size="+1"><b><u>Table of Contents</u></b></font></a> - <ul> - <li><a href="#acknowledgments">Acknowledgments</a></li> - <li><a href="#scope">Scope</a></li> - <li><a href="#architecture">Architecture</a></li> - <li><a href="#definitions">Definitions</a></li> - <li><a href="#blocking">Blocking</a></li> - <li><a href="#interchannel">Interchannel Decorrelation</a></li> - <li><a href="#prediction">Prediction</a></li> - <li><a href="#residualcoding">Residual Coding</a></li> - <li><a href="#format_overview">Format</a></li> - <li><a href="#subset">FLAC Subset</a></li> - <li>Specification - <ul> - <li><a href="#stream">STREAM</a> - <ul> - <li><a href="#metadata_block">METADATA_BLOCK</a> - <ul> - <li><a href="#metadata_block_header">METADATA_BLOCK_HEADER</a></li> - <li><a href="#metadata_block_data">METADATA_BLOCK_DATA</a> - <ul> - <li><a href="#metadata_block_streaminfo">METADATA_BLOCK_STREAMINFO</a></li> - <li><a href="#metadata_block_padding">METADATA_BLOCK_PADDING</a></li> - <li><a href="#metadata_block_application">METADATA_BLOCK_APPLICATION</a></li> - <li><a href="#metadata_block_seektable">METADATA_BLOCK_SEEKTABLE</a> - <ul> - <li><a href="#seekpoint">SEEKPOINT</a></li> - </ul> - </li> - <li><a href="#metadata_block_vorbis_comment">METADATA_BLOCK_VORBIS_COMMENT</a></li> - <li><a href="#metadata_block_cuesheet">METADATA_BLOCK_CUESHEET</a> - <ul> - <li><a href="#cuesheet_track">CUESHEET_TRACK</a> - <ul> - <li><a href="#cuesheet_track_index">CUESHEET_TRACK_INDEX</a></li> - </ul> - </li> - </ul> - </li> - <li><a href="#metadata_block_picture">METADATA_BLOCK_PICTURE</a></li> - </ul> - </li> - </ul> - </li> - </ul> - </li> - <li> - <ul> - <li><a href="#frame">FRAME</a> - <ul> - <li><a href="#frame_header">FRAME_HEADER</a></li> - <li><a href="#frame_footer">FRAME_FOOTER</a></li> - <li><a href="#subframe">SUBFRAME</a> - <ul> - <li><a href="#subframe_header">SUBFRAME_HEADER</a></li> - <li><a href="#subframe_constant">SUBFRAME_CONSTANT</a></li> - <li><a href="#subframe_fixed">SUBFRAME_FIXED</a></li> - <li><a href="#subframe_lpc">SUBFRAME_LPC</a></li> - <li><a href="#subframe_verbatim">SUBFRAME_VERBATIM</a> - <ul> - <li><a href="#residual">RESIDUAL</a> - <ul> - <li><a href="#partitioned_rice">RESIDUAL_CODING_METHOD_PARTITIONED_RICE</a> - <ul> - <li><a href="#rice_partition">RICE_PARTITION</a></li> - </ul> - </li> - <li><a href="#partitioned_rice2">RESIDUAL_CODING_METHOD_PARTITIONED_RICE2</a> - <ul> - <li><a href="#rice2_partition">RICE2_PARTITION</a></li> - </ul> - </li> - </ul> - </li> - </ul> - </li> - </ul> - </li> - </ul> - </li> - </ul> - </li> - </ul> - </li> - </ul> - <a name="acknowledgments"><font size="+1"><b><u>Acknowledgments</u></b></font></a><br /> - <br /> - FLAC owes much to the many people who have advanced the audio compression field so freely. For instance: - <ul> - <li> - <a href="http://svr-www.eng.cam.ac.uk/~ajr/">A. J. Robinson</a> for his work on <a href="http://svr-www.eng.cam.ac.uk/reports/abstracts/robinson_tr156.html">Shorten</a>; his paper is a good starting point on some of the basic methods used by FLAC. FLAC trivially extends and improves the fixed predictors, LPC coefficient quantization, and Rice coding used in Shorten. - </li> - <li> - <a href="https://web.archive.org/web/20040215005354/http://csi.usc.edu/faculty/golomb.html">S. W. Golomb</a> and Robert F. Rice; their universal codes are used by FLAC's entropy coder. - </li> - <li> - N. Levinson and J. Durbin; the reference encoder uses an algorithm developed and refined by them for determining the LPC coefficients from the autocorrelation coefficients. - </li> - <li> - And of course, <a href="http://en.wikipedia.org/wiki/Claude_Shannon">Claude Shannon</a> - </li> - </ul> - <a name="scope"><font size="+1"><b><u>Scope</u></b></font></a><br /> - <br /> - 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 <b>code</b> 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.<br /> - <br /> - 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.<br /> - <br /> - <a name="architecture"><font size="+1"><b><u>Architecture</u></b></font></a><br /> - <br /> - Similar to many audio coders, a FLAC encoder has the following stages: - <ul> - <li> - <a href="#blocking">Blocking</a>. The input is broken up into many contiguous blocks. With FLAC, the blocks may vary in size. The optimal size of the block is usually affected by many factors, including the sample rate, spectral characteristics over time, etc. Though FLAC allows the block size to vary within a stream, the reference encoder uses a fixed block size. - </li> - <li> - <a href="#interchannel">Interchannel Decorrelation</a>. In the case of stereo streams, the encoder will create mid and side signals based on the average and difference (respectively) of the left and right channels. The encoder will then pass the best form of the signal to the next stage. - </li> - <li> - <a href="#prediction">Prediction</a>. The block is passed through a prediction stage where the encoder tries to find a mathematical description (usually an approximate one) of the signal. This description is typically much smaller than the raw signal itself. Since the methods of prediction are known to both the encoder and decoder, only the parameters of the predictor need be included in the compressed stream. FLAC currently uses four different classes of predictors (described in the <a href="#prediction">prediction</a> section), but the format has reserved space for additional methods. FLAC allows the class of predictor to change from block to block, or even within the channels of a block. - </li> - <li> - <a href="#residualcoding">Residual coding</a>. If the predictor does not describe the signal exactly, the difference between the original signal and the predicted signal (called the error or residual signal) must be coded losslessy. If the predictor is effective, the residual signal will require fewer bits per sample than the original signal. FLAC currently uses only one method for encoding the residual (see the <a href="#residualcoding">Residual coding</a> section), but the format has reserved space for additional methods. FLAC allows the residual coding method to change from block to block, or even within the channels of a block. - </li> - </ul> - In addition, FLAC specifies a metadata system, which allows arbitrary information about the stream to be included at the beginning of the stream.<br /> - <br /> - <a name="definitions"><font size="+1"><b><u>Definitions</u></b></font></a><br /> - <br /> - 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. - <ul> - <li> - <b>Block</b>: One or more audio samples that span several channels. - </li> - <li> - <b>Subblock</b>: One or more audio samples within a channel. So a block contains one subblock for each channel, and all subblocks contain the same number of samples. - </li> - <li> - <b>Blocksize</b>: The number of samples in any of a block's subblocks. For example, a one second block sampled at 44.1KHz has a blocksize of 44100, regardless of the number of channels. - </li> - <li> - <b>Frame</b>: A frame header plus one or more subframes. - </li> - <li> - <b>Subframe</b>: A subframe header plus one or more encoded samples from a given channel. All subframes within a frame will contain the same number of samples. - </li> - </ul> - <a name="blocking"><font size="+1"><b><u>Blocking</u></b></font></a><br /> - <br /> - 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.<br /> - <br /> - 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.<br /> - <br /> - 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.<br /> - <br /> - <a name="interchannel"><font size="+1"><b><u>Interchannel Decorrelation</u></b></font></a><br /> - <br /> - 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. - <ul> - <li> - <b>Independent</b>. The left and right channels are coded independently. - </li> - <li> - <b>Mid-side</b>. The left and right channels are transformed into mid and side channels. The mid channel is the midpoint (average) of the left and right signals, and the side is the difference signal (left minus right). - </li> - <li> - <b>Left-side</b>. The left channel and side channel are coded. - </li> - <li> - <b>Right-side</b>. The right channel and side channel are coded - </li> - </ul> - 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.<br /> - <br /> - <a name="prediction"><font size="+1"><b><u>Prediction</u></b></font></a><br /> - <br /> - FLAC uses four methods for modeling the input signal: - <ul> - <li> - <b>Verbatim</b>. This is essentially a zero-order predictor of the signal. The predicted signal is zero, meaning the residual is the signal itself, and the compression is zero. This is the baseline against which the other predictors are measured. If you feed random data to the encoder, the verbatim predictor will probably be used for every subblock. Since the raw signal is not actually passed through the residual coding stage (it is added to the stream 'verbatim'), the encoding results will not be the same as a zero-order linear predictor. - </li> - <li> - <b>Constant</b>. This predictor is used whenever the subblock is pure DC ("digital silence"), i.e. a constant value throughout. The signal is run-length encoded and added to the stream. - </li> - <li> - <b>Fixed linear predictor</b>. FLAC uses a class of computationally-efficient fixed linear predictors (for a good description, see <a href="http://www.hpl.hp.com/techreports/1999/HPL-1999-144.pdf">audiopak</a> and <a href="http://svr-www.eng.cam.ac.uk/reports/abstracts/robinson_tr156.html">shorten</a>). FLAC adds a fourth-order predictor to the zero-to-third-order predictors used by Shorten. Since the predictors are fixed, the predictor order is the only parameter that needs to be stored in the compressed stream. The error signal is then passed to the residual coder. - </li> - <li> - <b>FIR Linear prediction</b>. For more accurate modeling (at a cost of slower encoding), FLAC supports up to 32nd order FIR linear prediction (again, for information on linear prediction, see <a href="http://www.hpl.hp.com/techreports/1999/HPL-1999-144.pdf">audiopak</a> and <a href="http://svr-www.eng.cam.ac.uk/reports/abstracts/robinson_tr156.html">shorten</a>). The reference encoder uses the Levinson-Durbin method for calculating the LPC coefficients from the autocorrelation coefficients, and the coefficients are quantized before computing the residual. Whereas encoders such as Shorten used a fixed quantization for the entire input, FLAC allows the quantized coefficient precision to vary from subframe to subframe. The FLAC reference encoder estimates the optimal precision to use based on the block size and dynamic range of the original signal. - </li> - </ul> - <a name="residualcoding"><font size="+1"><b><u>Residual Coding</u></b></font></a><br /> - <br /> - 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.)<br /> - <br /> - 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 <a href="http://www.hpl.hp.com/techreports/98/HPL-98-193.html">LOCO-I</a> and <a href="http://www.cs.tut.fi/~albert/Dev/pucrunch/packing.html">pucrunch</a> for descriptions of several universal codes.<br /> - <br /> - <a name="format_overview"><font size="+1"><b><u>Format</u></b></font></a><br /> - <br /> - 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.<br /> - <br /> - 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.<br /> - <br /> - Before the formal description of the stream, an overview might be helpful. - <ul> - <li> - A FLAC bitstream consists of the "fLaC" marker at the beginning of the stream, followed by a mandatory metadata block (called the STREAMINFO block), any number of other metadata blocks, then the audio frames. - </li> - <li> - FLAC supports up to 128 kinds of metadata blocks; currently the following are defined: - <ul> - <li><a name="def_STREAMINFO"><b>STREAMINFO</b></a>: This block has information about the whole stream, like sample rate, number of channels, total number of samples, etc. It must be present as the first metadata block in the stream. Other metadata blocks may follow, and ones that the decoder doesn't understand, it will skip.</li> - <li><a name="def_APPLICATION"><b>APPLICATION</b></a>: This block is for use by third-party applications. The only mandatory field is a 32-bit identifier. This ID is granted upon request to an application by the FLAC maintainers. The remainder is of the block is defined by the registered application. Visit the <a href="id.html">registration page</a> if you would like to register an ID for your application with FLAC.</li> - <li><a name="def_PADDING"><b>PADDING</b></a>: This block allows for an arbitrary amount of padding. The contents of a PADDING block have no meaning. This block is useful when it is known that metadata will be edited after encoding; the user can instruct the encoder to reserve a PADDING block of sufficient size so that when metadata is added, it will simply overwrite the padding (which is relatively quick) instead of having to insert it into the right place in the existing file (which would normally require rewriting the entire file).</li> - <li><a name="def_SEEKTABLE"><b>SEEKTABLE</b></a>: This is an optional block for storing seek points. It is possible to seek to any given sample in a FLAC stream without a seek table, but the delay can be unpredictable since the bitrate may vary widely within a stream. By adding seek points to a stream, this delay can be significantly reduced. Each seek point takes 18 bytes, so 1% resolution within a stream adds less than 2k. There can be only one SEEKTABLE in a stream, but the table can have any number of seek points. There is also a special 'placeholder' seekpoint which will be ignored by decoders but which can be used to reserve space for future seek point insertion.</li> - <li><a name="def_VORBIS_COMMENT"><b>VORBIS_COMMENT</b></a>: This block is for storing a list of human-readable name/value pairs. Values are encoded using UTF-8. It is an implementation of the <a href="http://xiph.org/vorbis/doc/v-comment.html">Vorbis comment specification</a> (without the framing bit). This is the only officially supported tagging mechanism in FLAC. There may be only one VORBIS_COMMENT block in a stream. In some external documentation, Vorbis comments are called FLAC tags to lessen confusion.</li> - <li><a name="def_CUESHEET"><b>CUESHEET</b></a>: This block is for storing various information that can be used in a cue sheet. It supports track and index points, compatible with Red Book CD digital audio discs, as well as other CD-DA metadata such as media catalog number and track ISRCs. The CUESHEET block is especially useful for backing up CD-DA discs, but it can be used as a general purpose cueing mechanism for playback.</li> - <li><a name="def_PICTURE"><b>PICTURE</b></a>: This block is for storing pictures associated with the file, most commonly cover art from CDs. There may be more than one PICTURE block in a file. The picture format is similar to the <a href="http://www.id3.org/id3v2.4.0-frames">APIC frame in ID3v2</a>. The PICTURE block has a type, MIME type, and UTF-8 description like ID3v2, and supports external linking via URL (though this is discouraged). The differences are that there is no uniqueness constraint on the description field, and the MIME type is mandatory. The FLAC PICTURE block also includes the resolution, color depth, and palette size so that the client can search for a suitable picture without having to scan them all.</li> - </ul> - </li> - <li> - The audio data is composed of one or more audio frames. Each frame consists of a frame header, which contains a sync code, information about the frame like the block size, sample rate, number of channels, et cetera, and an 8-bit CRC. The frame header also contains either the sample number of the first sample in the frame (for variable-blocksize streams), or the frame number (for fixed-blocksize streams). This allows for fast, sample-accurate seeking to be performed. Following the frame header are encoded subframes, one for each channel, and finally, the frame is zero-padded to a byte boundary. Each subframe has its own header that specifies how the subframe is encoded. - </li> - <li> - Since a decoder may start decoding in the middle of a stream, there must be a method to determine the start of a frame. A 14-bit sync code begins each frame. The sync code will not appear anywhere else in the frame header. However, since it may appear in the subframes, the decoder has two other ways of ensuring a correct sync. The first is to check that the rest of the frame header contains no invalid data. Even this is not foolproof since valid header patterns can still occur within the subframes. The decoder's final check is to generate an 8-bit CRC of the frame header and compare this to the CRC stored at the end of the frame header. - </li> - <li> - Again, since a decoder may start decoding at an arbitrary frame in the stream, each frame header must contain some basic information about the stream because the decoder may not have access to the STREAMINFO metadata block at the start of the stream. This information includes sample rate, bits per sample, number of channels, etc. Since the frame header is pure overhead, it has a direct effect on the compression ratio. To keep the frame header as small as possible, FLAC uses lookup tables for the most commonly used values for frame parameters. For instance, the sample rate part of the frame header is specified using 4 bits. Eight of the bit patterns correspond to the commonly used sample rates of 8/16/22.05/24/32/44.1/48/96 kHz. However, odd sample rates can be specified by using one of the 'hint' bit patterns, directing the decoder to find the exact sample rate at the end of the frame header. The same method is used for specifying the block size and bits per sample. In this way, the frame header size stays small for all of the most common forms of audio data. - </li> - <li> - Individual subframes (one for each channel) are coded separately within a frame, and appear serially in the stream. In other words, the encoded audio data is NOT channel-interleaved. This reduces decoder complexity at the cost of requiring larger decode buffers. Each subframe has its own header specifying the attributes of the subframe, like prediction method and order, residual coding parameters, etc. The header is followed by the encoded audio data for that channel. - </li> - <li> - <a name="subset">FLAC</a> specifies a subset of itself as the Subset format. The purpose of this is to ensure that any streams encoded according to the Subset are truly "streamable", meaning that a decoder that cannot seek within the stream can still pick up in the middle of the stream and start decoding. It also makes hardware decoder implementations more practical by limiting the encoding parameters such that decoder buffer sizes and other resource requirements can be easily determined. <span class="commandname">flac</span> generates Subset streams by default unless the "--lax" command-line option is used. The Subset makes the following limitations on what may be used in the stream: - <ul> - <li> - The blocksize bits in the <a href="#frame_header">frame header</a> must be 0001-1110. The blocksize must be <=16384; if the sample rate is <= 48000Hz, the blocksize must be <=4608. - </li> - <li> - The sample rate bits in the <a href="#frame_header">frame header</a> must be 0001-1110. - </li> - <li> - The bits-per-sample bits in the <a href="#frame_header">frame header</a> must be 001-111. - </li> - <li> - If the sample rate is <= 48000Hz, the filter order in <a href="#subframe_lpc">LPC subframes</a> must be less than or equal to 12, i.e. the subframe type bits in the <a href="#subframe_header">subframe header</a> may not be 101100-111111. - </li> - <li> - The Rice partition order in a <a href="#partitioned_rice">Rice-coded residual section</a> must be less than or equal to 8. - </li> - </ul> - </li> - </ul> - - 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.<br /> - </div> - <div class="box_footer"></div> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="stream"><font size="+1"><b>STREAM</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - "fLaC", the FLAC stream marker in ASCII, meaning byte 0 of the stream is 0x66, followed by 0x4C 0x61 0x43 - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#metadata_block_streaminfo"><i>METADATA_BLOCK</i></a> - </td> - <td> - This is the mandatory STREAMINFO metadata block that has the basic properties of the stream - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#metadata_block"><i>METADATA_BLOCK</i></a>* - </td> - <td> - Zero or more metadata blocks - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#frame"><i>FRAME</i></a>+ - </td> - <td> - One or more audio frames - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block"><font size="+1"><b>METADATA_BLOCK</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#metadata_block_header"><i>METADATA_BLOCK_HEADER</i></a> - </td> - <td> - A block header that specifies the type and size of the metadata block data. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#metadata_block_data"><i>METADATA_BLOCK_DATA</i></a> - </td> - <td> - - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_header"><font size="+1"><b>METADATA_BLOCK_HEADER</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1> - </td> - <td> - Last-metadata-block flag: '1' if this block is the last metadata block before the audio blocks, '0' otherwise. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <7> - </td> - <td> - BLOCK_TYPE<br /> - <ul> - <li> - <tt>0</tt> : STREAMINFO - </li> - <li> - <tt>1</tt> : PADDING - </li> - <li> - <tt>2</tt> : APPLICATION - </li> - <li> - <tt>3</tt> : SEEKTABLE - </li> - <li> - <tt>4</tt> : VORBIS_COMMENT - </li> - <li> - <tt>5</tt> : CUESHEET - </li> - <li> - <tt>6</tt> : PICTURE - </li> - <li> - <tt>7-126</tt> : reserved - </li> - <li> - <tt>127</tt> : invalid, to avoid confusion with a frame sync code - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <24> - </td> - <td> - Length (in bytes) of metadata to follow (does not include the size of the METADATA_BLOCK_HEADER) - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_data"><font size="+1"><b>METADATA_BLOCK_DATA</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#metadata_block_streaminfo"><i>METADATA_BLOCK_STREAMINFO</i></a><br /> - || <a href="#metadata_block_padding"><i>METADATA_BLOCK_PADDING</i></a><br /> - || <a href="#metadata_block_application"><i>METADATA_BLOCK_APPLICATION</i></a><br /> - || <a href="#metadata_block_seektable"><i>METADATA_BLOCK_SEEKTABLE</i></a><br /> - || <a href="#metadata_block_vorbis_comment"><i>METADATA_BLOCK_VORBIS_COMMENT</i></a><br /> - || <a href="#metadata_block_cuesheet"><i>METADATA_BLOCK_CUESHEET</i></a><br /> - || <a href="#metadata_block_picture"><i>METADATA_BLOCK_PICTURE</i></a> - </td> - <td> - The block data must match the block type in the block header. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_streaminfo"><font size="+1"><b>METADATA_BLOCK_STREAMINFO</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <16> - </td> - <td> - The minimum block size (in samples) used in the stream. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <16> - </td> - <td> - The maximum block size (in samples) used in the stream. (Minimum blocksize == maximum blocksize) implies a fixed-blocksize stream. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <24> - </td> - <td> - The minimum frame size (in bytes) used in the stream. May be 0 to imply the value is not known. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <24> - </td> - <td> - The maximum frame size (in bytes) used in the stream. May be 0 to imply the value is not known. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <20> - </td> - <td> - Sample rate in Hz. 20 bits are available, the maximum sample rate being 1048575Hz. Also, a value of 0 is invalid. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <3> - </td> - <td> - (number of channels)-1. FLAC supports from 1 to 8 channels - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <5> - </td> - <td> - (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. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <36> - </td> - <td> - 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. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <128> - </td> - <td> - 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. - </td> - </tr> - <tr> - <td> - </td> - <td bgcolor="#F4F4CC"> - <font size="+1">NOTES</font><br /> - <ul> - <li> - 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. - </li> - </ul> - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_padding"><font size="+1"><b>METADATA_BLOCK_PADDING</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n> - </td> - <td> - n '0' bits (n must be a multiple of 8) - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_application"><font size="+1"><b>METADATA_BLOCK_APPLICATION</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - Registered application ID. (Visit the <a href="id.html">registration page</a> to register an ID with FLAC.) - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n> - </td> - <td> - Application data (n must be a multiple of 8) - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_seektable"><font size="+1"><b>METADATA_BLOCK_SEEKTABLE</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#seekpoint"><i>SEEKPOINT</i></a>+ - </td> - <td> - One or more seek points. - </td> - </tr> - <tr> - <td> - </td> - <td bgcolor="#F4F4CC"> - <font size="+1">NOTE</font><br /> - <ul> - <li> - The number of seek points is implied by the metadata header 'length' field, i.e. equal to length / 18. - </li> - </ul> - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="seekpoint"><font size="+1"><b>SEEKPOINT</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <64> - </td> - <td> - Sample number of first sample in the target frame, or 0xFFFFFFFFFFFFFFFF for a placeholder point. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <64> - </td> - <td> - Offset (in bytes) from the first byte of the first frame header to the first byte of the target frame's header. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <16> - </td> - <td> - Number of samples in the target frame. - </td> - </tr> - <tr> - <td> - </td> - <td bgcolor="#F4F4CC"> - <font size="+1">NOTES</font><br /> - <ul> - <li> - For placeholder points, the second and third field values are undefined. - </li> - <li> - Seek points within a table must be sorted in ascending order by sample number. - </li> - <li> - Seek points within a table must be unique by sample number, with the exception of placeholder points. - </li> - <li> - 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. - </li> - </ul> - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_vorbis_comment"><font size="+1"><b>METADATA_BLOCK_VORBIS_COMMENT</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n> - </td> - <td> - Also known as FLAC tags, the contents of a vorbis comment packet as specified <a href="http://www.xiph.org/vorbis/doc/v-comment.html">here</a> (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. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_cuesheet"><font size="+1"><b>METADATA_BLOCK_CUESHEET</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <128*8> - </td> - <td> - 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. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <64> - </td> - <td> - 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. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1> - </td> - <td> - <tt>1</tt> if the CUESHEET corresponds to a Compact Disc, else <tt>0</tt>. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <7+258*8> - </td> - <td> - Reserved. All bits must be set to zero. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <8> - </td> - <td> - 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). - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#cuesheet_track"><i>CUESHEET_TRACK</i></a>+ - </td> - <td> - 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. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="cuesheet_track"><font size="+1"><b>CUESHEET_TRACK</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <64> - </td> - <td> - 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). - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <8> - </td> - <td> - 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. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <12*8> - </td> - <td> - Track ISRC. This is a 12-digit alphanumeric code; see <a href="http://isrc.ifpi.org/">here</a> and <a href="http://www.disctronics.co.uk/technology/cdaudio/cdaud_isrc.htm">here</a>. A value of 12 ASCII NUL characters may be used to denote absence of an ISRC. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1> - </td> - <td> - The track type: 0 for audio, 1 for non-audio. This corresponds to the CD-DA Q-channel control bit 3. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1> - </td> - <td> - 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 <a href="http://www.chipchapin.com/CDMedia/cdda9.php3">here</a>. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <6+13*8> - </td> - <td> - Reserved. All bits must be set to zero. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <8> - </td> - <td> - 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. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#cuesheet_track_index"><i>CUESHEET_TRACK_INDEX</i></a>+ - </td> - <td> - For all tracks except the lead-out track, one or more track index points. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="cuesheet_track_index"><font size="+1"><b>CUESHEET_TRACK_INDEX</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <64> - </td> - <td> - 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. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <8> - </td> - <td> - 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. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <3*8> - </td> - <td> - Reserved. All bits must be set to zero. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="metadata_block_picture"><font size="+1"><b>METADATA_BLOCK_PICTURE</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - The picture type according to the ID3v2 APIC frame:<br /> - <ul> - <li>0 - Other</li> - <li>1 - 32x32 pixels 'file icon' (PNG only)</li> - <li>2 - Other file icon</li> - <li>3 - Cover (front)</li> - <li>4 - Cover (back)</li> - <li>5 - Leaflet page</li> - <li>6 - Media (e.g. label side of CD)</li> - <li>7 - Lead artist/lead performer/soloist</li> - <li>8 - Artist/performer</li> - <li>9 - Conductor</li> - <li>10 - Band/Orchestra</li> - <li>11 - Composer</li> - <li>12 - Lyricist/text writer</li> - <li>13 - Recording Location</li> - <li>14 - During recording</li> - <li>15 - During performance</li> - <li>16 - Movie/video screen capture</li> - <li>17 - A bright coloured fish</li> - <li>18 - Illustration</li> - <li>19 - Band/artist logotype</li> - <li>20 - Publisher/Studio logotype</li> - </ul> - Others are reserved and should not be used. There may only be one each of picture type 1 and 2 in a file. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - The length of the MIME type string in bytes. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n*8> - </td> - <td> - The MIME type string, in printable ASCII characters 0x20-0x7e. The MIME type may also be <tt>--></tt> to signify that the data part is a URL of the picture instead of the picture data itself. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - The length of the description string in bytes. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n*8> - </td> - <td> - The description of the picture, in UTF-8. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - The width of the picture in pixels. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - The height of the picture in pixels. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - The color depth of the picture in bits-per-pixel. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - For indexed-color pictures (e.g. GIF), the number of colors used, or <tt>0</tt> for non-indexed pictures. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <32> - </td> - <td> - The length of the picture data in bytes. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n*8> - </td> - <td> - The binary picture data. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="frame"><font size="+1"><b>FRAME</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#frame_header"><i>FRAME_HEADER</i></a> - </td> - <td> - - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#subframe"><i>SUBFRAME</i></a>+ - </td> - <td> - One SUBFRAME per channel. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <?> - </td> - <td> - Zero-padding to byte alignment. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#frame_footer"><i>FRAME_FOOTER</i></a> - </td> - <td> - - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="frame_header"><font size="+1"><b>FRAME_HEADER</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <14> - </td> - <td> - Sync code '<tt>11111111111110</tt>' - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1> - </td> - <td> - Reserved: <a href="#frame_header_notes">[1]</a><br /> - <ul> - <li> - <tt>0</tt> : mandatory value - </li> - <li> - <tt>1</tt> : reserved for future use - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1> - </td> - <td> - Blocking strategy: <a href="#frame_header_notes">[2]</a> <a href="#frame_header_notes">[3]</a><br /> - <ul> - <li> - <tt>0</tt> : fixed-blocksize stream; frame header encodes the frame number - </li> - <li> - <tt>1</tt> : variable-blocksize stream; frame header encodes the sample number - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <4> - </td> - <td> - Block size in inter-channel samples:<br /> - <ul> - <li> - <tt>0000</tt> : reserved - </li> - <li> - <tt>0001</tt> : 192 samples - </li> - <li> - <tt>0010-0101</tt> : 576 * (2^(n-2)) samples, i.e. 576/1152/2304/4608 - </li> - <li> - <tt>0110</tt> : get 8 bit (blocksize-1) from end of header - </li> - <li> - <tt>0111</tt> : get 16 bit (blocksize-1) from end of header - </li> - <li> - <tt>1000-1111</tt> : 256 * (2^(n-8)) samples, i.e. 256/512/1024/2048/4096/8192/16384/32768 - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <4> - </td> - <td> - Sample rate:<br /> - <ul> - <li> - <tt>0000</tt> : get from STREAMINFO metadata block - </li> - <li> - <tt>0001</tt> : 88.2kHz - </li> - <li> - <tt>0010</tt> : 176.4kHz - </li> - <li> - <tt>0011</tt> : 192kHz - </li> - <li> - <tt>0100</tt> : 8kHz - </li> - <li> - <tt>0101</tt> : 16kHz - </li> - <li> - <tt>0110</tt> : 22.05kHz - </li> - <li> - <tt>0111</tt> : 24kHz - </li> - <li> - <tt>1000</tt> : 32kHz - </li> - <li> - <tt>1001</tt> : 44.1kHz - </li> - <li> - <tt>1010</tt> : 48kHz - </li> - <li> - <tt>1011</tt> : 96kHz - </li> - <li> - <tt>1100</tt> : get 8 bit sample rate (in kHz) from end of header - </li> - <li> - <tt>1101</tt> : get 16 bit sample rate (in Hz) from end of header - </li> - <li> - <tt>1110</tt> : get 16 bit sample rate (in tens of Hz) from end of header - </li> - <li> - <tt>1111</tt> : invalid, to prevent sync-fooling string of 1s - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <4> - </td> - <td> - Channel assignment - <ul> - <li> - <tt>0000-0111</tt> : (number of independent channels)-1. Where defined, the channel order follows SMPTE/ITU-R recommendations. The assignments are as follows: - <ul> - <li>1 channel: mono</li> - <li>2 channels: left, right</li> - <li>3 channels: left, right, center</li> - <li>4 channels: front left, front right, back left, back right</li> - <li>5 channels: front left, front right, front center, back/surround left, back/surround right</li> - <li>6 channels: front left, front right, front center, LFE, back/surround left, back/surround right</li> - <li>7 channels: front left, front right, front center, LFE, back center, side left, side right</li> - <li>8 channels: front left, front right, front center, LFE, back left, back right, side left, side right</li> - </ul> - </li> - <li> - <tt>1000</tt> : left/side stereo: channel 0 is the left channel, channel 1 is the side(difference) channel - </li> - <li> - <tt>1001</tt> : right/side stereo: channel 0 is the side(difference) channel, channel 1 is the right channel - </li> - <li> - <tt>1010</tt> : mid/side stereo: channel 0 is the mid(average) channel, channel 1 is the side(difference) channel - </li> - <li> - <tt>1011-1111</tt> : reserved - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <3> - </td> - <td> - Sample size in bits: <a href="#frame_header_notes">[5]</a><br /> - <ul> - <li> - <tt>000</tt> : get from STREAMINFO metadata block - </li> - <li> - <tt>001</tt> : 8 bits per sample - </li> - <li> - <tt>010</tt> : 12 bits per sample - </li> - <li> - <tt>011</tt> : reserved - </li> - <li> - <tt>100</tt> : 16 bits per sample - </li> - <li> - <tt>101</tt> : 20 bits per sample - </li> - <li> - <tt>110</tt> : 24 bits per sample - </li> - <li> - <tt>111</tt> : reserved - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1> - </td> - <td> - Reserved:<br /> - <ul> - <li> - <tt>0</tt> : mandatory value - </li> - <li> - <tt>1</tt> : reserved for future use - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <?> - </td> - <td> - if(variable blocksize)<br /> - <8-56>:"UTF-8" coded sample number (decoded number is 36 bits) <a href="#frame_header_notes">[4]</a><br /> - else<br /> - <8-48>:"UTF-8" coded frame number (decoded number is 31 bits) <a href="#frame_header_notes">[4]</a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <?> - </td> - <td> - if(blocksize bits == 011x)<br /> - 8/16 bit (blocksize-1) - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <?> - </td> - <td> - if(sample rate bits == 11xx)<br /> - 8/16 bit sample rate - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <8> - </td> - <td> - CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0) of everything before the crc, including the sync code - </td> - </tr> - <tr> - <td> - </td> - <td bgcolor="#F4F4CC"> - <a name="frame_header_notes"><font size="+1">NOTES</font></a><br /> - <ol> - <li> - This bit must remain reserved for <tt>0</tt> in order for a FLAC frame's initial 15 bits to be distinguishable from the start of an MPEG audio frame (<a href="http://lists.xiph.org/pipermail/flac-dev/2008-December/002607.html">see also</a>). - </li> - <li> - The "blocking strategy" bit must be the same throughout the entire stream. - </li> - <li> - The "blocking strategy" bit determines how to calculate the sample number of the first sample in the frame. If the bit is <tt>0</tt> (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 <tt>1</tt> (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). - </li> - <li> - 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. - </li> - <li> - 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. - </li> - </ol> - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="frame_footer"><font size="+1"><b>FRAME_FOOTER</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <16> - </td> - <td> - 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 - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="subframe"><font size="+1"><b>SUBFRAME</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#subframe_header"><i>SUBFRAME_HEADER</i></a> - </td> - <td> - - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#subframe_constant"><i>SUBFRAME_CONSTANT</i></a><br />|| <a href="#subframe_fixed"><i>SUBFRAME_FIXED</i></a><br />|| <a href="#subframe_lpc"><i>SUBFRAME_LPC</i></a><br />|| <a href="#subframe_verbatim"><i>SUBFRAME_VERBATIM</i></a> - </td> - <td valign="top"> - The SUBFRAME_HEADER specifies which one. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="subframe_header"><font size="+1"><b>SUBFRAME_HEADER</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1> - </td> - <td> - Zero bit padding, to prevent sync-fooling string of 1s - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <6> - </td> - <td> - Subframe type: - <ul> - <li> - <tt>000000</tt> : <a href="#subframe_constant">SUBFRAME_CONSTANT</a> - </li> - <li> - <tt>000001</tt> : <a href="#subframe_verbatim">SUBFRAME_VERBATIM</a> - </li> - <li> - <tt>00001x</tt> : reserved - </li> - <li> - <tt>0001xx</tt> : reserved - </li> - <li> - <tt>001xxx</tt> : if(xxx <= 4) <a href="#subframe_fixed">SUBFRAME_FIXED</a>, xxx=order ; else reserved - </li> - <li> - <tt>01xxxx</tt> : reserved - </li> - <li> - <tt>1xxxxx</tt> : <a href="#subframe_lpc">SUBFRAME_LPC</a>, xxxxx=order-1 - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <1+k> - </td> - <td> - 'Wasted bits-per-sample' flag: - <ul> - <li> - <tt>0</tt> : no wasted bits-per-sample in source subblock, k=0 - </li> - <li> - <tt>1</tt> : k wasted bits-per-sample in source subblock, k-1 follows, unary coded; e.g. k=3 => 001 follows, k=7 => 0000001 follows. - </li> - </ul> - 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. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="subframe_constant"><font size="+1"><b>SUBFRAME_CONSTANT</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n> - </td> - <td> - Unencoded constant value of the subblock, n = frame's bits-per-sample. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="subframe_fixed"><font size="+1"><b>SUBFRAME_FIXED</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n> - </td> - <td> - Unencoded warm-up samples (n = frame's bits-per-sample * predictor order). - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#residual"><i>RESIDUAL</i></a> - </td> - <td> - Encoded residual - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="subframe_lpc"><font size="+1"><b>SUBFRAME_LPC</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n> - </td> - <td> - Unencoded warm-up samples (n = frame's bits-per-sample * lpc order). - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <4> - </td> - <td> - (Quantized linear predictor coefficients' precision in bits)-1 (1111 = invalid). - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <5> - </td> - <td> - 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). - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n> - </td> - <td> - Unencoded predictor coefficients (n = qlp coeff precision * lpc order) (NOTE: the coefficients are signed two's-complement). - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#residual"><i>RESIDUAL</i></a> - </td> - <td> - Encoded residual - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="subframe_verbatim"><font size="+1"><b>SUBFRAME_VERBATIM</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <n*i> - </td> - <td> - Unencoded subblock; n = frame's bits-per-sample, i = frame's blocksize. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="residual"><font size="+1"><b>RESIDUAL</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <2> - </td> - <td> - Residual coding method:<br /> - <ul> - <li> - <tt>00</tt> : partitioned Rice coding with 4-bit Rice parameter; RESIDUAL_CODING_METHOD_PARTITIONED_RICE follows - </li> - <li> - <tt>01</tt> : partitioned Rice coding with 5-bit Rice parameter; RESIDUAL_CODING_METHOD_PARTITIONED_RICE2 follows - </li> - <li> - <tt>10-11</tt> : reserved - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#partitioned_rice"><i>RESIDUAL_CODING_METHOD_PARTITIONED_RICE</i></a> ||<br /> - <a href="#partitioned_rice2"><i>RESIDUAL_CODING_METHOD_PARTITIONED_RICE2</i></a> - </td> - <td> - - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="partitioned_rice"><font size="+1"><b>RESIDUAL_CODING_METHOD_PARTITIONED_RICE</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <4> - </td> - <td> - Partition order. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#rice_partition"><i>RICE_PARTITION</i></a>+ - </td> - <td> - There will be 2^order partitions. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="rice_partition"><font size="+1"><b>RICE_PARTITION</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <4(+5)> - </td> - <td> - Encoding parameter:<br /> - <ul> - <li> - <tt>0000-1110</tt> : Rice parameter. - </li> - <li> - <tt>1111</tt> : Escape code, meaning the partition is in unencoded binary form using n bits per sample; n follows as a 5-bit number. - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <?> - </td> - <td> - Encoded residual. The number of samples (n) in the partition is determined as follows:<br /> - <ul> - <li> - partition size = (frame's blocksize / (2^partition order)) - </li> - <li> - for first partition of the subframe, n = partition size - predictor - </li> - <li> - for remaining partitions, n = partition size - </li> - </ul> - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="partitioned_rice2"><font size="+1"><b>RESIDUAL_CODING_METHOD_PARTITIONED_RICE2</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <4> - </td> - <td> - Partition order. - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <a href="#rice2_partition"><i>RICE2_PARTITION</i></a>+ - </td> - <td> - There will be 2^order partitions. - </td> - </tr> - </table> - </td></tr></table> -</div> - -<br /> - -<div class="box"> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td colspan="2" bgcolor="#D3D4C5"> - <a name="rice2_partition"><font size="+1"><b>RICE2_PARTITION</b></font></a> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <5(+5)> - </td> - <td> - Encoding parameter:<br /> - <ul> - <li> - <tt>00000-11110</tt> : Rice parameter. - </li> - <li> - <tt>11111</tt> : Escape code, meaning the partition is in unencoded binary form using n bits per sample; n follows as a 5-bit number. - </li> - </ul> - </td> - </tr> - <tr> - <td align="right" valign="top" bgcolor="#F4F4CC"> - <?> - </td> - <td> - Encoded residual. The number of samples (n) in the partition is determined as follows:<br /> - <ul> - <li> - partition size = (frame's blocksize / (2^partition order)) - </li> - <li> - for first partition of the subframe, n = partition size - predictor - </li> - <li> - for remaining partitions, n = partition size - </li> - </ul> - </td> - </tr> - </table> - </td></tr></table> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - id</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - register - </div> - <div class="box_header"></div> - <div class="box_body"> - FLAC allows third-party applications to register an ID for use with FLAC <a href="format.html#def_APPLICATION">APPLICATION metadata blocks</a>. <a href="http://lists.xiph.org/mailman/listinfo/flac-dev">Contact the FLAC-dev mailinglist</a> 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.<br /> - <br /> - 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.<br /> - <br /> - 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.<br /> - </div> - <div class="box_footer"></div> -</div> - -<br /> - -<div class="box"> - <div class="box_title"> - <a name="directory">id directory</a> - </div> - <div class="box_header"></div> - <div class="box_body"> - Here is a list of all registered IDs and their applications:<br /> - <br /> - <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td> - <table width="100%" border="1" bgcolor="#EEEED4"> - <tr> - <td bgcolor="#D3D4C5"> - <font size="+1"><b>ID</b></font> - </td> - <td bgcolor="#D3D4C5"> - <font size="+1"><b>Application</b></font> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>41544348 - "ATCH"</tt> - </td> - <td> - <a href="http://firestuff.org/flacfile/">FlacFile</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>42534F4C - "BSOL"</tt> - </td> - <td> - beSolo - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>42554753 - "BUGS"</tt> - </td> - <td> - <a href="http://www.neowizbugs.com/">Bugs Player</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>43756573 - "Cues"</tt> - </td> - <td> - <a href="http://www.goldwave.com">GoldWave</a> cue points (<a href="http://www.goldwave.com/developer.php">specification</a>) - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>46696361 - "Fica"</tt> - </td> - <td> - <a href="http://www.enfis.it/details.php?id=24">CUE Splitter</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>46746F6C - "Ftol"</tt> - </td> - <td> - <a href="http://flac-tools.sourceforge.net/">flac-tools</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>4D4F5442 - "MOTB"</tt> - </td> - <td> - <a href="http://www.motb.org/">MOTB MetaCzar</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>4D505345 - "MPSE"</tt> - </td> - <td> - <a href="http://www.3delite.hu/MP3SE/index.html">MP3 Stream Editor</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>4D754D4C - "MuML"</tt> - </td> - <td> - MusicML: Music Metadata Language - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>52494646 - "RIFF"</tt> - </td> - <td> - Sound Devices RIFF chunk storage - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>5346464C - "SFFL"</tt> - </td> - <td> - Sound Font FLAC - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>534F4E59 - "SONY"</tt> - </td> - <td> - <a href="http://www.sonycreativesoftware.com/">Sony Creative Software</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>5351455A - "SQEZ"</tt> - </td> - <td> - flacsqueeze - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>54745776 - "TtWv"</tt> - </td> - <td> - <a href="http://twistedwave.com/">TwistedWave</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>55495453 - "UITS"</tt> - </td> - <td> - UITS Embedding tools - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>61696666 - "aiff"</tt> - </td> - <td> - FLAC AIFF chunk storage - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>696D6167 - "imag"</tt> - </td> - <td> - <a href="http://www.singingtree.com/software/">flac-image</a> application for storing arbitrary files in APPLICATION metadata blocks - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>7065656D - "peem"</tt> - </td> - <td> - <a href="http://peem.iconoclast.net/">Parseable Embedded Extensible Metadata</a> (<a href="http://peem.iconoclast.net/1.0/">specification</a>) - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>71667374 - "qfst"</tt> - </td> - <td> - <a href="http://qflacstudio.sourceforge.net/">QFLAC Studio</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>72696666 - "riff"</tt> - </td> - <td> - FLAC RIFF chunk storage - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>74756E65 - "tune"</tt> - </td> - <td> - <a href="http://www.tagtuner.com/">TagTuner</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>78626174 - "xbat"</tt> - </td> - <td> - <a href="http://xbat.org/">XBAT</a> - </td> - </tr> - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - <tt>786D6364 - "xmcd"</tt> - </td> - <td> - <a href="http://www.amb.org/xmcd/">xmcd</a> - </td> - </tr> - <!-- - <tr> - <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC"> - deadbeef - </td> - <td> - <a href="x">Application1</a> (<a href="y">specification</a>) - </td> - </tr> - --> - </table> - </td></tr></table> - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2000-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - Free Lossless Audio Codec</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - home | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<table border="0" cellpadding="0" cellspacing="0"> - <tr> - <td> - - <div class="box"> - <div class="box_title"> - <a name="what_is_flac">what is FLAC?</a> - </div> - <div class="box_header"></div> - <div class="box_body"> - <b>Please note: This is the source-code documentation, for more general information on FLAC, please visit <a href="http://xiph.org/flac">the on-line FLAC homepage</a></b><br /> - <br /> - 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 <a href="http://xiph.org/flac/links.html#hardware">supported devices</a>) just like you would an MP3 file.<br /> - <br /> - FLAC stands out as the <a href="http://xiph.org/flac/comparison.html">fastest and most widely supported lossless audio codec</a>, 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.<br /> - <br /> - See <a href="features.html">About FLAC</a> for more, or <a href="http://xiph.org/flac/documentation_tasks.html">Using FLAC</a> for how to play FLAC files, rip CDs to FLAC, etc. - </div> - <div class="box_footer"></div> - </div> - - </td> - </tr> -</table> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2000-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2004-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - license</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - license - </div> - <div class="box_header"></div> - <div class="box_body"> - FLAC is a free codec in the fullest sense. This page explicitly states all that you may do with the format and software.<br /> - <br /> - 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.<br /> - <br /> - The FLAC project also makes available software that implements the formats, which is distributed according to <a href="http://opensource.org/docs/definition.php">Open Source</a> licenses as follows:<br /> - <br /> - The reference implementation libraries are licensed under the New <a href="https://gitlab.xiph.org/xiph/flac/-/blob/master/COPYING.Xiph">BSD License</a>. 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 <span class="commandname">libFLAC</span> and <span class="commandname">libFLAC++</span>.<br /> - <br /> - The rest of the software that the FLAC project provides is licensed under the <a href="http://www.gnu.org/licenses/licenses.html#GPL">GNU General Public License</a> (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.<br /> - <br /> - Neither the FLAC nor Ogg FLAC formats nor any of the implemented encoding/decoding methods are covered by any known patent.<br /> - <br /> - 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 <a href="http://speex.org/fsos/">Speex</a> and <a href="http://www.vorbis.com/faq/#flic">Vorbis</a> license pages.<br /> - <br /> - If you would like to redistribute parts or all of FLAC under different terms, <a href="http://lists.xiph.org/mailman/listinfo/flac-dev">contact the FLAC-dev mailinglist</a>. - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2004-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> 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 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Copyright (c) 2004-2009 Josh Coalson --> -<!-- Copyright (c) 2011-2022 Xiph.Org Foundation --> -<!-- 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 --> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <meta name="author" content="Josh Coalson" /> - <meta name="description" content="A free, open source codec for lossless audio compression and decompression" /> - <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" /> - <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" /> - <link rel="stylesheet" type="text/css" href="flac.css" /> - <title>FLAC - ogg mapping</title> -</head> - -<body> - -<div class="logo"> - <a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a> -</div> - -<div class="above_nav"></div> - -<div class="navbar"> - <a href="index.html">home</a> | - <a href="faq.html">faq</a> | - <a href="documentation.html">documentation</a> | - <a href="developers.html">developers</a> | - <a href="changelog.html">changelog</a> | - <a href="http://xiph.org/flac">more</a> -</div> - -<div class="below_nav"></div> - -<div class="box"> - <div class="box_title"> - ogg mapping - </div> - <div class="box_header"></div> - <div class="box_body"> - This page specifies the way in which compressed FLAC data is encapsulated in an Ogg transport layer. It assumes basic knowledge of the <a href="format.html">FLAC format</a> and <a href="http://xiph.org/vorbis/doc/oggstream.html">Ogg structure</a> and <a href="http://xiph.org/vorbis/doc/framing.html">framing</a>.<br /> - <br /> - 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.<br /> - <br /> - 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).<br /> - <br /> - 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.<br /> - <br /> - 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.<br /> - <br /> - 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.<br /> - <br /> - 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 <span class="commandname">flac</span> versions before 1.1.1 should be decoded and re-encoded with <span class="commandname">flac</span> 1.1.1 or later (<span class="commandname">flac</span> 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.<br /> - <br /> - Version 1.0 of the FLAC-to-Ogg mapping then is a simple identifying header followed by pure native FLAC data, as follows: - <ul> - <li> - The first packet of a stream consists of: - <ul> - <li>The one-byte packet type 0x7F</li> - <li>The four-byte ASCII signature "FLAC", i.e. 0x46, 0x4C, 0x41, 0x43</li> - <li>A one-byte binary major version number for the mapping, e.g. 0x01 for mapping version 1.0</li> - <li>A one-byte binary minor version number for the mapping, e.g. 0x00 for mapping version 1.0</li> - <li>A two-byte, big-endian binary number signifying the number of header (non-audio) packets, not including this one. This number may be zero (0x0000) to signify 'unknown' but be aware that some decoders may not be able to handle such streams.</li> - <li>The four-byte ASCII native FLAC signature "fLaC" according to the <a href="format.html#stream">FLAC format specification</a></li> - <li>The <a href="format.html#metadata_block">STREAMINFO</a> metadata block for the stream.</li> - </ul> - This first packet is the only packet in the first page of the stream. This results in a first Ogg page of exactly 79 bytes at the very beginning of the logical stream. - </li> - <li> - This first page is marked 'beginning of stream' in the page flags. - </li> - <li> - The first packet is followed by one or more header packets. Each such packet will contain a single <a href="format.html#metadata_block">native FLAC metadata block</a>. The first of these must be a VORBIS_COMMENT block. These packets may span page boundaries but the last will finish the page on which it ends, so that the first audio packet begins a page. The first byte of these metadata packets serves also as the packet type, and has a legal range of (0x01-0x7E,0x81-0xFE). - </li> - <li> - The granule position of these first pages containing only headers is zero. - </li> - <li> - The first audio packet of the logical stream begins a fresh Ogg page. - </li> - <li> - Native FLAC audio frames appear as subsequent packets in the stream. Each packet corresponds to one FLAC audio frame. The first byte of each packet serves as the packet type. Since audio packets are native FLAC frames, this first byte will be always 0xFF according to the <a href="format.html#frame_header">native FLAC format specification</a>. - </li> - <li> - The last page is marked 'end of stream' in the page flags. - </li> - <li> - FLAC packets may span page boundaries. - </li> - <li> - The granule position of pages containing FLAC audio follows the same semantics as that for Ogg-encapsulated Vorbis as described <a href="http://xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-126000A">here</a>. - </li> - <li> - Redundant fields in the STREAMINFO packet may be set to zero (indicating "unknown" in native FLAC), which also facilitates single-pass encoding. These fields are: the minimum and maximum frame sizes, the total samples count, and the MD5 signature. "Unknown" values for these fields will not prevent a compliant native FLAC or Ogg FLAC decoder from decoding the stream. - </li> - </ul> - 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.<br /> - <br /> - 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. - </div> - <div class="box_footer"></div> -</div> - - -<div class="copyright"> - <!-- @@@ oh so hacky --> - <table> - <tr> - <td align="left"> - Copyright (c) 2004-2009 Josh Coalson - <br/> - Copyright (c) 2011-2022 Xiph.Org Foundation - </td> - </tr> - </table> -</div> - -</body> -</html> diff --git a/doc/html/images/Makefile.am b/doc/images/Makefile.am index 19a4bef7..19a4bef7 100644 --- a/doc/html/images/Makefile.am +++ b/doc/images/Makefile.am diff --git a/doc/html/images/logo.svg b/doc/images/logo.svg index 4ee2d418..4ee2d418 100644 --- a/doc/html/images/logo.svg +++ b/doc/images/logo.svg diff --git a/doc/html/images/logo130.gif b/doc/images/logo130.gif Binary files differindex 3200df34..3200df34 100644 --- a/doc/html/images/logo130.gif +++ b/doc/images/logo130.gif |
