FlappedEar Overlays User Guide Source on GitHub

Installation

FlappedEar Overlays is a native macOS application. Video export and video metadata need FFmpeg, which is installed separately.

Requirements

  • macOS. Development and automated testing use macOS 15 on Apple Silicon. Other macOS versions and Intel Macs have not been tested. Windows builds are paused.
  • FFmpeg and ffprobe, with an HEVC encoder. Needed to read video properties, for GoPro automatic synchronization and for export.
  • Enough free disk space for exports: the final video, a temporary overlay file and a 2 GiB reserve.

Opening telemetry and importing a track day do not need FFmpeg.

Installing the application

The application is currently distributed only as internal test builds; there is no public release. A test build is a .tar.gz archive that contains FlappedEar Overlays.app.

  1. Extract the archive.
  2. Move FlappedEar Overlays.app to your Applications folder (or another folder of your choice).
  3. Open it.

The application's icon is a dark rounded square with amber FlappedEar ears inside grey video-frame corners, above a small data panel with amber and white bars. Builds before 6 October 2026 had a different icon (ears inside a green ring with tick marks); after upgrading, the Dock may show the old one until it restarts: log out and back in, or run killall Dock in Terminal.

Test builds are not signed with a Developer ID or notarized by Apple, so macOS Gatekeeper may warn you or refuse to open the application. Do not disable system protection to work around this. Use only builds you received from the project owner.

Upgrading

  1. Quit the running application.
  2. Replace the application bundle with the new one. Older builds were named Flapped Ear Overlays.app, Flapped Ear Telemetry.app or FlappedEar Telemetry.app; remove the old bundle after installing the new one.
  3. Start the new version.

Preferences, custom templates, recovery data and the last project are kept. The app was renamed from FlappedEar Telemetry to FlappedEar Overlays: on its first start it brings these over from the old name, moving them without deleting or overwriting anything, and tells you if anything had to stay in its old place. Quit the old app before starting the new one. Do not delete the application's data folders (see Where files are stored). There is no automatic updater.

Installing FFmpeg

The application does not include FFmpeg. The simplest way to install it is Homebrew:

brew install ffmpeg

The application looks for ffmpeg and ffprobe on the program search path and, on macOS, also in /opt/homebrew/bin (Apple Silicon Homebrew) and /usr/local/bin (Intel Homebrew). There is no setting for another location.

Check the installation in Terminal:

ffmpeg -version
ffprobe -version
ffmpeg -hide_banner -encoders | grep hevc

The last command should list at least one HEVC encoder, such as hevc_videotoolbox (Apple hardware) or libx265 (software).

Export needs FFmpeg 8.1 or newer. It uses filters that older builds lack; FFmpeg 8.0.1, 7.1.1 and 6.1.1, for example, fail. Before rendering, the application runs a short test of the exact processing it needs and stops with a clear error if FFmpeg is not suitable. A current Homebrew FFmpeg is recommended.

Building from source

For developers. You need CMake 3.24 or newer, a C++20 compiler (Xcode command-line tools), and Qt 6.8 or newer with Concurrent, Core, Gui (with GuiPrivate headers), Qml, Quick, Quick Controls 2, Multimedia, Test, SVG and Shader Tools. The build downloads zlib, so it needs internet access.

With Homebrew Qt on Apple Silicon:

git clone https://github.com/FlappedEar/Overlay.git
cd VBOOverlay
cmake -S . -B build-native \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/qt
cmake --build build-native --parallel
ctest --test-dir build-native --output-on-failure
open "build-native/native/FlappedEar Overlays.app"

Developer documentation, including testing and packaging, is in the repository's README and docs folder.