gopro-overlay: turn a GoPro clip or a GPX track into a data dashboard video

What the tools actually do

The repository description is precise: programs to process GoPro MP4 and generic GPX or FIT files and create video dashboards and maps. The README's own summary line is the best description: create video overlays from GoPro videos or any GPX or FIT file.

The feature list has seven items and two of them define the scope. Overlaying exciting graphics onto GoPro videos with super-exact synchronization is the headline. And creating videos from any GPX or FIT file, with no GoPro required, is the second mode, which the README calls overlay only mode and demonstrates with a dashboard image produced from a GPX file.

The rest are about coverage and speed. Support for multiple resolutions, most GoPro models, and the normal, timelapse and timewarp modes. Support for GPUs to create movies at up to 17x realtime. Conversion of GoPro movie metadata to GPX or CSV files. Cutting sections from GoPro movies, including the metadata. And Linux, Mac and Windows.

The GoPro-specific point is worth understanding. A GoPro camera records GPS and sensor data as a telemetry track inside the MP4 file itself, in a separate data stream alongside the video. That is why this tool can produce a dashboard for a recording without any external input: the track is already in the file. The overlay-only mode exists for the other case, where the track comes from a phone, a Garmin or a DJI drone instead.

The project is packaged on PyPI as gopro-overlay, and there is a Docker image as well. The primary language is Python, the licence is GPL-3.0, the default branch is main, and the last push was on 2026-08-04 with the project not archived. The repository publishes no GitHub releases, so the PyPI version is the release channel, and the project metadata gives it as version 0.134.0 with the development status classifier of Production/Stable.

Installing it, and the system libraries people trip over

The requirements are short: Python 3.10, with development done on Python 3.11, ffmpeg with the ffmpeg program installed, and libraqm which is needed by Pillow. The package metadata is stricter than the README, since requires-python is 3.11 or newer, so the README's 3.10 line is out of date.

The local install is a virtual environment and one pip command:

python -m venv venv
venv/bin/pip install gopro-overlay

Then there is the font. The Roboto font needs to be installed on your system, and the README offers the usual distribution-specific commands:

pacman -S ttf-roboto
apt install truetype-roboto
apt install fonts-roboto

That is a real dependency rather than a cosmetic one, because the dashboard draws text on top of video and Pillow needs a font file to draw with. A missing Roboto installation produces a dashboard with no text rather than an error, which is the kind of failure that wastes an afternoon.

Pycairo is optional. The README notes that some widgets require the cairo library, which must be installed separately, and gives the pinned version:

venv/bin/pip install pycairo==1.23.0

And it lists the system libraries the pycairo documentation suggests: libcairo2-dev, pkg-config and python3-dev on Ubuntu and Debian, or cairo and pkg-config through Homebrew on macOS.

The Docker image is the answer for anyone who does not want to manage cairo, libraqm, ffmpeg and a font on their machine, and there is a separate document for Windows as well, which is a sensible split since Windows is the platform where the system library story is worst.

Running it, and the privacy flag worth understanding

The example command is the whole interface for the common case:

venv/bin/gopro-dashboard.py --gpx ~/Downloads/Morning_Ride.gpx --privacy 52.000,-0.40000,0.50 ~/gopro/GH020073.MP4 GH020073-dashboard.MP4

Two arguments beyond the flags: a GPX file to supply the track, and the input and output video. The privacy flag takes three comma-separated values, and the README explains what it does: privacy allows you to set a privacy zone, and various widgets will not draw points within that zone.

That is a feature that is easy to miss and easy to be grateful for. The overlay shows the route on a map and draws the position as the video plays, and a route that passes your house is a thing you may not want visible in a video you post. The privacy zone covers part of the map, so the widget does not draw points there.

The caveats section is where the honest limitations live. The GPS track in Hero 9 seems to be very poor, and if you supply a GPX file from a Garmin or whatever, the program will use that instead for the GPS. Hero 11 GPS is much improved.

