SSD Reference

Copyright 2007 by Thomas Becker, D-49080 Osnabrück.
All rights reserved.

Methods and Functions

function tak_SSD_Create_FromFile

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

function tak_SSD_Create_FromStream

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:

TtakStreamIoInterface

procedure tak_SSD_Destroy

Pascal:

procedure tak_SSD_Destroy (ADecoder : TtakSeekableStreamDecoder); cdecl;

C:

void tak_SSD_Destroy(TtakSeekableStreamDecoder ADecoder);

Destroys ADecoder and deallocates all allocated resources.

function tak_SSD_Valid

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.

function tak_SSD_State

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:

tak_res_xxx, tak_res_ssd_xxx

function tak_SSD_GetStateInfo

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:

TtakSSDResult

function tak_SSD_GetErrorString

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.

function tak_SSD_GetStreamInfo

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:

Ttak_str_StreamInfo

function tak_SSD_GetFrameSize

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.

function tak_SSD_Seek

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!

function tak_SSD_ReadAudio

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.

function tak_SSD_GetReadPos

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.

function tak_SSD_GetCurFrameBitRate

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.

function tak_SSD_GetSimpleWaveDataDesc

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:

Ttak_str_SimpleWaveDataHeader

function tak_SSD_ReadSimpleWaveData

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.

function tak_SSD_GetEncoderInfo

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:

Ttak_str_MetaEncoderInfo

function tak_SSD_GetAPEv2Tag

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:

TtakAPEv2Tag

Types

TtakSeekableStreamDecoder

Decoder instance.

Pascal:

type
  TtakSeekableStreamDecoder = Pointer;

C:

typedef void * TtakSeekableStreamDecoder;

TtakSSDOptions

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.

TtakSSDDamageItem

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.

TSSDDamageCallback

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:

TtakSSDDamageItem

type TtakSSDResult

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.

Constants

tak_res_ssd_xxx

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.