TAK SDK 1.0.5

Software Developement Kit für TAK, (T)om's lossless (A)udio (K)ompressor.

Version: TAK SDK 1.0.5, 2007-12-05

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

Die Nutzungsbedingungen sowie weitere wichtige Informationen finden Sie in der Datei "Liesmich.html" im Stammverzeichnis.

Inhalt

Wichtige Hinweise

Allgemeine Definitionen

APEv2-Tag (APE)

Seekable Stream Decoder (SSD)

Wichtige Hinweise

Begriffe

Positions- und Größennangaben in Samples

sind immer so zu interpretieren, als ob es nur einen Audiokanal gäbe. So entspricht z.B. bei CD-Audio-Qualität 44100 immer der zeitlichen Position 1 Sekunde, gleichgültig ob die Datei in Mono oder Stereo vorliegt.

Anwender

Anwender bezeichnet im folgenden den Entwickler, der das SDK einsetzt.

Schnittstellen

Strukturen

Strukturen (record, struct) müssen gepackt sein, d.h. es dürfen keine Füllbytes für Datenalignment eingefügt werden.

Alle aktuellen Strukturen enthalten ausschließlich die Datentypen Int32 und Int64. Deshalb sollte es möglich, auch mit aktiviertem Alignment zu leben, wenn man Int64 durch zwei Int32 für low und high ersetzt. Dann haben alle Elemente die Größe 4.

Funktionsparameter

Alle Funktionsparameter werden von TAK grundsätzlich überprüft (Bereichsüberschreitungen, Puffergrößen, Null-Referenzen).

Alle Daten werden grundsätzlich in interne Strukturen kopiert, so daß sie nach dem Funktionsaufruf nicht mehr benötigt (keine Referenzen auf externe Daten) und somit zerstört werden können.

Interne Fehler

Die Bibliothek enthält noch einiges an Debugcode, der Exceptions auswerfen kann. Da diese derzeit nicht abgefangen werden, also bis zur Anwenderschicht durchdringen können, dürften unschöne crashes resultieren...

Wir arbeiten daran...

Funktionsergebnisse und Fehlerbehandlung

Die meisten Funktionen liefern das Ausführungsergebnis als TtakResult, manchmal als TtakBool.

TtakResult kann allgemeine oder auch objektspezifische (siehe z.B. Dekoder) Ergebniswerte annehmen.

Erfolg wird in der Regel mittels tak_res_Ok angezeigt.

Die übrigen Ergebniswerte gliedern sich in Warnungen, nicht-fatale und fatale Fehler.

Warnungen sind:

Nicht-fatale Fehler sind:

Fatale Fehler sind:

Nicht-fatale und fatale Fehler werden von jedem Objekt in einer Statusvariablen festgehalten, die mittels der State-Funktion (z.B. tak_SSD_State) abgefragt werden kann. Treten mehrere Fehler nacheinander auf, wird der gravierendste festgehalten.

Achtung: Warnungen werden zwar von der betroffenen Funktion geliefert, aber nicht im Status gespeichert!

So kann z.B. tak_SSD_GetSimpleWaveDataDesc das Ergebnis tak_res_ssd_MetaDataMissing liefern und ein nachfolgender Aufruf von tak_SSD_State dennoch tak_res_Ok.

Sobald ein fataler Fehler auftritt, wird das betroffene Objekt gesperrt. Die meisten Objektfunktionen kehren dann unmittelbar zurück und liefern als Ergebnis den Code des fatalen Fehlers. Nur einige Statusfunktionen sind noch verfügbar.

Jedes Objekt definiert eine Valid-Funktion, die tak_true liefert, solange kein fataler Fehler aufgetreten ist, so z.B. tak_SSD_Valid.

Allgemeine Definitionen

Allgemeine Definitionen, die sich nicht einem spezifischen Objekt zuordnen lassen.

Referenz

Elementare Typen Beschreibung
type TtakInt64 Vorzeichenbehafteter Ganzzahltyp mit 64 Bit.
type TtakInt32 Vorzeichenbehafteter Ganzzahltyp mit 32 Bit.
type TtakUInt32 Vorzeichenloser Ganzzahltyp mit 32 Bit.
type TtakBool Boolescher Typ.
Funktionsergebnisse Beschreibung
type TtakResult Funktionsergebnis und Objektstatus.
const tak_res_xxx Allgemeine Ergebniskonstanten.
Bibliothek Beschreibung
const tak_InterfaceVersion Die Version der Bibliotheksschnitstelle.
func tak_GetLibraryVersion Liefert Versionsinformationen der Bibliothek.
System Beschreibung
type TtakCpuOptions Spezifiziert CPU Features für Optimierungen.
const tak_Cpu_xxx Flags für CPU Features und Optimierungen.
type TtakStreamIoInterface Interface für externe Implementierungen der Dateizugriffe.
Audioformat Beschreibung
const tak_AudioFormat_xxx Spezifikation des Audiodatenformates.
type TtakAudioFormat Spezifikation des Audioformates.
Codecs und Presets Beschreibung
func tak_GetCodecName Liefert den Namen eines Codecs.
type TtakPresets Encoder-Presets.
type TtakPresetEvaluations Preset-Evaluation.
const tak_PresetEval_xxx Preset-Evaluationskonstanten.
Stream / Container Beschreibung
type Ttak_str_EncoderInfo Informationen über den verwendeten Codec.
type TtakFrameSizeTypes Framegrößentyp.
type Ttak_str_SizeInfo Informationen über Größenparameter des Streams.
type Ttak_str_StreamInfo Faßt alle für das Dekodieren benötigten Informationen über einen Stream zusammen.
type Ttak_str_SimpleWaveDataHeader Beschreibung der Metadatenbereiche einer Wavedatei.
type Ttak_str_MetaEncoderInfo Informationen über den verwendeten Encoder.

