GoPro Telemetry

Work in progress. Don't rely on it for important stuff yet.

Reads telemetry from the GPMF track in GoPro cameras (Hero5 and later).

Created for the GoPro Telemetry Extractor.

Here's a playlist with cool uses of the GoPro metadata .

Accepts binary data and returns a JavaScript object. See samples/example.js for a basic implementation.

You must extract the raw GMPF data from the video file first. You can do so with gpmf-extract

Install:

$ npm i gopro-telemetry

Use:

const goproTelemetry = require('gopro-telemetry');
const telemetry = goproTelemetry(rawData, options);

Options (optional)

Some options may be incompatible with others.

• debug (boolean) Outputs some feedback. Default: false
• tolerant (boolean) Returns data even if format does not match expectations. Default: false
• raw (boolean) Returns the data as close to raw as possible. No matrix transformations, no scaling. Disables the following options. Default: false
• timing (object) Provides timing information such as starting time, framerate, payload duration... as extracted from gpmf-extract. See a sample below. Default: null
• style (string) Formats the output following some standard. For example, geoJSON. Implementation pending. Default: null
• filter (array of string) Returns only the selected information (GPS, gyroscope...). Implementation pending. Default: null
• time (string) Groups samples in time units. Ideally will accept things like frames, milliseconds, seconds, timecode. Implementation pending. Default: null

Example:

const telemetry = goproTelemetry(rawData, { debug: true, tolerant: true, interpret: false, filter: ['GPS'] });

timing option example:

{ frameSpeed: 0.03336666666666667,
  start: 2017-04-17T19:27:57.000Z,//Date object
  samples:
   [ { cts: 0, duration: 1001 },//Starting point and duration in milliseconds
     { cts: 1001, duration: 1001 },
     { cts: 2002, duration: 1001 },
     { cts: 3003, duration: 1001 },
     { cts: 4004, duration: 1001 } ] }

Available data

Depending on the camera, model, settings and accessories, these are some of the available data:

• GPS location (deg, m)
• GPS speed (m/s)
• Accelerometer (m/s²)
• Gyroscope (rad/s)
• ISO
• Shutter Speed (s)
• Timestamps (µs)
• Magnetometer (µT)
• Face detection
• Highlights (manual and computed)
• White balance
• Luma
• Hue
• Image uniformity
• Scene classifier

This project is possible thanks to the gpmf-parser documentation, open sourced by GoPro.

More creative coding

If you liked this you might like other creative coding projects.

To-Do

• Interpret data
  • Calculate time (take reference from mp4 file if gps missing)
  • Add filtering options (GPS, Accel, Gyro...)
  • What to do with EMPT, TSMP?
  • Enable grouping packets per time unit / frame
• Test interpretation
• Review console.log/error usage
• Create additional package for converting the data to other formats
• Refactoring for performance?

Maybe To-Do

• Take potential nested arrays into account f[8]? Never found one to test
• Pending types:
  • d | 64-bit double precision (IEEE 754) | double
  • G | 128-bit ID (like UUID) | uint8_t guid[16]
  • q | 32-bit Q Number Q15.16 | uint32_t | 16-bit integer (A) with 16-bit fixed point (B) for A.B value (range -32768.0 to 32767.99998)
  • Q | 64-bit Q Number Q31.32 | uint64_t | 32-bit integer (A) with 32-bit fixed point (B) for A.B value.