motorsport_telemetry

Search Shortcut cmd + k | ctrl + k

Documentation

Downloads 4.8kthis week

GitHub stars 9

Extension descriptor (YAML)

Query AiM MP4, Cosworth PDS, MoTeC LD, Racelogic VBOX and .telemetry recordings directly in DuckDB, with stint-aware laps

Maintainer(s): tobi

Compatibility Matrix

This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

Platform	1.4.4	1.4.5	1.5.5	1.5.6	2.0.0
Linux AMD64
Linux ARM64
macOS AMD64
macOS ARM64
Windows AMD64
Windows ARM64
WebAssembly

Installing and Loading

INSTALL motorsport_telemetry FROM community;
LOAD motorsport_telemetry;

Example

SELECT name, unit, frequency_hz, sample_count
FROM telemetry_metadata('run.ld')
WHERE sample_count > 0;

SELECT *
FROM read_telemetry('run.ld',
  rate := 100,
  channels := 'Ground Speed,Throttle Pos,Brake Pedal Pos');

SELECT name, unit, frequency_hz, sample_count
FROM telemetry_metadata('run.mp4')
WHERE sample_count > 0;

SELECT *
FROM read_aim('run.mp4',
  rate := 10,
  channels := 'RPM,GPS Speed,GPS Latitude,GPS Longitude');

About motorsport_telemetry

motorsport_telemetry reads AiM aimd telemetry embedded in MP4, Pi Research/Cosworth PDS, MoTeC i2 LD, Racelogic VBOX VBO, and motorsport-telemetry-rs .telemetry recordings (zstd-compressed MTJ JSONL) without an export step. telemetry_laps returns each lap with a session-monotonic virtual lap number, stint index, the dash's own stint lap counter, and a normalized kind (flying, out, in, out-in, pit); telemetry_file_metadata reports flying-lap and stint counts and picks the fastest flying lap. AiM MP4 support is native-only; the DuckDB-Wasm build does not link the AiM parser, so .mp4 inputs and the read_aim/read_aimd functions are unavailable in the browser. The native reader exposes scalar CHS channels and expands each valid 56-byte GPS0 aggregate into 16 GPS channels, including WGS84 position, speed, heading, accuracy, timing, and status. It provides exact channel metadata, native-rate long-form samples, and projected wide readers with time/channel pruning and type-aware interpolation. Integer and event channels always use previous-value semantics; only floating-point channels can interpolate linearly. The parsers memory-map native files and table functions produce vectorized DuckDB output.

Added Functions

function_name	function_type	description	comment	examples
read_aim	table	Projected wide telemetry with type-aware interpolation and optional unit tags.	NULL	[SELECT * FROM read_aim('run.mp4');]
read_aimd	table	Projected wide telemetry with type-aware interpolation and optional unit tags.	NULL	[SELECT * FROM read_aimd('run.mp4');]
read_cosworth	table	Projected wide telemetry with type-aware interpolation and optional unit tags.	NULL	[SELECT * FROM read_cosworth('run.pds');]
read_motec	table	Projected wide telemetry with type-aware interpolation and optional unit tags.	NULL	[SELECT * FROM read_motec('run.ld');]
read_telemetry	table	Projected wide telemetry with type-aware interpolation and optional unit tags.	NULL	[SELECT * FROM read_telemetry('run.pds');]
read_telemetry_normalized	table	Normalized telemetry channels at each native instant.	NULL	[SELECT * FROM read_telemetry_normalized('run.pds');]
read_telemetry_session	table	Synchronized wide telemetry across related files in a session.	NULL	[SELECT * FROM read_telemetry_session('run.pds');]
read_vbo	table	Projected wide telemetry with type-aware interpolation and optional unit tags.	NULL	[SELECT * FROM read_vbo('run.vbo');]
telemetry_can_convert	scalar	Whether two telemetry units have compatible dimensions.	NULL	[telemetry_can_convert('m/s', 'km/h')]
telemetry_column_comments	table	SQL column comments preserving telemetry units and provenance.	NULL	[SELECT * FROM telemetry_column_comments('run.pds', 'run');]
telemetry_convert	scalar	Convert compatible telemetry units; incompatible dimensions raise an error.	NULL	[telemetry_convert(10.0, 'm/s', 'km/h')]
telemetry_convert_column	scalar	Convert a numeric column carrying a telemetry unit alias.	NULL	[telemetry_convert_column(speed, 'km/h')]
telemetry_file_metadata	table	File identity, track, session and lap summaries.	NULL	[SELECT * FROM telemetry_file_metadata('run.pds');]
telemetry_laps	table	Session-monotonic laps, stints and lap kinds from telemetry files.	NULL	[SELECT * FROM telemetry_laps('run.pds');]
telemetry_metadata	table	Channel metadata, units and native sample rates from telemetry files.	NULL	[SELECT * FROM telemetry_metadata('run.pds');]
telemetry_samples	table	Exact native-rate telemetry samples, with channel and time pruning.	NULL	[SELECT * FROM telemetry_samples('run.pds');]
telemetry_session_metadata	table	Groups related telemetry files into sessions.	NULL	[SELECT * FROM telemetry_session_metadata('run.pds');]
telemetry_units	table	Discover canonical telemetry units, aliases and compatible dimensions.	NULL	[SELECT * FROM telemetry_units();]
write_telemetry	table	Exports telemetry to MoTeC LD with optional channel and unit mappings.	NULL	[SELECT * FROM write_telemetry('run.pds', 'run.ld');]

Overloaded Functions

This extension does not add any function overloads.

Added Types

type_name	type_size	logical_type	type_category	internal
LIST	16	LIST	COMPOSITE	true

Added Settings

name	description	input_type	scope	aliases	typed_value
temp_directory	Set the directory to which temporary files are written.	VARCHAR	GLOBAL	[]	post.db.tmp

In this article