# General reference

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

## Elementary types

### type TtakInt64

A signed 64-bit integer. Allocates 8 bytes.

### type TtakInt32

A signed 32-bit integer. Allocates 4 bytes.

### type TtakUInt32

An unsigned 32-bit integer. Allocates 4 bytes.

### type TtakBool

Can only take two values:

tak_False

false / no.

tak_True

true / yes.

### type TtakAnsiChar

Ansi character with 8 bits. Windows codepage encoding.

### type TtakWideChar

Unicode character with 16 bits. UTF-16 encoding.

## Function results and errors

### type TtakResult

Function result and object status

Pascal:

    type
      TtakResult = TtakInt32;

C:

    typedef TtakInt32 TtakResult;

### const tak_res_xxx

General result constants. Every object can define further object-specific results.

Success:

tak_res_Ok

OK.

System errors:

tak_res_InternalError

TAK's error...

tak_res_NotImplemented

This function is not implemented yet.

tak_res_IncompatibleVersion

The library version currently in use does not support this function. This applies to new codecs, for example

tak_res_OutOfMemory

A memory request could not be followed.

User errors:

tak_res_InvalidParameter

Invalid function parameter, for example range exceeded or NULL reference.

tak_res_InvalidIoInterface

A TtakStreamIoInterface does not provide a requested functionality.

tak_res_InvalidMode

The object was in a mode which does not allow execution of the desired function.

tak_res_BufferTooSmall

A buffer assigned as a parameter (for strings, for example) was too small.

tak_res_NotEnoughAudioData

The encoder was commanded to terminate despite having written less audio data than specified at its initialisation.

tak_res_TooMuchAudioData

The encoder was commanded to write more audio data than specified at its initialisation.

## Library

### const tak_InterfaceVersion

The library interface version. By comparison to the version information provided by tak_GetLibraryVersion, the compatibility to the currently used library DLL can be checked:

tak_InterfaceVersion has to be <= AVersion and >= ACompatibility.

### function tak_GetLibraryVersion

Provides version information of the library.

Pascal:

    function tak_GetLibraryVersion (var AVersion       : TtakInt32;
                                    var ACompatibility : TtakInt32) : TtakResult; cdecl;

C:

    TtakResult tak_GetLibraryVersion (TtakInt32 * AVersion,
                                      TtakInt32 * ACompatibility);

AVersion contains the library's three-digit version number, each with a size of 1 byte. The lowest byte is the lowest digit.

Example: 00010000h = 1.0.0

ACompatibility contains the version number of the oldest library the current version is downwards compatible with.

If all parameters are valid, the result is always tak_res_Ok.

## System

### type TtakCpuOptions

Specifies CPU features for optimizations.

Pascal:

    type
      TtakCpuOptions = TtakInt32;

C:

    typedef TtakInt32 TtakCpuOptions;

Following flags can be set and combined per bit-wise OR, if necessary:

tak_Cpu_None

Use no code optimizations at all.

tak_Cpu_Asm

Use Assembler optimizations, utilizing no CPU-specific instructions.

tak_Cpu_MMX

tak_Cpu_SSE

tak_Cpu_SSE2

tak_Cpu_SSE3

tak_Cpu_SSSE3

tak_Cpu_SSE41

tak_Cpu_SSE42

tak_Cpu_AVX

tak_Cpu_AVX2

Use the respective instruction set.

tak_Cpu_Any

Use all code optimizations supported by your target system.

TAK automatically deactivates optimizations not supported by the CPU. Decoder V 2.3.2 supports tak_Cpu_None, tak_Cpu_Asm and tak_Cpu_SSE2.

### type TtakStreamIoInterface

Interface for external file access implementations.

