Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
<!doctype html>
<html lang="en" data-type="software">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="page-type" content="software">
<meta name="site-kind" content="software">
<meta name="theme-color" content="#121816">
<title>How Aircraft Doppler Audio Geolocation Works — DOPPLERGEIST</title>
<meta name="description" content="How DOPPLERGEIST locates audio: detect Doppler frequency ridges, match historical ADS-B flight paths, model sound propagation and search for the microphone.">
<meta name="robots" content="index,follow,max-image-preview:large">
<link rel="canonical" href="https://1337isnot1337.github.io/DOPPLERGEIST/how-it-works.html">
<link rel="preload" href="site-fonts/GeistSerif-Regular.woff2" as="font" type="font/woff2" crossorigin>
<link rel="stylesheet" href="site.css?v=5">
<script src="site.js?v=5" defer></script>
<link rel="icon" href="site-media/favicon.svg" type="image/svg+xml">
<meta property="og:type" content="website">
<meta property="og:site_name" content="DOPPLERGEIST">
<meta property="og:title" content="How Aircraft Doppler Audio Geolocation Works — DOPPLERGEIST">
<meta property="og:description" content="How DOPPLERGEIST locates audio: detect Doppler frequency ridges, match historical ADS-B flight paths, model sound propagation and search for the microphone.">
<meta property="og:url" content="https://1337isnot1337.github.io/DOPPLERGEIST/how-it-works.html">
<meta property="og:image" content="https://1337isnot1337.github.io/DOPPLERGEIST/site-media/livermore-automatic-mp3.png">
<meta property="og:image:width" content="2610">
<meta property="og:image:height" content="1278">
<meta property="og:image:alt" content="Aircraft Doppler spectrogram and satellite map from the real Livermore recording">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="How Aircraft Doppler Audio Geolocation Works — DOPPLERGEIST">
<meta name="twitter:description" content="How DOPPLERGEIST locates audio: detect Doppler frequency ridges, match historical ADS-B flight paths, model sound propagation and search for the microphone.">
<meta name="twitter:image" content="https://1337isnot1337.github.io/DOPPLERGEIST/site-media/livermore-automatic-mp3.png">
<meta name="twitter:image:alt" content="Aircraft Doppler spectrogram and satellite map from the real Livermore recording">
<script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://1337isnot1337.github.io/DOPPLERGEIST/#website","url":"https://1337isnot1337.github.io/DOPPLERGEIST/","name":"DOPPLERGEIST"},{"@type":"WebPage","@id":"https://1337isnot1337.github.io/DOPPLERGEIST/how-it-works.html#page","url":"https://1337isnot1337.github.io/DOPPLERGEIST/how-it-works.html","name":"How Aircraft Doppler Audio Geolocation Works — DOPPLERGEIST","description":"How DOPPLERGEIST locates audio: detect Doppler frequency ridges, match historical ADS-B flight paths, model sound propagation and search for the microphone.","isPartOf":{"@id":"https://1337isnot1337.github.io/DOPPLERGEIST/#website"},"primaryImageOfPage":{"@type":"ImageObject","contentUrl":"https://1337isnot1337.github.io/DOPPLERGEIST/site-media/livermore-automatic-mp3.png"}},{"@type":"SoftwareSourceCode","@id":"https://1337isnot1337.github.io/DOPPLERGEIST/#software","name":"DOPPLERGEIST","description":"Audio geolocation software that matches aircraft Doppler signatures to historical ADS-B flight trajectories.","codeRepository":"https://github.com/1337isnot1337/DOPPLERGEIST","programmingLanguage":"Python","runtimePlatform":"Python 3.11 or later","license":"https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/LICENSE","author":{"@type":"Person","name":"Cinna Davis","url":"https://github.com/1337isnot1337"}},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"DOPPLERGEIST","item":"https://1337isnot1337.github.io/DOPPLERGEIST/"},{"@type":"ListItem","position":2,"name":"How it works","item":"https://1337isnot1337.github.io/DOPPLERGEIST/how-it-works.html"}]}]}</script>
</head>
<body>
<header class="site-header nav">
<a class="skip skip-link" href="#main">Skip to content</a>
<div class="wrap header-content">
<a class="brand" href="./" aria-label="DOPPLERGEIST home">DOPPLERGEIST</a>
<nav aria-label="Main navigation"><a href="./">Overview</a><a href="examples.html">Examples</a><a href="how-it-works.html" aria-current="page">How it works</a><a class="nav-repo" href="https://github.com/1337isnot1337/DOPPLERGEIST">GitHub <span aria-hidden="true">↗</span></a></nav>
</div></header>
<main id="main">
<section class="page-heading wrap"><h1>A moving source.<br><span>A changing pitch.</span></h1><p>A passing aircraft’s pitch changes with its motion relative to the microphone. DOPPLERGEIST matches that change to recorded flight paths.</p></section>
<section class="section first wrap" aria-labelledby="pitch"><div class="section-intro"><h2 id="pitch">Why the pitch falls.</h2><p>On approach, each wave has less distance to travel than the one before it. Waves arrive closer together: a higher pitch. As the aircraft recedes, they arrive farther apart: a lower pitch.</p></div><div class="doppler-demo" data-doppler>
<svg class="doppler-scene" viewBox="0 0 1080 490" role="img" aria-labelledby="demo-title demo-desc">
<title id="demo-title">How motion changes the pitch at a microphone</title>
<desc id="demo-desc">An aircraft moves from left to right, emitting evenly timed sound waves. Waves are closer together ahead and farther apart behind. The received pitch drops as the aircraft passes. The diagram includes sound travel time and illustrates a constant tone and speed; it is not recorded data.</desc>
<defs><clipPath id="wave-area"><rect width="1080" height="310"/></clipPath></defs>
<g clip-path="url(#wave-area)"><path class="flight-line" d="M40 105H1040"/><g class="wavefronts" data-waves><circle cx="402.86" cy="105" r="42.00"/><circle cx="383.27" cy="105" r="98.00"/><circle cx="363.67" cy="105" r="154.00"/><circle cx="344.08" cy="105" r="210.00"/><circle cx="324.49" cy="105" r="266.00"/><circle cx="304.90" cy="105" r="322.00"/><circle cx="285.31" cy="105" r="378.00"/><circle cx="265.71" cy="105" r="434.00"/><circle cx="246.12" cy="105" r="490.00"/><circle cx="226.53" cy="105" r="546.00"/><circle cx="206.94" cy="105" r="602.00"/><circle cx="187.35" cy="105" r="658.00"/></g>
<path class="sound-link" data-sound-link d="M417.55 105L540 268.27"/>
<g class="aircraft" data-plane transform="translate(417.55 105)"><path d="M22 0 0-5-14-23-21-23-14-4-29-7-33-3-23 0-33 3-29 7-14 4-21 23-14 23 0 5Z"/></g>
<g data-receiver transform="translate(0 3.27)"><circle class="receiver-hit" cx="540" cy="265" r="30"/><circle class="receiver-halo" cx="540" cy="265" r="21"/><g class="receiver"><rect x="536" y="252" width="8" height="15" rx="4"/><path d="M532 262v3a8 8 0 0 0 16 0v-3m-8 11v7m-6 0h12"/></g><text x="577" y="271">Microphone</text></g>
</g>
<text x="44" y="40">AIRCRAFT MOTION →</text>
<path class="chart-grid" d="M80 340V456H1000M80 405H1000"/>
<text x="80" y="330">RECEIVED PITCH</text><text x="1000" y="395" text-anchor="end">Source pitch</text>
<path class="pitch-curve" data-curve d="M80.00,359.68 L84.60,359.74 L89.20,359.79 L93.80,359.85 L98.40,359.91 L103.00,359.97 L107.60,360.03 L112.20,360.10 L116.80,360.16 L121.40,360.23 L126.00,360.30 L130.60,360.37 L135.20,360.45 L139.80,360.52 L144.40,360.60 L149.00,360.68 L153.60,360.76 L158.20,360.84 L162.80,360.93 L167.40,361.02 L172.00,361.11 L176.60,361.21 L181.20,361.30 L185.80,361.40 L190.40,361.51 L195.00,361.61 L199.60,361.72 L204.20,361.83 L208.80,361.95 L213.40,362.07 L218.00,362.19 L222.60,362.32 L227.20,362.45 L231.80,362.58 L236.40,362.72 L241.00,362.87 L245.60,363.01 L250.20,363.17 L254.80,363.32 L259.40,363.49 L264.00,363.66 L268.60,363.83 L273.20,364.01 L277.80,364.19 L282.40,364.39 L287.00,364.58 L291.60,364.79 L296.20,365.00 L300.80,365.22 L305.40,365.44 L310.00,365.68 L314.60,365.92 L319.20,366.17 L323.80,366.42 L328.40,366.69 L333.00,366.97 L337.60,367.25 L342.20,367.55 L346.80,367.85 L351.40,368.17 L356.00,368.50 L360.60,368.83 L365.20,369.18 L369.80,369.54 L374.40,369.92 L379.00,370.30 L383.60,370.70 L388.20,371.11 L392.80,371.54 L397.40,371.97 L402.00,372.43 L406.60,372.89 L411.20,373.37 L415.80,373.87 L420.40,374.38 L425.00,374.91 L429.60,375.45 L434.20,376.01 L438.80,376.58 L443.40,377.17 L448.00,377.77 L452.60,378.39 L457.20,379.02 L461.80,379.67 L466.40,380.34 L471.00,381.01 L475.60,381.70 L480.20,382.41 L484.80,383.13 L489.40,383.86 L494.00,384.60 L498.60,385.35 L503.20,386.11 L507.80,386.89 L512.40,387.67 L517.00,388.45 L521.60,389.24 L526.20,390.04 L530.80,390.84 L535.40,391.64 L540.00,392.45 L544.60,393.25 L549.20,394.05 L553.80,394.86 L558.40,395.65 L563.00,396.44 L567.60,397.23 L572.20,398.01 L576.80,398.78 L581.40,399.54 L586.00,400.30 L590.60,401.04 L595.20,401.77 L599.80,402.49 L604.40,403.19 L609.00,403.88 L613.60,404.56 L618.20,405.22 L622.80,405.87 L627.40,406.51 L632.00,407.13 L636.60,407.73 L641.20,408.32 L645.80,408.89 L650.40,409.45 L655.00,409.99 L659.60,410.51 L664.20,411.03 L668.80,411.52 L673.40,412.00 L678.00,412.47 L682.60,412.92 L687.20,413.36 L691.80,413.79 L696.40,414.20 L701.00,414.59 L705.60,414.98 L710.20,415.35 L714.80,415.71 L719.40,416.06 L724.00,416.40 L728.60,416.73 L733.20,417.04 L737.80,417.35 L742.40,417.64 L747.00,417.93 L751.60,418.20 L756.20,418.47 L760.80,418.73 L765.40,418.98 L770.00,419.22 L774.60,419.45 L779.20,419.68 L783.80,419.90 L788.40,420.11 L793.00,420.31 L797.60,420.51 L802.20,420.70 L806.80,420.89 L811.40,421.07 L816.00,421.24 L820.60,421.41 L825.20,421.57 L829.80,421.73 L834.40,421.88 L839.00,422.03 L843.60,422.17 L848.20,422.31 L852.80,422.45 L857.40,422.58 L862.00,422.70 L866.60,422.83 L871.20,422.95 L875.80,423.06 L880.40,423.17 L885.00,423.28 L889.60,423.39 L894.20,423.49 L898.80,423.59 L903.40,423.69 L908.00,423.78 L912.60,423.88 L917.20,423.96 L921.80,424.05 L926.40,424.13 L931.00,424.22 L935.60,424.30 L940.20,424.37 L944.80,424.45 L949.40,424.52 L954.00,424.59 L958.60,424.66 L963.20,424.73 L967.80,424.80 L972.40,424.86 L977.00,424.92 L981.60,424.98 L986.20,425.04 L990.80,425.10 L995.40,425.16 L1000.00,425.21"/><path class="chart-cursor" data-cursor d="M375.71 340V456"/><circle class="pitch-dot" data-dot cx="375.71" cy="370.02" r="6"/>
<text x="80" y="482">Approach</text><text x="1000" y="482" text-anchor="end">Recession · time →</text>
</svg>
<div class="demo-controls" hidden>
<div class="demo-transport"><button type="button" class="play-button" data-play>Play flyover</button><label class="timeline-label"><span>Flyover position</span><input data-time type="range" min="0" max="1000" value="321" aria-label="Scrub through the flyover"></label><div class="pitch-readout"><output data-pitch aria-live="off">Higher pitch</output><span class="demo-phase" data-phase>Approaching · higher pitch</span></div></div>
<div class="demo-parameters"><label for="demo-speed"><span>Aircraft speed <output data-speed-value for="demo-speed">120 m/s</output></span><input id="demo-speed" data-speed type="range" min="60" max="140" step="5" value="120"></label><label for="demo-distance"><span>Microphone distance <output data-distance-value for="demo-distance">800 m</output></span><input id="demo-distance" data-distance type="range" min="250" max="850" step="10" value="800"></label></div>
</div>
</div><details class="physics-detail"><summary>The physics behind the curve</summary><div><p>For a steady source tone and a stationary microphone, the received frequency is <code>f = f₀ c / (c + vᵣ)</code>. Here <code>f₀</code> is the source frequency, <code>c</code> is sound speed, and <code>vᵣ</code> is radial velocity at emission, positive when moving away.</p><p>Sound emitted at time <code>τ</code> arrives at <code>t = τ + r(τ) / c</code>. The model solves for that emission time before calculating the pitch. The sound of closest approach arrives after the aircraft has passed.</p><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/METHODOLOGY.md#physical-model-and-sign-convention">Read the physical model ↗</a></div></details></section>
<nav class="page-jumps wrap" aria-label="On this page"><a href="#hear">Detect</a><a href="#flight">Match</a><a href="#search">Locate</a><a href="#run">Run locally</a></nav>
<section class="section wrap" aria-labelledby="hear"><div class="section-intro"><h2 id="hear">Find the aircraft in the audio.</h2><p>The detector scans the full recording for moving frequency ridges and groups harmonics from the same passage.</p></div>
<figure class="evidence-figure"><div class="figure-heading"><span>Across the recording</span><span aria-hidden="true">↗</span></div><a class="figure-link" href="site-media/discovery-overview.png" aria-label="View full-size image: Automatic acoustic discovery plot showing Doppler ridges at multiple times in a real recording"><img src="site-media/discovery-overview.webp" srcset="site-media/discovery-overview-960.webp 960w, site-media/discovery-overview.webp 1560w" sizes="(max-width: 700px) calc(100vw - 62px), (max-width: 900px) calc(100vw - 98px), min(1166px, calc(100vw - 146px))" width="1560" height="650" loading="lazy" decoding="async" alt="Automatic acoustic discovery plot showing Doppler ridges at multiple times in a real recording"></a><figcaption>Moving-frequency proposals found by the detector; proposals are not confirmed aircraft.</figcaption></figure>
</section>
<section class="section wrap" aria-labelledby="flight"><div class="section-intro"><h2 id="flight">Match the flight path.</h2><p>Historical ADS-B data supplies aircraft positions and velocities. The model predicts the sound received at each possible microphone position, including its travel time.</p></div>
<figure class="evidence-figure"><div class="figure-heading"><span>The flight-path model</span><span aria-hidden="true">↗</span></div><a class="figure-link" href="site-media/physical-model.png" aria-label="View full-size image: Cyan sound-propagation model aligned with a measured aircraft Doppler curve"><img src="site-media/physical-model.webp" srcset="site-media/physical-model-960.webp 960w, site-media/physical-model.webp 1600w" sizes="(max-width: 700px) calc(100vw - 62px), (max-width: 900px) calc(100vw - 98px), min(1166px, calc(100vw - 146px))" width="1600" height="640" loading="lazy" decoding="async" alt="Cyan sound-propagation model aligned with a measured aircraft Doppler curve"></a><figcaption>A trajectory-based prediction over the recorded spectrogram.</figcaption></figure>
</section>
<section class="section wrap location-section" aria-labelledby="search"><div><h2 id="search">Find the shared position.</h2><p>The search fits independent flyovers to one location and recording clock. Terrain and aircraft altitude enter the sound-propagation calculation.</p><p>The result includes ranked locations and a decision. Ambiguous matches or incomplete coverage produce an inconclusive result.</p><a class="text-link" href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/CONFIDENCE.md">Decision rules <span aria-hidden="true">↗</span></a></div>
<figure class="evidence-figure"><div class="figure-heading"><span>The candidate map</span><span aria-hidden="true">↗</span></div><a class="figure-link" href="site-media/location-scores.png" aria-label="View full-size image: Scored microphone positions on a geographic grid, with the highest score marked by a star"><img src="site-media/location-scores.webp" srcset="site-media/location-scores-960.webp 960w, site-media/location-scores.webp 1120w" sizes="(max-width: 700px) calc(100vw - 62px), (max-width: 900px) calc(100vw - 98px), min(1166px, calc(100vw - 146px))" width="1120" height="960" loading="lazy" decoding="async" alt="Scored microphone positions on a geographic grid, with the highest score marked by a star"></a><figcaption>Color encodes fit score, not location probability.</figcaption></figure>
</section>
<section class="section wrap setup" aria-labelledby="run"><h2 id="run">Run it locally.</h2><p>Install Python 3.11 or later and FFmpeg, then start the local upload interface.</p>
<pre tabindex="0" role="region" aria-label="Local installation commands"><code>git clone https://github.com/1337isnot1337/DOPPLERGEIST.git
cd DOPPLERGEIST
python -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/dopplergeist serve --jobs jobs --online --port 8765</code></pre>
<p>Open <code>http://127.0.0.1:8765</code> and provide your audio and recording-time window. File upload time does not establish when the audio was recorded.</p><a class="text-link" href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md">Full setup instructions <span aria-hidden="true">↗</span></a></section>
<div class="next-page wrap"><span>See the method in recorded data</span><a href="examples.html">Explore the examples <span aria-hidden="true">→</span></a></div>
</main>
<footer class="wrap">
<a class="brand" href="./">DOPPLERGEIST</a>
<nav aria-label="Footer navigation"><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md">Documentation</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/LICENSE">License</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/COMMERCIAL-LICENSING.md">Commercial use</a></nav>
</footer>
</body>
</html>