User handbook

DataRide - User Handbook¶

DataRide is a desktop application for Windows and macOS. It reads telemetry (e.g. from GoPro videos) and composes overlays (speed gauge, maps, charts, airtime, etc.) into the video - with preview and export as a new video file.

1. Prerequisites¶

• Installation: Download DataRide from this website and install the application.
• FFmpeg and ffprobe must be installed on your computer and available on the PATH. They are required for video metadata, preview, and export.

If the video contains no usable telemetry, the app works with sample data so you can still explore the interface.

2. First steps: load and watch video¶

1. File -> Import Video... (or Ctrl+I / Cmd+I) or drag a video file into the window.
2. Left: recognized channels appear (speed, GPS, acceleration, ...).
3. Center: Preview with video and timeline - zoom or scrub playback position. While dragging the timeline, preview is throttled and drawn with faster scaling; after release, a sharp frame is shown.
4. Right: Overlay Inspector - add readout widgets ("overlays") and adjust them here.

3. Overlays: add and customize¶

The app stores normalized positions (relative to video size; X/Y typically 0-1, X/Y above 1 allows pushing overlays beyond the frame edge). The same layouts can be reused for other resolutions or batch export.

Adding¶

• In the Overlay Inspector, use buttons such as + Speed gauge, + Elevation gain/loss, + GPS track, + Altitude chart, + G-ball, + Rotation ball, + Jump list, etc.
• One instance per overlay type is usually allowed in a project. If a type already exists, its button is disabled - remove the existing instance first if you want to start fresh.

Selection and editing¶

• Click an overlay in the list - the editable area below adapts.
• Layout, typography, and appearance appear only when a row is selected and then apply to that instance.- Design: Use the "Preset" dropdown to choose between several overlay designs (e.g. round dial, minimal, or bar style for the speed gauge). The default design is a modern neon/glow look (glowing readouts, gradient arcs, chamfered cards) - the airtime HUD and its end-of-clip summary use this style too. In neon design, speed gauge, G-ball, rotation ball, elevation gain/loss, GPS track, and altitude profile share the same chamfered neon frame as the airtime summary and jump-list cards. Speed gauge, G-ball, and rotation ball sit in a square frame (equal padding on all sides). For GPS track with map, the map follows the chamfered corners while the neon frame stays visible. When switching designs, matching colors/options are applied; you can then fine-tune appearance and typography. New designs can be added later as files (see below).
• Layout: position (X/Y), size, rotation, anchor (which point of the box is pinned to the grid).
• Typography: font size and weight.
• Appearance: primary and secondary color, background opacity, stroke width.

Special options¶

The inspector shows these sections only for matching overlay types:
- GPS track: e.g. background map (loads tiles from the internet - observe OpenStreetMap terms of use).
- Speed gauge: The scale adjusts automatically to the video: the max value is the highest speed in the clip + 20%, rounded to a nice number. Tick marks use round values only (e.g. 0, 20, 40 ... 120). The needle stays in range and the scale fits each ride.
- Elevation gain/loss: Shows live meters gained and lost since clip/trim start, rounded to 1 m steps, with up/down arrows in neon style. On insert, the overlay starts square (width matched to video aspect ratio). Width and height can be adjusted independently afterward.
- Airtime: Parameters for jump detection (threshold |a|, hysteresis, minimum air time, merge gap) when an airtime HUD or jump list is selected; jump list entries only for the jump list; HUD options (live/outro) only for the HUD. While the airtime HUD is selected, preview shows its summary continuously (even outside the outro) so you can position and size it via layout (X/Y, width/height). Jump list cards have a fixed size (not tied to count); set card size via layout width/height - the newest card sits at the overlay position, older cards stack below. With no jumps detected, the list shows a demo card with value "0" for sizing.

Adding more designs (download)¶

Designs are plain JSON files and can be added without reinstalling the app. Put downloaded design files in your Overlay Styles folder:

• macOS: ~/Library/Application Support/DataRide/overlay_styles/
• Windows: %LOCALAPPDATA%\DataRide\overlay_styles\
• Linux: ~/.local/share/DataRide/overlay_styles/

After restart, new presets appear in the Design dropdown for the matching overlay type. Invalid files are ignored.

Removing¶

• Select an overlay in the list and use - Remove (in the inspector area with the add buttons).

