caf

Documentation

Overview

caf package implements an Apple Core Audio Format (CAF) parser.

Apple’s Core Audio Format (CAF) is a file format (container) for storing and transporting digital audio data. It simplifies the management and manipulation of many types of audio data without the file-size limitations of other audio file formats. CAF provides high performance and flexibility and is scalable to future ultra-high resolution audio recording, editing, and playback. CAF files can contain audio or even define patches, or musical voice configurations.

The primary goal of this package is to allow the transcoding/conversion of CAF files to other formats. Note that because CAF fiels contain other metadata than just audio data, the conversion will be lossy, not in the sound quality meaning of the sense but in the data senses.

That said here is some information about CAF provided by Apple.

CAF files have several advantages over other standard audio file formats:

* Unrestricted file size Whereas AIFF, AIFF-C, and WAV files are limited in size to 4 gigabytes, which might represent as little as 15 minutes of audio, CAF files use 64-bit file offsets, eliminating practical limits. A standard CAF file can hold audio data with a playback duration of hundreds of years.

* Safe and efficient recording Applications writing AIFF and WAV files must either update the data header’s size field at the end of recording—which can result in an unusable file if recording is interrupted before the header is finalized—or they must update the size field after recording each packet of data, which is inefficient. With CAF files, in contrast, an application can append new audio data to the end of the file in a manner that allows it to determine the amount of data even if the size field in the header has not been finalized.

* Support for many data formats CAF files serve as wrappers for a wide variety of audio data formats. The flexibility of the CAF file structure and the many types of metadata that can be recorded enable CAF files to be used with practically any type of audio data. Furthermore, CAF files can store any number of audio channels.

* Support for many types of auxiliary data In addition to audio data, CAF files can store text annotations, markers, channel layouts, and many other types of information that can help in the interpretation, analysis, or editing of the audio.

* Support for data dependencies Certain metadata in CAF files is linked to the audio data by an edit count value. You can use this value to determine when metadata has a dependency on the audio data and, furthermore, when the audio data has changed since the metadata was written.

Vocab:

* Sample One number for one channel of digitized audio data.

* Frame A set of samples representing one sample for each channel. The samples in a frame are intended to be played together (that is, simultaneously). Note that this definition might be different from the use of the term “frame” by codecs, video files, and audio or video processing applications.

* Packet The smallest, indivisible block of data. For linear PCM (pulse-code modulated) data, each packet contains exactly one frame. For compressed audio data formats, the number of frames in a packet depends on the encoding. For example, a packet of AAC represents 1024 frames of PCM. In some formats, the number of frames per packet varies.

* Sample rate The number of complete frames of samples per second of noncompressed or decompressed data.

The format is documented by Apple at https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CAFSpec/CAF_spec/CAF_spec.html#//apple_ref/doc/uid/TP40001862-CH210-TPXREF101

Index

• Variables
• type AudioDescChunk
• type Decoder
  • func NewDecoder(r io.ReadSeeker) *Decoder
  • func (d *Decoder) Duration() time.Duration
  • func (d *Decoder) Err() error
  • func (d *Decoder) NextChunk() (*chunk.Reader, error)
  • func (d *Decoder) Read(dst interface{}) error
  • func (d *Decoder) ReadByte() (byte, error)
  • func (d *Decoder) ReadInfo() error
  • func (d *Decoder) String() string
• type Metadata

Variables

