source-caption-creator

is a tool for creating, managing and compiling captions/subtitles for the Source Engine.

It takes JSON data as input and outputs .txt, .dat or .kv3 resource files.

Note

For more information on Closed Captions in the Source Engine, visit the Valve Developer Community.

Important

The tool is currently only available as CLI (converting/compiling only), the GUI version is work-in-progress!

Usage

1. Create a new .json caption file. Either by manually editing the file or editing it through the GUI (not finished yet!).
2. Convert/Compile the file into a usable format: python src/cli.py -game <full path to game directory> -json <full path to json caption file> [Convert/Compile flags]
3. Start your game and enjoy!

Arguments (CLI)

Option(s)	Type	Description
-game	String	Full path to Source Engine game directory
-json	String	Full path to JSON Caption File
--to-kv3, -kv3	String (multi-use)	(Strata Source) Convert JSON data of to <type>_<lang>.kv3 files
--to-txt, -txt	String (multi-use)	Convert JSON data of to <type>_<lang>.txt files
--to-dat, -dat	String (multi-use)	Compile converted data of from (<type>_<lang>.txt) to <type>_<lang>.dat

Supported keys

Key	Type	Description
txt	String	The actual caption message.
dn	String	Display name (Speaker).
ndn	Bool	If true, hides the display name.
clr	String	Color in "R,G,B" or "#HEX".
playerclr	List	["client_color", "other_color"] for specific targeting.
sfx	String	Marks the line as a sound effect.
bold/italic	Bool	Toggles text styling.
len	Int	Overrides display duration (seconds).
norepeat	Int	Sets how often a line can repeat.
nocatinkey	Bool	Removes the category. prefix from the output key.

Building

1. Clone the repository: git clone https://github.com/timmycelle/source-caption-creator.git/
2. Create virtual environment: python3 -m venv venv
3. Activate virtual environment: Linux: source venv/bin/activate | Windows: .\venv\Scripts\activate.ps1
4. Install required modules: pip install -r requirements.txt
5. Build executable: Linux: ./build.sh | Windows: .\build.bat

Conversion procedure

The tool uses an inheritance-based system to build captions. This allows you to define global styles and override them for specific lines.

The system goes as follows:

1. Data merging

The program processes each language (e.g. english, german, etc.) by merging its specific data with the data of the shared block. shared is mainly used for colors, general formatting and miscellaneous data that should be shared across every language.

Order: shared ➔ language (Language overrides Shared).

2. Category & Line overrides

Within a language, lines inherit properties (like color clr or display names dn) from their parent category and apply their own on top.

Order: category ➔ line (Line overrides Category).

3. Line processing

Once the current line has finished properties, the program takes them and formats them into a caption token that the user can then use.

Example:

Input (*.json)

{
    "info": "My Epic Portal 2 Mod | 2026 timmycelle",
    "data": {
        "variables": {
            "color1": "#ff00ff",
            "color2": "#ffff00",
            "color3": "#ff0000"
        },
        "subtitles": {
            "shared": {
                "glados": {
                    "clr": "$color1",
                    "lines": {
                        "mod-2-yellow": {
                            "clr": "$color2",
                            "ndn": true
                        },
                        "mod-3-red": {
                            "clr": "$color3",
                            "bold": true
                        }
                    }
                }
            },
            "english": {
                "glados": {
                    "dn": "GLaDOS",
                    "lines": {
                        "mod-1-magenta": { "txt": "I'm magenta." },
                        "mod-2-yellow": { "txt": "I'm yellow and I won't show you my name!" },
                        "mod-3-red": { "txt": "I'm red and I'm...bold?" }
                    }
                }
            }
        }
    }
}

Output (subtitles_english.txt)

"lang"
{
	"Language" "english"
	"Tokens"
	{
		"glados.mod-2-yellow" "<clr:255,255,0>I'm yellow and I won't show you my name!"
		"glados.mod-3-red" "<clr:255,0,0><B>GLaDOS:<B> <B>I'm red and I'm...bold?"
		"glados.mod-1-magenta" "<clr:255,0,255><B>GLaDOS:<B> I'm magenta."
	}
}

// My Epic Portal 2 Mod | 2026 timmycelle

// Generated with source-caption-creator INDEV by timmycelle
// See https://www.github.com/timmycelle/source-caption-creator for more info