---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: motorsport_telemetry
excerpt: |
  DuckDB Community Extensions
  Query AiM MP4, Cosworth PDS, MoTeC LD, Racelogic VBOX and .telemetry recordings directly in DuckDB, with stint-aware laps

extension:
  name: motorsport_telemetry
  description: Query AiM MP4, Cosworth PDS, MoTeC LD, Racelogic VBOX and .telemetry recordings directly in DuckDB, with stint-aware laps
  version: 2.0.0
  language: Rust
  build: cargo
  license: MIT
  requires_toolchains: "rust;python3"
  excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads;linux_amd64_musl;linux_arm64_musl;windows_amd64_mingw;windows_amd64_rtools"
  maintainers:
    - tobi

repo:
  github: tobi/duckdb_motorsport_telemetry
  ref: 11895b4c1ffd9d217b57c45c02720010908cf693

docs:
  hello_world: |
    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');
  extended_description: |
    `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.

extension_star_count: 10
extension_star_count_pretty: 10
extension_download_count: 1049
extension_download_count_pretty: 1.0k
image: '/images/community_extensions/social_preview/preview_community_extension_motorsport_telemetry.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), 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.

<div class="extension_compatibility_table"></div>

| 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
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

|       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

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

| type_name | type_size | logical_type | type_category | internal |
|-----------|----------:|--------------|---------------|----------|
| LIST      | 16        | LIST         | COMPOSITE     | true     |

### Added Settings

<div class="extension_settings_table"></div>

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