So there is a model-dependent accuracy difference that determines whether you need to supply an external track at all.

The second caveat is about time, and it is the subtler of the two. The data recorded in the GoPro video uses GPS time, which broadly is UTC. The renderer will use your local timezone to interpret this, and will use the local timezone. This may produce strange results if you go on holiday somewhere and then render the files when you get back home, and on Linux you can use the TZ variable to change the timezone used.

That is a genuinely useful warning, because the failure mode is not an error. The dashboard appears, the map is right, and the speed and timing are quietly shifted by your offset against the camera's UTC timestamps.

The dashboard layout is an XML file

Several dashboards are built in to the software, but the dashboard layout is highly configurable, controlled by an XML file, and the README points to a document on the extensibility of the layout plus a directory of examples.

The word highly is doing work there, and it is worth being precise about what that means in practice. A built-in dashboard is a starting point; the XML is the thing you edit to move a speed readout from the top-left to the bottom-right, to change which units a metric is shown in, to add or remove a widget, to restyle a gauge, and to place widgets relative to each other rather than at fixed positions.

The reason XML rather than a Python configuration or a web UI is a reasonable guess based on the rest of the project: the layout describes positions and appearances over a range of video resolutions, and the set of example dashboard images in the repository shows the same dashboard rendered at different aspect ratios, including a 2704x1520 example with Cairo widgets. A resolution-independent description is much easier to write in a declarative format with coordinates and anchors than in code.

The examples directory reinforces the point. Alongside the photo-realistic action shots there are images whose names describe widget layouts rather than activities, such as moto_1080_2bars, moto_1080_needle, moto_2160_needle and moto_2160_2bars. Those are dashboards with two bar gauges, a needle gauge, at 1080p and 2160p. So the widget vocabulary includes both bars and needles, and both a resolution-specific and a resolution-independent set of designs exist.

There is also an examples/layout directory referenced in the README, described as an example with Richmond Park and Cairo widgets, which suggests the layout system can be driven from a working example rather than only from documentation.

ffmpeg profiles, GPUs and the performance story

The ffmpeg section exists because the program is really a video pipeline, and the default encoding settings are not always what you want.

The README's framing is that ffmpeg has a lot of options, and that the program comes with some mostly sensible defaults, but to use GPUs and control the output much more carefully, including framerates and bitrates, you can use a JSON file containing a number of profiles and select the profile you want when running the program.

So there are two levers: a JSON profile file for the encoding, and the profile selection itself on the command line. The documentation points at a guide section for selecting these, with an example of an Nvidia GPU, and there are two more documents for performance, one at the root and one in the docs directory.

The claim in the feature list is that GPUs let the program create movies at up to 17x realtime, and the repository shows the work behind it: the examples directory contains several files whose names are perfetto captures, with names referring to ffmpeg wait, map images, new map, and map before and after. Perfetto is a system-level tracing tool, and the captures in the repository are the evidence for the performance work rather than a marketing number.

That the performance analysis is published is the interesting part. A dashboard overlay involves three expensive things per frame: fetching map tiles, drawing the widgets with Pillow or Cairo, and encoding the composited frame. The traces suggest the author has measured where the time actually goes rather than guessing, and the map image captures point at tile fetching as one of the things being measured.

For a user, the practical consequence is that a first run tends to be slow, and the documentation on profiles and performance is where to look before assuming the machine is at fault.

The companion tools, and the repository layout

There is a family of commands around the main renderer, and the project manifest lists the scripts it installs.

gopro-to-gpx.py converts a GoPro file to a GPX file:

venv/bin/gopro-to-gpx.py <input-file> [output-file]

That one is more useful than it sounds, because it lets you extract the telemetry track and feed it to other tools, or supply an external track to the overlay tool.

gopro-join.py joins a sequence of MP4 files together. Given a single file from the sequence, it will find and join together all the files. The README is refreshingly candid about the limits: the joined file almost certainly won't work in the GoPro tools, but it should work with gopro-dashboard.py, and the author says they will look into the additional technical stuff required to make it work in the GoPro tools. It also warns that this will require a lot of disk space.