var (

	// Chunk IDs
	StreamDescriptionChunkID = [4]byte{'d', 'e', 's', 'c'}
	AudioDataChunkID         = [4]byte{'d', 'a', 't', 'a'}
	ChannelLayoutChunkID     = [4]byte{'c', 'h', 'a', 'n'}
	FillerChunkID            = [4]byte{'f', 'r', 'e', 'e'}
	MarkerChunkID            = [4]byte{'m', 'a', 'r', 'k'}
	RegionChunkID            = [4]byte{'r', 'e', 'g', 'n'}
	InstrumentChunkID        = [4]byte{'i', 'n', 's', 't'}
	MagicCookieID            = [4]byte{'k', 'u', 'k', 'i'}
	InfoStringsChunkID       = [4]byte{'i', 'n', 'f', 'o'}
	EditCommentsChunkID      = [4]byte{'e', 'd', 'c', 't'}
	PacketTableChunkID       = [4]byte{'p', 'a', 'k', 't'}
	StringsChunkID           = [4]byte{'s', 't', 'r', 'g'}
	UUIDChunkID              = [4]byte{'u', 'u', 'i', 'd'}
	PeakChunkID              = [4]byte{'p', 'e', 'a', 'k'}
	OverviewChunkID          = [4]byte{'o', 'v', 'v', 'w'}
	MIDIChunkID              = [4]byte{'m', 'i', 'd', 'i'}
	UMIDChunkID              = [4]byte{'u', 'm', 'i', 'd'}
	FormatListID             = [4]byte{'l', 'd', 's', 'c'}
	IXMLChunkID              = [4]byte{'i', 'X', 'M', 'L'}

	// Format IDs
	// Linear PCM
	AudioFormatLinearPCM = [4]byte{'l', 'p', 'c', 'm'}
	// Apple’s implementation of IMA 4:1 ADPCM. Has no format flags.
	AudioFormatAppleIMA4 = [4]byte{'i', 'm', 'a', '4'}
	// MPEG-4 AAC. The mFormatFlags field must contain the MPEG-4 audio object type constant indicating the specific kind of data.
	AudioFormatMPEG4AAC = [4]byte{'a', 'a', 'c', ' '}
	// MACE 3:1; has no format flags.
	AudioFormatMACE3 = [4]byte{'M', 'A', 'C', '3'}
	// MACE 6:1; has no format flags.
	AudioFormatMACE6 = [4]byte{'M', 'A', 'C', '6'}
	// μLaw 2:1; has no format flags.
	AudioFormatULaw = [4]byte{'u', 'l', 'a', 'w'}
	// aLaw 2:1; has no format flags.
	AudioFormatALaw = [4]byte{'a', 'l', 'a', 'w'}
	// MPEG-1 or 2, Layer 1 audio. Has no format flags.
	AudioFormatMPEGLayer1 = [4]byte{'.', 'm', 'p', '1'}
	// MPEG-1 or 2, Layer 2 audio. Has no format flags.
	AudioFormatMPEGLayer2 = [4]byte{'.', 'm', 'p', '2'}
	// MPEG-1 or 2, Layer 3 audio (that is, MP3). Has no format flags.
	AudioFormatMPEGLayer3 = [4]byte{'.', 'm', 'p', '3'}
	// Apple Lossless; has no format flags.
	AudioFormatAppleLossless = [4]byte{'a', 'l', 'a', 'c'}

	// ErrFmtNotSupported is a generic error reporting an unknown format.
	ErrFmtNotSupported = errors.New("format not supported")
	// ErrUnexpectedData is a generic error reporting that the parser encountered unexpected data.
	ErrUnexpectedData = errors.New("unexpected data content")
)

Types

type AudioDescChunk

type AudioDescChunk struct {
}

type Decoder

type Decoder struct {

	// Format: the file type. This value must be set to 'caff'.
	// You should consider only files with the Type field set to 'caff' to be valid CAF files.
	Format [4]byte
	// Version: The file version. For CAF files conforming to this specification, the version must be set to 1.
	// If Apple releases a substantial revision of this specification, files compliant with that revision will have their Version
	// field set to a number greater than 1.
	Version uint16
	// Flags reserved by Apple for future use. For CAF v1 files, must be set to 0. You should ignore any value of this field you don’t understand,
	// and you should accept the file as a valid CAF file as long as the version and file type fields are valid.
	Flags uint16

	// The number of sample frames per second of the data. You can combine this value with the frames per packet to determine the amount of time represented by a packet. This value must be nonzero.
	SampleRate float64

	// A four-character code indicating the general kind of data in the stream.
	FormatID [4]byte

	// Flags specific to each format. May be set to 0 to indicate no format flags.
	// Detailed specification linear PCM, MPEG-4 AAC, and AC-3
	FormatFlags uint32

	// The number of bytes in a packet of data. For formats with a variable packet size,
	// this field is set to 0. In that case, the file must include a Packet Table chunk Packet Table Chunk.
	// Packets are always aligned to a byte boundary. For an example of an Audio Description chunk for a format with a variable packet size
	BytesPerPacket uint32

	// The number of sample frames in each packet of data. For compressed formats,
	// this field indicates the number of frames encoded in each packet. For formats with a variable number of frames per packet,
	// this field is set to 0 and the file must include a Packet Table chunk Packet Table Chunk.
	FramesPerPacket uint32

	// The number of channels in each frame of data. This value must be nonzero.
	ChannelsPerFrame uint32

	// The number of bits of sample data for each channel in a frame of data.
	// This field must be set to 0 if the data format (for instance any compressed format) does not contain separate samples for each channel
	BitsPerChannel uint32

	// Size of the audio data
	//A size value of -1 indicates that the size of the data section for this chunk is unknown. In this case, the Audio Data chunk must appear last in the file
	// so that the end of the Audio Data chunk is the same as the end of the file.
	// This placement allows you to determine the data section size.
	AudioDataSize int64
	// contains filtered or unexported fields
}

