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.
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 bezeichnet im folgenden den Entwickler, der das SDK einsetzt.
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.
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.
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...
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, die sich nicht einem spezifischen Objekt zuordnen lassen.
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. |
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:
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. |
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. |
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. |
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.
Folgende Programmbeispiele sind verfügbar:
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. |
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. |
Konstante | Beschreibung |
tak_res_ssd_xxx | SSD-spezifische Fehler und Warnungen. |