APEv2-Tag (APE)

Das APEv2-Tag-Objekt (APE) erlaubt den Zugriff auf ggfs. im Stream enthaltene APEv2-Tag-Informationen. Tagobjekte werden ausschließlich von anderen Objekten (Decoder oder Encoder) zur Verfügung gestellt. Der Anwender kann selbst keine Instanzen erzeugen.

Die Implementierung der Lese- und Schreibfunktionen sowie Gültigkeitsregeln basiert auf der Formatspezifikation des Hydrogenaudio-Wikis.

Folgende Terminologie wird verwendet:

TAK's aktuelle Implementierung weist folgende Restriktionen auf:

Referenz

Methoden und Funktionen

Statusfunkionen Beschreibung
tak_APE_Valid Zeigt an, ob ein fataler Fehler aufgetreten ist.
tak_APE_State Liefert den aktuellen Fehlerstatus bzw. den schlimmsten bislang aufgetretenen Fehler.
tak_APE_GetErrorString Liefert einen englischen Fehlertext zu einem Fehlercode.
tak_APE_ReadOnly Liefert den Zugriffsmodus.
tak_APE_GetDesc Liefert Informationen über das Tag.
tak_APE_GetItemNum Liefert die Itemanzahl.
Bearbeiten Beschreibung
tak_APE_GetIndexOfKey Ermittelt die Position eines Items über seinen Schlüssel.
tak_APE_GetItemDesc Liefert Informationen über ein Item.
tak_APE_GetItemKey Liefert den ASCII-kodierten Schüssel eines Items.
tak_APE_GetItemValue Liefert den UTF8-kodierten Wert eines Items.
tak_APE_GetTextItemValueAsAnsi Liefert den ANSI-kodierten Wert eines Textitems oder auch selektierte Werte, sofern das Item mehrere enthält.

Typen

Typ Beschreibung
TtakAPEv2Tag APEv2-Tag-Instanz.
TtakAPEv2TagDesc Informationen über ein APEv2-Tag.
TtakAPEv2ItemType Spezifiziert den Typ eines APEv2-Items.
TtakAPEv2ItemDesc Informationen über ein APEv2-Item.

Konstanten

Konstante Beschreibung
tak_apev2_Version Unterstützte Tag-Version.
tak_apev2_ItemNumMax Maximale Itemanzahl.
tak_apev2_TagSizeMax Maximale Tag-Größe.
tak_res_ape_xxx APEv2-Tag-spezifische Fehler und Warnungen.

Seekable Stream Decoder (SSD)

Der Seekable Stream Decoder (SSD) dekodiert Audiodaten, die aus einer Datei oder mittels eines Streaminterfaces gelesen werden. Er unterstützt samplegenaues Positionieren und Extrahieren beliebiger Teile der Audiodaten.

Beispiele

Folgende Programmbeispiele sind verfügbar:

Beispiel 1 in Pascal

Beispiel 1 in C

Referenz

Methoden und Funktionen

Objekte erzeugen und zerstören Beschreibung
tak_SSD_Create_FromFile Erzeugt eine Dekoderinstanz, die eine Datei dekodiert.
tak_SSD_Create_FromStream Erzeugt eine Dekoderinstanz, die einen externen Stream dekodiert.
tak_SSD_Destroy Zerstört eine Dekoderinstanz.
Statusfunkionen Beschreibung
tak_SSD_Valid Zeigt an, ob ein fataler Fehler aufgetreten ist.
tak_SSD_State Liefert den aktuellen Fehlerstatus bzw. den schlimmsten bislang aufgetretenen Fehler.
tak_SSD_GetStateInfo Liefert erweiterte Statusinformationen.
tak_SSD_GetErrorString Liefert einen englischen Fehlertext zu einem Fehlercode.
tak_SSD_GetStreamInfo Liefert Informationen über den Stream.
tak_SSD_GetFrameSize Liefert die Framegröße in Samples.
Dekodieren Beschreibung
tak_SSD_Seek Setzt die Leseposition.
tak_SSD_ReadAudio Liest und dekodiert Samples.
tak_SSD_GetReadPos Liefert die aktuelle Leseposition in Samples.
tak_SSD_GetCurFrameBitRate Liefert die komprimierte Bitrate des letzen Frames.
tak_SSD_GetSimpleWaveDataDesc Liefert eine Bescheibung der Wave-Metadaten.
tak_SSD_ReadSimpleWaveData Liest Wave-Metadaten.
tak_SSD_GetEncoderInfo Liefert Informationen über den verwendeten Encoder.
tak_SSD_GetAPEv2Tag Liefert eine Referenz auf das APEv2-Tag-Objekt.

Typen

Typ Beschreibung
TtakSeekableStreamDecoder Dekoderinstanz.
TtakSSDOptions Optionen.
TtakSSDDamageItem Informationen über Datenfehler, die an die Damage-Callbackfunktion übergeben werden.
TSSDDamageCallback Callbackfunktion, die beim Auftreten von Datenfehlern aufgerufen wird.

Konstanten

Konstante Beschreibung
tak_res_ssd_xxx SSD-spezifische Fehler und Warnungen.