The KotOR engine handles text, voice, and character sound effects through a set of interconnected formats. TLK (Talk Table) files store every localized string the game displays or speaks — dialogue lines, item names, journal entries, feedback messages [tlk_data.py]. SSF (Sound Set File) files map character combat and movement sounds to TLK entries. LIP files drive facial animation timing to match spoken dialogue. WAV files provide the raw audio data. Together, these formats implement the localization and voice-over pipeline that runs from authored content through to in-game playback. xoreos-tools mirrors that workflow from the tooling side with dedicated TLK conversion utilities and an explicit language-ID/encoding matrix for Aurora/Odyssey talk tables, which makes it a useful external corroboration source for KotOR localization behavior [Running xoreos-tools, Tlk2xml, TLK language IDs and encodings].

• TLK — Talk Table
• SSF — Sound Set File
• LIP — Lip Sync
• WAV — Waveform Audio

The Talk Table is the game's central string database. Every piece of text the player sees — dialogue, item descriptions, journal entries, feedback messages, character names — is stored in dialog.tlk and accessed by a numeric index called a StrRef [tlk_data.py L1–L35]. This design makes localization straightforward: translating the game means replacing one file rather than hunting through thousands of individual resources. Each entry can also reference a voice-over sound file (ResRef), so the engine can play spoken audio alongside the displayed text [TLKEntry]. xoreos's tlk2xml page is also useful here because it describes why TLK tooling cannot rely on the header alone to infer text encoding: the format family reuses language IDs differently across games, and tools often need either an explicit game target or an explicit code page [Tlk2xml, TLK language IDs and encodings].

To modify TLK entries in a mod, use TSLPatcher/HoloPatcher TLKList syntax — this appends new entries or patches existing ones without replacing the entire file, which is critical for mod compatibility. TLK entries are referenced from GFF resources (especially DLG dialogue files), 2DA tables, and SSF sound sets.

• TLK — Talk Table
  • File Structure Overview
  • Binary Format
    • File Header
    • String Data Table
    • String Entries
  • TLKEntry Structure
  • String References (StrRef)
    • Custom TLK Files
  • Localization
  • Cross-reference: implementations

TLK files store localized strings in a binary format. The game loads dialog.tlk at startup and references strings throughout the game using StrRef numbers (array indices). String lookups use the same resource resolution order as other resources (override, then module/SAV, then KEY/BIF), so custom TLKs in override or in a MOD take precedence over the base game dialog.tlk. External tooling reflects the same constraints: xoreos's tlk2xml can read the classic V3.0/V4.0 talk-table families and exposes game-specific switches such as --kotor and --kotor2 precisely because the encoding cannot be safely autodetected from TLK content alone [Tlk2xml].

Implementation: Libraries/PyKotor/src/pykotor/resource/formats/tlk/

Cross-reference implementations (line anchors are against master and may drift):

• PyKotor:

  • binary layout in module docstring: tlk_data.py L1–L39
  • TLK / TLKEntry: tlk_data.py L54–L282
  • tlk_data.py L285–L420
  • read path (Kaitai + legacy 40-byte rows): io_tlk.py _load_tlk_from_kaitai L32–L63
  • _load_tlk_legacy L66–L120
  • TLKBinaryReader.load L149–L156
  • write path: TLKBinaryWriter L168–L219 (_write_file_header L183–L192, _write_entry L194–L219)

• reone:

  • tlkreader.cpp TlkReader::load L34–L43 (8-byte "TLK V3.0" signature + language/count/offset)
  • loadStrings L45–L71 (40-byte rows, lowercases sound ResRef)
  • flag constants L28–L32

• xoreos — talktable.cpp (Aurora talk table shared with other Aurora titles)

• xoreos-tools — talktable.cpp (CLI / tooling)

• KotOR.js: TLKObject.ts LoadFromBuffer L51–L96 — 20-byte header then per-entry metadata; note the last field before text is read with readUInt32() while the on-disk field is a float sound length—compare PyKotor struct.unpack("<f", ...) L106.

• KotOR-Unity: TLKObject.cs.

• Kotor.NET: TLKBinaryStructure.cs FileHeader / StringData / FileRoot L16–L130.

• 2DA File Format - Game tables with name/description StrRefs
• GFF File Format - Dialogue and templates that reference TLK strings
• SSF File Format - Sound sets that reference TLK entries
• TSLPatcher TLKList Syntax - Modding TLK files with TSLPatcher

