DOCSEARCHbyAlgolia
Submit Docs

FLAC (Free Lossless Audio Codec)

repository·master·Indexed 25 days ago

https://github.com/xiph/flac

Reference implementation for the Free Lossless Audio Codec, providing high-performance lossless encoding and decoding of digital audio signals. Includes libFLAC, a C++ wrapper libFLAC++, the flac command-line utility for audio processing, and metaflac for metadata editing. Supports various input/output formats including RIFF WAVE, Wave64, RF64, and AIFF.

Tokens
11K
Snippets
9
Records
60
Agent score
81%

What's inside FLAC

  1. Overview of FLAC components

    master

    FLAC (Free Lossless Audio Codec) is a reference implementation for lossless audio compression. The project consists of the following core components:

    • libFLAC: The primary library implementing reference encoders and decoders for native FLAC and Ogg FLAC, including a metadata interface.
    • libFLAC++: A C++ object wrapper library built around libFLAC.
    • flac: A command-line utility for encoding and decoding audio files.
    • metaflac: A command-line utility for viewing and editing FLAC metadata.
    • Documentation: Includes API documentation (Doxygen) and command-line tool manuals.

  2. How to use the flac command-line tool

    master

    The flac tool is a command-line utility used for encoding, decoding, testing, and analyzing FLAC streams.

    Core Modes of Operation

    By default, flac operates in encoding mode. You can switch modes using the following flags:

    • Encoding (Default): Converts uncompressed audio (WAVE, AIFF, etc.) to FLAC.
    • Decoding (-d or --decode): Converts FLAC or Ogg FLAC back to uncompressed formats (WAVE, AIFF, etc.).
    • Testing (-t or --test): Similar to decoding, but does not write an output file. It is used to detect stream errors and MD5 signature mismatches.
    • Analyzing (-a or --analyze): Used for stream analysis.

    Input and Output Behavior

    • Input Formats: Supports RIFF WAVE, Wave64, RF64, AIFF, FLAC, Ogg FLAC, or raw interleaved samples (4 to 32 bits per sample).
    • Output Formats: The decoder can output to RIFF WAVE, Wave64, RF64, AIFF, or raw interleaved samples.
    • File Handling: If a single input file is provided, flac creates a similarly named output file (e.g., abc.wav becomes abc.flac). If using stdin (-), flac writes to stdout.
    • Best Practice for I/O: When encoding or decoding from stdin to a file, use the -o option instead of shell redirection (>) to allow flac to seek backwards for header writing.
    flac [options] -o outputfile