Decoder CAF files begin with a file header, which identifies the file type and the CAF version, followed by a series of chunks. A chunk consists of a header, which defines the type of the chunk and indicates the size of its data section, followed by the chunk data. The nature and format of the data is specific to each type of chunk.

The only two chunk types required for every CAF file are the Audio Data chunk and the Audio Description chunk, which specifies the audio data format.

The Audio Description chunk must be the first chunk following the file header. The Audio Data chunk can appear anywhere else in the file, unless the size of its data section has not been determined. In that case, the size field in the Audio Data chunk header is set to -1 and the Audio Data chunk must come last in the file so that the end of the audio data chunk is the same as the end of the file. This placement allows you to determine the data section size when that information is not available in the size field.

Audio is stored in the Audio Data chunk as a sequential series of packets. An audio packet in a CAF file contains one or more frames of audio data.

Every chunk consists of a chunk header followed by a data section. Chunk headers contain two fields: * A four-character code indicating the chunk’s type * A number indicating the chunk size in bytes

The format of the data in a chunk depends on the chunk type. It consists of a series of sections, typically called fields. The format of the audio data depends on the data type. All of the other fields in a CAF file are in big-endian (network) byte order.

func NewDecoder

func NewDecoder(r io.ReadSeeker) *Decoder

NewDecoder creates a new reader reading the given reader. It is the caller's responsibility to call Close on the reader when done.

func (*Decoder) Duration

func (d *Decoder) Duration() time.Duration

func (*Decoder) Err

func (d *Decoder) Err() error

Err returns the last non-EOF error that was encountered by the Decoder.

func (*Decoder) NextChunk

func (d *Decoder) NextChunk() (*chunk.Reader, error)

NextChunk returns the next available chunk

func (*Decoder) Read

func (d *Decoder) Read(dst interface{}) error

read reads n bytes from the parser's reader and stores them into the provided dst, which must be a pointer to a fixed-size value.

func (*Decoder) ReadByte

func (d *Decoder) ReadByte() (byte, error)

func (*Decoder) ReadInfo

func (d *Decoder) ReadInfo() error

ReadInfo reads the underlying reader finds the data it needs. This method is safe to call multiple times.

func (*Decoder) String

func (d *Decoder) String() string

String implements the stringer interface

type Metadata

type Metadata struct {

	// BaseNote The MIDI note number, and fractional pitch, for
	// the base note of the MIDI instrument. The integer portion of this field
	// indicates the base note, in the integer range 0 to 127, where a value of
	// 60 represents middle C and each integer is a step on a standard piano
	// keyboard (for example, 61 is C# above middle C). The fractional part of
	// the field specifies the fractional pitch; for example, 60.5 is a pitch
	// halfway between notes 60 and 61.
	BaseNote float32
	// MIDILowNote The lowest note for the region, in the integer range 0 to
	// 127, where a value of 60 represents middle C (following the MIDI
	// convention). This value represents the suggested lowest note on a
	// keyboard for playback of this instrument definition. The sound data
	// should be played if the instrument is requested to play a note between
	// MIDILowNote and MIDIHighNote, inclusive. The BaseNote value must be
	// within this range.
	MIDILowNote uint8
	// MIDIHighNote The highest note for the region when used as a MIDI
	// instrument, in the integer range 0 to 127, where a value of 60 represents
	// middle C. See the discussions of the BaseNote and MIDILowNote fields
	// for more information.
	MIDIHighNote uint8
	// MIDILowVelocity The lowest MIDI velocity for playing the region , in the integer range 0 to 127.
	MIDILowVelocity  uint8
	MIDIHighVelocity uint8
	DBGain           float32
	StartRegionID    uint32
	SustainRegionID  uint32
	ReleaseRegionID  uint32
	InstrumentID     uint32
}

Metadata represent the amount of metadata one can store/retrieve from a caf file. See https://developer.apple.com/library/content/documentation/MusicAudio/Reference/CAFSpec/CAF_spec/CAF_spec.html