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.

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_Asm

Use Assembler optimizations, utilizing no CPU-specific instructions. Currently ignored.

tak_Cpu_MMX

Use MMX (64-Bit).

tak_Cpu_SSE

Use SSE1. Currently not implemented.

tak_Cpu_None

Use no code optimizations at all.

tak_Cpu_Any

Use all code optimizations supported by your target system.

TAK automatically deactivates optimizations not supported by the CPU.

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.

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)

This structure will be extended for more than 2 channels.

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:

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:

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

Summarizes all stream information necessary for decoding.

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_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