Pascal:

    type
      PtakStreamIoInterface = ^TtakStreamIoInterface;
      TtakStreamIoInterface = packed record
        CanRead   : function (AUser : Pointer) : TtakBool; cdecl;
        CanWrite  : function (AUser : Pointer) : TtakBool; cdecl;
        CanSeek   : function (AUser : Pointer) : TtakBool; cdecl;
        Read      : function (    AUser    : Pointer;
                                  ABuf     : Pointer;
                                  ANum     : TtakInt32;
                              var AReadNum : TtakInt32) : TtakBool; cdecl;
        Write     : function (AUser : Pointer;
                              ABuf  : Pointer;
                              ANum  : TtakInt32) : TtakBool; cdecl;
        Flush     : function (AUser : Pointer) : TtakBool; cdecl;
        Truncate  : function (AUser : Pointer) : TtakBool; cdecl;
        Seek      : function (AUser : Pointer;
                              APos  : TtakInt64) : TtakBool; cdecl;
        GetLength : function (    AUser   : Pointer;
                              var ALength : TtakInt64) : TtakBool; cdecl;
      end;

C:

    typedef struct TtakStreamIoInterface {
        TtakBool (*CanRead)  (void * AUser);
        TtakBool (*CanWrite) (void * AUser);
        TtakBool (*CanSeek)  (void * AUser);
        TtakBool (*Read)     (void *      AUser,
                              void *      ABuf,
                              TtakInt32   ANum,
                              TtakInt32 * AReadNum );
        TtakBool (*Write)    (void *       AUser,
                              const void * ABuf,
                              TtakInt32    ANum);
        TtakBool (*Flush)    (void * AUser);
        TtakBool (*Truncate) (void * AUser);
        TtakBool (*Seek)     (void *    AUser,
                              TtakInt64 APos);
        TtakBool (*GetLength)(void *      AUser,
                              TtakInt64 * ALength);
    } TtakStreamIoInterface;
    typedef TtakStreamIoInterface* PtakStreamIoInterface;

Functions:

CanRead

CanWrite

CanSeek

Can be read / written / seeked?

Read

Reads a maximum of ANum Bytes into ABuf. AReadNum contains the number of bytes actually read.

ATTENTION: Currently AReadNum may be less than ANum only at the end of a file!

Write

Writes ANum bytes out of ABuf into the file. The user might have to buffer manually, as writing less than ANum bytes is not possible.

Flush

Writes all buffer content into the file. Usually used by TAK only once at the end of a file.

Truncate

Erases everything from the current position on. Results in truncation of the file. Probably necessary for APEv2 tag updates.

Seek

Sets the file pointer on absolute position APos.

GetLength

Outputs the file size (in bytes) to ALength.

ATTENTION: On repeated function calls, the file size may only change according to writing operations requested by TAK!

In the first parameter, every function is supplied user data by means of the pointer AUser, specified at the interface handoff to a TAK object.

Unless otherwise specified, every error is reported by means of the function result tak_False. Furthermore, every error is considered fatal, thus terminating all file operation.

## Audio format

### const tak_AudioFormat_xxx

Specification of the audio data format:

tak_AudioFormat_DataType_PCM

PCM audio.

### tak_str_ChannelNumMax = 16

Maximum number of channels supported by the stream.

### type TtakAudioFormat

Specification of the audio format.

Pascal:

    type
      TtakAudioFormat = packed record
        DataType   : TtakInt32;
        SampleRate : TtakInt32;
        SampleBits : TtakInt32;
        ChannelNum : TtakInt32;
        BlockSize  : TtakInt32;
      end;

C:

    typedef struct TtakAudioFormat {
        TtakInt32 DataType;
        TtakInt32 SampleRate;
        TtakInt32 SampleBits;
        TtakInt32 ChannelNum;
        TtakInt32 BlockSize;
    } TtakAudioFormat;

Fields:

DataType

Currently always = tak_AudioFormat_DataType_PCM.

SampleRate

Samples per second (per channel).

SampleBits

Bits per sample.

ChannelNum

Number of channels.

BlockSize

= ChannelNum * ((SampleBits + 7) / 8)

New applications should use TtakAudioFormatEx.

### const tak_Speaker_xxx

Specification of the speaker assignment of a channel in the TAK stream.

tak_Speaker_None

