Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ SkyEye is production ready software. It is used by a few public servers and many

SkyEye is **free software**. It is free as in beer; you can download and run it for free. It is also free as in freedom; the source code is available for you to study and modify to fit your needs.

As of late 2025, SkyEye is curently **maintained but not actively developed**. The author hopes to resume active development in the future, but is currently too busy with professional work and other hobbies to dedicate the necessary time. The author intends to publish compatibility updates for new versions of DCS/SRS/Tacview as needed, but new features are on pause.
As of late 2025, SkyEye is currently **maintained but not actively developed**. The author hopes to resume active development in the future, but is currently too busy with professional work and other hobbies to dedicate the necessary time. The author intends to publish compatibility updates for new versions of DCS/SRS/Tacview as needed, but new features are on pause.

## Getting Started

Expand Down Expand Up @@ -69,7 +69,7 @@ See the [admin guide](docs/ADMIN.md) for detailed instructions on installing, co

There are a few different ways to run SkyEye.

1. On an Apple Sillicon Mac networked to your DCS server, using local speech recognition. This offers the fastest speech recognition and the highest quality AI voice.
1. On an Apple Silicon Mac networked to your DCS server, using local speech recognition. This offers the fastest speech recognition and the highest quality AI voice.
2. On your Windows or Linux computer with a GPU, using local speech recognition and the experimental Vulkan build of SkyEye. This offers fast speech recognition and good quality AI voices, although the performance and quality of the speech recognition can vary based on GPU hardware and drivers.
3. On your Windows or Linux computer, using the OpenAI API for speech recognition. This offers fast speech recognition and good quality AI voices, but requires a credit card accepted by OpenAI to purchase API credits from OpenAI. At current pricing, $1 of OpenAI credit pays to recognize more than 1000 transmissions over SRS.
4. On a separate Windows or Linux computer networked to your DCS server, using local speech recognition. This offers good-enough speech recognition performance and good quality AI voice. This also works with rented cloud servers, some of whom accept other payment methods compared to OpenAI.
Expand Down Expand Up @@ -108,19 +108,19 @@ As of this writing, DCS' built-in VoIP does not support external clients. SkyEye

SkyEye uses an embedded LLM for speech-to-text, but I deliberately chose not to use an LLM for SkyEye's language parsing or decision-making logic.

Within the domain of air combat communication, these problems are less linguistic and more mathematical in nature. Air combat communication uses a limited, highly specific vocabulary and a low-context grammar that can be parsed quickly with traditional programming methods. The workflow for the tactical controller is a straightforward decision tree mostly based on tables of aircraft data, some middle school geometry and a few statistical methods. These workflows can be implemented in a few hundred lines of code and run in a few milliseconds. An LLM would have worse performance, no guarantee of consistency, much larger CPU and memory requirements, and introduces a large surface area of ML-specific issues such as privacy of training data sets, debugging hallucinations, and a much more difficult testing and validation process.
Within the domain of air combat communication, these problems are less linguistic and more mathematical in nature. Air combat communication uses a limited, highly specific vocabulary and a low-context grammar that can be parsed quickly with traditional programming methods. The workflow for the tactical controller is a straightforward decision tree mostly based on tables of aircraft data, some middle school geometry and a few statistical methods. These workflows can be implemented in a few hundred lines of code and run in a few milliseconds. An LLM would have worse performance, no guarantee of consistency, much larger CPU and memory requirements, and would introduce a large surface area of ML-specific issues such as privacy of training data sets, debugging hallucinations, and a much more difficult testing and validation process.

While working on this software I spoke to a number of people who thought it would be as easy as feeding a bunch of PDFs to an LLM and it would magically learn how to be a competent tactical controller. This could not be further from the truth!

### Can I use a separate Whisper server or Speech Recognition API?

I don't plan on adding support to this in the main repo because the inregration with Whisper is deeper than a simple transcription request. Certain context from the GCI controller is also passed to the model to improve speech recognition accuracy, e.g. for non-English airport names. If you have a use case for this and are willing to program, I can give you advice on how to do this in your fork.
I don't plan on adding support to this in the main repo because the integration with Whisper is deeper than a simple transcription request. Certain context from the GCI controller is also passed to the model to improve speech recognition accuracy, e.g. for non-English airport names. If you have a use case for this and are willing to program, I can give you advice on how to do this in your fork.

