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