tak_Speaker_Front_Left

tak_Speaker_Front_Right

tak_Speaker_Front_Center

tak_Speaker_Low_Frequency

tak_Speaker_Back_Left

tak_Speaker_Back_Right

tak_Speaker_Front_Left_Of_Center

tak_Speaker_Front_Right_Of_Center

tak_Speaker_Back_Center

tak_Speaker_Side_Left

tak_Speaker_Side_Right

tak_Speaker_Top_Center

tak_Speaker_Top_Front_Left

tak_Speaker_Top_Front_Center

tak_Speaker_Top_Front_Right

tak_Speaker_Top_Back_Left

tak_Speaker_Top_Back_Center

tak_Speaker_Top_Back_Right

### type TtakSpeakerAssignment

For each channel of the stream a tak_Speaker_xxx-value defining the speaker assignment. While the definition principially supports arbitrary channel orderings, currently only those are supported, which can be represented in WaveFormatExtensible.

Pascal:

    type
      TtakSpeakerAssignment = Array[0..tak_str_ChannelNumMax - 1] of Byte;

C:

    typedef char TtakSpeakerAssignment[tak_str_ChannelNumMax];

### type TtakAudioFormatEx

Extension of TtakAudioFormat for more than two channels.

Pascal:

    type
      TtakAudioFormatEx = packed record
        DataType             : TtakInt32;
        SampleRate           : TtakInt32;
        SampleBits           : TtakInt32;
        ChannelNum           : TtakInt32;
        BlockSize            : TtakInt32;

        HasExtension         : TtakBool;
        ValidBitsPerSample   : TtakInt32;
        HasSpeakerAssignment : TtakBool;
        SpeakerAssignment    : TtakSpeakerAssignment;
      end;

C:

    typedef struct TtakAudioFormatEx {
        TtakInt32             DataType;
        TtakInt32             SampleRate;
        TtakInt32             SampleBits;
        TtakInt32             ChannelNum;
        TtakInt32             BlockSize;

        TtakBool              HasExtension;
        TtakInt32             ValidBitsPerSample;
        TtakBool              HasSpeakerAssignment;
        TtakSpeakerAssignment SpeakerAssignment;
    } TtakAudioFormatEx;

Additional fields:

HasExtension

Are the following fields valid?

ValidBitsPerSample

Analogous to WaveFormatExtensible the count of the top most sample bits containing audio data. This value is taken from the wave header and not calculated by TAK.

HasSpeakerAssignment

True, if SpeakerAssignment is valid.

SpeakerAssignment

If HasSpeakerAssignment is true, this field holds the speaker assignment of the audio channels.

### const tak_Speaker_Flag_xxx

Flags for speaker assignment, analogous to WaveFormatExtensible.

tak_Speaker_Flag_None

tak_Speaker_Flag_Front_Left

tak_Speaker_Flag_Front_Right

tak_Speaker_Flag_Front_Center

tak_Speaker_Flag_Low_Frequency

tak_Speaker_Flag_Back_Left

tak_Speaker_Flag_Back_Right

tak_Speaker_Flag_Front_Left_Of_Center

tak_Speaker_Flag_Front_Right_Of_Center

tak_Speaker_Flag_Back_Center

tak_Speaker_Flag_Side_Left

tak_Speaker_Flag_Side_Right

tak_Speaker_Flag_Top_Center

tak_Speaker_Flag_Top_Front_Left

tak_Speaker_Flag_Top_Front_Center

tak_Speaker_Flag_Top_Front_Right

tak_Speaker_Flag_Top_Back_Left

tak_Speaker_Flag_Top_Back_Center

tak_Speaker_Flag_Top_Back_Right

### function tak_GetWaveExtensibleSpeakerMask

Converts the speaker assignment of the audio channels from TAK's representation to the format used by the channel mask of WaveFormatExtensible.

Pascal:

    function tak_GetWaveExtensibleSpeakerMask (const AFormat : TtakAudioFormatEx;
                                               var   AMask   : TtakUInt32) : TtakBool;  cdecl;