### Could this provide ATC services?

I have no plans to attempt an ATC bot due to limitations within DCS.

AI aircraft in DCS cannot be directly commanded through scripting or external software and are incapable of safely operating in controlled airspace. for example, AI aircraft in DCS do not sequence for landing, and will only begin an approach if the entire approach and runway are clear. AI aircraft also cannot execute a hold or a missed approach, and they make no effort to maintain separation from other aircraft.
AI aircraft in DCS cannot be directly commanded through scripting or external software and are incapable of safely operating in controlled airspace. For example, AI aircraft in DCS do not sequence for landing, and will only begin an approach if the entire approach and runway are clear. AI aircraft also cannot execute a hold or a missed approach, and they make no effort to maintain separation from other aircraft.

While working on this software I spoke to a number of people who thought it would be as easy as feeding a bunch of PDFs to an LLM and it would magically become a capable Air Traffic Controller. This could not be further from the truth!

Expand Down
28 changes: 14 additions & 14 deletions docs/ADMIN.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,17 +32,17 @@ I do not respond to direct messages on social media or the Eagle Dynamics forums

SkyEye can be deployed in three architectures:

- Local speech recongition, running SkyEye on a different PC as DCS and speech recognition on the CPU
- Local speech reconition, running SkyEye on the same PC as DCS and speech recognition on the GPU
- Local speech recognition on CPU, running SkyEye on a different PC from DCS
- Local speech recognition on GPU, running SkyEye on either the same PC as or a different PC from DCS
- Cloud speech recognition, running SkyEye on the same PC as DCS and offloading speech recognition to the OpenAI API

Local speech recognition is more hardware intensive than cloud speech recognition. However, it has a number of advantages:

- Local speech recognition generally has a predictable fixed cost; it costs the same whether players talk only a little or chatter a lot. This makes hosting costs more predictable and reduces the impact a of a malicious or abusive player.
- Local speech recognition generally has a predictable fixed cost; it costs the same whether players talk only a little or chatter a lot. This makes hosting costs more predictable and reduces the impact of a malicious or abusive player.
- Local speech recognition is fully self-contained. It has better privacy qualities, and you can expect it to continue to work far into the future.
- Local speech recognition can be self-hosted on your own hardware. This makes it a viable option for some international groups whose payment methods are not accepted by cloud hosting providers.
- If you have a powerful CPU, or a GPU, self-hosting can be lower-latency and/or cheaper than cloud speech recognition.
- If you have a Mac with an Apple Sillicon CPU, local speech recognition is the best option, since it uses the GPU/Neural Engine for extremely fast performance.
- If you have a Mac with an Apple Silicon CPU, local speech recognition is the best option, since it uses the GPU/Neural Engine for extremely fast performance.

On the other hand, cloud speech recognition has a separate set of tradeoffs:

Expand All @@ -65,11 +65,11 @@ flowchart LR

#### Caution: Running SkyEye with Local Speech Recognition on CPU along with DCS World on One Computer

**Running SkyEye with local speech recognition on CPU on the same computer as DCS World is not intended and probably won't work. I cannott provide support for this configuration.** Even if I wanted to support this configuration, I do not have the appropriate tools to troubleshoot _your specific hardware configuration_. It's difficult enough to troubleshoot these kinds of issues when the hardware is physically in front of me and I have full admin access. Trying to troubleshoot a non-technical user's hardware remotely is impossible. (This is a big reason AI applications, including SkyEye, are so much better on Apple devices; standardized hardware is much easier to support.)
**Running SkyEye with local speech recognition on CPU on the same computer as DCS World is not intended and probably won't work. I cannot provide support for this configuration.** Even if I wanted to support this configuration, I do not have the appropriate tools to troubleshoot _your specific hardware configuration_. It's difficult enough to troubleshoot these kinds of issues when the hardware is physically in front of me and I have full admin access. Trying to troubleshoot a non-technical user's hardware remotely is impossible. (This is a big reason AI applications, including SkyEye, are so much better on Apple devices; standardized hardware is much easier to support.)

