mirrors
/
flac
mirror of https://github.com/xiph/flac
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Martijn van Beurden 2022-09-05 19:11:31 +02:00 committed by GitHub
parent 5e67c6278e
commit dd8a264c56
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
28 changed files with 371 additions and 4074 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -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

74
CONTRIBUTING.md Normal file
View File

@ -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.

1
Makefile.am
View File

@ -56,6 +56,7 @@ EXTRA_DIST = \
COPYING.GPL \
COPYING.LGPL \
COPYING.Xiph \
README.md \
autogen.sh \
config.rpath \
depcomp \

291
README
View File

@ -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.

279
README.md Normal file
View File

@ -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.

3
configure.ac
View File

@ -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 \

46
doc/CMakeLists.txt
View File

@ -12,43 +12,15 @@ if (NOT BUILD_DOXYGEN)
return()
endif()
set(DOXYGEN_HTML_FOOTER doxygen.footer.html)
set(DOXYGEN_GENERATE_TAGFILE FLAC.tag)
set(top_srcdir "${PROJECT_SOURCE_DIR}")
configure_file(Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
if(CMAKE_VERSION VERSION_LESS 3.12)
doxygen_add_docs(FLAC-doxygen
ALL
"${PROJECT_SOURCE_DIR}/include/FLAC"
"${PROJECT_SOURCE_DIR}/include/FLAC++")
else()
doxygen_add_docs(FLAC-doxygen
"${PROJECT_SOURCE_DIR}/include/FLAC"
"${PROJECT_SOURCE_DIR}/include/FLAC++")
install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/html/"
DESTINATION "${CMAKE_INSTALL_DOCDIR}/html/api")
add_custom_target(FLAC-doxygen ALL
COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen"
VERBATIM )
endif()
install(FILES
html/images/logo.svg
html/images/logo130.gif
html/changelog.html
html/developers.html
html/documentation.html
html/documentation_bugs.html
html/documentation_example_code.html
html/documentation_format_overview.html
html/documentation_tools.html
html/documentation_tools_flac.html
html/documentation_tools_metaflac.html
html/faq.html
html/favicon.ico
html/features.html
html/flac.css
html/format.html
html/id.html
html/index.html
html/license.html
html/ogg_mapping.html
DESTINATION "${CMAKE_INSTALL_DOCDIR}/html")
install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/api/"
DESTINATION "${CMAKE_INSTALL_DOCDIR}/api")

12
doc/Makefile.am
View File

@ -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

7
doc/doxygen.header.html
View File

@ -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 -->

50
doc/html/Makefile.am
View File

@ -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

127
doc/html/developers.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;developers&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

91
doc/html/documentation.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;documentation&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

85
doc/html/documentation_bugs.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

67
doc/html/documentation_example_code.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

116
doc/html/documentation_format_overview.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

77
doc/html/documentation_tools.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

390
doc/html/faq.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;faq&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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&amp;st=75&amp;p=466078&amp;#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>

BIN
doc/html/favicon.ico
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.4 KiB

113
doc/html/features.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

194
doc/html/flac.css
View File

@ -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}

1849
doc/html/format.html
View File

File diff suppressed because it is too large Load Diff

289
doc/html/id.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

79
doc/html/index.html
View File

@ -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">
&nbsp;home&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

79
doc/html/license.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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>

124
doc/html/ogg_mapping.html
View File

@ -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">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<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-&gt;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&lt;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>

0
doc/html/images/Makefile.am → doc/images/Makefile.am
View File

0
doc/html/images/logo.svg → doc/images/logo.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

0
doc/html/images/logo130.gif → doc/images/logo130.gif
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.8 KiB

After

Width:  |  Height:  |  Size: 3.8 KiB