Skip to content

v1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@OGMatrix OGMatrix released this 17 May 11:24
v1.0.0
5ec027a
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Changelog

v1.0.0 — 2026-05-16

First public release. Everything below is new.

What is klartext

klartext decodes the telemetry stream your dashcam hides inside its MP4 and burns a clean HUD onto a copy of the video — entirely on your machine, no cloud, no accounts.

Today it ships with one decoder: the Audi A5 (2026, E3 1.2 / MIB4) protobuf-in-tx3g format. The architecture is built for more: every new format plugs behind the same pipeline. The goal is to read telemetry from any dashcam that embeds or hides it.

Audi A5 decoder

The Audi factory dashcam writes a hidden tx3g (3GPP timed-text) subtitle track into every exported MP4. Each cue contains a base64-encoded Protocol Buffers message at roughly 5 Hz. klartext decodes it without a .proto file — the firmware writes field names as plaintext strings directly into the wire format.

Confirmed fields decoded:

Field Meaning
id200_01 UTC timestamp (ISO 8601)
id200_02 Latitude, decimal degrees, WGS-84
id200_03 Longitude, decimal degrees, WGS-84
id200_04 GPS carrier-to-noise ratio (C/N₀), dB-Hz
id200_05 Ground speed, m/s
id200_06 Cumulative odometer, metres
idOC_02 Street name
idOC_04 City
idOC_06 Country code
idOC_08 Region / sub-city district (hypothesis)
idOC_12 Right turn indicator — 1 while right stalk active
idOC_13 Left turn indicator — 1 while left stalk active
idOC_15 High-beam headlights active
idOC_40 Firmware version string
idOC_42 Vehicle model identifier (hypothesis)
idOC_46 Hazard / warning triangle active

All other fields are still exported verbatim in the JSON output for inspection. See §06 of the README for the full reference.

Tested against firmware t11_DEU_1p0_2p50_3p0_1s0 on a 2026 Audi A5. Other E3 1.2 / MIB4 vehicles (Q6 e-tron, A6 e-tron, Porsche Macan EV) are expected to use the same schema but have not yet been verified with sample clips.

Outputs

For an input drive.mp4, klartext produces:

File Format
drive.telemetry.csv Wide CSV, one row per cue, all decoded fields
drive.telemetry.json Structured JSON with raw fields included
drive.track.gpx GPX 1.1 with klartext-specific extensions
drive.hud.ass Advanced SubStation Alpha subtitle overlay
drive.hud.mp4 Re-encoded video with HUD burned in

HUD renderer

When Pillow is installed, klartext renders an Audi-MMI-style graphical HUD:

  • top-left — semi-transparent panel: date/time + (country) city – street
  • bottom-left — satellite minimap with heading-aware GPS marker and Audi-orange border
  • bottom-centre — ‹‹ NN km/h ›› speed readout
  • bottom-right — klartext brand watermark

Minimap tile providers:

  • ESRI World Imagery (default) — satellite + road overlay, completely free, no account required
  • Mapbox Satellite Streets — opt-in via --mapbox, higher detail at low zoom levels, requires a free token (see MAPBOX.md)

Tiles are cached to ~/.cache/klartext/tiles/ — repeated processing of nearby clips skips network requests.

When Pillow is not installed, klartext falls back to ASS subtitle overlay only (no minimap, no graphical icons).

Video encoder

Hardware-accelerated encoding is auto-detected in this order: NVIDIA NVENC → Intel QSV → AMD/Mesa VAAPI → libx265 software. Override with --encoder if needed.

CLI flags

python klartext.py INPUT.MP4 [options]

  -o, --output-dir DIR      write outputs here (default: same directory as input)
  --no-burn                 export CSV/JSON/GPX/ASS only; skip re-encode
  --no-video                same as --no-burn, kept for legacy scripts
  --encoder ENC             override hardware encoder (e.g. libx264, h264_nvenc)
  --crf N                   quality/size tradeoff; default 22
  --font NAME               HUD font hint; default "DejaVu Sans"
  --strip-telemetry         drop the hidden tx3g track from the output (for sharing)
  --no-map                  skip the satellite minimap
  --mapbox                  use Mapbox Satellite Streets tiles
  --mapbox-token TOKEN      save/update the Mapbox token
  --map-zoom N              minimap zoom level; default 16
  --whatsapp                re-encode for WhatsApp compatibility
  -v, --verbose             print full decode log
  --version                 print version and exit

klartext-viewer

klartext-viewer.py is a companion browser-based telemetry explorer built on Dash and Plotly. Load the JSON output from any klartext run and inspect speed, GPS track, and all context fields interactively.

pip install dash plotly pandas
python klartext-viewer.py drive.telemetry.json

Requirements

Component Version Required?
Python ≥ 3.8 yes
ffmpeg / ffprobe ≥ 5.0 yes — must be on $PATH
rich latest yes
Pillow ≥ 10.0 recommended — enables graphical HUD

Installation

git clone https://github.com/OGMatrix/klartext
cd klartext
pip install rich Pillow
python klartext.py drive.mp4

What's next

See ROADMAP.md for the full plan. Short version:

  • GoPro GPMF and DJI SRT decoders (next formats)
  • NMEA 0183 sidecar support (Garmin, Viofo, Thinkware, Nextbase)
  • Additional HUD modules: speed sparkline, altitude, compass widget, g-sensor indicator
  • pip install klartext (PyPI)
  • klartext.dev — browser-based HUD designer

If you own an E3 1.2 Audi that isn't the A5, or a camera on any of the planned formats, open an issue with a sample clip — your data is what drives new decoders.

License

MIT. See LICENSE.

The klartext brand watermark is retained in all outputs under the watermark policy. Removal requires a separate commercial arrangement.

Assets 3
Loading