SSD Referenz

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

Methoden und Funktionen

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);

Öffnet die Datei ASourcePath (maximal tak_MaxPathLen Zeichen ohne abschließende 0!) und erzeugt einen passenden Decoder, der als Funktionsergebnis zurückgeliefert und als Kontextparameter für die übrigen Funktionen verwendet wird.

Nach Aufruf dieser Funktion sollte grundsätzlich mittels tak_SSD_Valid geprüft werden, ob der Decoder einsatzbereit ist! Das Funktionsergebnis ist nämlich nur dann nil, wenn ein gravierender Systemfehler vorliegt, z.B. ein OutOfMemory!

AOptions spezifiziert Optionen.

ADamageCallback und ACallbackUser sind optional, dürfen also nil sein.

ADamageCallback wird ggfs. immer dann aufgerufen, wenn der Decoder einen beschädigten Datenblock übersprungen hat. Die dabei übergebenen Informationen können für die Erstellung eines Fehlerliste verwendet werden.

ACallbackuser sind beliebige Anwenderdaten, die beim Callbackaufruf zusätzlich übergeben werden, z.B. als Anwenderkontext.

Falls eine Zusammenfassung aller Beschädigungen ausreicht, ist es einfacher, am Dateiende einmal tak_SSD_GetStateInfo aufzurufen.

Siehe auch:

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);

Wie tak_SSD_Create_FromFile, nur daß die zu dekodierenden Daten mittels des Interfaces ASourceStream gelesen werden. ASourceStreamUser enthält beliebige Anwenderdaten, die bei jedem Aufruf einer Interfacefunktion als zusätzlicher Parameter übergeben werden.

Der SSD verwendet derzeit folgende Funktionen des Interfaces:

      CanRead
      CanWrite
      CanSeek
      Read
      Seek
      GetLength

Siehe auch:

TtakStreamIoInterface

procedure tak_SSD_Destroy

Pascal:

procedure tak_SSD_Destroy (ADecoder : TtakSeekableStreamDecoder); cdecl;

C:

void tak_SSD_Destroy(TtakSeekableStreamDecoder ADecoder);

Zerstört ADecoder und gibt dabei alle belegten Resourcen frei.

function tak_SSD_Valid

Pascal:

function tak_SSD_Valid (ADecoder : TtakSeekableStreamDecoder) : TtakBool; cdecl;

C:

TtakBool tak_SSD_Valid (TtakSeekableStreamDecoder ADecoder);

Liefert tak_True, wenn kein fataler Fehler aufgetreten ist. Dann können weitere Lesezugriffe erfolgen.

function tak_SSD_State

Pascal:

function tak_SSD_State (ADecoder : TtakSeekableStreamDecoder) : TtakResult; cdecl;

C:

TtakResult tak_SSD_State (TtakSeekableStreamDecoder ADecoder);

Liefert den aktuellen Fehlerstatus bzw. den schlimmsten bislang aufgetretenen Fehler.

Siehe auch:

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);

Liefert erweiterte Statusinformationen in AInfo.

Das Ergebnis ist immer tak_res_Ok, wenn die Parameter gültig sind.

Achtung: Jeder Seek setzt folgende Felder in AInfo auf 0:

    ReadSampleNum
    DamagedSampleNum
    SkippedDataBlockNum

Siehe auch:

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);

Liefert in AString einen englischen Fehlertext für den Fehler AError. AStringSize enthält die Größe von AString in Bytes und sollte wenigstens tak_ErrorStringSizeMax sein.

Das Ergebnis ist immer tak_res_Ok, wenn die Parameter gültig sind.

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);

Liefert in AInfo Informationen über den Stream.

Siehe auch:

Ttak_str_StreamInfo

function tak_SSD_GetFrameSize

Pascal:

function tak_SSD_GetFrameSize (ADecoder : TtakSeekableStreamDecoder) : TtakInt32; cdecl;

C:

TtakInt32 tak_SSD_GetFrameSize (TtakSeekableStreamDecoder ADecoder);

Liefert die Framegröße in Samples oder -1, wenn ein fataler Fehler aufgetreten ist.

function tak_SSD_Seek

Pascal:

function tak_SSD_Seek (ADecoder   : TtakSeekableStreamDecoder;
                       ASamplePos : TtakInt64) : TtakResult; cdecl;

C:

TtakResult tak_SSD_Seek (TtakSeekableStreamDecoder ADecoder,
                         TtakInt64                 ASamplePos);

Setzt die Leseposition für nachfolgende Aufrufe von tak_SSD_ReadAudio auf Sampleposition ASamplePos.

ASamplePos muß zwischen 0 und Streamlänge - 1 liegen.

Derzeit klappt Seeking nur dann, wenn die obligatorische Seektable nicht beschädigt ist und keine Dateiteile entfernt oder unsinniges eingefügt wurde.

Spezielle Funktionsergebnisse:

tak_res_ssd_FrameDamaged

Es wurden beschädigte Audiodaten gefunden. Das ist kein fataler Fehler!

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);