flac -d [options] -o outputfile

  3. Pruning libFLAC for embedded systems

    master

    For embedded implementations where memory footprint is critical, libFLAC can be pruned by editing configure.ac and src/libFLAC/Makefile.am.

    To create a pure decoding application, you can safely remove the following modules:

    • stream_encoder.h
    • Metadata editing interfaces

    The following dependency hierarchy shows what can be removed for decoding:

    • metadata.h depends on stream_decoder.h and format.h.
    • stream_decoder.h depends on format.h.

    Additionally, look for comments marked with OPT: in the source code to find #define options that enable platform-specific optimizations.

  4. Re-encode existing FLAC files

    master

    You can use flac to re-encode an existing FLAC or Ogg FLAC file. This is useful for changing compression levels or applying new metadata.

    Note: This is an encoding operation by default. To re-encode a file with the same name, you must use the --force or -f option, otherwise flac will error out because the output file already exists.

    Re-encoding will preserve existing metadata (tags, seekpoints, etc.) unless you explicitly override them with new options.

  5. Append a metadata block to a FLAC file

    master

    You can insert a binary metadata block into a FLAC file using --append. The insertion point is determined by --block-number, and the new block is placed after the specified block. This ensures the STREAMINFO block (block 0) remains at the start.

    To copy a block from one file to another, export it as binary first, then append it to the target file.

  6. Use metaflac to manage FLAC metadata

    master

    Overview

    metaflac is a command-line tool used to list, add, remove, or edit metadata in FLAC files. It supports both "major operations" (modes of operation) and "shorthand operations" (convenient synonyms for common tasks).

    Command Syntax

    metaflac [options] [operations] FLACfile ...

    Key Concepts

    • Major Operations: Specify a mode of operation (e.g., listing or removing blocks).
    • Shorthand Operations: Convenient aliases for common tasks (e.g., --show-sample-rate). You can combine multiple shorthand operations in a single command.
    • Global Options: Affect all operations (e.g., --preserve-modtime).

    Examples

    Show MD5 signatures for multiple files:

    metaflac --show-md5sum file1.flac file2.flac file3.flac

    Remove specific tags while preserving file modification times:

    metaflac --preserve-modtime --remove-tag=DESCRIPTION --remove-tag=COMMENT file1.flac file2.flac file3.flac

  7. Encode audio to FLAC

    master

    Use the flac command to encode various uncompressed audio formats into FLAC.

    Common Encoding Tasks

    • Default encoding: flac abc.wav (creates abc.flac).
    • Highest compression: Use --best or -8 to maximize compression ratio at the cost of speed.
    • Verify encoding: Use --verify or -V to encode the file and then internally decode it to ensure the output matches the input.
    • Overwrite existing files: Use --force or -f to overwrite an existing .flac file.
    • Delete input on success: Use --delete-input-file to remove the source file if encoding completes without errors.
    • Batch encoding: Supports wildcards (e.g., *.wav).
    • Adding tags: Use --tag-from-file or -T to add metadata. Note that using these options on an existing FLAC file will wipe all existing tags unless specifically managed.

    Handling Filenames with Leading Dashes

    If your filename starts with a dash (e.g., -7.wav), use -- to signal the end of options so the filename isn't treated as a flag.

  8. Decode FLAC to uncompressed audio

    master

    Use the -d or --decode flag to convert FLAC files back to uncompressed formats like WAVE or AIFF.

    Common Decoding Tasks

    • Standard decode: flac -d abc.flac (creates abc.wav).
    • Specify output format: Use -o to define the output filename and format (e.g., flac -d -o abc.aiff abc.flac).
    • Force overwrite: Use --force or -f to overwrite an existing uncompressed file.
    • Recover corrupted files: Use -F to decode even if errors are found in the stream. Use this with caution as it may produce loud noises or conceal errors.
    • Preserve non-audio metadata: Use --keep-foreign-metadata-if-present to restore non-audio chunks (like original WAVE/AIFF metadata) if they exist in the FLAC stream.

  9. Preserve foreign metadata when converting to FLAC

    master

    When converting WAVE, RF64, AIFF, AIFF-C, or Wave64 files to FLAC, you can preserve the original file's metadata by using the --keep-foreign-metadata option with the flac command-line tool.

    This option stores the original chunks as application metadata blocks within the FLAC file. The process preserves the order of chunks and copies them completely, with two exceptions to ensure proper restoration:

    1. The first chunk (the container chunk) has only its header (identifier and size) copied.
    2. The chunk containing the actual audio data has only its header copied.

    This mechanism allows for the eventual restoration of the original file format while using the FLAC streaminfo for the actual audio parameters.

  10. Build FLAC using CMake CLI

    master

    CMake is a cross-platform build system supported by FLAC for Windows, Linux, and macOS. It is recommended to use an out-of-tree build (a separate build folder) to keep the source directory clean.

    To build using the default generator (e.g., Makefiles on UNIX):

    1. Navigate to your build directory.
    2. Run cmake pointing to the source directory.
    3. Run make to compile.
    4. (Optional) Run make test to verify the build.
    5. Run make install to install libraries and headers.

    To use a specific generator (like Ninja or Xcode), use the -G flag.

    # Configure the build
/path/to/flac-build$ cmake /path/to/flac-source

# Build
/path/to/flac-build$ make

# Test and Install
/path/to/flac-build$ make test
/path/to/flac-build$ make install

# Example using Ninja generator
/path/to/flac-build$ cmake /path/to/flac-source -GNinja
/path/to/flac-build$ ninja

  11. Build FLAC using GNU autotools

    master

    For systems using autotools, FLAC uses autoconf and libtool.

    Note: If you are building from a git clone rather than a release tarball, you may need to run ./autogen.sh first to generate the configure script.

    Standard build workflow:

    1. Run ./configure (use ./autogen.sh if necessary).
    2. Run make to build.
    3. Run make check to verify (optional, can take ~1 hour).
    4. Run sudo make install to install.

    Warning: Do not run make check as root, as it can interfere with certain tests.

    # If building from git
./autogen.sh

# Standard build sequence
./configure
make && make check
sudo make install

  12. Use metaflac for FLAC metadata editing

    master

    The metaflac command-line tool is used to edit and manipulate metadata within FLAC files. It operates by parsing command-line options and then executing a series of metadata operations based on those options.

    While the specific flags are defined in the options.h and operations.h headers, the tool follows a standard CLI pattern: metaflac [options] [file].