**If you open a GitHub Issue regarding performance issues with this configuration, I will tell you to use a second computer or switch to cloud speech recognition.** Almost every report I've received about performance issues with SkyEye have been from users attempting to run SkyEye's local speech recognition on the same computer as DCS World, which is **not an intended way to run SkyEye**. 😾
**If you open a GitHub Issue regarding performance issues with this configuration, I will tell you to use a second computer or switch to cloud speech recognition.** Almost every report I've received about performance issues with SkyEye has been from users attempting to run SkyEye's local speech recognition on the same computer as DCS World, which is **not an intended way to run SkyEye**. 😾

If you have read all of the above, and are still serious about, attempting this, here is the best advice I have:
If you have read all of the above, and are still serious about attempting this, here is the best advice I have:

1. [Watch this talk by Xe Iaso about running AI workloads using local infrastructure](https://xeiaso.net/talks/2025/ai-chatbot-friends/). It's a good primer on the complexity of the problem you're trying to ignore.
2. If, after watching that talk, you still want to try this, click the button for some hints:
Expand Down Expand Up @@ -101,7 +101,7 @@ flowchart TD

## Software

SkyEye is officially supported on Windows AMD64, Linux AMD64 and Apple Silicon. The Windows version bundles all required libraries within `skyeye.exe`. The Linux and macOS versions require [Opus](https://opus-codec.org/) and [SoX Resampler](https://sourceforge.net/p/soxr/wiki/Home/) to be installed through the package manager or Homebrew, respectively. Additionally, the Linux Vulkan version requires GPU driver packages and `libvulcan`. Consult your Linux distro documentation for more information.
SkyEye is officially supported on Windows AMD64, Linux AMD64 and Apple Silicon. The Windows version bundles all required libraries within `skyeye.exe`. The Linux and macOS versions require [Opus](https://opus-codec.org/) and [SoX Resampler](https://sourceforge.net/p/soxr/wiki/Home/) to be installed through the package manager or Homebrew, respectively. Additionally, the Linux Vulkan version requires GPU driver packages and `libvulkan`. Consult your Linux distro documentation for more information.

## Hardware

Expand All @@ -117,13 +117,13 @@ Intel Core|Haswell (2013)
AMD|Excavator (2015)
Intel Pentium/Celeron|Tiger Lake (2020)

SkyEye currently only officially supports the AMD64 (x86-64) CPU architecure on Windows and Linux. ARM CPUs are not yet officially supported on these operating systems.
SkyEye currently only officially supports the AMD64 (x86-64) CPU architecture on Windows and Linux. ARM CPUs are not yet officially supported on these operating systems.

I've found that at least 4 dedicated CPU cores are needed for a good experience, but this may differ by the exact CPU being used, so experiment and see what works well for you. It is important that the CPU cores be **dedicated** cores. Shared core virtual machines are **not supported** and will result in **high latency and stuttering audio.**

##### GPU

When running on Windows or Linux with local speech recognition on GPU, SkyEye requires a any decent multithreaded CPU, 3GB of RAM, about 2GB of VRAM, and about 2GB of disk space. The CPU must have support for [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2).
When running on Windows or Linux with local speech recognition on GPU, SkyEye requires any decent multithreaded CPU, 3GB of RAM, about 2GB of VRAM, and about 2GB of disk space. The CPU must have support for [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2).

#### macOS

Expand Down Expand Up @@ -165,7 +165,7 @@ Examples of suitable servers include:
* [Vultr Optimized Cloud Compute (CPU Optimized)](https://www.vultr.com/pricing/#optimized-cloud-compute)
* [Linode Dedicated CPU Instances](https://www.linode.com/pricing/#compute-dedicated)

I won't provide an endorsement of any particular provider, but I will point out that as of August 2024 Hetzner's CCX23 instance is probably the cheapest way the run SkyEye on public cloud. The cheapest way to run SkyEye overall is probably on a spare computer in your house.
As of 2026, cloud server prices have been increasing, so do your due diligence to compare prices.

### Cloud Speech Recognition

Expand Down Expand Up @@ -202,7 +202,7 @@ log-level: debug

The config file's default location on Linux is `/etc/skyeye/config.yaml`. You can override this location by setting `--config-file` or `SKYEYE_CONFIG_FILE`. On Windows, the installer uses a `config.yaml` file within the same directory as `skyeye.exe`.

It is recommended to use the configuration file as the main source of config. Most users find it the easiest option, and a file is simple to protect using access control policies, unlike a processes' environment or arguments.
It is recommended to use the configuration file as the main source of config. Most users find it the easiest option, and a file is simple to protect using access control policies, unlike a process's environment or arguments.

A sample configuration file is provided in the download which should be customized to fit your needs. It contains many explanatory comments which guide you through customization.

Expand Down Expand Up @@ -297,7 +297,7 @@ The body of the POST request is a JSON object with the following fields:

By implementing a small webservice or serverless function that creates or destroys a SkyEye instance on demand, the cost of running SkyEye can be significantly reduced. This is particularly useful for servers that are only active for a few hours a week, such as a private squadron server.

An example WinSW service definition is provided in the Windows release archive. You can edit this example file to include your webhook URL and the frequencies you want to monitor, then install and run it it using the included `skyeye-scaler-service.exe` executable:
An example WinSW service definition is provided in the Windows release archive. You can edit this example file to include your webhook URL and the frequencies you want to monitor, then install and run it using the included `skyeye-scaler-service.exe` executable:

```batch
:: Install SkyEye Scaler
Expand Down Expand Up @@ -337,7 +337,7 @@ Also note that TTS is pretty fast in practice and you might not need to set `voi

If you are not running multiple instances, these locks are harmful to performance and should not be used. This can especially be a problem if your machine has a slow or busy disk.

Be aware that it is technically possible for the file lock to become deadlocked in some cases, such as if SkyEye is unable to exit cleanly. If you use this feature you should monitor the logs and traces for errors related to lock acquisition. You may need to manually resolve a deadlock by stopping down all SkyEye instances, deleting the lock file and restarting the instances.
Be aware that it is technically possible for the file lock to become deadlocked in some cases, such as if SkyEye is unable to exit cleanly. If you use this feature you should monitor the logs and traces for errors related to lock acquisition. You may need to manually resolve a deadlock by shutting down all SkyEye instances, deleting the lock file and restarting the instances.

This architecture is marked experimental because I don't test this configuration. You are responsible for testing these features on your hardware.

Expand Down
8 changes: 4 additions & 4 deletions docs/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ make install-fedora-dependencies

Run `make` to build `skyeye`.

Anyhwere this guide mentions `skyeye.exe`, remove `.exe` - just run `skyeye`.
Anywhere this guide mentions `skyeye.exe`, remove `.exe` - just run `skyeye`.

<!-- TODO(vulkan): Document `make skyeye-vulkan` to build the experimental GPU-accelerated skyeye-vulkan binary. -->

Expand All @@ -66,7 +66,7 @@ make install-macos-dependencies

Run `make` to build `skyeye`.

Anyhwere this guide mentions `skyeye.exe`, remove `.exe` - just run `skyeye`.
Anywhere this guide mentions `skyeye.exe`, remove `.exe` - just run `skyeye`.

## Run Against a Live Server

Expand All @@ -80,7 +80,7 @@ Install [DCS-SRS](http://dcssimpleradio.com/). This can be on a different comput

Launch the DCS server and SRS server. Load a mission on the DCS server.

You will need to download an OpenAI Whisper model, or use the OpenAI API. Downloading and using a local model is free, but performance intensive. Using the OpenAPI API requires payment to OpenAI.
You will need to download an OpenAI Whisper model, or use the OpenAI API. Downloading and using a local model is free, but performance intensive. Using the OpenAI API requires payment to OpenAI.

### Using a Local Model

Expand Down Expand Up @@ -172,7 +172,7 @@ Wow, that was easy!

The canonical way to run the unit tests is by running `make test`. This can run tests for code that uses CGO. **This is the gate used for PR checks.** You can pass additional flags to `go test` using TEST_FLAGS. For example, `TEST_FLAGS=-parallel=1 make test` will run the tests without parallelism (1 test worker), which can make the logs for a failed test easier to understand.

I have made an effort to structure packages so that CGO is never imported directly or indirectly within packages that aren't directly related to the Speech-To-Text and Text-To-Speech models. This means that most tests can be run though Visual Studio Code without the complexity and performance hit of CGO. **This is the easiest way to test and debug during development.**
I have made an effort to structure packages so that CGO is never imported directly or indirectly within packages that aren't directly related to the Speech-To-Text and Text-To-Speech models. This means that most tests can be run through Visual Studio Code without the complexity and performance hit of CGO. **This is the easiest way to test and debug during development.**

## Benchmark

Expand Down
Loading
Loading