4. Airtime (jumps)¶

Enable and disable¶

• In the Overlay Inspector, click "+ Jump list".
  This inserts the jump list and enables the airtime HUD
  (in-air jump display and summary near the end of the clip).
  If a HUD already exists in the project (e.g. from an older project), it is simply re-enabled.
• To remove the combination, select the jump list and click - Remove - the associated HUD is removed too (Undo available).

Fine tuning¶

• Select the airtime overlay or jump list in the inspector.
• Settings threshold |a|, hysteresis, min. air time, and merge gap
  are shared by HUD and jump list: it does not matter which of the two
  is active - a change always applies to both.
• Typical settings (short guide):
• Threshold |a|: below this value, "in the air" is assumed.
• Hysteresis: reduces rapid toggling between ground/air.
• Min. air time: very short phases are discarded.
• Merge gap: nearby phases may be merged.

• Jump list - entries: maximum number of most recently finished jumps in the list (newest on top). Only real jumps are shown - the list grows until the maximum is reached; then the oldest visible card drops off. The number is the jump over the whole ride (1 = first jump), not the row position.

• Debugging (advanced): Before starting the app, set environment variable
  DATARIDE_AIRTIME_DEBUG=1 to enable extra diagnostic logging (see
  developer documentation). Not needed for normal use.

Under Extras -> Jump list preview (test data)... you can preview the jump list with fixed demo values and try font size, colors, and entry count. Apply to project "Jump list" copies the configured look to the jump list in the current project (overlay must exist).

5. Save and open project¶

• File -> Save Project / Save Project As...
  Project files use the extension .dro.json. They store layout, overlay settings, export options, and a reference to your video - not the full telemetry as bulk data.
• File -> Open Project...
  After opening, the video should be found again (absolute path or relative to the project folder). If the file is missing, the app warns you.
• If needed, airtime settings between HUD and jump list are synced automatically on open; if that changes anything, the project is marked modified - saving writes the harmonized values to disk.

An autosave file may sit next to the project; on open you may be asked whether to load the newer version.

6. Overlay template (reuse layout)¶

To reuse a set of overlays (positions, styles, order) for other videos or projects:

• File -> Save Overlay Template... - saves the current overlay configuration as .drot.json (name used as title).
• File -> Load Overlay Template... - replaces all existing overlays in the project (with confirmation). Undo via Edit -> Undo.

7. Export video¶

1. Optionally set the output range (trim) in preview with the sliders under "Export range".
2. Choose File -> Export Video.... In the dialog, set destination file, export format,
   and output resolution; format and resolution are stored in the project (Undo available) and prefill batch export.
   Export formats include MP4 (H.264), MP4 for iPhone/iPad
   (H.264 + AAC, for reliable playback in the Photos app), HEVC, MOV, MKV, and WebM (VP9) - names match the dialog list.
3. Export starts FFmpeg processing; progress can be cancelled.

Batch export: Under File -> Batch Export... select multiple videos, an output folder, export format, and output resolution in the dialog (prefilled from project; your choice is written to the project on start). Overlay positions and trim range still come from the current project; telemetry is read per file and trim adapts to each clip length. No video needs to be loaded in preview - only saved overlay and export data matter. A table shows status and progress percent per file; Cancel stops the current run and marks remaining entries.

Export may take several minutes depending on length and resolution. Ensure FFmpeg is installed correctly.

7b. Menu overview (excerpt)¶

8. Keyboard shortcuts (excerpt)¶

9. Tips¶

• Series: Batch export and overlay templates save time with many similar clips.
• Performance: Very high output resolution lengthens export (and indirectly CPU load while encoding). Preview uses a fixed render resolution; when scrubbing the timeline, frames are cached and updates throttled (~14 fps) to keep the UI responsive.
• Dialogs: Hints, errors, and confirmations show the DataRide logo instead of the Python symbol.
• Updates: On start, the app checks in the background for a newer version. If available, a notice offers Open download (browser to your personal download page when enabled, otherwise the website). Each server version is shown only once. After a version upgrade, a What's new dialog appears once with key changes (e.g. overlay elevation gain/loss, update notice).
• Privacy / maps: GPS and map features may use location data and network access (map tiles).
• Online handbook: At dataride.app/docs (German/English).
• Feedback: Via the website at dataride.app/feedback.