Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

Document Windows discovery-only support (#424)

Cinna Davis615a1acc1ccc
diff --git a/README.md b/README.md
index 4d1a63e..a2c68db 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,11 @@ The integrated application and command-line workflow are available on `main`. Se
Install the [published PyPI package](https://pypi.org/project/dopplergeist/) with `pipx`. It requires Python 3.11+; Intel Macs require Python 3.11–3.13. Install **FFmpeg** separately and make sure that `ffmpeg` and `ffprobe` are on your `PATH`.
+The full CLI and browser workflow require Linux or macOS. On native Windows,
+the published wheels support `discover` only; `analyze`, `serve`, and `job`
+depend on POSIX facilities and fail to start. Windows users can run the full
+workflow inside WSL with Linux, Python, and FFmpeg installed there.
+
```bash
pipx install dopplergeist
dopplergeist --help
diff --git a/docs/PYPI.md b/docs/PYPI.md
index 792a554..53b6d4e 100644
--- a/docs/PYPI.md
+++ b/docs/PYPI.md
@@ -6,6 +6,11 @@ DOPPLERGEIST is published on [PyPI](https://pypi.org/project/dopplergeist/) as `
Requirements: **Python 3.11+** and **FFmpeg**. Intel Macs require Python 3.11–3.13; Python 3.14 on Intel macOS is not supported. Install `ffmpeg` and `ffprobe` separately and make sure that both commands are on your `PATH`.
+The full CLI and browser workflow require Linux or macOS. Native Windows wheels
+support `discover` only; `analyze`, `serve`, and `job` depend on POSIX facilities
+and fail to start. Run the full workflow in WSL with Linux, Python, and FFmpeg
+installed there.
+
For a standalone command-line installation, use `pipx`:
```bash
@@ -20,7 +25,7 @@ python -m pip install dopplergeist
dopplergeist --help
```
-The wheel provides the Python package, CLI, and local browser application. It does **not** bundle the FFmpeg executables or aircraft and terrain data. See the [Quickstart](../README.md#quickstart) and [Setup](SETUP.md) guides.
+The wheel provides the Python package, CLI, and local browser application, subject to the platform limits above. It does **not** bundle the FFmpeg executables or aircraft and terrain data. See the [Quickstart](../README.md#quickstart) and [Setup](SETUP.md) guides.
## Maintainer: publish a new release
diff --git a/docs/PYPI_README.md b/docs/PYPI_README.md
index c81b60f..0337675 100644
--- a/docs/PYPI_README.md
+++ b/docs/PYPI_README.md
@@ -12,6 +12,11 @@ The illustrated real-recording experiment ranked a location 476 m from an *infer
Requires **Python 3.11+**. Intel Macs require Python 3.11–3.13; Python 3.14 on Intel macOS is not supported. Install **FFmpeg** separately so that both `ffmpeg` and `ffprobe` are on your `PATH`.
+The full CLI and browser workflow require Linux or macOS. Native Windows wheels
+support `discover` only: `analyze`, `serve`, and `job` depend on POSIX facilities
+and fail to start. For the full workflow on Windows, use WSL with Linux, Python,
+and FFmpeg installed inside it.
+
For the CLI:
```sh
diff --git a/docs/SETUP.md b/docs/SETUP.md
index a861971..fc4f37a 100644
--- a/docs/SETUP.md
+++ b/docs/SETUP.md
@@ -2,6 +2,10 @@
## Requirements
+- Linux or macOS for the full CLI and browser workflow. Native Windows wheels
+ support `discover` only; `analyze`, `serve`, and `job` fail to start because
+ they require POSIX facilities. On Windows, use a Linux WSL environment for the
+ full workflow and install Python and FFmpeg inside it.
- Python 3.11 or newer. Intel Macs require Python 3.11–3.13. Fresh Linux environments were checked with Python 3.12.15
and 3.14.8 for this checkpoint; CI also exercises the declared Python 3.11 minimum.
- `ffmpeg` and `ffprobe` on PATH. The MP3 smoke tests use ffmpeg's `libmp3lame`
diff --git a/pyproject.toml b/pyproject.toml
index 73d0196..58702d1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -52,4 +52,4 @@ testpaths = ["tests"]
[tool.cibuildwheel]
build = "cp311-* cp312-* cp313-* cp314-*"
skip = "*-musllinux_* cp314-macosx_x86_64"
-test-command = "dopplergeist --help && python -c \"import dopplergeist.advanced_discovery; from importlib.resources import files; assert files('dopplergeist.web').joinpath('index.html').is_file()\""
+test-command = "dopplergeist --help && python -c \"import sys, dopplergeist.advanced_discovery; from importlib.resources import files; assert files('dopplergeist.web').joinpath('index.html').is_file(); sys.platform == 'win32' or __import__('dopplergeist.jobs'); sys.platform == 'win32' or __import__('dopplergeist.tiled_search')\""