C:

    TAK_API TtakBool tak_GetWaveExtensibleSpeakerMask (TtakAudioFormatEx *  AFormat;
                                                       TtakUInt32 *         AMask);

Converts the speaker assigment in AFormat to AMask.

If AFormat is valid and the speaker assignment can be represented as channel mask, the result is tak_True.

You may use the tak_Speaker_Flag_xxx-constants to access the channel mask.

## Codecs and presets

### function tak_GetCodecName

Provides the name of a codec.

Pascal:

    function tak_GetCodecName (ACodec    : TtakInt32;
                               AName     : PChar;
                               ANameSize : TtakInt32) : TtakResult; cdecl;

C:

    TtakResult tak_GetCodecName (TtakInt32 ACodec,
                                 char *    AName,
                                 TtakInt32 ANameSize);

AName contains a plain text name for ACodec. ANameSize is the size of AName in bytes and should be tak_CodecNameLenSize at least.

Special function results:

tak_res_IncompatibleVersion

ACodec is unknown, AName is not defined.

### type TtakPresets

Encoder presets.

Pascal:

    type
      TtakPresets = TtakInt32;

C:

    typedef TtakInt32 TtakPresets;

### type TtakPresetEvaluations

Preset evaluations.

Pascal:

    type
      TtakPresetEvaluations = TtakInt32;

C:

    typedef TtakInt32 TtakPresetEvaluations;

Following values are possible:

tak_PresetEval_Standard

tak_PresetEval_Extra

tak_PresetEval_Max

TAK's Preset evaluations (Standard to Max).

## Stream / Container

### const tak_FrameSizeMax = 16384

Maximum number of samples in a frame.

### const tak_FrameDurationMax = 250

Maximum length of a frame (in ms).

### const tak_str_SimpleWaveDataSizeMax = 1024 * 1024

Maximum size of Wave metadata.

### type Ttak_str_EncoderInfo

Information about the used codec.

Pascal:

    type
      Ttak_str_EncoderInfo = packed record
        Codec   : TtakInt32;
        Profile : TtakPresets;
      end;

C:

    typedef struct Ttak_str_EncoderInfo {
        TtakInt32   Codec;
        TtakPresets Profile;
    } Ttak_str_EncoderInfo;

Fields:

Codec

Codec type. Range: 0-63.

In TAK 1.0 this value is always 0. Other values are possible when new codecs are added or an existing codec's error correction leads to incompatibilities with older decoders.

tak_GetCodecName provides the name of a codec.

Profile

Hardware profile, codec-specific where appropriate.

In case the user uses the standard settings of the pre-defined presets, the value matches the chosen preset.

Profiles define performance requirements for the decoder. The relevant parameters are:

- The frame length (memory requirements)
- The number of predictors (CPU performance)
- Usage of the method 'Channel decorrelation - Prediction'. (CPU performance)
- Usage of the prefilter. (CPU performance)

Example: If the user chooses the TURBO preset and increases the number of predictors from 16 to 128, HIGH is saved as the profile.

### type TtakFrameSizeTypes

TAK defines a limited number of frame size types, specifying either the frame length in ms or the frame size in samples.

Pascal:

    type
      TtakFrameSizeTypes = TtakInt32;

C:

    typedef TtakInt32 Ttak_str_FrameSizeTypes;

Possible values:

tak_FrameSizeType_94_ms

tak_FrameSizeType_125_ms

tak_FrameSizeType_188_ms

tak_FrameSizeType_250_ms

Frame size in ms.

tak_FrameSizeType_4096

tak_FrameSizeType_8192

tak_FrameSizeType_16384

tak_FrameSizeType_512

tak_FrameSizeType_1024

tak_FrameSizeType_2048

Frame size in samples.

Frame sizes are specified as time values by default. There are only two exceptions:

- With high sample rates the desired frame length cannot be achieved without exceeding the maximum number of samples per frame. In this case tak_FrameSizeType_16384 is set.
- A hardware decoder only has limited memory available, thus it might not be able to cope with frame sizes higher than, for example, 4096. In this case the frame size can be limited accordingly during encoding.