The file header is 20 bytes in size:

References:

• reone TlkReader::load L34–L43
• PyKotor header parse — _load_tlk_legacy L71–L75
• PyKotor Kaitai path — _load_tlk_from_kaitai L35–L44
• Kotor.NET FileHeader L66–L76
• KotOR.js LoadFromBuffer L59–L64.

The string data table contains metadata for each string entry. Each entry is 40 bytes:

References:

• Kotor.NET StringData L92–L129
• PyKotor row decode _load_tlk_legacy L96–L112
• reone loadStrings L45–L69
• KotOR.js LoadFromBuffer L65–L75.

flag bits:

• bit 0 (0x0001): Text present - string has text content
• bit 1 (0x0002): Sound present - string has associated voice-over audio
• bit 2 (0x0004): Sound length present - sound length field is valid

flag Combinations:

Common flag patterns in KotOR TLK files:

The engine uses these flags to decide:

• Whether to display subtitles (Text present flag) [io_tlk.py L108]
• Whether to play voice-over audio (Sound present flag) [io_tlk.py L109]

The soundlength-present flag (bit 2) is parsed into soundlength_present [io_tlk.py L110] but is noted as "Unused by KOTOR1 and 2" in PyKotor's writer [io_tlk.py L210]. The sound_length float stores duration in seconds but the engine does not appear to require the flag to be set to read that value.

Missing flags are treated as false by PyKotor's reader [io_tlk.py L108–L110] — if Text present is not set, the string is treated as empty even if text data exists.

String entries follow the string data table:

string text is stored at the offset specified in the string data table entry. The encoding depends on the language ID; see:

• Concepts — Language IDs
• Localization below

Each TLK entry contains:

References:

• PyKotor TLK / TLKEntry — tlk_data.py L54–L420
• entry serialization — io_tlk.py _write_entry L194–L219.

string references (StrRef) are integer indices into the TLK file's entry array:

• StrRef 0: First entry in the TLK file
• StrRef -1: No string reference (used to indicate missing/empty strings)
• StrRef N: Nth entry (0-based indexing)

The game uses StrRef values throughout GFF files, scripts, and other resources to reference localized text. When displaying text, the game looks up the StrRef in dialog.tlk and displays the corresponding text.

Mods can add custom TLK files to extend available strings:

dialog.tlk structure:

• Base game: dialog.tlk (read-only, ~50,000-100,000 entries)
• Custom content: dialogf.tlk or custom TLK files placed in override

StrRef Ranges:

• 0 to ~50,000: Base game strings (varies by language)
• 16,777,216 (0x01000000) and above: Custom TLK range (TSLPatcher convention)
• Negative values: Invalid/missing references

Mod Tools Approach:

TSLPatcher and similar tools use high StrRef ranges for custom strings:

