Copyright 2007 by Thomas Becker, D-49080 Osnabrück.
All rights reserved.
Pascal:
function tak_SSD_Create_FromFile ( ASourcePath : PChar; const AOptions : TtakSSDOptions; ADamageCallback : TSSDDamageCallback; ACallbackUser : Pointer): TtakSeekableStreamDecoder; cdecl;
C:
TtakSeekableStreamDecoder tak_SSD_Create_FromFile (const char * ASourcePath, const TtakSSDOptions * AOptions, TSSDDamageCallback ADamageCallback, void * ACallbackUser);
This opens the file ASourcePath (maximum of tak_MaxPathLen characters without trailing 0!) and creates an appropriate decoder which is returned as the function result and used as a context parameter for the following functions.
Afterwards, the decoder's operational readiness should categorically be tested by means of tak_SSD_Valid! The function result will only be nil when a serious system error (like OutOfMemory) occurred.
AOptions specifies options.
ADamageCallback and ACallbackUser are optional and thus may also be nil.
ADamageCallback is called each time the decoder skips an erroneous data block. The information transferred along the way can be used to create an error list.
ACallbackuser is arbitrary user data transferred during each call of a callback as user context information, for example.
If a damage summary is sufficient, it is easier to call tak_SSD_GetStateInfo once at the end of a file.
See also:
TtakSSDOptions, TSSDDamageCallback, TtakSeekableStreamDecoder
Pascal:
function tak_SSD_Create_FromStream ( ASourceStream : PtakStreamIoInterface; ASourceStreamUser : Pointer; const AOptions : TtakSSDOptions; ADamageCallback : TSSDDamageCallback; ACallbackUser : Pointer) : TtakSeekableStreamDecoder; cdecl;
C:
TtakSeekableStreamDecoder tak_SSD_Create_FromStream (const TtakStreamIoInterface * ASourceStream, void * ASourceStreamUser, const TtakSSDOptions * AOptions, TSSDDamageCallback ADamageCallback, void * ACallbackUser);
Apart from the fact that the data due to decoding is read by means of the ASourceStream interface, this works like tak_SSD_Create_FromFile. ASourceStreamUser contains arbitrary user data which is transferred as a parameter each time an interface function is called.
Currently, the SSD uses the following functions of the interface:
CanRead CanWrite CanSeek Read Seek GetLength
See also:
Pascal:
procedure tak_SSD_Destroy (ADecoder : TtakSeekableStreamDecoder); cdecl;
C:
void tak_SSD_Destroy(TtakSeekableStreamDecoder ADecoder);
Destroys ADecoder and deallocates all allocated resources.
Pascal:
function tak_SSD_Valid (ADecoder : TtakSeekableStreamDecoder) : TtakBool; cdecl;
C:
TtakBool tak_SSD_Valid (TtakSeekableStreamDecoder ADecoder);
Returns tak_True if no fatal error occurred. Then further read access can take place.
Pascal:
function tak_SSD_State (ADecoder : TtakSeekableStreamDecoder) : TtakResult; cdecl;
C:
TtakResult tak_SSD_State (TtakSeekableStreamDecoder ADecoder);
Returns the current error state, respectively the worst error occurred so far.
See also:
Pascal:
function tak_SSD_GetStateInfo ( ADecoder : TtakSeekableStreamDecoder; var AInfo : TtakSSDResult) : TtakResult; cdecl;
C:
TtakResult tak_SSD_GetStateInfo (TtakSeekableStreamDecoder ADecoder, TtakSSDResult * AInfo);
Provides extended status information in AInfo.
With valid parameters, the result is always tak_res_Ok.
Attention: Every seek resets the following fields in AInfo to 0:
ReadSampleNum DamagedSampleNum SkippedDataBlockNum
See also:
Pascal:
function tak_SSD_GetErrorString (AError : TtakResult; AString : PChar; AStringSize : TtakInt32) : TtakResult; cdecl;
C:
TtakResult tak_SSD_GetErrorString (TtakResult AError, char * AString, TtakInt32 AStringSize);
Provides an English error text for AError in AString. AStringSize contains the size of AString in Bytes and should be at least tak_ErrorStringSizeMax.
With valid parameters, the result is always tak_res_Ok.
Pascal:
function tak_SSD_GetStreamInfo ( ADecoder : TtakSeekableStreamDecoder; var AInfo : Ttak_str_StreamInfo) : TtakResult; cdecl;
C:
TtakResult tak_SSD_GetStreamInfo (TtakSeekableStreamDecoder ADecoder, Ttak_str_StreamInfo * AInfo);
Provides stream information in AInfo.
See also:
Pascal:
function tak_SSD_GetFrameSize (ADecoder : TtakSeekableStreamDecoder) : TtakInt32; cdecl;
C:
TtakInt32 tak_SSD_GetFrameSize (TtakSeekableStreamDecoder ADecoder);
Returns the frame size (in samples) or -1, if a fatal error occurred.
Pascal:
function tak_SSD_Seek (ADecoder : TtakSeekableStreamDecoder; ASamplePos : TtakInt64) : TtakResult; cdecl;
C:
TtakResult tak_SSD_Seek (TtakSeekableStreamDecoder ADecoder, TtakInt64 ASamplePos);
Sets the read position on sample position ASamplePos for following tak_SSD_ReadAudio calls.
ASamplePos must be a value between 0 and (stream length - 1).
Currently seeking only works if the obligatory seek table is undamaged and data integrity is preserved, meaning no file parts have been removed and no nonsense has been inserted into the file.
Special function results:
tak_res_ssd_FrameDamaged
Damaged audio data was found. This is no fatal error!
Pascal:
function tak_SSD_ReadAudio ( ADecoder : TtakSeekableStreamDecoder; ASamples : Pointer; ASampleNum : TtakInt32; var AReadNum : TtakInt32) : TtakResult; cdecl;
C:
TtakResult tak_SSD_ReadAudio (TtakSeekableStreamDecoder ADecoder, void * ASamples, TtakInt32 ASampleNum, TtakInt32 * AReadNum);
Reads up to ASampleNum samples to ASamples. AReadNum contains the number of samples actually read. AReadNum can be less than ASampleNum only at the end of the file.
The audio data format complies to common Wave file conventions; each sample only takes up as many bytes as necessary to save the sample bits. Samples up to 8 bits are unsigned, the rest is signed. Multiple channels are interleaved sample by sample.
Special function results:
tak_res_Ok
Even when AReadNum = 0, in case no error occurred!
tak_res_ssd_FrameDamaged
Damaged audio data was read. This is no fatal error!
If a file is read sequentially from the beginning, it might be faster to read exactly one frame per function call. You can query the frame size using tak_SSD_GetFrameSize.
Pascal:
function tak_SSD_GetReadPos (ADecoder : TtakSeekableStreamDecoder) : TtakInt64; cdecl;
C:
TtakInt64 tak_SSD_GetReadPos (TtakSeekableStreamDecoder ADecoder);
Returns current read position in samples. The next tak_SSD_ReadAudio call reads from this position on.
The result is -1 in case a fatal error occurred.
Pascal:
function tak_SSD_GetCurFrameBitRate (ADecoder : TtakSeekableStreamDecoder) : TtakInt32; cdecl;
C:
TtakInt32 tak_SSD_GetCurFrameBitRate (TtakSeekableStreamDecoder ADecoder);
Returns the compressed bit rate (bits per second) of the last read frame or -1 in case a fatal error occurred.
Pascal:
function tak_SSD_GetSimpleWaveDataDesc ( ADecoder : TtakSeekableStreamDecoder; var ADesc : Ttak_str_SimpleWaveDataHeader) : TtakResult; cdecl;
C:
TtakResult tak_SSD_GetSimpleWaveDataDesc (TtakSeekableStreamDecoder ADecoder, Ttak_str_SimpleWaveDataHeader * ADesc);
Reads the description of the Wave metadata - provided the container holds any - to ADesc.
Special function results:
tak_res_ssd_MetaDataMissing
The stream does not contain any Wave metadata.
tak_res_ssd_MetaDataDamaged
The Wave metadata is damaged.
See also:
Pascal:
function tak_SSD_ReadSimpleWaveData (ADecoder : TtakSeekableStreamDecoder; ABuf : Pointer; ABufSize : TtakInt32) : TtakResult; cdecl;
C:
TtakResult tak_SSD_ReadSimpleWaveData (TtakSeekableStreamDecoder ADecoder, void * ABuf, TtakInt32 ABufSize);
Reads leading and trailing Wave metadata - provided the container holds any - to ABuf. ABufSize has to hold the size of ABuf.
The metadata size has to be queried beforehand, using tak_SSD_GetSimpleWaveDataDesc.
The header is at the beginning of ABuf and is Ttak_str_SimpleWaveDataHeader.HeadSize bytes of size, with TailSize bytes for attached metadata following.
Special function results:
tak_res_ssd_MetaDataMissing
The stream does not contain any Wave metadata.
tak_res_ssd_MetaDataDamaged
The Wave metadata is damaged.
Pascal:
function tak_SSD_GetEncoderInfo ( ADecoder : TtakSeekableStreamDecoder; var AInfo : Ttak_str_MetaEncoderInfo) : TtakResult; cdecl;
C:
TtakResult tak_SSD_GetEncoderInfo (TtakSeekableStreamDecoder ADecoder, Ttak_str_MetaEncoderInfo * AInfo);
Provides information about the used encoder.
Special function results:
tak_res_ssd_MetaDataDamaged
This metadata is damaged.
Attention: Files created with TAK 1.0 actually do not contain any metadata information about the encoder. However, the decoder reconstructs the metadata if possible: In case a file does not contain encoder metadata information, 1.0.0 (for TAK 1.0) is used as encoder version. The preset is gathered from the StreamInfo. As there is no possibility to assign the preset evaluation in TAK 1.0, it is always set to tak_PresetEval_Standard. Therefore applications should show an "Unknown" preset evaluation if the encoder version is 1.0.0.
See also:
Pascal:
function tak_SSD_GetAPEv2Tag (ADecoder : TtakSeekableStreamDecoder) : TtakAPEv2Tag; cdecl;
C:
TtakAPEv2Tag tak_SSD_GetAPEv2Tag (TtakSeekableStreamDecoder ADecoder);
Provides a reference to the APEv2 tag object of the decoder or Nil (or NULL resp.) if ADecoder is Nil (or NULL resp.).
Before using the tag object its validity has to be checked!
At the first call of this function the tag is read from the file into the memory for further use, so consecutive function calls do not perform any access to the file.
See also:
Decoder instance.
Pascal:
type TtakSeekableStreamDecoder = Pointer;
C:
typedef void * TtakSeekableStreamDecoder;
Options.
Pascal:
type TtakSSDOptions = packed record Cpu : TtakCpuOptions; Flags : TtakInt32; end;
C:
typedef struct TtakSSDOptions { TtakCpuOptions Cpu; TtakInt32 Flags; } TtakSSDOptions;
Fields:
Cpu
Which CPU optimizations shall be used? tak_Cpu_Any for best performance. See also TtakCpuOptions.
Flags
Options as tak_ssd_opt_xxx-Flags.
Following values can be used as Flags:
tak_ssd_opt_OpenWriteable
Open the source file as writeable.
Not yet implemented. May probably be used for writing tags later.
tak_ssd_opt_BufferInput
Shall read operations be buffered?
Current recommendation: This should NOT be used!
Earlier TAK versions categorically buffered, but tests of the current decoder showed no speed advantages over inactive buffering. This option only remains for other test systems' potential problems with inactive buffering.
tak_ssd_opt_SequentialRead
Sequential audio data reading only, allowing the decoder to use a few optimizations, but prohibiting seek operations.
tak_ssd_opt_SkipDamagedFrames
By default, audio data of damaged frames is replaced with silence. If this option is activated, damaged frames are skipped.
As this option requires tak_ssd_opt_SequentialRead, no seek operation is possible in this mode.
tak_ssd_opt_CheckMd5
If the source file contains a MD5 checksum of the original raw audio data, the decoder will calculate the MD5 of the decoded data and compare it with the checksum stored in the file when the whole file has been decoded. If the checksums don't match, the state is set to tak_res_ssd_FrameDamaged.
As this option requires tak_ssd_opt_SequentialRead, no seek operation is possible in this mode.
Information about data errors which is transferred to the DamageCallback function.
Pascal:
type PtakSSDDamageItem = ^TtakSSDDamageItem; TtakSSDDamageItem = packed record SamplePosition : TtakInt64; SampleSize : TtakInt64; end;
C:
typedef struct TtakSSDDamageItem { TtakInt64 SamplePosition; TtakInt64 SampleSize; } TtakSSDDamageItem, *PtakSSDDamageItem;
Fields:
SamplePosition
SampleSize
SampleSize undecodable samples from SamplePosition on.
Callback function called on every occurrence of a data error.
Pascal:
type TSSDDamageCallback = procedure (AUser : Pointer; ADamage : PtakSSDDamageItem); cdecl;
C:
typedef void (*TSSDDamageCallback)(void * AUser, PtakSSDDamageItem ADamage);
See also:
Extended status information.
Pascal:
type TtakSSDResult = packed record OpenResult : TtakResult; SumResult : TtakResult; StreamSampleNum : TtakInt64; ReadSampleNum : TtakInt64; DamagedSampleNum : TtakInt64; SkippedDataBlockNum : TtakInt32; end;
C:
typedef struct TtakSSDResult { TtakResult OpenResult; TtakResult SumResult; TtakInt64 StreamSampleNum; TtakInt64 ReadSampleNum; TtakInt64 DamagedSampleNum; TtakInt32 SkippedDataBlockNum; } TtakSSDResult;
Fields:
OpenResult
Not defined.
SumResult
Worst error occurred so far, thus matching the result of tak_SSD_State.
StreamSampleNum
File size in samples, according to StreamInfo.
ReadSampleNum
Total number of output samples.
DamagedSampleNum
Number of damaged samples out of ReadSampleNum.
SkippedDataBlockNum
Number of undecodable and skipped data blocks, each one containing at least one, possibly multiple frames.
Decoder-specific errors and warnings.
Hierarchy: Higher values = worse.
Warnings:
tak_res_ssd_MetaDataMissing
The requested metadata is optional and could not be found in the container.
Errors:
tak_res_ssd_MetaDataDamaged
One or more metadata structures are damaged.
tak_res_ssd_FrameDamaged
One or more audio frames could not be decoded or the MD5 check failed.
tak_res_ssd_ErrorFirst
Codes >= this value are errors.
Fatal errors:
tak_res_ssd_SourceIoError
Error while reading the source file.
tak_res_ssd_IncompatibleVersion
The file was created with a newer program version using methods this library does not support.
tak_res_ssd_Undecodable
The source file is no TAK file or it is too heavily damaged for decoding a single audio frame.
tak_res_ssd_FatalErrorFirst
Codes >= this value are fatal errors.