Liest bis zu ASampleNum Samples nach ASamples. AReadNum enthält die Anzahl tatsächlich gelesener Samples. Nur am Dateiende kann AReadNum kleiner ASampleNum sein.

Das Format der Audiodaten entspricht den gängigen Wavedateikonventionen; so belegt z.B. jedes individuelle Sample gerade so viele Bytes wie zur Aufnahme der Sampebits nötig sind. Samples bis zu 8 Bit sind vorzeichenlos, alle anderen vorzeichenbehaftet. Mehrere Kanäle werden sampleweise verschachtelt.

Spezielle Funktionsergebnisse:

tak_res_Ok

Auch wenn AReadNum = 0, sofern kein Fehler aufgetreten ist!

tak_res_ssd_FrameDamaged

Es wurden beschädigte Audiodaten gelesen. Das ist kein fataler Fehler!

Wird eine Datei von Anfang an sequentiell gelesen, kann es geschwindigkeitstechnisch vorteilhaft sein, bei jedem Aufruf genau einen Frame zu lesen. Die Framegröße kann mittels tak_SSD_GetFrameSize erfragt werden.

function tak_SSD_GetReadPos

Pascal:

function tak_SSD_GetReadPos (ADecoder : TtakSeekableStreamDecoder) : TtakInt64; cdecl;

C:

TtakInt64 tak_SSD_GetReadPos (TtakSeekableStreamDecoder ADecoder);

Liefert die aktuelle Leseposition in Samples. Der nächste Aufruf von tak_SSD_ReadAudio liest von dieser Stelle.

Das Ergebnis ist -1, wenn ein fataler Fehler aufgetreten ist.

function tak_SSD_GetCurFrameBitRate

Pascal:

function tak_SSD_GetCurFrameBitRate (ADecoder : TtakSeekableStreamDecoder) : TtakInt32; cdecl;

C:

TtakInt32 tak_SSD_GetCurFrameBitRate (TtakSeekableStreamDecoder ADecoder);

Liefert die komprimierte Bitrate (Bits pro Sekunde) des letzen gelesenen Frames oder -1, wenn ein fataler Fehler aufgetreten ist.

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);

Liest -sofern im Container enthalten- die Bescheibung der Wave-Metadaten nach ADesc.

Spezielle Funktionsergebnisse:

tak_res_ssd_MetaDataMissing

Der Stream enthält keine Wave-Metadaten.

tak_res_ssd_MetaDataDamaged

Die Wave-Metadaten sind beschädigt.

Siehe auch:

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);

Liest -sofern im Container enthalten-, führende und abschließende Wave-Metadaten nach ABuf. ABufSize muß die Größe von ABuf enthalten.

Die Größen sind zuvor mittels tak_SSD_GetSimpleWaveDataDesc zu ermitteln.

Der Header steht am Beginn von ABuf und ist Ttak_str_SimpleWaveDataHeader.HeadSize Bytes groß. Darauf folgen TailSize Bytes für angehängte Metadaten.

Spezielle Funktionsergebnisse:

tak_res_ssd_MetaDataMissing

Der Stream enthält keine Wave-Metadaten.

tak_res_ssd_MetaDataDamaged

Die Wave-Metadaten sind beschädigt.

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);

Liefert Informationen über den verwendeten Encoder.

Spezielle Funktionsergebnisse:

tak_res_ssd_MetaDataDamaged

Diese Metadaten sind beschädigt.

Achtung: Dateien, die mit TAK 1.0 erzeugt wurden, enthalten eigentlich keine Metainformationen über den Encoder. Der Decoder rekonstruiert sie aber soweit möglich: Enthält eine Datei keine (ab TAK 1.0.1 obligatorischen) Encoder- Metainformationen, wird als Encoderversion 1.0.0 (für TAK 1.0) eingesetzt. Das Preset wird aus der StreamInfo entnommen. Da es in TAK 1.0 keine Möglichkeit gibt, die Preset-Evaluation zu bestimmen, wird diese immer auf tak_PresetEval_Standard gesetzt. Anwendungen sollten deshalb bei Encoderversion 1.0.0 als Preset-Evaluation "Unbekannt" anzeigen.

Siehe auch:

Ttak_str_MetaEncoderInfo

function tak_SSD_GetAPEv2Tag

Pascal:

function tak_SSD_GetAPEv2Tag (ADecoder : TtakSeekableStreamDecoder) : TtakAPEv2Tag; cdecl;

C:

TtakAPEv2Tag tak_SSD_GetAPEv2Tag (TtakSeekableStreamDecoder ADecoder);

Liefert eine Referenz auf das APEv2-Tag-Objekt des Decoders oder Nil bzw. NULL, wenn ADecoder Nil bzw. NULL ist.

Vor dem Einsatz des Tag-Objektes ist zunächst zu prüfen, ob es gültig ist!

Das Tag wird beim ersten Aufruf dieser Funktion aus der Datei in den Speicher geladen und dort gehalten. Nachfolgende Funktionsaufrufe führen also keine Dateizugriffe aus.

Siehe auch:

TtakAPEv2Tag

Typen

