Copyright 2007 by Thomas Becker, D-49080 Osnabrück.
All rights reserved.
A signed 64-bit integer. Allocates 8 bytes.
A signed 32-bit integer. Allocates 4 bytes.
An unsigned 32-bit integer. Allocates 4 bytes.
Can only take two values:
tak_False
false / no.
tak_True
true / yes.
Ansi character with 8 bits. Windows codepage encoding.
Unicode character with 16 bits. UTF-16 encoding.
Function result and object status
Pascal:
type TtakResult = TtakInt32;
C:
typedef TtakInt32 TtakResult;
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.
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.
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.
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.
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.
Specification of the audio data format:
tak_AudioFormat_DataType_PCM
PCM audio.
Maximum number of channels supported by the stream.
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.
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
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];
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.
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
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.
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.
Encoder presets.
Pascal:
type TtakPresets = TtakInt32;
C:
typedef TtakInt32 TtakPresets;
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).
Maximum number of samples in a frame.
Maximum length of a frame (in ms).
Maximum size of Wave metadata.
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.
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:
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:
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
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
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).
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
MD5 sum.
Pascal:
type Ttak_str_MD5 = Array[0..15] of Byte;
C:
typedef char Ttak_str_MD5[16];