FLAC/metadata.h: metadata interfaces

Modules
	FLAC/metadata.h: metadata level 0 interface

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 native FLAC files. Note that currently only the Chain interface (level 2) supports Ogg FLAC files, and it is read-only i.e. no writing back changed metadata to file.

There are three metadata interfaces of increasing complexity:

Level 0: Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks.

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? Since FLAC metadata appears at the beginning of the file, 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 accommodated 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.

All levels access files via their filenames. In addition, level 2 has additional alternative read and write functions that take an I/O handle and callbacks, for situations where access by filename is not possible.

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.