Software Development Kit for TAK, (T)om's lossless (A)udio (K)ompressor.
Version: TAK SDK 1.1.1, 2009-03-11
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.
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.
In the following, User refers to the developer utilizing the SDK.
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.
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.
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...
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:
Non-fatal errors are:
Fatal errors are:
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.
General definitions not associated with a particular object.
Elementary types | Description |
type TtakInt64 | Signed integer type with 64 bits. |
type TtakInt32 | Signed integer type with 32 bits. |
type TtakUInt32 | Unsigned integer type with 32 bits. |
type TtakBool | Boolean type. |
Function results | Description |
type TtakResult | Function result and objekt status. |
const tak_res_xxx | General result contants. |
Library | Description |
const tak_InterfaceVersion | Version of the library interface. |
func tak_GetLibraryVersion | Provides library version information. |
System | Description |
type TtakCpuOptions | Specifies CPU features for optimizations. |
const tak_Cpu_xxx | Flags for CPU features and optimizations. |
type TtakStreamIoInterface | Interface for external file access implementations. |
Audio format | Description |
const tak_AudioFormat_xxx | Specification of the audio data format. |
type TtakAudioFormat | Specification of the audio format. |
Codecs and presets | Description |
func tak_GetCodecName | Provides the name of a codec. |
type TtakPresets | Encoder presets. |
type TtakPresetEvaluations | Preset evaluations. |
const tak_PresetEval_xxx | Preset evaluation constants. |
Stream / container | Description |
type Ttak_str_EncoderInfo | Information about the used codec. |
type TtakFrameSizeTypes | Frame size type. |
type Ttak_str_SizeInfo | Information about size parameters of the stream. |
type Ttak_str_StreamInfo | Summarizes all stream information necessary for decoding. |
type Ttak_str_SimpleWaveDataHeader | Description of a Wave file's metadata blocks. |
type Ttak_str_MetaEncoderInfo | Information about the used encoder. |
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:
TAK's current implementation features following restrictions:
Status functions | Descriptions |
tak_APE_Valid | Shows whether a fatal error occurred or not. |
tak_APE_State | Provides the current error status or the worst error occurred so far, respectively. |
tak_APE_GetErrorString | Provides an english error text for an error code. |
tak_APE_ReadOnly | Returns the access mode. |
tak_APE_GetDesc | Provides information about the tag. |
tak_APE_GetItemNum | Returns the number of items. |
Editing | Descriptions |
tak_APE_GetIndexOfKey | Returns the index of an item key. |
tak_APE_GetItemDesc | Provides information about an item. |
tak_APE_GetItemKey | Returns the ASCII-coded item key. |
tak_APE_GetItemValue | Returns the UTF8-coded item value. |
tak_APE_GetTextItemValueAsAnsi | Provides the ANSI-coded value of a text item or selected values when the item has multiple values. |
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.
Following program examples are available:
Create and destroy objects | Description |
tak_SSD_Create_FromFile | Creates a decoder instance which decodes a file. |
tak_SSD_Create_FromStream | Creates a decoder instance which decodes an external stream. |
tak_SSD_Destroy | Destroys a decoder instance. |
Status functions | Description |
tak_SSD_Valid | Shows whether a fatal error occurred. |
tak_SSD_State | Returns the current error state, respectively the worst error occurred so far. |
tak_SSD_GetStateInfo | Provides extended status information. |
tak_SSD_GetErrorString | Provides an appropriate English error text for an error code. |
tak_SSD_GetStreamInfo | Provides information about the stream. |
tak_SSD_GetFrameSize | Returns the frame size in samples. |
Decode | Description |
tak_SSD_Seek | Sets read position. |
tak_SSD_ReadAudio | Reads and decodes samples. |
tak_SSD_GetReadPos | Returns the current read position in samples. |
tak_SSD_GetCurFrameBitRate | Returns the compressed bitrate of the last frame. |
tak_SSD_GetSimpleWaveDataDesc | Provides a description of the Wave metadata. |
tak_SSD_ReadSimpleWaveData | Reads Wave metadata. |
tak_SSD_GetEncoderInfo | Provides information about the used encoder. |
tak_SSD_GetAPEv2Tag | Provides a reference to the APEv2 tag object. |
Type | Description |
TtakSeekableStreamDecoder | Decoder instance. |
TtakSSDOptions | Options. |
TtakSSDDamageItem | Information about data errors which is transferred to the damage callback function. |
TSSDDamageCallback | Callback function called when encountering data errors. |
Constant | Description |
tak_res_ssd_xxx | SSD-specific errors and warnings. |