### type Ttak_str_SizeInfo

Information about size parameters.

Pascal:

    type
      Ttak_str_SizeInfo = packed record
        FrameSize          : TtakFrameSizeTypes;
        FrameSizeInSamples : TtakInt32;
        SampleNum          : TtakInt64;
      end;

C:

    typedef struct Ttak_str_SizeInfo {
        Ttak_str_FrameSizeTypes FrameSize;
        TtakInt32               FrameSizeInSamples;
        TtakInt64               SampleNum;
    } Ttak_str_SizeInfo;

Fields:

FrameSize

Frame size type.

FrameSizeInSamples

Frame size in samples. Range: 1 to 16384.

SampleNum

Stream length in samples.

The maximum stream length for TAK 1.0 always fits into an unsigned long.

See also:

TtakFrameSizeTypes

### type Ttak_str_StreamInfo

Superseded by Ttak_str_StreamInfo_V22.

Pascal:

    type
      Ttak_str_StreamInfo = packed record
        Encoder : Ttak_str_EncoderInfo;
        Sizes   : Ttak_str_SizeInfo;
        Audio   : TtakAudioFormat;
      end;

C:

    typedef struct Ttak_str_StreamInfo {
        Ttak_str_EncoderInfo Encoder;
        Ttak_str_SizeInfo    Sizes;
        TtakAudioFormat      Audio;
    } Ttak_str_StreamInfo;

See also:

Ttak_str_EncoderInfo, Ttak_str_SizeInfo, TtakAudioFormat

### type Ttak_str_StreamInfo_V22

Summarizes all stream information necessary for decoding.

Pascal:

    type
      Ttak_str_StreamInfo_V22 = packed record
        Encoder : Ttak_str_EncoderInfo;
        Sizes   : Ttak_str_SizeInfo;
        Audio   : TtakAudioFormatEx;
      end;

C:

    typedef struct Ttak_str_StreamInfo_V22 {
        Ttak_str_EncoderInfo Encoder;
        Ttak_str_SizeInfo    Sizes;
        TtakAudioFormatEx    Audio;
    } Ttak_str_StreamInfo_V22;

See also:

Ttak_str_EncoderInfo, Ttak_str_SizeInfo, TtakAudioFormatEx

### type Ttak_str_SimpleWaveDataHeader

Description of the metadata block of a Wave file.

Pascal:

    type
      Ttak_str_SimpleWaveDataHeader = packed record
        HeadSize : TtakInt32;
        TailSize : TtakInt32;
      end;

C:

    typedef struct Ttak_str_SimpleWaveDataHeader {
        TtakInt32 HeadSize;
        TtakInt32 TailSize;
    } Ttak_str_SimpleWaveDataHeader;

Fields:

HeadSize

Size of the Wave header (in Bytes).

TailSize

Size of the metadata following the audio data at the end of a file (where applicable).

### type Ttak_str_MetaEncoderInfo

Information about the used encoder.

Pascal:

    type
      Ttak_str_MetaEncoderInfo = packed record
        Version    : TtakInt32;
        Preset     : TtakPresets;
        Evaluation : TtakPresetEvaluations;
      end;

C:

    typedef struct Ttak_str_MetaEncoderInfo {
        TtakInt32             Version;
        TtakPresets           Preset;
        TtakPresetEvaluations Evaluation;
    } Ttak_str_MetaEncoderInfo;

Fields:

Version

The encoder's three-digit version number, each with a size of 1 byte. The lowest byte is the lowest digit. Example: 00010000h = 1.0.0

Preset

Encoder preset.

Evaluation

Preset evaluation.

See also:

TtakPresets, TtakPresetEvaluations

### type Ttak_str_MD5

MD5 sum.

Pascal:

    type
      Ttak_str_MD5 = Array[0..15] of Byte;

C:

    typedef char Ttak_str_MD5[16];