venv/bin/gopro-join.py /media/sdcard/DCIM/100GOPRO/GH030170.MP4 /data/gopro/nice-ride.MP4

The reason joining matters is that GoPro splits long recordings into numbered chunks, and a dashboard video of a long ride has to span them.

The repository listing shows the shape of the project. There is gopro_overlay/ for the package itself, bin/ for the command line scripts, docs/ for the documentation tree including the bin, xml, maps and windows sub-documents, examples/ for the images, docker/ for the image build, build-scripts/, tests/ and tests-dist/, and a scratch/ directory. There is a pyproject.toml with setuptools as the build backend, a Makefile, a requirements.txt, a requirements-dev.txt, a pytest.ini, and a CHANGELOG.md and CONTRIBUTING.md. There is also a SECURITY.md and a .bumpversion.cfg, so the version number is managed by a tool rather than by hand, and the project version of 0.134.0 comes from gopro_overlay.__version__ as the Makefile shows.

The two requirements files differ slightly, and it is worth knowing which one applies to you. The pyproject dependencies list the same set as requirements.txt but with different pins in two places, pint at 0.25.1 in pyproject against 0.22 in requirements.txt, and requests at 2.32.5 against 2.32.4, and requirements.txt adds geotiler, which the pyproject dependencies list does not have directly. If you install from PyPI you get the pyproject set; if you install from source following requirements.txt you get the other one.

What is still open, and how to evaluate it

The repository has a Help Wanted section and a Work In Progress section, and together they describe the direction of travel.

The help wanted items are adding additional graphics widgets, ideally using cairo; validation and improvement of smoothing, with Kalman Filters named as an example; and suggestions for handling acceleration and orientation data, with the note that this is parsed but display options are few.

That last one is a good example of a gap that only shows up once you use the tool. Acceleration and orientation are in the telemetry, so the data is there, but there are not many ways to show them. The same applies to the work in progress item, adding min, max and moving averages to metrics.

Smoothing deserves a note because the examples show it explicitly. There are two example images whose names differ only by speed-no-smoothing and speed-with-smoothing, which is a good way to show what the filter changes. Raw GPS speed is noisy, and a speed readout straight from the track jumps around, so the smoothing is what turns a legible gauge into a flickering one.

For an evaluation, four things decide it. Whether your camera's telemetry is good enough on its own or you need to supply an external track, since the README singles out Hero 9 as poor and Hero 11 as much improved. Whether the layout XML gives you the design you want without writing a widget from scratch, which you can judge quickly from the examples directory. Whether you need GPU encoding to make the render time acceptable, which is a hardware question. And whether your platform is supported, with Windows, macOS and Linux all listed and separate Windows and Docker documentation provided.

What you get for it is a package with a long version history, a PyPI release, a Docker image, a PyPI description, and a helper programme with a published performance analysis. The GPL-3.0 licence matters if you intend to embed it, since it is copyleft, but for the personal use it is aimed at, a video of a ride with a speed gauge on it is exactly what it does.

Editorial conclusion

Adopt gopro-overlay if you record rides, flights or drives on a camera that writes telemetry into the video and want a speed, distance and map dashboard burned into the footage, or if you want to build such a video from a GPX or FIT track with no camera involved at all. Do not adopt it expecting the telemetry to be accurate on every model, since the README singles out the Hero 9 as poor and recommends an external GPX file, and do not expect the renderer to be timezone-agnostic, because it interprets UTC timestamps with your local offset. Before you commit, install Roboto or the text will be missing, decide whether you need the optional cairo widgets, use the JSON ffmpeg profiles if you want GPU encoding or specific framerates and bitrates, and read the privacy zone documentation before publishing a route that passes somewhere you would rather not show.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. time4tea/gopro-dashboard-overlay on GitHub