FlappedEar Overlays
FlappedEar Overlays (formerly FlappedEar Telemetry, bundle identifier com.flappedear.overlays) is a native desktop application for video telemetry overlay editing and generation. By owner decision (2 October 2026) the product is split into two applications: this desktop overlay editor for macOS and Windows, and the FlappedEar Telemetry analysis app for macOS, Windows, iOS and Android (com.flappedear.telemetry), a new Flutter app started from a blank page in its own repository and Jira project, which shares no code with this one and cross-references it (architect handover). On 5 October 2026 the owner approved removing the Lap Analysis window and analysis workflows from this app (KAN-166, done; day import is removed too, so Overlays opens days saved by Telemetry; the last main commit with the full analysis, 7eae6cd, is recorded on KAN-169). The View menu, welcome and transport entry points are gone; the editor header picks a day's run, and export finds the day's best lap by itself (KAN-185). Both apps read and write one compatible .fetproject format (KAN-170). The first start after the rename moves the previous preferences, templates, recovery data and logs across without deleting or overwriting anything (application identity). See the product split plan.
Status
Version 0.3.0, in development; no release is approved. The overlay editor and export pipeline work, and the track-day analysis, now being removed from this app (KAN-166), implemented milestones M0–M4: whole-day import, compatible rankings, independent A/B lap comparison, reviewed segments and the Corner Analyzer, sector theoretical best, ranked time losses, consistency, G-G, temperature and heart-rate summaries, and the day report. These are validated by synthetic CI tests and one private real day without video; the owner's real-video acceptance (M5) is still open.
The product vision defines the complete intended scope. The delivery ledger is the single current status record: what is implemented, what remains, and the acceptance evidence. Distribution still requires the exact candidate's acceptance evidence.
User guide
End-user documentation is published at https://flappedear.github.io/Overlay/.
Its sources live in docs/user-guide.
Current capabilities
Saved events use Event → Run → Lap, with independent source references and
video synchronization per run. Track days come from FlappedEar Telemetry as
.fetproject files; the editor header picks the run to edit, and export finds
the day's best lap by itself. Lap exclusions, run names and every other analysis
field saved by Telemetry are kept. The
user guide describes every screen.
- MP4/MOV playback with timeline controls and preview overlays.
- RaceChrono and VBOX VBO telemetry import, plus native single-session RaceChrono RCZ import (supported format).
- Track-day events opened and saved with their runs, alternative recordings and analysis decisions.
- GoPro chapter groups reviewed before loading and played as one continuous timeline. Exporting a chaptered video is not available yet (KAN-106).
- GoPro GPMF GPS extraction and GPS-speed auto synchronization.
- A visual scene editor, a widget editor for designing your own widgets from text, values, bars, lap times and shapes (KAN-191), a My widgets library shared across projects, projects, two built-in layouts (Motorsport Broadcast HUD and Tech HUD), a Classic or Tech style per widget (KAN-193), and shareable templates. Both editor sidebars remain fully scrollable at the supported 1180×720 minimum size.
- Source-defined RaceChrono Start-gate parsing, raw-GPS lap derivation, fastest-lap state, and lap navigation for Out lap, each measured lap, and In lap.
- Independent Best, Current, and Delta tiles for lap time and speed comparison against the best completed lap.
- Source-driven CFR HEVC/AAC MP4 export at the effective rational export rate, including runtime raster/profile checks, validated 8-bit and 10-bit SDR preservation, custom SMPTE ranges, and single-lap hotlap ranges with configurable 5–8 second handles, progress, cancellation, and verbose diagnostics retained in a durable per-export log.
- Portable
.fetproject media references with project-relative lookup, bounded source fingerprints, missing-media recovery, explicit relinking, and stale asynchronous-result rejection.
- Crash-safe export-output handling with state-bound overwrite consent, atomic project saving, and explicit unsaved-change recovery.
- Resource-bounded external JSON documents and subprocess output, with visible recovery-protection warnings when automatic snapshots cannot be persisted.
Keyboard controls
Space plays or pauses. Left/Right seek five seconds; Shift+Left/Right seek thirty seconds; Home/End seek to the first/last actual video frame. These playback shortcuts are disabled while typing or operating a focused editor control. Ctrl/Cmd+E opens Export. The platform full-screen shortcut (⌃⌘F on macOS) enters full screen and Escape leaves it. Full-screen preview provides the same visible transport and scrubber as the editor.
Very Verbose export diagnostics follow the live tail until the user scrolls into history. Historical inspection stays fixed while new lines arrive; Jump to latest explicitly resumes following.
Requirements
- CMake 3.24 or newer.
- A C++20 compiler.
- Qt 6.8 or newer with Concurrent, Core, Gui and matching GuiPrivate headers, Qml, Quick, Quick Controls 2, Multimedia, and Test; include the SVG and Shader Tools modules in binary SDK installations.
- FFmpeg and ffprobe available at runtime. Export depends on an externally installed FFmpeg and a working HEVC encoder; the command-line tools are not bundled. A small production-filter preflight also requires explicit alpha-mode support (
setparams alpha_mode), which needs FFmpeg 8.1 or newer; 8.0.1 and older fail the preflight. CI uses Homebrew FFmpeg 9.0.1.
Development targets macOS, with coordinator implementation and local Codex handoffs as requested. Cloud CI was resumed by owner direction on 13 September 2026 for macOS Debug and Release; Windows builds and validation remain paused. See task delivery for local implementation and validation instructions. Existing Windows NSIS packaging is retained for later resumption.
For replacing an older named bundle without losing preferences or recovery, see
application identity and upgrades.
Build
For per-task local Codex instructions and the update/build/test
handoff, see task delivery and local acceptance.
On Apple Silicon with Homebrew Qt in /opt/homebrew/opt/qt:
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"
If the build suddenly fails everywhere with CMAKE_OSX_SYSROOT ... does not exist and missing system headers (stdio.h, type_traits, TargetConditionals.h), an Xcode or Command Line Tools update removed the SDK that your build-native directory cached. The repository does not set the SDK path. Delete build-native/CMakeCache.txt and configure again, or run cmake -S . -B build-native -UCMAKE_OSX_SYSROOT.
Continuous integration
Native CI runs on pull requests, pushes to main, and manual dispatch. It builds and tests macOS Debug and Release; Release also validates deployed startup and produces an internal candidate. Windows remains paused. Keep local builds and CTest, and report hardware-encoder and private-media acceptance separately. See CI guidance.
Architecture
The application keeps telemetry parsing, synchronization, video/media handling, widgets, and QML presentation separate. Preview and export mount the same TelemetryScene.qml with independent render contexts. Track geometry is converted once per source; playback updates only the current position.
Widget editing
The widget catalog holds the widgets the owner uses (KAN-192): Speed, Heart rate, Steering wheel (KAN-270: BetterDriver's obd_steering_angle, hidden when a recording has none), Track map (KAN-271: the GPS outline with the car, the lap so far and the start/finish line, whole track or a window around the car; hidden without GPS), Pedals, F1 G-Force Radar, G-Force Bar, Retro Custom, Current lap time, Retro RPM and Tyres, plus designed widgets. Eighteen older types were removed on 5 October 2026; a project, template or My widgets entry that holds one opens without it, and the status bar says how many widgets were left out. G-Force widgets can invert lateral and longitudinal presentation axes independently, without changing imported telemetry. The catalog includes an F1 G-Force Radar with a dark semi-transparent circular field, 1.5 g range, and six 0.25 g concentric-ring levels by default, plus a compact G-Force Bar that shows true combined magnitude while clamping only its fill. Speed, pedals, Heart Rate, Retro Custom, and G-Force Bar use the same translucent charcoal broadcast panel, typography, rounded border, and neutral bar-track treatment; throttle is green, brake is red only when it has fill, and G-Force is amber. The analog retro tachometer keeps its circular identity with a matching rounded dark RPM plate. Retro Custom accepts arbitrary channel, adjustment, formatting, unit, fallback, and palette settings. A Tyres widget shows each corner's recorded tyre temperature (°C) and pressure (bar or psi), with a dash where a corner has no data. Text-bearing value widgets offer Font size: Auto retains their responsive legacy sizing, while a positive canonical size is scene-scaled consistently for preview and every export resolution.
New widget… adds a designed widget and opens the widget editor: elements are placed on a live canvas at the playhead (drag, resize, grid snap, undo/redo), and preview and export draw them with the same renderer. Save to My widgets keeps any widget, designed or built-in, for every project; library entries export and import as .fetwidget files. See the user guide.
Template writes validate structure, count and serialized size before atomic replacement; a rejected store remains protected until successfully reloaded. Templates have two explicit operations. Save current updates the custom template that was applied (or just created), preserving its ID, name, and description. Selecting a template alone does not make it editable, so Save current opens Save as new until that custom template is applied. Built-in templates are immutable and always use Save as new.
The Current lap time tile uses the same compact translucent panel family. Scaling it scales its typography, margins, border, and corner radius together. Editor interaction geometry follows widget rotation, and normalized size/scale changes keep the unrotated widget rectangle inside the canvas.
A single GUI editor owns the shared application-data directory through a process lock; export workers remain independent. A saved .fetproject is the authoritative clean document. It can open without its external video or VBO/RCZ assets; missing or mismatched sources remain independently relinkable without losing the scene or settings. Unsaved persistent edits are held separately in an atomic recovery snapshot and are recovered or discarded explicitly at startup only when their logical document state is newer than the saved authority. Before Quit, New, or Open can discard current edits, the editor presents a branded Save / Discard / Cancel confirmation. A leftover snapshot after successful Save is cleanup debt, not degraded recovery protection or a user warning. QSettings stores only application preferences and the last project path. The portable source format is documented in docs/project-format.md.
External JSON documents are size- and structure-bounded before they can create editor models. FFprobe payloads, FFmpeg diagnostics, progress lines, and export-worker messages are bounded as well; diagnostic tails retain the newest useful output. If automatic recovery storage fails, the editor shows a persistent manual-save warning and retries safely after a backoff. A requested recovery discard is durable before cleanup: a matching residual snapshot is suppressed at the next startup, while newer or different-document recovery remains available.
Module details are in docs/architecture.md. The project source lives in native/src/project.
Telemetry semantics
Telemetry has strict no-data semantics: missing is distinct from a measured numeric zero, public raw lookup never returns NaN or infinity, and raw analysis does not bridge missing samples or real timestamp gaps. Preview/export overlays use a separate bounded hold and lightweight smoothing policy to remain stable between ordinary samples without changing raw telemetry. See docs/telemetry-semantics.md.
Export
Export stages a frame-cadenced telemetry overlay, converts the source onto that same CFR cadence before composition, and validates the staged overlay and final MP4 before committing the target file. Scheduling is integer frame-addressed: full-video ranges use the actual source frame domain, and C++ owns inclusive SMPTE NDF IN/OUT parsing. Qt Quick offscreen pixels retain an explicit premultiplied-alpha contract through QRhi readback and FFV1 staging. Before 10-bit YUV composition, Stage B explicitly unpremultiplies that overlay and uses straight-alpha blending so transparent RGB-to-YUV chroma offsets cannot alter the source. Source raster and bit depth remain authoritative rather than being reduced to presets; HDR/Log, non-zero rotation metadata, and non-square sample-aspect-ratio sources are explicitly rejected only at export preflight until their display transforms can be preserved. Import, probe, playback, and editing remain available. Each prepared export writes a separate support log in the app-data exports directory; failures and cancellations keep their logs. See docs/export-pipeline.md, docs/media-color-policy.md, and docs/export-output-safety.md.
Private integration tests
Private recordings are ignored by Git and can be supplied through environment variables:
FLAPPEDEAR_REAL_GOPRO=/path/to/video.mp4 \
FLAPPEDEAR_REAL_VBO=/path/to/session.vbo \
ctest --test-dir build-native -R flappedear_native_tests_ --output-on-failure
A private RaceChrono fixture has been validated with 32,718 samples, 49 channels, 3,271.7 seconds, and zero parser warnings. An August 2026 macOS regression run on one private GoPro/VBO pair restored 1,536-packet / 14,796-sample GPS extraction and +90.217 s auto-sync at 0.999575 correlation. The exact 3840×2160, 60000/1001, 30→90 HEVC/AAC export also passed with 3,597 final video packets, alongside short 1080p59.94 and 720p29.97 checks. These are development results, not cross-platform performance guarantees.
Current limitations
- Real-media coverage is limited: one private track day without video plus earlier GoPro/VBO checks. The owner's full-day walkthrough with matching video (M5) is open.
- Defects found by the independent audit of 2 October 2026 are tracked in Jira epic KAN-144; open technical items are listed in the delivery ledger.
- Internal candidate packaging is automated; clean-machine acceptance, distribution notices and Developer ID signing/notarization remain pending.
- Windows builds and validation are paused. Earlier results covered one Windows 11 / Qt 6.11 / MSVC 2022 / Intel Iris Plus / Quick Sync configuration.
- Chaptered GoPro videos play as one timeline, but exporting them is refused until KAN-106; auto-sync reads GPS from the first chapter only.
- Export requires compatible external FFmpeg at runtime, including the production overlay filters; the application fails early when these are absent.
- Identified RaceChrono VBO versions other than Pro 10.2.4 retain telemetry but omit unverified timing gates with a warning.
- VBO channel units are not stored, so VBO values are shown without units; RCZ units are kept.
- GPS-incomplete laps retain their measured timings but are excluded from spatial references and best-lap ranking, with explicit quality/no-delta states. A/B comparison and rankings require compatible runs (layout, direction and timing gate).
- Rotation and sample-aspect-ratio display-transform preservation, HDR/Log color-managed preservation, and production 8K validation remain pending. One real HERO11 5312×2988 10-bit SDR fixture has passed native and 3840×2160 macOS exports; this is not a broader hardware guarantee.
- Interactive map tiles are pending; the local GPS track view works without map tiles.
- Lap timing requires exactly one valid RaceChrono Start gate and usable synchronized GPS; a manual Start/Finish override is not implemented.
The end-user list of limitations is in the user guide. For remaining work, see the delivery ledger. Developer contribution rules are in AGENTS.md, and local test guidance is in docs/testing.md.
Editor instance and recovery
Run one FlappedEar Overlays editor per user data directory. A second launch asks you to use
or close the existing window, protecting unsaved recovery and custom templates.
Export workers are unaffected. Close older builds before opening this version.
