# TAK SDK 2.3.3

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

Version: TAK SDK 2.3.3, 2022-06-30

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:

- Some object results. For example, it is no error when the decoder cannot read optional metadata because of the container not holding any.

Non-fatal errors are:

- Some object results. For example, the decoder can proceed even when single audio frames are damaged.

Fatal errors are:

- All system errors (such as OutOfMemory).
- All user errors (for example, invalid function parameters).
- Most object results.

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.

## Versions

The reference below contains version numbers for each item. For functions this is the first library version that provided the function even though it might not have been declared in the header files at this time. Any other object shows when it was declared in the header files. Extensions of enumerations like function results are not documented.

# General definitions

General definitions not associated with a particular object.

## Reference

Elementary types | Description | Version
type TtakInt64 | Signed integer type with 64 bits. | 1.0.1
type TtakInt32 | Signed integer type with 32 bits. | 1.0.1
type TtakUInt32 | Unsigned integer type with 32 bits. | 1.0.1
type TtakBool | Boolean type. | 1.0.1
type TtakAnsiChar | Character type with 8 bits. | 2.3.2
type TtakWideChar | Character type with 16 bits. | 2.3.2
Function results | Description | Version
type TtakResult | Function result and objekt status. | 1.0.1
const tak_res_xxx | General result contants. | 1.0.1
Library | Description | Version
const tak_InterfaceVersion | Version of the library interface. | 1.0.1
func tak_GetLibraryVersion | Provides library version information. | 1.0.1
System | Description | Version
type TtakCpuOptions | Specifies CPU features for optimizations. | 1.0.1
const tak_Cpu_xxx | Flags for CPU features and optimizations. | 1.0.1
type TtakStreamIoInterface | Interface for external file access implementations. | 1.0.1
Audio format | Description | Version
const tak_AudioFormat_xxx | Specification of the audio data format. | 1.0.1
type TtakAudioFormat | Specification of the audio format. | 1.0.1
const tak_Speaker_xxx | Speaker assignment of a channel in the TAK stream. | 2.3.2
type TtakSpeakerAssignment | Speaker assignments for all channels in a TAK-stream. | 2.3.2
type TtakAudioFormatEx | Extension of TtakAudioFormat for more than two channels. | 2.3.2
const tak_Speaker_Flag_xxx | Flags for speaker assignment, analogous to WaveFormatExtensible. | 2.3.2
func tak_GetWaveExtensibleSpeakerMask | Converts the speaker assignment from TAK's representation to the format used by WaveFormatExtensible. | 2.2.0
Codecs and presets | Description | Version
func tak_GetCodecName | Provides the name of a codec. | 1.0.1
type TtakPresets | Encoder presets. | 1.0.1
type TtakPresetEvaluations | Preset evaluations. | 1.0.1
const tak_PresetEval_xxx | Preset evaluation constants. | 1.0.1
Stream / container | Description | Version
type Ttak_str_EncoderInfo | Information about the used codec. | 1.0.1
type TtakFrameSizeTypes | Frame size type. | 1.0.1
type Ttak_str_SizeInfo | Information about size parameters of the stream. | 1.0.1
type Ttak_str_StreamInfo | Superseded by Ttak_str_StreamInfo_V22. | 1.0.1
type Ttak_str_StreamInfo_V22 | Summarizes all stream information necessary for decoding. | 2.3.2
type Ttak_str_SimpleWaveDataHeader | Description of a Wave file's metadata blocks. | 1.0.1
type Ttak_str_MetaEncoderInfo | Information about the used encoder. | 1.0.1
type Ttak_str_MD5 | MD5 checksum. | 2.3.2

# 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:

- Tag refers to the whole APEv2 structure.
- The tag contains one or multiple items holding the actual information.
- Every item consists of the following components: An explicit Key for identification and one or multiple values, assigned to this key.
- The item type specifies the type of the item value.

TAK's current implementation features following restrictions:

- The structure has to be compatible with the format version 2.000.
- The total tag size is limited to 16 MBytes.
- A tag can hold a maximum of 100 items.
- The tag has to be at the end of the file.

## Reference

#### Methods and functions

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

# 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 | Version
tak_SSD_Create_FromFile | Creates a decoder instance which decodes a file. (ANSI) | 1.0.1
tak_SSD_Create_FromFileW | Creates a decoder instance which decodes a file. (Unicode) | 2.3.2
tak_SSD_Create_FromStream | Creates a decoder instance which decodes an external stream. | 1.0.1
tak_SSD_Destroy | Destroys a decoder instance. | 1.0.1
Status functions | Description | Version
tak_SSD_Valid | Shows whether a fatal error occurred. | 1.0.1
tak_SSD_State | Returns the current error state, respectively the worst error occurred so far. | 1.0.1
tak_SSD_GetStateInfo | Provides extended status information. | 1.0.1
tak_SSD_GetErrorString | Provides an appropriate English error text for an error code. | 1.0.1
tak_SSD_GetStreamInfo | Superseded by tak_SSD_GetStreamInfo_V22. | 1.0.1
tak_SSD_GetStreamInfo_V22 | Provides information about the stream. | 2.2.0
tak_SSD_GetFrameSize | Returns the frame size in samples. | 1.0.1
Decode | Description | Version
tak_SSD_Seek | Sets read position. | 1.0.1
tak_SSD_ReadAudio | Reads and decodes samples. | 1.0.1
tak_SSD_GetReadPos | Returns the current read position in samples. | 1.0.1
tak_SSD_GetCurFrameBitRate | Returns the compressed bitrate of the last frame. | 1.0.1
tak_SSD_GetSimpleWaveDataDesc | Provides a description of the Wave metadata. | 1.0.1
tak_SSD_ReadSimpleWaveData | Reads Wave metadata. | 1.0.1
tak_SSD_GetEncoderInfo | Provides information about the used encoder. | 1.0.1
tak_SSD_GetAPEv2Tag | Provides a reference to the APEv2 tag object. | 1.0.1
tak_SSD_GetMD5 | Provides the MD5 checksum of the audio data. | 2.2.0

#### Types

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

#### Constants

Constant | Description | Version
tak_res_ssd_xxx | SSD-specific errors and warnings. | 1.0.1