telemetrik

Extract GPS, gyroscope, accelerometer, and other sensor data from GoPro video files.

telemetrik is a pure-Python parser for the GoPro Metadata Format (GPMF) — no compiled dependencies, no FFmpeg, just pip install and go.

Install

pip install telemetrik

Usage

Python

from telemetrik import extract_all_telemetry

streams = extract_all_telemetry("GX010042.MP4")

# GPS track
for ts, (lat, lon, alt, spd2d, spd3d, fix, dop) in streams["GPS5"].data:
    if fix >= 3:  # 3D fix
        print(f"{lat:.6f}, {lon:.6f}  alt={alt:.0f}m")

# 200 Hz accelerometer
for ts, (x, y, z) in streams["ACCL"].data:
    print(f"{ts}ms  accel=({x:.2f}, {y:.2f}, {z:.2f}) m/s²")

# Camera orientation quaternions
for ts, (w, x, y, z) in streams["CORI"].data:
    print(f"{ts}ms  quat=({w:.4f}, {x:.4f}, {y:.4f}, {z:.4f})")

Command line

telemetrik GX010042.MP4                        # extract all streams
telemetrik --streams ACCL,GYRO,GPS5 *.MP4      # specific streams, batch

Each stream is saved as <stem>.<fourcc> (e.g. GX010042.accl, GX010042.gps5) in CSV format with millisecond timestamps.

Supported streams

Pass any GPMF FourCC to extract unlisted streams: extract_all_telemetry(path, streams=["MWET"]).

Timestamps

Every TelemetryStream carries two timestamp arrays:

• data — (ms, value) pairs from the GPMF STMP clock (millisecond precision, always available)
• pts_data — (seconds, value) pairs on the video presentation timeline (available when the MP4 has timing atoms)

Use pts_data to align telemetry with video frames.

GPS quality fields

The GPS stream includes two "sticky" metadata fields that persist across samples:

Filter on fix >= 3 and dop < 500 for reliable positions.

API reference

extract_all_telemetry(video_path, streams=None)

Extract all (or selected) telemetry streams from an MP4 file.

Parameters:

• video_path — path to a GoPro MP4 file
• streams — list of FourCC strings, or None for all default streams

Returns: dict[str, TelemetryStream] — only streams with data are included.

Raises: ValueError if the file has no GPMF metadata track.

TelemetryStream

get_stream_data(f, samples, stream_key, scale=True, time_base=None)

Low-level extraction of a single stream from an open file handle. Use this when you need control over file I/O or want to extract non-standard streams.

Attribution

Core MP4 box walking and GPMF binary parsing adapted from gopro-video-sync by Ethan Vo (MIT).

License

MIT