TAK SDK 1.1.1

Software Development Kit for TAK, (T)om's lossless (A)udio (K)ompressor.

Version: TAK SDK 1.1.1, 2009-03-11

Copyright 2007 by Thomas Becker, D-49080 Osnabrück.
All rights reserved.

The license and further important information can be found in the "Readme.html" file in the root directory.

Content

Important advice

General definitions

APEv2-Tag (APE)

Seekable Stream Decoder (SSD)

Important advice

Terms

Position and size descriptions in samples

always have to be interpreted independently on the number of audio channels. With CD-Audio quality, for example, 44100 samples always corresponds to 1 second, no matter whether the file is mono or stereo.

User

In the following, User refers to the developer utilizing the SDK.

Interfaces

Structures

Structures (record, struct) have to be packed; insertion of filling bytes for data alignment is not allowed.

All current structures exclusively contain the data types Int32 and Int64. It should be possible to cope with activated alignment by replacing Int64 with two Int32 for low and high. Then all elements have a size of 4.

Function parameters

All function parameters are categorically checked by TAK (range exceedance, buffer sizes, Null references).

All data is categorically copied to intern structures, thus they are not needed after a function call anymore (no references to external data) and can be destroyed.

Internal errors

The library still contains some debug code which is able to throw exceptions. These are not catched at present and can get through to the user layer, resulting in unattractive crashes...

Work in progress...

Function results and error handling

Most functions return their process results as TtakResult, sometimes as TtakBool.

TtakResult can take general or object-specific (see Decoder, for example) result values.

Success is usually reported by means of tak_res_Ok.

The other result values are divided into warnings, non-fatal and fatal errors.

Warnings are:

Non-fatal errors are:

Fatal errors are:

Every object records non-fatal and fatal errors to a status variable which can be queried by the state function (tak_SSD_State, for example). In case of multiple consecutive errors, the worst one is recorded.

Attention: Warnings are provided by the respective function, but are not saved!

For example, tak_SSD_GetSimpleWaveDataDesc can return the result tak_res_ssd_MetaDataMissing, but a following tak_SSD_State call will nonetheless result in tak_res_Ok.

Once a fatal error occurs, the affected object is locked. In this case, most object functions "come back empty-handed", returning the code of the fatal error as a result. Only a few status functions are still available.

Every object defines a Valid function, such as tak_SSD_Valid, which returns tak_true in case no fatal error occurred.

General definitions

General definitions not associated with a particular object.

Reference

Elementary types Description
type TtakInt64 Signed integer type with 64 bits.
type TtakInt32 Signed integer type with 32 bits.
type TtakUInt32 Unsigned integer type with 32 bits.
type TtakBool Boolean type.
Function results Description
type TtakResult Function result and objekt status.
const tak_res_xxx General result contants.
Library Description
const tak_InterfaceVersion Version of the library interface.
func tak_GetLibraryVersion Provides library version information.
System Description
type TtakCpuOptions Specifies CPU features for optimizations.
const tak_Cpu_xxx Flags for CPU features and optimizations.
type TtakStreamIoInterface Interface for external file access implementations.
Audio format Description
const tak_AudioFormat_xxx Specification of the audio data format.
type TtakAudioFormat Specification of the audio format.
Codecs and presets Description
func tak_GetCodecName Provides the name of a codec.
type TtakPresets Encoder presets.
type TtakPresetEvaluations Preset evaluations.
const tak_PresetEval_xxx Preset evaluation constants.
Stream / container Description
type Ttak_str_EncoderInfo Information about the used codec.
type TtakFrameSizeTypes Frame size type.
type Ttak_str_SizeInfo Information about size parameters of the stream.
type Ttak_str_StreamInfo Summarizes all stream information necessary for decoding.
type Ttak_str_SimpleWaveDataHeader Description of a Wave file's metadata blocks.
type Ttak_str_MetaEncoderInfo Information about the used encoder.

APEv2 tag (APE)

The APEv2 tag object (APE) allows access to APEv2 tag information contained in the stream. Tag objects are provided exclusively by other objects (decoder or encoder). The user cannot create any instances himself.

The implementation of reading and writing functions as well as validity rules are based on the format specification described in the Hydrogenaudio wiki.

Following terminology is used:

TAK's current implementation features following restrictions:

Reference

Methods and functions

Status functions Descriptions
tak_APE_Valid Shows whether a fatal error occurred or not.
tak_APE_State Provides the current error status or the worst error occurred so far, respectively.
tak_APE_GetErrorString Provides an english error text for an error code.
tak_APE_ReadOnly Returns the access mode.
tak_APE_GetDesc Provides information about the tag.
tak_APE_GetItemNum Returns the number of items.
Editing Descriptions
tak_APE_GetIndexOfKey Returns the index of an item key.
tak_APE_GetItemDesc Provides information about an item.
tak_APE_GetItemKey Returns the ASCII-coded item key.
tak_APE_GetItemValue Returns the UTF8-coded item value.
tak_APE_GetTextItemValueAsAnsi Provides the ANSI-coded value of a text item or selected values when the item has multiple values.

Seekable Stream Decoder (SSD)

The Seekable Stream Decoder (SSD) decodes audio data read from a file or by means of a stream interface. It supports sample-precise positioning and extracting of arbitrary parts of an audio file.

Examples

Following program examples are available:

Example 1 in Pascal

Example 1 in C

Reference

Methods and functions

Create and destroy objects Description
tak_SSD_Create_FromFile Creates a decoder instance which decodes a file.
tak_SSD_Create_FromStream Creates a decoder instance which decodes an external stream.
tak_SSD_Destroy Destroys a decoder instance.
Status functions Description
tak_SSD_Valid Shows whether a fatal error occurred.
tak_SSD_State Returns the current error state, respectively the worst error occurred so far.
tak_SSD_GetStateInfo Provides extended status information.
tak_SSD_GetErrorString Provides an appropriate English error text for an error code.
tak_SSD_GetStreamInfo Provides information about the stream.
tak_SSD_GetFrameSize Returns the frame size in samples.
Decode Description
tak_SSD_Seek Sets read position.
tak_SSD_ReadAudio Reads and decodes samples.
tak_SSD_GetReadPos Returns the current read position in samples.
tak_SSD_GetCurFrameBitRate Returns the compressed bitrate of the last frame.
tak_SSD_GetSimpleWaveDataDesc Provides a description of the Wave metadata.
tak_SSD_ReadSimpleWaveData Reads Wave metadata.
tak_SSD_GetEncoderInfo Provides information about the used encoder.
tak_SSD_GetAPEv2Tag Provides a reference to the APEv2 tag object.

Types

Type Description
TtakSeekableStreamDecoder Decoder instance.
TtakSSDOptions Options.
TtakSSDDamageItem Information about data errors which is transferred to the damage callback function.
TSSDDamageCallback Callback function called when encountering data errors.

Constants

Constant Description
tak_res_ssd_xxx SSD-specific errors and warnings.