Base [StrRef](Audio-and-Localization-Formats#string-references-strref):   0 - 50,000 (dialog.tlk)
Custom Range:  16777216+ (custom TLK files)

This avoids conflicts with base game strings and allows mods to add thousands of custom text entries without overwriting existing content.

Multiple TLK files:

The game can load multiple TLK files:

1. dialog.tlk - Primary game text
2. dialogf.tlk - Female-specific variants (polish K1 only)

Priority: Custom TLKs --> dialogf.tlk --> dialog.tlk

Numeric language IDs and typical encodings (0–8) are defined on Concepts. The notes below focus on TLK-specific behavior.

KotOR: Retail builds usually install one dialog.tlk per language; the file header’s Language ID is often ignored at runtime and is mainly useful for tools tagging which language a TLK was built for.

Encoding: Western languages (IDs 0–4) normally use Windows-1252 in legacy tooling; Polish (5) uses Windows-1250. IDs 6–8 use UTF-8 in the wider Aurora spec. String payloads may still be UTF-8 or Windows-1252 depending on the tool and target game—see the string entry description above.

Windows-1252 is a single-byte encoding (256 code points) and is often loosely called "ISO-8859-1" or cp1252.

Kotor.NET: TLKBinaryStructure.cs L16–L130.

See Cross-reference implementations under File structure overview for reone, xoreos, KotOR.js, and KotOR-Unity.

• Concepts -- Language IDs and encodings
• TSLPatcher TLKList Syntax -- Modifying TLK via HoloPatcher/TSLPatcher
• 2DA-File-Format
• GFF-File-Format -- StrRef consumers
• NSS-File-Format -- Script strings
• Bioware-Aurora-TalkTable -- Aurora talk table spec
• Concepts -- Resource resolution
• Container-Formats#key -- KEY/BIF index
• Community sources and archives -- DeadlyStream, forums for TLK/StrRef modding

SSF files map 28 creature sound events — battle cries, selection acknowledgements, pain grunts, death screams — to StrRef indices into dialog.tlk. Each creature template references an SSF by ResRef, and the engine plays the associated voice-over line whenever the corresponding event fires. Slots that store -1 (0xFFFFFFFF) produce no sound.

To modify SSF files in mods, see the TSLPatcher SSFList syntax guide. SSF StrRefs resolve through the same TLK string table used for dialogue and UI text.

• SSF — Sound Set File
  • Table of Contents
  • File structure overview
  • Binary Format
    • File Header
    • Sound Table
  • Sound event types
  • Cross-reference: implementations

SSF files define 28 logical sound slots (indices 0–27) that creatures use for battle cries, selection lines, grunts, UI feedback, etc. Each slot holds a StrRef into dialog.tlk (or -1 / 0xFFFFFFFF for “no sound”). SSF files load through the same resource resolution order as other resources (override, MOD/SAV, KEY/BIF).

On-disk size:

• The header is 12 bytes; the semantic KotOR table is 28 × 4 = 112 bytes.
• Some writers emit 40 × 4 = 160 bytes after the header (28 mapped slots plus 12 extra 0xFFFFFFFF words).
• PyKotor’s writer does this (io_ssf.py L177–L181).
• Kotor.NET models a 40-entry table in SSFBinaryStructure.cs SoundTable L61–L77.
• Readers that only consume the first 28 entries after offset still match vanilla behavior.
• KotOR.js SSFObject.Open derives soundCount = (length - 12) / 4 and therefore accepts either width.

Implementation (PyKotor): Libraries/PyKotor/src/pykotor/resource/formats/ssf/

Cross-reference implementations (line anchors are against master and may drift):

• PyKotor:

  • format notes in module docstring: io_ssf.py L1–L42
  • legacy load path (28 slots, order fixed): _load_ssf_legacy L63–L112
  • reader dispatch: SSFBinaryReader.load L152–L159
  • writer: SSFBinaryWriter.write L171–L181
  • enum + semantics: SSFSound L123–L234

• reone — ssfreader.cpp SsfReader::load L28–L36 (validates SSF V1.1, seeks to table offset, reads all remaining int32s into an array — works for 28- or 40-word tables).

• xoreos — Aurora SSF (src/aurora/ssffile.cpp), shared with other Aurora titles.

• KotOR.js:

  • SSFObject.ts
  • slot names: SSFType enum L14–L43 (same indices as PyKotor SSFSound; identifier spellings differ slightly — see table below)

• Kotor.NET:

  • header + 40-slot table: SSFBinaryStructure.cs L29–L77
  • high-level read loop (28 creature sounds): SSFBinaryReader.Read L31–L45

• TSLPatcher SSFList Syntax - Modding SSF files with TSLPatcher
• TLK File Format - Talk Table containing actual sound references
• Bioware Aurora SSF Format - Official BioWare specification
• GFF-UTC - creature templates that reference SSF files
• 2DA-soundset - Sound set definitions table

The file header is 12 bytes in size:

After the header, the file contains a contiguous array of little-endian int32 StrRefs. KotOR uses the first 28 entries (indices 0–27) as in the Sound event types table below. -1 or 0xFFFFFFFF means “no sound” for that slot.

Some files and tools use 40 uint32 entries (extra trailing -1 words). Treat anything beyond index 27 as padding unless you have a specific toolchain that assigns meaning to it.

Indices are fixed; do not reorder. PyKotor names are authoritative for this repo; KotOR.js SSFType uses the same numeric values with different spellings on a few rows (noted in the third column).

Primary references:

• ssf_data.py SSFSound L123–L234
• io_ssf.py _load_ssf_legacy L80–L110
• KotOR.js SSFType.ts L14–L43

LIP files drive mouth animation for voiced dialogue. Each file stores a compact series of keyframes that pair a timestamp (in seconds) with a viseme index (0–15), and the engine interpolates between them while playing the companion WAV voice line. The LIP length field must match the WAV playback duration exactly, or the mouth animation will desynchronize. LIP files load through the same resource resolution order as other game assets.

LIP is always paired with a WAV of matching ResRef. Dialogue nodes in DLG trigger the voice line, which in turn triggers the LIP animation on the speaking creature model.

• LIP — Lip Synchronization
  • Table of Contents
  • File Structure Overview
  • Binary format
    • Header
    • Keyframe Table
  • Mouth Shapes (Viseme Table)
  • Animation Rules

• LIP files are always binary ("LIP V1.0" signature) and contain only animation data.

• They are paired with WAV voice-over resources of identical duration; the LIP length field must match the WAV data playback time for glitch-free animation.

• keyframes are sorted chronologically and store a timestamp (float seconds) plus a 1-byte viseme index (0–15).

• The layout is identical across these implementations (header / keyframe offsets below are cross-confirmed):

  • reone
  • xoreos
  • Kotor.NET
  • KotOR.js
  • mdlops (Perl reference implementation)

Implementation (PyKotor):

• package: resource/formats/lip/
• binary read LIPBinaryReader.load L95+
• write LIPBinaryWriter.write L117+
• data model in lip_data.py
• XML/JSON in io_lip_xml, io_lip_json

Comparable LIP implementations include reone's C++ parser (lipreader.cpp L27+), xoreos's Aurora reader (lipfile.cpp), KotOR.js's LIP object and binary reader (LIPObject.ts L26+, readBinary L112-L136), and Kotor.NET's in-memory DTO layer (LIP.cs L11+).

• TLK File Format - Talk Table containing voice-over references
• WAV File Format - Audio format paired with LIP files
• GFF-DLG - dialogue files that trigger LIP animations

The LIP header layout is corroborated by reone's parser (lipreader.cpp L27-L42).

keyframes follow immediately after the header; there is no padding.

• Entries are stored sequentially and must be sorted ascending by timestamp.

• Libraries average multiple implementations to validate this layout:

  • reone
  • xoreos
  • KotOR.js
  • Kotor.NET

KotOR.js's binary reader shows the same contiguous keyframe-table decode (LIPObject.ts readBinary L112-L136).

KotOR reuses the 16-shape Preston Blair phoneme set. Every implementation agrees on the byte value assignments; KotOR.js only renames a few labels but the indices match.

PyKotor's LIPShape table and related phoneme helpers define the same core viseme set used throughout the surrounding LIP tooling ecosystem.

• Interpolation: The engine interpolates between consecutive keyframes, and PyKotor's LIP.get_shapes() computes the left and right visemes plus blend factor from that timeline.
• Sorting: When adding frames, PyKotor removes existing entries at the same timestamp and keeps the list sorted.
• Duration Alignment: PyKotor updates LIP.length to the maximum timestamp so exported animations stay aligned with their WAV line.
• Generation: Automated pipelines (MDLOps, KotORBlender) map phonemes to visemes via LIPShape.from_phoneme(), and the same mapping table appears in the vendor projects referenced above to keep authoring tools consistent.

PyKotor's LIP reader and data model (io_lip.py, lip_data.py) stay aligned with the same header and keyframe encoding used by reone (lipreader.cpp L27+), xoreos (lipfile.cpp), KotOR.js (LIPObject.ts L26+), and Kotor.NET (LIP.cs L11+).

KotOR stores both standard WAV voice-over lines and Bioware-obfuscated sound-effect files. Voice-over assets are regular RIFF containers with PCM headers, while SFX assets prepend a 470-byte custom block before the RIFF data. PyKotor handles both variants transparently. WAV files are resolved using the same resource resolution order as other resources:

• override
• MOD/ERF/SAV
• KEY/BIF

Hex type id 0x0004 is listed under Resource type identifiers.

Implementation (PyKotor)

• Binary reader/writer:

  • io_wav.py
  • WAVBinaryReader L100+
  • load L148+ (SFX obfuscation + RIFF)
  • WAVBinaryWriter L302+
  • RIFF parse helper _parse_riff_wave_from_kaitai L56+

• Data model: wav_data.py.

Cross-reference implementations (line anchors are against master and may drift):

• reone — wavreader.cpp — WavReader::load L32+ (470-byte SFX signature FF F3 60 C4 then seek 0x1DA, RIFF/fmt/data, MP3-in-WAV edge case).

• KotOR.js — AudioFile.ts — SFX probe fakeHeaderTest / riffHeaderTest L12-L13, strip 470-byte prefix processFile L118-L124, MP3-in-WAV riffSize == 50 branch L131-L137.

• Kotor.NET — no dedicated KotorWAV reader on the default branch; creature sound StrRefs (resolved to .wav via TLK at runtime) are modeled in Kotor.NET/Formats/KotorSSF/SSF.cs L12+. For byte-level RIFF/SFX layout, prefer the implementations above:

  • PyKotor (io_wav.py in this section)
  • reone
  • KotOR.js

For mod developers: WAV files are referenced from:

• TLK (voice-over)
• SSF

See HoloPatcher README for Mod Developers.

Related formats:

• TLK (StrRef -> sound)
• SSF
• LIP
• DLG (VO_ResRef)

• WAV — Audio
  • Table of Contents
  • File Types
  • Standard RIFF/WAVE Structure
    • Format Chunk
    • Data Chunk
  • KotOR SFX Header
  • Encoding Details
  • Cross-reference: implementations

PyKotor exposes these via the WAVType enum (VO vs. SFX) so tools know whether to insert/remove the proprietary header (io_wav.py:52-121).

KotOR sticks to the canonical RIFF chunk order:

After the fmt chunk (and any optional fact chunk), the "data" chunk begins:

KotOR voice-over WAVs add a "fact" chunk with a 32-bit sample count, which PyKotor writes for compatibility (io_wav.py:182-186).

• SFX assets start with 470 bytes of obfuscated metadata (magic numbers plus filler 0x55).
• After this header, the file resumes at the "RIFF" signature described above.
• When exporting SFX, PyKotor recreates the header verbatim so the game recognizes the asset (io_wav.py:150-163).

(See Cross-reference implementations above for reone / KotOR.js / Kotor.NET line anchors.)

• PCM (audio_format = 0x0001): Most dialogue is 16-bit mono PCM, which streams directly through the engine mixer.
• IMA ADPCM (audio_format = 0x0011): Some ambient SFX use compressed ADPCM frames; when present, the fmt chunk includes the extra coefficient block defined by the WAV spec.
• KotOR requires block_align and bytes_per_sec to match the values implied by the codec; mismatched headers can crash the in-engine decoder.

External tooling such as SithCodec and SWKotOR-Audio-Encoder implement the same formats; PyKotor simply exposes the metadata so conversions stay lossless.

• Deadly Stream — SithCodec (Windows tool for KotOR audio header strip/add; pair with PyKotor io_wav when verifying bytes).
• Deadly Stream — Extracting dialogue — community-reported layout notes (e.g. some assets under StreamWaves / StreamVoice); treat thread as workflow hints, not normative RIFF layout—verify against PyKotor / reone / KotOR.js above.

TSLPatcher-era threads discuss Streamsounds / Streamwaves paths, codec issues in Miles-based workflows, and DLG-related StreamVoice layout (e.g. alienvo.2da -> StreamVoice\AVO\). Treat these as dated player/modder reports, not engine specifications—pair with SithCodec, PyKotor io_wav, and the cross-refs at the top of this page.

• Convert KOTOR sounds to a usable audio file
• Editing KotOR voiceover files — which program?
• Listening and editing KotOR I & II audio
• KotOR/TSL GUI Dialog Editor (DLGEditor) — StreamVoice / alienvo discussion (e.g. p.2)

• Reference implementations (engines): same as Cross-reference implementations at the top of this page (PyKotor io_wav.py, reone wavreader.cpp, KotOR.js AudioFile.ts).
• Community tooling (not normative): SithCodec — encode/decode helper; SWKotOR-Audio-Encoder — batch-friendly encoder. Prefer verifying headers against PyKotor / reone / KotOR.js when debugging engine mismatches.

With this structure, WAV assets authored in PyKotor will play identically in the base game and in the other vendor tools.

• Resource formats and resolution - Resource type identifiers (WAV / 0x0004)
• TLK File Format - Talk table that references WAV voice-over
• SSF File Format - Sound set files that reference WAV via StrRef
• LIP File Format - Lip-sync paired with WAV dialogue
• GFF-DLG - Dialogue files that reference WAV (VO_ResRef)