AlanBacker/audio-flyover-geolocation

English | 简体中文
An agent skill that works out where an audio or video recording was made from the faint propeller aircraft in
its background. It ships a complete, tested Python pipeline and comes in English and Simplified Chinese.
Small aircraft give off a steady tone. As one flies past, the Doppler effect bends that tone into a falling
curve, and the shape of the curve gives the aircraft's speed, its closest distance to the microphone and the
second it was closest. Public ADS-B archives record where every transponder-equipped aircraft was at every
second. If you search those tracks for the place where the predicted curve matches what was recorded, you find
the microphone. Two fly-overs in one recording are enough, even when the recording time is unknown, because
their time difference is fixed by the recording itself.
The method comes from colsto's video
I discovered a sound that leaks your exact location
(2026-11-02). colsto did not release code; this repository is an independent implementation with no affiliation.
Synthetic blind test (seed 23): each fly-over alone gives a strip of possible locations. Scored together on one
shared clock, they give a point 46 m from the true recording location, inside the 0.9-score region the pipeline
reports (radius 182 m).
## Contents
How it works
Accuracy on synthetic blind tests
Install
Use
Check your own videos
Limitations
Responsible use
Repository layout and development
Credits and sources
## How it works
mermaid
flowchart LR
A[Audio or video] --> B[Whitened spectrogram]
B --> C[Trace each Doppler ridge]
C --> D["Fit v, d, f0, tCPA k = v²/d"]
E[Historical ADS-B tracks] --> F
D --> F["Search funnel corridor → CPA match → ΔT → silence"]
F --> G["Exact emission-time scoring both events on one clock"]
G --> H["Location + error region + recording start time"]
1. Read the curve. The heard frequency is f = f0 / (1 + Ṙ/c), where Ṙ is the aircraft's range rate at
the moment the sound was emitted. The two flat ends of the curve give the speed
(v = c·(fhi − flo)/(fhi + flo)). The steepness at closest approach gives the distance
(d = f0·v²/(c·|slope|)).
2. Trace it out of the noise. The spectrogram is whitened against a running median background, and
frames with speech or knocks are gated out. A monotone Viterbi path is then accepted only if it beats a null
path computed on time-shuffled frames, so the tracer does not hallucinate curves in pure noise. When the flat
ends are faint, v and d trade off against each other, but k = v²/d stays well determined. The search
therefore checks every candidate aircraft against k computed from its own ADS-B ground speed.
3. Search the ADS-B archive. The search runs on a 200 m grid with 3D slant distances in ECEF and DEM
ground elevation, and narrows the candidates in stages:
1. corridors around tracks that fit the aircraft class and speed;
2. a closest-point-of-approach match that includes the sound's travel time;
3. the time offset between the two fly-overs;
4. a silence check: no other aircraft may have passed close while the recording was quiet.
4. Score against the exact physics. For each surviving candidate, the curve is predicted from the
aircraft's real track by emission time, and the spectrogram is sampled along it. Both events share one clock