Main Page Modules Class Hierarchy Alphabetical List Compound List File List Compound Members File Members

# FLAC/metadata.h: metadata interfaces
[FLAC C API]

This module provides functions for creating and manipulating FLAC metadata blocks in memory, and three progressively more powerful interfaces for traversing and editing metadata in FLAC files. More...

## Modules

FLAC/metadata.h: metadata level 0 interface
| The level 0 interface consists of a single routine to read the STREAMINFO block.

FLAC/metadata.h: metadata level 1 interface
| The level 1 interface provides read-write access to FLAC file metadata and operates directly on the FLAC file.

FLAC/metadata.h: metadata level 2 interface
| The level 2 interface provides read-write access to FLAC file metadata; all metadata is read into memory, operated on in memory, and then written to file, which is more efficient than level 1 when editing multiple blocks.

FLAC/metadata.h: metadata object methods
| This module contains methods for manipulating FLAC metadata objects.

## Detailed Description

This module provides functions for creating and manipulating FLAC metadata blocks in memory, and three progressively more powerful interfaces for traversing and editing metadata in FLAC files.

There are three metadata interfaces of increasing complexity:

Level 0: Read-only access to the STREAMINFO block.

Level 1: Read-write access to all metadata blocks. This level is write- efficient in most cases (more on this below), and uses less memory than level 2.

Level 2: Read-write access to all metadata blocks. This level is write- efficient in all cases, but uses more memory since all metadata for the whole file is read into memory and manipulated before writing out again.

What do we mean by efficient? When writing metadata back to a FLAC file it is possible to grow or shrink the metadata such that the entire file must be rewritten. However, if the size remains the same during changes or PADDING blocks are utilized, only the metadata needs to be overwritten, which is much faster.

Efficient means the whole file is rewritten at most one time, and only when necessary. Level 1 is not efficient only in the case that you cause more than one metadata block to grow or shrink beyond what can be accomodated by padding. In this case you should probably use level 2, which allows you to edit all the metadata for a file in memory and write it out all at once.

All levels know how to skip over and not disturb an ID3v2 tag at the front of the file.

In addition to the three interfaces, this module defines functions for creating and manipulating various metadata objects in memory. As we see from the Format module, FLAC metadata blocks in memory are very primitive structures for storing information in an efficient way. Reading information from the structures is easy but creating or modifying them directly is more complex. The metadata object routines here facilitate this by taking care of the consistency and memory management drudgery.

Unless you will be using the level 1 or 2 interfaces to modify existing metadata however, you will not probably not need these.

From a dependency standpoint, none of the encoders or decoders require the metadata module. This is so that embedded users can strip out the metadata module from libFLAC to reduce the size and complexity.