TtakSeekableStreamDecoder

Decoderinstanz.

Pascal:

type
  TtakSeekableStreamDecoder = Pointer;

C:

typedef void * TtakSeekableStreamDecoder;

TtakSSDOptions

Optionen.

Pascal:

   
type
  TtakSSDOptions = packed record
    Cpu   : TtakCpuOptions;
    Flags : TtakInt32;
  end;

C:

typedef struct TtakSSDOptions {
    TtakCpuOptions Cpu;
    TtakInt32      Flags;
} TtakSSDOptions;

Felder:

Cpu

Welche CPU-Optimierungen sollen verwendet werden? tak_Cpu_Any für beste Performance. Siehe auch TtakCpuOptions.

Flags

Optionen als tak_ssd_opt_xxx-Flags.

Folgende Werte können in Flags eingesetzt werden:

tak_ssd_opt_OpenWriteable

Quelldatei auch zum Schreiben öffnen.

Nicht implementiert. Wird später vielleicht zum Schreiben von Tags benötigt.

tak_ssd_opt_BufferInput

Sollen die Leseoperationen gepuffert werden?

Aktuelle Empfehlung: Sollte nicht verwendet werden!

Früherer TAK-Versionen pufferten grundsätzlich, aber Tests des aktuellen Decoders zeigten keinerlei Geschwindigkeitsvorteil gegenüber deaktivierter Pufferung. Die Option bleibt nur für den Fall erhalten, daß andere Testsysteme negativ auf ein Abschalten der Pufferung reagieren.

tak_ssd_opt_SequentialRead

Die Audiodaten werden ausschließlich sequentiell gelesen. Erlaubt dem Decoder einige Optimierungen. Verbietet Seek-Operationen.

tak_ssd_opt_SkipDamagedFrames

Standardmäßig werden die Audiodaten beschädigter Frames durch Stille ersetzt. Bei Aktivierung dieser Option werden sie stattdessen ersatzlos entfernt.

Muß in Verbindung mit tak_ssd_opt_SequentialRead eingesetzt werden. Also sind in diesem Modus auch keine Seek-Operationen möglich.

TtakSSDDamageItem

Informationen über Datenfehler, die an die DamageCallback-Funktion übergeben werden.

Pascal:

type
  PtakSSDDamageItem = ^TtakSSDDamageItem;
  TtakSSDDamageItem = packed record
    SamplePosition : TtakInt64;
    SampleSize     : TtakInt64;
  end;

C:

typedef struct TtakSSDDamageItem {
    TtakInt64 SamplePosition;
    TtakInt64 SampleSize;
} TtakSSDDamageItem, *PtakSSDDamageItem;

Felder:

SamplePosition

SampleSize

SampleSize undekodierbare Samples ab Sampleposition SamplePosition.

TSSDDamageCallback

Callbackfunktion, die beim Auftreten jedes Datenfehlers aufgerufen wird.

Pascal:

type
  TSSDDamageCallback = procedure (AUser   : Pointer;
                                  ADamage : PtakSSDDamageItem); cdecl;

C:

typedef void (*TSSDDamageCallback)(void *            AUser,
                                   PtakSSDDamageItem ADamage);

Siehe auch:

TtakSSDDamageItem

type TtakSSDResult

Erweiterte Statusinformationen.

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;

Felder:

OpenResult

Not defined.

SumResult

Schlimmster bislang aufgetretener Fehler. Entspricht dem Ergebnis von tak_SSD_State.

StreamSampleNum

Dateigröße in Samples laut StreamInfo.

ReadSampleNum

Gesamtanzahl ausgegebener Samples.

DamagedSampleNum

Von ReadSampleNum waren so viele beschädigt.

SkippedDataBlockNum

Soviele Datenblöcke konnten nicht dekodiert werden und wurden übersprungen. Jeder enthält mindestens einen, möglicherweise mehrere Frames.

Konstanten

tak_res_ssd_xxx

Decoderspezifische Fehler und Warnungen.

Hierachisch: Gößere Werte = schlimmer.

Warnungen:

tak_res_ssd_MetaDataMissing

Die gewünschten Metadaten sind optional und nicht im Container enthalten.

Fehler:

tak_res_ssd_MetaDataDamaged

Eine oder mehrere Metadatenstrukturen sind beschädigt.

tak_res_ssd_FrameDamaged

Wenigstens ein Audioframe konnte nicht dekodiert werden.

tak_res_ssd_ErrorFirst

Codes >= diesem Wert sind Fehler.

Fatale Fehler:

tak_res_ssd_SourceIoError

Fehler beim Lesen der Quelldatei.

tak_res_ssd_IncompatibleVersion

Datei wurde mit einer neueren Programmversion erzeugt, die Methoden verwendet hat, die diese Bibliothek nicht unterstützt.

tak_res_ssd_Undecodable

Entweder ist die Quelldatei keine TAK-Datei oder sie ist zu schwer beschädigt, um auch nur einen Audioframe dekodieren zu können.

tak_res_ssd_FatalErrorFirst

Codes >= diesem Wert sind fatal.