FLAC Documentation

1.2.1

Introduction

This is the documentation for the FLAC C and C++ APIs. It is highly interconnected; this introduction should give you a top level idea of the structure and how to find the information you need. As a prerequisite you should have at least a basic knowledge of the FLAC format, documented here.

FLAC C API

The FLAC C API is the interface to libFLAC, a set of structures describing the components of FLAC streams, and functions for encoding and decoding streams, as well as manipulating FLAC metadata in files. The public include files will be installed in your include area (for example /usr/include/FLAC/...).

By writing a little code and linking against libFLAC, it is relatively easy to add FLAC support to another program. The library is licensed under Xiph's BSD license. Complete source code of libFLAC as well as the command-line encoder and plugins is available and is a useful source of examples.

Aside from encoders and decoders, libFLAC provides a powerful metadata interface for manipulating metadata in FLAC files. It allows the user to add, delete, and modify FLAC metadata blocks and it can automatically take advantage of PADDING blocks to avoid rewriting the entire FLAC file when changing the size of the metadata.

libFLAC usually only requires the standard C library and C math library. In particular, threading is not used so there is no dependency on a thread library. However, libFLAC does not use global variables and should be thread-safe.

libFLAC also supports encoding to and decoding from Ogg FLAC. However the metadata editing interfaces currently have limited read-only support for Ogg FLAC files.

FLAC C++ API

The FLAC C++ API is a set of classes that encapsulate the structures and functions in libFLAC. They provide slightly more functionality with respect to metadata but are otherwise equivalent. For the most part, they share the same usage as their counterparts in libFLAC, and the FLAC C API documentation can be used as a supplement. The public include files for the C++ API will be installed in your include area (for example /usr/include/FLAC++/...).

libFLAC++ is also licensed under Xiph's BSD license.

Getting Started

A good starting point for learning the API is to browse through the modules. Modules are logical groupings of related functions or classes, which correspond roughly to header files or sections of header files. Each module includes a detailed description of the general usage of its functions or classes.

From there you can go on to look at the documentation of individual functions. You can see different views of the individual functions through the links in top bar across this page.

If you prefer a more hands-on approach, you can jump right to some example code.

Porting Guide

Starting with FLAC 1.1.3 a Porting Guide has been introduced which gives detailed instructions on how to port your code to newer versions of FLAC.

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 src/libFLAC/Makefile.am. In general, the decoders, encoders, and metadata interface are all independent from each other.

It is easiest to just describe the dependencies:

All modules depend on the Format module.
The decoders and encoders depend on the bitbuffer.
The decoder is independent of the encoder. The encoder uses the decoder because of the verify feature, but this can be removed if not needed.
Parts of the metadata interface require the stream decoder (but not the encoder).
Ogg support is selectable through the compile time macro FLAC__HAS_OGG.

For example, if your application only requires the stream decoder, no encoder, and no metadata interface, you can remove the stream encoder and the metadata interface, which will greatly reduce the size of the library.

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.