From 8128f96db216a3a96ed866841fc2ad9976e2923b Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Thu, 2 Jul 2026 17:48:57 -0600 Subject: [PATCH 1/9] Fix container images by matching runtime base to builder golang:1.26 is Debian trixie (glibc 2.41), but the runtime stages used debian:bookworm-slim (glibc 2.36). Binaries built in the builder stage fail to start on the runtime image with "GLIBC_2.38 not found". Use debian:trixie-slim for the runtime base to match the builder. Co-Authored-By: Claude Fable 5 --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 4ec21f9d..c63e626b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -22,7 +22,7 @@ COPY pkg pkg RUN make skyeye RUN make skyeye-scaler -FROM debian:bookworm-slim AS base +FROM debian:trixie-slim AS base RUN apt-get update && apt-get install -y \ ca-certificates \ libopus0 \ From 29b3fc3450fb2574885839fef944ed1d01a747cc Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Thu, 2 Jul 2026 17:49:19 -0600 Subject: [PATCH 2/9] Add experimental Vulkan GPU builds for Windows and Linux Build whisper.cpp with -DGGML_VULKAN=ON to accelerate speech recognition on GPUs. make skyeye-vulkan produces a skyeye-vulkan binary (skyeye-vulkan.exe on Windows) using a separate whisper.cpp build directory so CPU and Vulkan builds don't collide. At runtime the Vulkan build needs only the GPU driver's Vulkan loader: vulkan-1.dll ships with Windows GPU drivers, and the container image includes libvulkan1 plus Mesa ICDs for AMD/Intel (the NVIDIA container toolkit injects NVIDIA's ICD). When no Vulkan device is present, whisper.cpp logs "no GPU found" and falls back to CPU inference. Releases gain skyeye-linux-amd64-vulkan.tar.gz and skyeye-windows-amd64-vulkan.zip, and images are pushed to ghcr.io with a -vulkan tag suffix. Co-Authored-By: Claude Fable 5 --- .github/actions/build-container/action.yaml | 6 + .github/actions/build-whisper/action.yaml | 6 +- .github/workflows/skyeye.yaml | 130 ++++++++++++++++++++ Dockerfile | 20 +++ Makefile | 61 ++++++++- 5 files changed, 216 insertions(+), 7 deletions(-) diff --git a/.github/actions/build-container/action.yaml b/.github/actions/build-container/action.yaml index eed2231d..796da89b 100644 --- a/.github/actions/build-container/action.yaml +++ b/.github/actions/build-container/action.yaml @@ -21,6 +21,10 @@ inputs: skyeye-version: description: 'Version to use in build args' required: true + tag-suffix: + description: 'Suffix appended to image tags (e.g. -vulkan)' + required: false + default: '' runs: using: composite steps: @@ -35,6 +39,8 @@ runs: uses: docker/metadata-action@v5 with: images: ${{ inputs.registry }}/${{ inputs.image-name }} + flavor: | + suffix=${{ inputs.tag-suffix }},onlatest=true - name: Build and push Docker image id: push uses: docker/build-push-action@v6 diff --git a/.github/actions/build-whisper/action.yaml b/.github/actions/build-whisper/action.yaml index ef1b93e0..61e38357 100644 --- a/.github/actions/build-whisper/action.yaml +++ b/.github/actions/build-whisper/action.yaml @@ -21,9 +21,13 @@ inputs: description: 'The shell to use' required: true default: 'bash' + make-args: + description: 'Extra arguments passed to make (e.g. GGML_VULKAN=1)' + required: false + default: '' runs: using: composite steps: - name: Build whisper.cpp shell: ${{ inputs.shell }} - run: make whisper + run: make whisper ${{ inputs.make-args }} diff --git a/.github/workflows/skyeye.yaml b/.github/workflows/skyeye.yaml index da7d8b36..7954ea71 100644 --- a/.github/workflows/skyeye.yaml +++ b/.github/workflows/skyeye.yaml @@ -182,6 +182,117 @@ jobs: path: dist/skyeye-windows-amd64.zip if-no-files-found: error overwrite: true + build-linux-amd64-vulkan: + name: Build on Linux AMD64 (Vulkan) + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Checkout + uses: actions/checkout@v6 + - name: Setup + uses: ./.github/actions/setup + - name: Build whisper.cpp + uses: ./.github/actions/build-whisper + with: + make-args: GGML_VULKAN=1 + - name: Build SkyEye + run: make skyeye-vulkan + - name: Build SkyEye Scaler + run: make skyeye-scaler + - name: Smoke test + run: ./skyeye-vulkan --help + - name: Create dist + shell: bash + run: | + mkdir -p dist/skyeye-linux-amd64-vulkan/docs/ + cp skyeye-vulkan dist/skyeye-linux-amd64-vulkan/skyeye-vulkan + cp skyeye-scaler dist/skyeye-linux-amd64-vulkan/skyeye-scaler + chmod +x dist/skyeye-linux-amd64-vulkan/skyeye-vulkan + chmod +x dist/skyeye-linux-amd64-vulkan/skyeye-scaler + cp README.md dist/skyeye-linux-amd64-vulkan/README.md + cp LICENSE dist/skyeye-linux-amd64-vulkan/LICENSE + cp config.yaml dist/skyeye-linux-amd64-vulkan/config.yaml + cp docs/*.md dist/skyeye-linux-amd64-vulkan/docs/ + tar -czf dist/skyeye-linux-amd64-vulkan.tar.gz -C dist skyeye-linux-amd64-vulkan + - name: Upload artifact + if: startsWith(github.ref, 'refs/tags/') + uses: actions/upload-artifact@v5 + with: + name: skyeye-linux-amd64-vulkan.tar.gz + path: dist/skyeye-linux-amd64-vulkan.tar.gz + if-no-files-found: error + overwrite: true + build-windows-amd64-vulkan: + name: Build on Windows AMD64 (Vulkan) + runs-on: windows-latest + permissions: + contents: read + env: + GOROOT: /ucrt64/lib/go + steps: + - name: Checkout + uses: actions/checkout@v6 + - name: Set up MSYS2 + uses: msys2/setup-msys2@v2 + with: + msystem: UCRT64 + install: | + base-devel + git + mingw-w64-ucrt-x86_64-cmake + mingw-w64-ucrt-x86_64-gcc + mingw-w64-ucrt-x86_64-toolchain + mingw-w64-ucrt-x86_64-opus + mingw-w64-ucrt-x86_64-libsoxr + mingw-w64-ucrt-x86_64-gcc + mingw-w64-ucrt-x86_64-go + mingw-w64-ucrt-x86_64-curl + mingw-w64-ucrt-x86_64-vulkan-headers + mingw-w64-ucrt-x86_64-vulkan-loader + mingw-w64-ucrt-x86_64-shaderc + mingw-w64-ucrt-x86_64-spirv-headers + zip + - name: Build whisper.cpp + uses: ./.github/actions/build-whisper + with: + os: windows + shell: msys2 {0} + make-args: GGML_VULKAN=1 + - name: Build Skyeye + shell: msys2 {0} + run: make skyeye-vulkan + - name: Build Skyeye Scaler + shell: msys2 {0} + run: make skyeye-scaler.exe + - name: Smoke test + shell: msys2 {0} + run: ./skyeye-vulkan.exe --help + - name: Create dist + shell: msys2 {0} + run: | + mkdir -p dist/skyeye-windows-amd64-vulkan/docs/ + cp skyeye-vulkan.exe dist/skyeye-windows-amd64-vulkan/skyeye-vulkan.exe + cp skyeye-scaler.exe dist/skyeye-windows-amd64-vulkan/skyeye-scaler.exe + curl -fsL https://github.com/winsw/winsw/releases/download/v2.12.0/WinSW-x64.exe -o winsw.exe + cp README.md dist/skyeye-windows-amd64-vulkan/README.md + cp LICENSE dist/skyeye-windows-amd64-vulkan/LICENSE + cp config.yaml dist/skyeye-windows-amd64-vulkan/config.yaml + cp docs/*.md dist/skyeye-windows-amd64-vulkan/docs/ + cp winsw.exe dist/skyeye-windows-amd64-vulkan/skyeye-service.exe + sed 's/^executable: skyeye.exe$/executable: skyeye-vulkan.exe/' init/winsw/skyeye-service.yml > dist/skyeye-windows-amd64-vulkan/skyeye-service.yml + cp winsw.exe dist/skyeye-windows-amd64-vulkan/skyeye-scaler-service.exe + cp init/winsw/skyeye-scaler-service.yml dist/skyeye-windows-amd64-vulkan/skyeye-scaler-service.yml + cd dist + zip -r skyeye-windows-amd64-vulkan.zip skyeye-windows-amd64-vulkan + - name: Upload artifact + if: startsWith(github.ref, 'refs/tags/') + uses: actions/upload-artifact@v5 + with: + name: skyeye-windows-amd64-vulkan.zip + path: dist/skyeye-windows-amd64-vulkan.zip + if-no-files-found: error + overwrite: true build-image: name: Build container image if: "!startsWith(github.ref, 'refs/tags/')" @@ -196,6 +307,12 @@ jobs: with: build-args: | SKYEYE_VERSION: ${{ env.GITHUB_REF_NAME }} + - name: Build Vulkan image + uses: docker/build-push-action@v6 + with: + build-args: | + SKYEYE_VERSION: ${{ env.GITHUB_REF_NAME }} + target: skyeye-vulkan release: name: Upload release assets if: startsWith(github.ref, 'refs/tags/') @@ -207,6 +324,8 @@ jobs: - build-linux-amd64 - build-windows-amd64 - build-macos-arm64 + - build-linux-amd64-vulkan + - build-windows-amd64-vulkan runs-on: ubuntu-latest steps: - name: Checkout @@ -224,6 +343,8 @@ jobs: dist/skyeye-linux-amd64.tar.gz dist/skyeye-macos-arm64.tar.gz dist/skyeye-windows-amd64.zip + dist/skyeye-linux-amd64-vulkan.tar.gz + dist/skyeye-windows-amd64-vulkan.zip token: ${{ secrets.RELEASE_TOKEN }} push-images: name: Build and push container images @@ -256,3 +377,12 @@ jobs: image-name: ${{ github.repository }}-scaler target: skyeye-scaler skyeye-version: ${{ env.GITHUB_REF_NAME }} + - name: Build and push Vulkan image + uses: ./.github/actions/build-container + with: + registry-username: ${{ github.actor }} + registry-password: ${{ secrets.GITHUB_TOKEN }} + image-name: ${{ github.repository }} + target: skyeye-vulkan + tag-suffix: -vulkan + skyeye-version: ${{ env.GITHUB_REF_NAME }} diff --git a/Dockerfile b/Dockerfile index c63e626b..47177ad4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -36,3 +36,23 @@ ENTRYPOINT ["/opt/skyeye/bin/skyeye"] FROM base AS skyeye-scaler COPY --from=builder /skyeye/skyeye-scaler /opt/skyeye/bin/skyeye-scaler ENTRYPOINT ["/opt/skyeye/bin/skyeye-scaler"] + +FROM builder AS builder-vulkan +RUN apt-get update && apt-get install -y \ + libvulkan-dev \ + glslc \ + spirv-headers \ + && rm -rf /var/lib/apt/lists/* +RUN make whisper GGML_VULKAN=1 +RUN make skyeye-vulkan + +FROM base AS skyeye-vulkan +# libvulkan1: Vulkan loader. mesa-vulkan-drivers: Vulkan ICDs for AMD/Intel GPUs +# passed in with --device /dev/dri. NVIDIA users don't need it: the NVIDIA +# container toolkit injects NVIDIA's own ICD. Unused ICDs are harmless. +RUN apt-get update && apt-get install -y \ + libvulkan1 \ + mesa-vulkan-drivers \ + && rm -rf /var/lib/apt/lists/* +COPY --from=builder-vulkan /skyeye/skyeye-vulkan /opt/skyeye/bin/skyeye +ENTRYPOINT ["/opt/skyeye/bin/skyeye"] diff --git a/Makefile b/Makefile index 5a94c505..9e10f7de 100644 --- a/Makefile +++ b/Makefile @@ -78,6 +78,31 @@ EXTLDFLAGS = $(shell pkg-config $(LIBRARIES) --libs --static) LDFLAGS += -linkmode external -extldflags "$(EXTLDFLAGS) -lgomp -static" endif +# Experimental: Vulkan GPU acceleration for whisper.cpp (Windows and Linux). +# Build with: make skyeye-vulkan +ifeq ($(GGML_VULKAN),1) +ifeq ($(OS_DISTRIBUTION),macOS) +$(error GGML_VULKAN is not supported on macOS; the Metal backend is already used there) +endif +SKYEYE_BIN = skyeye-vulkan +ifeq ($(OS_DISTRIBUTION),Windows) +SKYEYE_BIN = skyeye-vulkan.exe +endif +# Suffix --version output to distinguish Vulkan builds +SKYEYE_VERSION := $(SKYEYE_VERSION)+vulkan +# Separate build directory so CPU-only and Vulkan whisper.cpp builds don't collide +WHISPER_CPP_BUILD_DIR = $(WHISPER_CPP_PATH)/build_go_vulkan +WHISPER_CPP_CMAKE_ARGS += -DGGML_VULKAN=ON +LIBRARY_PATHS := $(LIBRARY_PATHS):$(ABS_WHISPER_CPP_BUILD_DIR)/ggml/src/ggml-vulkan +ifeq ($(OS_DISTRIBUTION),Windows) +# MSYS2's vulkan-loader provides libvulkan-1.dll.a; the exe imports vulkan-1.dll +# from the GPU driver / System32 at runtime +BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan -lvulkan-1' +else +BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan -lvulkan' +endif +endif + # AMD64-specific settings (Windows and Linux) ifeq ($(GOARCH),amd64) # Pin CPU features explicitly instead of letting ggml auto-detect via @@ -103,7 +128,11 @@ install-msys2-dependencies: $(MINGW_PACKAGE_PREFIX)-toolchain \ $(MINGW_PACKAGE_PREFIX)-go \ $(MINGW_PACKAGE_PREFIX)-opus \ - $(MINGW_PACKAGE_PREFIX)-libsoxr + $(MINGW_PACKAGE_PREFIX)-libsoxr \ + $(MINGW_PACKAGE_PREFIX)-vulkan-headers \ + $(MINGW_PACKAGE_PREFIX)-vulkan-loader \ + $(MINGW_PACKAGE_PREFIX)-shaderc \ + $(MINGW_PACKAGE_PREFIX)-spirv-headers .PHONY: install-arch-linux-dependencies install-arch-linux-dependencies: @@ -113,7 +142,11 @@ install-arch-linux-dependencies: cmake \ go \ opus \ - libsoxr + libsoxr \ + vulkan-headers \ + vulkan-icd-loader \ + shaderc \ + spirv-headers .PHONY: install-debian-dependencies install-debian-dependencies: @@ -126,7 +159,10 @@ install-debian-dependencies: libopus-dev \ libopus0 \ libsoxr-dev \ - libsoxr0 + libsoxr0 \ + libvulkan-dev \ + glslc \ + spirv-headers .PHONY: install-fedora-dependencies install-fedora-dependencies: @@ -139,7 +175,11 @@ install-fedora-dependencies: opus-devel \ opus \ soxr-devel \ - sox + sox \ + vulkan-headers \ + vulkan-loader-devel \ + glslc \ + spirv-headers-devel .PHONY: install-macos-dependencies install-macos-dependencies: @@ -179,7 +219,16 @@ generate: $(BUILD_VARS) $(GO) generate $(BUILD_FLAGS) ./... $(SKYEYE_BIN): generate $(SKYEYE_SOURCES) $(LIBWHISPER_PATH) $(WHISPER_H_PATH) - $(BUILD_VARS) $(GO) build $(BUILD_FLAGS) ./cmd/skyeye/ + $(BUILD_VARS) $(GO) build $(BUILD_FLAGS) -o "$(SKYEYE_BIN)" ./cmd/skyeye/ + +# Wrapper for the experimental Vulkan build. Re-runs make with GGML_VULKAN=1, +# which renames SKYEYE_BIN to skyeye-vulkan[.exe] so the rule above builds it. +# Only defined when GGML_VULKAN is unset to avoid clashing with that rule. +ifneq ($(GGML_VULKAN),1) +.PHONY: skyeye-vulkan skyeye-vulkan.exe +skyeye-vulkan skyeye-vulkan.exe: + $(MAKE) GGML_VULKAN=1 +endif $(SKYEYE_SCALER_BIN): generate $(SKYEYE_SOURCES) $(BUILD_VARS) $(GO) build $(BUILD_FLAGS) ./cmd/skyeye-scaler/ @@ -218,7 +267,7 @@ format: .PHONY: mostlyclean mostlyclean: - rm -f "$(SKYEYE_BIN)" "$(SKYEYE_SCALER_BIN)" + rm -f "$(SKYEYE_BIN)" "$(SKYEYE_SCALER_BIN)" skyeye-vulkan skyeye-vulkan.exe find . -type f -name 'mock_*.go' -delete .PHONY: clean From 840f87146d946928be04cbe435806ebcf7709e91 Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Thu, 2 Jul 2026 18:01:51 -0600 Subject: [PATCH 3/9] Fix Vulkan import library linkage on Windows The -static linker flag limits -l searches to static libraries, so ld cannot find -lvulkan-1 (MSYS2 ships only the import library libvulkan-1.dll.a). Explicit file arguments bypass the search rules, so link the import library by full path instead. Co-Authored-By: Claude Fable 5 --- Makefile | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 9e10f7de..a9738c47 100644 --- a/Makefile +++ b/Makefile @@ -95,9 +95,10 @@ WHISPER_CPP_BUILD_DIR = $(WHISPER_CPP_PATH)/build_go_vulkan WHISPER_CPP_CMAKE_ARGS += -DGGML_VULKAN=ON LIBRARY_PATHS := $(LIBRARY_PATHS):$(ABS_WHISPER_CPP_BUILD_DIR)/ggml/src/ggml-vulkan ifeq ($(OS_DISTRIBUTION),Windows) -# MSYS2's vulkan-loader provides libvulkan-1.dll.a; the exe imports vulkan-1.dll -# from the GPU driver / System32 at runtime -BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan -lvulkan-1' +# Link MSYS2's Vulkan import library by full path: -static limits -l searches +# to static libraries, but explicit file arguments are always accepted. The exe +# imports vulkan-1.dll from the GPU driver / System32 at runtime. +BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan /ucrt64/lib/libvulkan-1.dll.a' else BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan -lvulkan' endif From e8fddacdfcb2d6ef2111cf3e17ddd7b78d982077 Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Thu, 2 Jul 2026 18:06:11 -0600 Subject: [PATCH 4/9] Ship Vulkan build binaries under the standard names Name the binary skyeye/skyeye.exe inside the Vulkan release archives to match the standard archives, so the winsw service config and documented paths work unchanged. Co-Authored-By: Claude Fable 5 --- .github/workflows/skyeye.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/skyeye.yaml b/.github/workflows/skyeye.yaml index 7954ea71..12063a50 100644 --- a/.github/workflows/skyeye.yaml +++ b/.github/workflows/skyeye.yaml @@ -206,9 +206,9 @@ jobs: shell: bash run: | mkdir -p dist/skyeye-linux-amd64-vulkan/docs/ - cp skyeye-vulkan dist/skyeye-linux-amd64-vulkan/skyeye-vulkan + cp skyeye-vulkan dist/skyeye-linux-amd64-vulkan/skyeye cp skyeye-scaler dist/skyeye-linux-amd64-vulkan/skyeye-scaler - chmod +x dist/skyeye-linux-amd64-vulkan/skyeye-vulkan + chmod +x dist/skyeye-linux-amd64-vulkan/skyeye chmod +x dist/skyeye-linux-amd64-vulkan/skyeye-scaler cp README.md dist/skyeye-linux-amd64-vulkan/README.md cp LICENSE dist/skyeye-linux-amd64-vulkan/LICENSE @@ -272,7 +272,7 @@ jobs: shell: msys2 {0} run: | mkdir -p dist/skyeye-windows-amd64-vulkan/docs/ - cp skyeye-vulkan.exe dist/skyeye-windows-amd64-vulkan/skyeye-vulkan.exe + cp skyeye-vulkan.exe dist/skyeye-windows-amd64-vulkan/skyeye.exe cp skyeye-scaler.exe dist/skyeye-windows-amd64-vulkan/skyeye-scaler.exe curl -fsL https://github.com/winsw/winsw/releases/download/v2.12.0/WinSW-x64.exe -o winsw.exe cp README.md dist/skyeye-windows-amd64-vulkan/README.md @@ -280,7 +280,7 @@ jobs: cp config.yaml dist/skyeye-windows-amd64-vulkan/config.yaml cp docs/*.md dist/skyeye-windows-amd64-vulkan/docs/ cp winsw.exe dist/skyeye-windows-amd64-vulkan/skyeye-service.exe - sed 's/^executable: skyeye.exe$/executable: skyeye-vulkan.exe/' init/winsw/skyeye-service.yml > dist/skyeye-windows-amd64-vulkan/skyeye-service.yml + cp init/winsw/skyeye-service.yml dist/skyeye-windows-amd64-vulkan/skyeye-service.yml cp winsw.exe dist/skyeye-windows-amd64-vulkan/skyeye-scaler-service.exe cp init/winsw/skyeye-scaler-service.yml dist/skyeye-windows-amd64-vulkan/skyeye-scaler-service.yml cd dist From 2c59bb107cc636577a0119a3f18fd032632a9f23 Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Thu, 2 Jul 2026 18:06:11 -0600 Subject: [PATCH 5/9] Stub TODOs for Vulkan build documentation Co-Authored-By: Claude Fable 5 --- README.md | 5 +++++ docs/ADMIN.md | 14 ++++++++++++++ docs/CONTRIBUTING.md | 7 +++++++ 3 files changed, 26 insertions(+) diff --git a/README.md b/README.md index 831d6fa3..1177285a 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,9 @@ On Windows and Linux, SkyEye can be downloaded from [GitHub Releases](https://gi On Linux, SkyEye is also available as a container: `ghcr.io/dharmab/skyeye:latest`. Note this container won't work on Windows or macOS. + + + On macOS, SkyEye can be installed using [Homebrew](https://brew.sh/): ```bash @@ -82,6 +85,8 @@ Generally, local speech recognition requires one of: * Any Apple Silicon Mac, such as a Mac Mini or MacBook Air/Pro. * A Windows or Linux computer with a fast quad-core CPU from the last 2-3 CPU generations. + + Cloud speech recognition requirements are quite modest. See the [Hardware section of the admin guide](docs/ADMIN.md#hardware) for more details, including a table of benchmarks. diff --git a/docs/ADMIN.md b/docs/ADMIN.md index 5fd9bc70..c8a598d8 100644 --- a/docs/ADMIN.md +++ b/docs/ADMIN.md @@ -38,6 +38,9 @@ Local speech recognition is more performance intensive, usually requiring two co - If you have very powerful hardware, 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. + + + On the other hand, cloud speech recognition has a separate set of tradeoffs: - Less technical users will likely prefer cloud speech recognition, since it requires only one computer instead of two networked together. @@ -91,6 +94,9 @@ flowchart TD 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. + + + ## Hardware ### Cloud Speech Recognition @@ -103,6 +109,9 @@ When using cloud speech recognition, SkyEye has relatively modest requirements: When running on Windows and Linux, local speech recognition runs on the CPU. In this configuration, SkyEye requires a fast, multithreaded, **dedicated** CPU, 3GB of RAM, 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). + + + CPU Series|AVX2 Added In -|- Intel Core|Haswell (2013) @@ -409,6 +418,9 @@ sudo systemctl restart skyeye > Note: The container image is only supported on Linux; it will not work correctly on macOS or Windows because of CPU latency requirements. + + + ### Manual Installation with Native Binary You can install SkyEye on a Linux server by manually downloading a release and installing it. The instructions below should be compatible with Debian, Ubuntu, Fedora and Arch Linux, and adaptable to other distributions. @@ -427,6 +439,8 @@ sudo dnf install opus sox sudo pacman -Syu opus soxr ``` + + Install SkyEye: ```sh diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8b380906..aa8e69ab 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -29,6 +29,8 @@ Run `make install-msys2-dependencies` to install the C++ and Go compilers as wel Run `make` to build `skyeye.exe`. + + ### Linux Clone this Git repository somewhere, and navigate to it in your favorite terminal. @@ -48,6 +50,8 @@ Run `make` to build `skyeye`. Anyhwere this guide mentions `skyeye.exe`, remove `.exe` - just run `skyeye`. + + ### macOS Install [Homebrew](https://brew.sh/). @@ -178,6 +182,9 @@ SkyEye's performance bottleneck on most systems is speech recognition. A small b SKYEYE_WHISPER_MODEL=$(pwd)/path/to/whisper-model.bin make benchmark-whisper ``` + + + ## Lint You can run `make lint` and `make vet` to run some linters to catch some common mistakes, like forgetting to check an error. These also run on every submitted PR as a required check. From f218939b9c27903b21f1f8708b85b8da31ccca90 Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Thu, 2 Jul 2026 18:13:17 -0600 Subject: [PATCH 6/9] Convert Vulkan import library path for the native linker ld.exe is a native Windows program and cannot resolve MSYS2 virtual paths like /ucrt64. Convert the import library path to a Windows path with cygpath. (MSYS2 auto-converts environment variables that look like path lists, such as LIBRARY_PATH, but CGO_LDFLAGS contains flags and is passed through unconverted.) Co-Authored-By: Claude Fable 5 --- Makefile | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index a9738c47..2af69a47 100644 --- a/Makefile +++ b/Makefile @@ -96,9 +96,11 @@ WHISPER_CPP_CMAKE_ARGS += -DGGML_VULKAN=ON LIBRARY_PATHS := $(LIBRARY_PATHS):$(ABS_WHISPER_CPP_BUILD_DIR)/ggml/src/ggml-vulkan ifeq ($(OS_DISTRIBUTION),Windows) # Link MSYS2's Vulkan import library by full path: -static limits -l searches -# to static libraries, but explicit file arguments are always accepted. The exe -# imports vulkan-1.dll from the GPU driver / System32 at runtime. -BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan /ucrt64/lib/libvulkan-1.dll.a' +# to static libraries, but explicit file arguments are always accepted. The +# path must be converted with cygpath because the linker is a native Windows +# program that doesn't understand MSYS2 paths like /ucrt64. The exe imports +# vulkan-1.dll from the GPU driver / System32 at runtime. +BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan $(shell cygpath -m /ucrt64/lib/libvulkan-1.dll.a)' else BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan -lvulkan' endif From dde77393f7f7792e257b7a1bc5a5dd5fac54b049 Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Thu, 2 Jul 2026 18:23:58 -0600 Subject: [PATCH 7/9] Resolve libstdc++ symbols for ggml-vulkan on Windows CGO_LDFLAGS is appended after the Go binding's link flags, so -lggml-vulkan lands after -lstdc++. With -static the linker does not re-scan libstdc++.a for symbols only libggml-vulkan.a needs (threads, stringstreams). Repeat -lstdc++ at the end of the link order. Co-Authored-By: Claude Fable 5 --- Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 2af69a47..c3052a0b 100644 --- a/Makefile +++ b/Makefile @@ -100,7 +100,9 @@ ifeq ($(OS_DISTRIBUTION),Windows) # path must be converted with cygpath because the linker is a native Windows # program that doesn't understand MSYS2 paths like /ucrt64. The exe imports # vulkan-1.dll from the GPU driver / System32 at runtime. -BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan $(shell cygpath -m /ucrt64/lib/libvulkan-1.dll.a)' +# Repeat -lstdc++ because the static libstdc++.a earlier in the link order is +# not re-scanned for symbols that only libggml-vulkan.a needs. +BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan $(shell cygpath -m /ucrt64/lib/libvulkan-1.dll.a) -lstdc++' else BUILD_VARS += CGO_LDFLAGS='-lggml-vulkan -lvulkan' endif From a96527d73c5fbb1fb59edbabec6f1dd2e96150e2 Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Fri, 10 Jul 2026 01:52:23 -0600 Subject: [PATCH 8/9] Add per-OS deployment guides and retire redundant admin/quickstart docs Stub out standalone, complete deployment guides for each OS and speech recognition method (Windows/Linux CPU, GPU, and cloud API; macOS GPU) ahead of the Vulkan GPU release, and fold the old Windows/macOS/Hetzner/Vultr quickstarts and ADMIN.md's Installation section into them so there's a single source of truth per deployment scenario. --- README.md | 19 +- docs/ADMIN.md | 436 ++---------------- docs/QUICKSTART-MACOS.md | 91 ---- .../cloud-providers/hetzner.md} | 16 +- .../cloud-providers/vultr.md} | 16 +- docs/deployment/linux/api.md | 228 +++++++++ docs/deployment/linux/cpu.md | 243 ++++++++++ docs/deployment/linux/gpu.md | 294 ++++++++++++ docs/deployment/macos/gpu.md | 164 +++++++ .../windows/api.md} | 55 ++- docs/deployment/windows/cpu.md | 134 ++++++ docs/deployment/windows/gpu.md | 124 +++++ 12 files changed, 1299 insertions(+), 521 deletions(-) delete mode 100644 docs/QUICKSTART-MACOS.md rename docs/{QUICKSTART-HETZNER.md => deployment/cloud-providers/hetzner.md} (85%) rename docs/{QUICKSTART-VULTR.md => deployment/cloud-providers/vultr.md} (79%) create mode 100644 docs/deployment/linux/api.md create mode 100644 docs/deployment/linux/cpu.md create mode 100644 docs/deployment/linux/gpu.md create mode 100644 docs/deployment/macos/gpu.md rename docs/{QUICKSTART-WINDOWS.md => deployment/windows/api.md} (61%) create mode 100644 docs/deployment/windows/cpu.md create mode 100644 docs/deployment/windows/gpu.md diff --git a/README.md b/README.md index 1177285a..b519b508 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ SkyEye is a substantial improvement over the DCS AWACS: 4. SkyEye supports a larger number of commands, including [PICTURE](docs/PLAYER.md#picture), [BOGEY DOPE](docs/PLAYER.md#bogey-dope), [DECLARE](docs/PLAYER.md#declare), [SNAPLOCK](docs/PLAYER.md#snaplock), [SPIKED](docs/PLAYER.md#spikedstrobe), [STROBE](docs/PLAYER.md#spikedstrobe), [ALPHA CHECK](docs/PLAYER.md#alpha-check) and [VECTOR](docs/PLAYER.md#vector). 5. SkyEye intelligently monitors the battlespace, providing automatic [THREAT](docs/PLAYER.md#threat), [MERGED](docs/PLAYER.md#merged) and [FADED](docs/PLAYER.md#faded) callouts to improve situational awareness. -SkyEye uses Speech-To-Text and Text-To-Speech technology which can run locally on the same computer as SkyEye. No cloud APIs are required, although cloud APIs are optionally supported. It works with any DCS mission, singleplayer or multiplayer. No special scripting or mission editor setup is required. You can run it for less than a nickel per hour on a cloud server, or run it on a computer in your home running Windows, Linux or macOS. +SkyEye uses Speech-To-Text and Text-To-Speech technology which can run locally on the same computer as SkyEye. No cloud APIs are required, although cloud APIs are optionally supported. It works with any DCS mission, singleplayer or multiplayer. No special scripting or mission editor setup is required. You can run it on a cloud server, or run it on a computer in your home running Windows, Linux or macOS. SkyEye is production ready software. It is used by a few public servers and many private squadrons. Based on download statistics, I estimate over 100 communities are using SkyEye, such as: @@ -53,10 +53,7 @@ See https://limakilo.net for server details. On Windows and Linux, SkyEye can be downloaded from [GitHub Releases](https://github.com/dharmab/skyeye/releases). -On Linux, SkyEye is also available as a container: `ghcr.io/dharmab/skyeye:latest`. Note this container won't work on Windows or macOS. - - - +On Linux, SkyEye is also available as a container: `ghcr.io/dharmab/skyeye:latest` (CPU version) and `ghcr.io/dharmab/skyeye/latest-vulkan` (GPU version). On macOS, SkyEye can be installed using [Homebrew](https://brew.sh/): @@ -70,23 +67,21 @@ See the [admin guide](docs/ADMIN.md) for detailed instructions on installing, co ### What do I need to run SkyEye? -There are a few different ways to run SkyEye. In order from best to least recommended: +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. -2. On your DCS server, 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. -3. 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 voices without any credit card required. This also works with rented cloud servers, some of whom accept other payment methods compared to OpenAI. - -Running SkyEye on the same computer as DCS, using local speech recognition, is not recommended and no support can be provided for that configuration. Use a separate computer or OpenAI's API instead. +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 DCS server, 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 voices without any credit card required. This also works with rented cloud servers, some of whom accept other payment methods compared to OpenAI. ### What kind of hardware does it require? Generally, local speech recognition requires one of: * Any Apple Silicon Mac, such as a Mac Mini or MacBook Air/Pro. +* A Windows or Linux computer with a GPU. * A Windows or Linux computer with a fast quad-core CPU from the last 2-3 CPU generations. - - Cloud speech recognition requirements are quite modest. See the [Hardware section of the admin guide](docs/ADMIN.md#hardware) for more details, including a table of benchmarks. diff --git a/docs/ADMIN.md b/docs/ADMIN.md index c8a598d8..2843b1bf 100644 --- a/docs/ADMIN.md +++ b/docs/ADMIN.md @@ -2,12 +2,13 @@ This is a technical article on how to deploy SkyEye, targeted at multiplayer server administrators. It assumes you are a semi-technical user who is comfortable administering a Linux or Windows server. -For an easier step-by-step guide, see one of the quickstart guides: +For a step-by-step guide, see one of the deployment guides. -- [Windows](QUICKSTART-WINDOWS.md) -- [macOS](QUICKSTART-MACOS.md) -- [Linux on Hetzner Cloud](QUICKSTART-HETZNER.md) -- [Linux on Vultr](QUICKSTART-VULTR.md) +|Operating System|Voice Recognition on CPU|Voice Recognition on GPU|Voice Recognition via Cloud API| +|-|-|-|-| +|macOS|N/A|[guide](deployment/macos/gpu.md)|N/A| +|Windows|[guide](deployment/windows/cpu.md)|[guide](deployment/windows/gpu.md)|[guide](deployment/windows/api.md)| +|Linux|[guide](deployment/linux/cpu.md)|[guide](deployment/linux/gpu.md)|[guide](deployment/linux/api.md)| # Getting Help @@ -24,35 +25,36 @@ I do not respond to direct messages on social media or the Eagle Dynamics forums - If using any older version of Tacview, SkyEye does not have access to the terrain height. It instead falls back to a 50 knot speed filter. Unfortunately, this excludes hostile helicopters that are moving slowly or hovering. - By default, SkyEye uses a simple spherical earth model for calculating distance and bearings. This is accurate enough near the equator, but becomes increasingly inaccurate at extreme latitudes, such as on the Kola and South Atlantic maps. Workaround: See the `x-detect-terrain` experimental config option. This is not enabled by default because it uses a "best guess" method to detect the current map, which may actually reduce accuracy in certain cases, such as when playing on a map that was released after the current version of SkyEye. - SkyEye does not work when (1) running on macOS 15 or newer AND (2) as a background service AND (3) connecting to a SRS, Tacview, or DCS-gRPC server running within the same LAN. [Bug tracked here, multiple workarounds available](https://github.com/dharmab/skyeye/issues/566). +- The Vulkan build of SkyEye has varying quality and performance on different OSes, GPU hardware, and GPU drivers. Because I have very limited access to GPU hardware, I am unable to provide troubleshooting/debugging for many of these issues. - See also [this section in the player guide](PLAYER.md#a-word-of-warning) about the bot's limitations. ## System Architecture -SkyEye can be deployed in two architectures: Local speech recognition and cloud-hosted speech recognition. Neither is universally better than the other; they each suit different use cases. +SkyEye can be deployed in three architectures: -Local speech recognition is more performance intensive, usually requiring two computers with quite good CPUs (one to run DCS and one to run SkyEye). However, it has a number of advantages: +- 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 +- 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 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 very powerful hardware, self-hosting can be lower-latency and/or cheaper than cloud speech recognition. +- 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. - - - On the other hand, cloud speech recognition has a separate set of tradeoffs: -- Less technical users will likely prefer cloud speech recognition, since it requires only one computer instead of two networked together. - Cloud speech recognition has a variable cost; this can be an advantage or disadvantage. In general, light to moderate usage is less expensive when using cloud speech recognition compared to using local speech recognition on a rented server. However, this can still be more expensive compared to self-hosted local speech recognition, or if you have a particularly chatty group of players. On public servers, there is a potential for abuse if a particular player spams the channel and racks up the cloud services bill. And of course, the company providing the service may choose to change their prices in the future. - Cloud speech recognition shares audio recordings with a third party, which may be a privacy concern. - Cloud speech recognition depends on an externally hosted API. It could break temporarily or permanently if the external API has an outage, makes a breaking change, or the company decides to stop providing the service to you. - Cloud speech recognition has good performance; while local speech recognition can be faster, in practice most players will be satisfied with the performance of cloud speech recognition. - When using cloud speech recognition, you have a **legal obligation** to disclose to your players that they are interacting with AI. (ref: [OpenAI Usage Policies](https://openai.com/policies/usage-policies/)). Of course, you should be doing this anyway! I recommend adding a disclosure to your mission briefing, and enabling "Show Transmitter Name" in your SRS server. -### Deployment with Local Speech Recognition +### Deployment with Local Speech Recognition on CPU -When using local speech recognition, SkyEye works best when run on a dedicated system, separate from the DCS World and SRS servers. +When using local speech recognition on CPU, SkyEye works best when run on a dedicated system, separate from the DCS World and SRS servers. _Recommended Architecture: DCS, TacView and SRS on one Windows server. SkyEye on another Linux or macOS server._ @@ -61,9 +63,9 @@ flowchart LR dcs[Windows
DCS World Server
TacView Exporter
SRS Server] <--> skyeye[Linux/macOS
SkyEye] ``` -#### Caution: Running SkyEye and DCS World on One Computer +#### Caution: Running SkyEye with Local Speech Recognition on CPU along with DCS World on One Computer -**Running SkyEye with local speech recognition 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 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.) **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**. 😾 @@ -79,7 +81,14 @@ If you have read all of the above, and are still serious about, attempting this, -Running SkyEye with cloud speech recognition on the same computer as DCS World _is_ supported. 🤗 +### Deployment with Local Speech Recognition on GPU + +When using local speech recognition on GPU, you may deploy SkyEye on the same computer as DCS World and the SRS Server. + +```mermaid +flowchart TD + gpu[GPU Driver] <--> dcs[Windows
DCS World Server
TacView Exporter
SRS Server
SkyEye] +``` ### Deployment with Cloud Speech Recognition @@ -92,25 +101,15 @@ 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. - - - +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. ## Hardware -### Cloud Speech Recognition - -When using cloud speech recognition, SkyEye has relatively modest requirements: Any decent multithreaded CPU, around 1.5GB of RAM, and about 2GB of disk space. - -### Local Speech Recognition - #### Windows and Linux -When running on Windows and Linux, local speech recognition runs on the CPU. In this configuration, SkyEye requires a fast, multithreaded, **dedicated** CPU, 3GB of RAM, 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). - - +##### CPU +When running on Windows or Linux with local speech recognition on CPU, SkyEye requires a fast, multithreaded, **dedicated** CPU, 3GB of RAM, 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). CPU Series|AVX2 Added In -|- @@ -122,6 +121,10 @@ SkyEye currently only officially supports the AMD64 (x86-64) CPU architecure on 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). + #### macOS When running on macOS, local speech recognition uses the GPU/Neural Engine. Therefore, SkyEye does not use much CPU and should run very well on any Apple Silicon Mac. SkyEye requires around 3GB of RAM and about 2GB of disk space. @@ -164,6 +167,10 @@ Examples of suitable servers include: 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. +### Cloud Speech Recognition + +When using cloud speech recognition, SkyEye has relatively modest requirements: Any decent multithreaded CPU, around 1.5GB of RAM, and about 2GB of disk space. + ## Configuration SkyEye can be configured using a YAML or JSON configuration file, environment variables and/or command-line flags. The order of priority is: @@ -236,55 +243,7 @@ You can select between these voices using the `voice` configuration option. If y ### macOS -SkyEye uses AI generated voices built into macOS. - -By default, the "Samantha" voice is used. This is the version of Siri's voice from the iPhone 4s, iPhone 5 and iPhone 6, based on [Susan Bennett](https://susancbennett.com/). - -It is also possible to use one of the newer Siri voices. **I strongly recommend enabling one of the newer voices.**, because they provide excellent quality, nearly indistinguishable from a human voice. - -Not all Siri voices work equally well; many struggle to pronounce aviation terminology. I've manually validated a voice for each version of macOS: - -#### macOS 26 Tahoe - -On macOS 26 Tahoe, the best voice is **Siri Voice 2**. - -1. Open System Settings -2. Click on "Accessibility" -3. Click on "Siri" -4. If the system language is not English, set the system speech language to English -5. Next to "System Voice", click the "i" button -6. In the list of languages, make sure "English" is selected -7. Click on "Voice" -8. Scroll down to "Siri". -9. Download Siri Voice 2. -10. Click "Done" -11. Set the system voice to Siri Voice 2. - -#### macOS 15 Tahoe - -On macOS 15 Sequoia, the best voice is **Siri Voice 5**. - -1. Open System Settings -2. Click on "Accessibility" -3. Click on "Spoken Content" -4. If the system language is not English, set the system speech language to English -5. Next to "System Voice", click the "i" button -6. In the list of languages, make sure "English" is selected -7. Click on "Voice" -8. Scroll down to "Siri". -9. Download the English (United States) Siri Voice 5. -10. Click "Done" -11. Set the system voice to Siri Voice 5. - -#### Testing the System Voice - -To test your change, open Terminal and run this command: - -```sh -say "Hello! This should be read in the voice you chose." -``` - -Finally, to use the selected voice instead of Samantha, set SkyEye's `use-system-voice` configuration option to `true`. +SkyEye uses AI generated voices built into macOS. See [the macOS deployment guide](deployment/macos/gpu.md#configure-system-voice-optional-strongly-recommended) for recommended voice configuration. ## Networking @@ -380,321 +339,6 @@ This architecture is marked experimental because I don't test this configuration Lastly, I cannot predict how these locks work in combination with CPU Core Affinity/Process Lasso. I suspect results will vary depending on the CPU's core and cache layout. To repeat and emphasize: **Core Affinity/Process Lasso configurations have no guarantees of performance and are at your own risk.** -# Installation - -You will need to install the Tacview Exporter in your DCS server. Use the official TacView client to verify that you can connect to the Real-Time Telemetry address and port. (Real-Time Telemetry is a paid feature of the Tacview client, but is available in the free trial if you don't have a paid license.) - -You will need to enable External AWACS Mode (EAM) in your SRS server settings and configure an EAM password for the coalition(s) you want SkyEye to serve (i.e. configure the blue password for SkyEye to provide GCI to blue players). - -## Linux - -_Note: I am planning to improve the installation on Linux by creating a method to install and run SkyEye using [podman-systemd](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)._ - -### Automated Installation with Container Image - -A sample [cloud-init](https://cloudinit.readthedocs.io/en/latest/) config is provided in the `/init/cloud-init` directory in the Git repository ([direct link](https://raw.githubusercontent.com/dharmab/skyeye/refs/heads/main/init/cloud-init/cloud-config.yaml)). This automates the installation and startup on a new cloud server instance, using the container `ghcr.io/dharmab/skyeye`. It should be compatible with most Linux distributions including Debian, Ubuntu, Fedora, Arch Linux and OpenSUSE. - -See documentation on cloud-init: - -- [Official documentation](https://cloudinit.readthedocs.io/en/latest/index.html) -- [AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html#user-data-cloud-init) -- Hetzner: [GUI](https://docs.hetzner.com/cloud/servers/getting-started/creating-a-server), [API](https://docs.hetzner.cloud/#servers-create-a-server) -- [Linode](https://techdocs.akamai.com/cloud-computing/docs/add-user-data-when-deploying-a-compute-instance) -- [Vultr](https://docs.vultr.com/how-to-deploy-a-vultr-server-with-cloudinit-userdata) - -To customize this cloud-init file: - -1. Edit the `content` field of the `/etc/skyeye/config.yaml` file with your desired configuration. -1. If you want to pin to a specific version of SkyEye, replace `ghcr.io/dharmab/skyeye:latest` with the desired version. I strongly recommend you pin the version in case of any breaking changes in the future. - -If you wish to change the version of SkyEye in the future: - -```sh -# Edit the image.env file to change the image version -sudoedit /etc/skyeye/image.env -# Restart SkyEye -sudo systemctl restart skyeye -``` - -> Note: The container image is only supported on Linux; it will not work correctly on macOS or Windows because of CPU latency requirements. - - - - -### Manual Installation with Native Binary - -You can install SkyEye on a Linux server by manually downloading a release and installing it. The instructions below should be compatible with Debian, Ubuntu, Fedora and Arch Linux, and adaptable to other distributions. - -Install shared libraries for [Opus](https://opus-codec.org/) and [SoX Resampler](https://sourceforge.net/p/soxr/wiki/Home/): - -```sh -# Install shared libraries on Debian/Ubuntu -sudo apt-get update -sudo apt-get install libopus0 libsoxr0 - -# Install shared libraries on Fedora -sudo dnf install opus sox - -# Install shared libraries on Arch Linux -sudo pacman -Syu opus soxr -``` - - - -Install SkyEye: - -```sh -# Create a user named "skyeye" to run SkyEye -sudo useradd -G users skyeye - -# Download the latest version of SkyEye and install to /opt/skyeye -curl -sL https://github.com/dharmab/skyeye/releases/download/latest/skyeye-linux-amd64.tar.gz -o /tmp/skyeye-linux-amd64.tar.gz -tar -xzf /tmp/skyeye-linux-amd64.tar.gz -C /tmp/ -sudo mkdir -p /opt/skyeye/bin -sudo mv /tmp/skyeye-linux-amd64/skyeye /opt/skyeye/bin/skyeye -sudo chmod +x /opt/skyeye/bin/skyeye - -# Download a Whisper speech recognition model and install it to /opt/skyeye/models -sudo mkdir -p /opt/skyeye/models -curl -sL https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin -o /opt/skyeye/models/ggml-small.en.bin - -# Grant the "skyeye" user ownership of the SkyEye installation directory -sudo chown -R skyeye:users /opt/skyeye - -# Create a SkyEye config directory and copy the sample config file there. -sudo mkdir -p /etc/skyeye -sudo mv /tmp/skyeye-linux-amd64/config.yaml /etc/skyeye/config.yaml - -# Grant the "skyeye" user ownership of the SkyEye config directory -sudo chmod 600 /etc/skyeye/config.yaml -sudo chown -R skyeye:users /etc/skyeye - -# Clean up the downloaded files -rm -rf /tmp/skyeye-linux-amd64.tar.gz /tmp/skyeye-linux-amd64 -``` - -Edit the config file as required: - -```sh -# Edit the configuration file using the text editor specified in the EDITOR environment variable -sudoedit /etc/skyeye/config.yaml -``` - -If you are a Linux noob, you can use [micro](https://micro-editor.github.io/) for a friendly experience: - -```sh -# Install micro on Ubuntu -sudo apt-get install micro -# Install micro on Arch Linux -sudo pacman -Syu micro - -# Edit the configuration file using micro -EDITOR=micro sudoedit /etc/skyeye/config.yaml -``` - -Save this systemd unit to `/etc/systemd/system/skyeye.service`: - -```ini -[Unit] -Description=SkyEye GCI Bot -After=network-online.target - -[Service] -Type=simple -User=skyeye -WorkingDirectory=/opt/skyeye -ExecStart=/opt/skyeye/bin/skyeye -Restart=always -RestartSec=60 - -[Install] -WantedBy=multi-user.target -``` - -To start SkyEye, and enable it to start on boot: - -```sh -# Load changes to skyeye.service file -sudo systemctl daemon-reload -# Configure SkyEye to start on boot, and also start it immediately -sudo systemctl enable skyeye.service --now -``` - -If you wish to change the version of SkyEye in the future: - -```sh -# Remove any old downloads -rm -rf /tmp/skyeye-linux-amd64.tar.gz /tmp/skyeye-linux-amd64 -# Set new_version to whichever version you want to change to -new_version=v1.1.4 -# Download the new version and replace the SkyEye executable -curl -sL https://github.com/dharmab/skyeye/releases/dowload/$new_version/skyeye-linux-amd64.tar.gz -o /tmp/skyeye-linux-amd64.tar.gz -tar -xzf /tmp/skyeye-linux-amd64.tar.gz -C /tmp/ -sudo mv /tmp/skyeye-linux-amd64/skyeye /opt/skyeye/bin/skyeye -sudo chown skyeye:users /opt/skyeye/bin/skyeye -# Restart SkyEye -sudo systemctl start skyeye.service -``` - -### Service Management - -Use `systemctl` to manage SkyEye: - -```sh -# Load changes to skyeye.service file -sudo systemctl daemon-reload - -# Start the bot -sudo systemctl start skyeye.service - -# Stop the bot -sudo systemctl stop skyeye.service - -# Autostart the bot when the system boots -sudo systemctl enable skyeye.service - -# Disable autostart on boot -sudo systemctl disable skyeye.service -``` - -View the logs with `journalctl`: - -```sh -# Stream the logs -journalctl -fu skyeye - -# Page through recent logs -journalctl -u skyeye - -# Save recent logs to a file (handy for bug reports) -journalctl -u skyeye > skyeye.log -``` - -## macOS - -### Installation - -Install [Homebrew](https://brew.sh). - -Install SkyEye. The installation includes the `ggml-small.en.bin` model. - -```sh -brew tap dharmab/skyeye -brew trust dharmab/skyeye/skyeye -brew install dharmab/skyeye/skyeye -``` - -Configure SkyEye by editing the config file at `$(brew --prefix)/etc/skyeye/config.yaml` as required. - -```sh -$EDITOR "$(brew --prefix)/etc/skyeye/config.yaml" -``` - -You'll likely want to configure local speech recognition, since on macOS it is as fast or faster than cloud speech recognition: - -```yaml -recognizer: openai-whisper-local -whisper-model: /opt/homebrew/share/skyeye/models/ggml-small.en.bin -``` - -It also also strongly recommended to configure the system voice as documented in [Speech Synthesis section](#speech-synthesis), and configure SkyEye to use the system voice: - -```yaml -use-system-voice: true -``` +# Next Steps -To start SkyEye, and automatically start it on login: - -```sh -brew services start dharmab/skyeye/skyeye -``` - -If you wish to upgrade to the latest version of SkyEye: - -```sh -brew update -brew upgrade dharmab/skyeye/skyeye -brew services restart dharmab/skyeye/skyeye -``` - -### Service Management - -Use `brew services` to manage SkyEye: - -```sh -# Start the bot without enabling autostart -brew services run dharmab/skyeye/skyeye - -# Stop the bot without disabling autostart -brew services kill dharmab/skyeye/skyeye - -# Start the bot and enable autostart on login -brew services start dharmab/skyeye/skyeye - -# Stop the bot and disable autostart on login -brew services stop dharmab/skyeye/skyeye - -# Restart SkyEye -brew services restart dharmab/skyeye/skyeye - -# Uninstall SkyEye -brew uninstall dharmab/skyeye/skyeye -``` - -Logs will be saved to `$(brew --prefix)/var/log/skyeye.log`: - -```sh -# Follow logs -tail -f "$(brew --prefix)/var/log/skyeye.log" - -# Examine the full log -less "$(brew --prefix)/var/log/skyeye.log" -``` - -## Windows - -Download the SkyEye release ZIP from the [releases page](https://github.com/dharmab/skyeye/releases) and extract it. - -Edit `config.yaml` to configure SkyEye as desired. Note that any provided value of `whisper-model` here is ignored because it is overridden in `skyeye-service.yml`. If you wish to change the whisper.cpp model, edit `skyeye-service.yml`. - -If you want SkyEye to automatically start on boot, edit `skyeye-service.yml` and change `startmode` to "Automatic". - -Use the bundled `skyeye-service.exe` to install and start SkyEye: - -```batch -:: Install SkyEye -./skyeye-service.exe install - -:: Start SkyEye -./skyeye-service.exe start - -:: Check if SkyEye is running -./skyeye-service.exe status - -:: Stop SkyEye -./skyeye-service.exe stopwait - -:: Restart SkyEye -./skyeye-service.exe restart - -:: Uninstall SkyEye -./skyeye-service.exe uninstall -``` - -Refer to the [WinSW documentation](https://github.com/winsw/winsw/tree/v2.12.0) for more information (`skyeye-service.exe` is a renamed `winsw.exe`). - -Logs will be saved in a `skyeye-service.err.log` file in the same directory as `skyeye-service.yml`. - -If you want to change the version of SkyEye in the future: - -```batch -:: Stop and Uninstall SkyEye -./skyeye-service.exe stopwait skyeye-service.yml -./skyeye-service.exe uninstall skyeye-service.yml - -:: Download a newer version of SkyEye and replace both skyeye.exe and skyeye-service.yml - -:: Install and Start the new version of SkyEye -./skyeye-service.exe install skyeye-service.yml -./skyeye-service.exe start skyeye-service.yml -``` +Once you've decided on an architecture, follow the [deployment guide](#deployment) for your operating system and speech recognition method to install and configure SkyEye. diff --git a/docs/QUICKSTART-MACOS.md b/docs/QUICKSTART-MACOS.md deleted file mode 100644 index bdca65f0..00000000 --- a/docs/QUICKSTART-MACOS.md +++ /dev/null @@ -1,91 +0,0 @@ -# Simple Quickstart on macOS - -This guide is a step-by-step on how to run SkyEye on macOS, using local speech recognition. - -## Getting Help - -See [the admin guide](ADMIN.md#getting-help) for how to get help if you have a problem. - -## Set Up DCS, TacView, and SRS - -Install DCS on a Windows computer (either the client for singleplayer/hosted multiplayer use, or a dedicated server for multiplayer use). - -Install the TacView Exporter on the DCS machine. Within DCS, go to OPTIONS → SPECIAL → Tacview and enable Real-Time Telemetry. (See https://www.tacview.net/documentation/dcs/en/) - -Install SRS on a Windows computer. Start and configure the SRS Server. Ensure EAM mode is enabled and an EAM password is set. - -Make sure DCS is running an unpaused mission with both friendly and hostile air units so you can do some tests. - -## Configure System Voice (Optional, Strongly Recommended) - -For the best possible AI voice, set your macOS system voice to Siri Voice 2 (macOS Tahoe) or Siri Voice 5 (macOS Sequoia). Step by step instructions are in the admin guide [here](ADMIN.md#macos-1). - -## Install Homebrew - -Follow the instructions at https://brew.sh to install Homebrew. - -## Install SkyEye - -Run the following commands in a terminal: - -```sh -brew tap skyeye/skyeye -brew trust dharmab/skyeye/skyeye -brew install dharmab/skyeye/skyeye -``` - -Open `$(brew --prefix)/etc/skyeye/config.yaml` with a text editor. It's probably at `/opt/homebrew/etc/skyeye/config.yaml`. (If you don't have a text editor, download [Visual Studio Code](https://code.visualstudio.com). I don't recommend trying to edit YAML with TextEdit because it's easy to make an indentation error.) Edit the file as required and save your changes. - -A minimal sample config file might look like: - -```yaml -callsign: Focus -recognizer: openai-whiser-local -whisper-model: /opt/homebrew/share/skyeye/models/ggml-small.en.bin -telemetry-address: tacview.example.com:42674 -telemetry-password: yourtacviewpasswordhere -srs-server-address: srs.example.com:5002 -srs-eam-password: yoursrspasswordhere -use-system-voice: true # Set to false if you didn't configure Siri Voice 5 above -``` - -Run this command to start SkyEye: - -```sh -brew services run dharmab/skyeye/skyeye -``` - -Confirm SkyEye is running: - -```sh -brew services info dharmab/skyeye/skyeye -``` - -The output should indicate that SkyEye is running. - -Also, take a look at the logs: - -```sh -tail -f "$(brew --prefix)/var/log/skyeye.log" -``` - -If you see a lot of repeated WARN or ERROR lines that don't go away, something may be wrong. - -If you see an error message containing `connect: no route to host`, see [this issue](https://github.com/dharmab/skyeye/issues/566) for a possible cause and workarounds. - -On a Windows computer, connect to your DCS and SRS servers. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](PLAYER.md).) - -To stop SkyEye, run this command: - -```sh -brew services kill dharmab/skyeye/skyeye -``` - -For instructions on : - -- Uninstalling SkyEye -- Upgrading to a newer version of SkyEye -- Automatically starting SkyEye on login -- Using voices other than Siri Voice 5 - -See [the full admin guide](ADMIN.md). diff --git a/docs/QUICKSTART-HETZNER.md b/docs/deployment/cloud-providers/hetzner.md similarity index 85% rename from docs/QUICKSTART-HETZNER.md rename to docs/deployment/cloud-providers/hetzner.md index c874513f..82519a2e 100644 --- a/docs/QUICKSTART-HETZNER.md +++ b/docs/deployment/cloud-providers/hetzner.md @@ -1,12 +1,14 @@ -# Quickstart on Hetzner Cloud +# Deploy SkyEye on Hetzner Cloud -This guide is a step-by-step on how to run SkyEye on [Hetzner Cloud](https://www.hetzner.com/cloud) using local speech recogntion. +This guide is a step-by-step on how to run SkyEye on [Hetzner Cloud](https://www.hetzner.com/cloud) using local speech recognition. It is assumed that you have set up an account and a billing method. +This guide is provider-specific. For a provider-agnostic guide, see [the Linux CPU guide](../linux/cpu.md). + ## Getting Help -See [the admin guide](ADMIN.md#getting-help) for how to get help if you have a problem. +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. ## Set Up DCS, TacView, and SRS @@ -83,9 +85,9 @@ Labels: Add the label "skyeye" to the labels. Cloud config: -Copy the contents of [`cloud-config.yaml`](../init/cloud-init/cloud-config.yaml) into a text editor. +Copy the contents of [`cloud-config.yaml`](../../../init/cloud-init/cloud-config.yaml) into a text editor. -Find the line that contains `/etc/skyeye/config.yaml`, then below it, the block under `content:`. This indented block is your SkyEye config file. Reference the [example config file](../config.yaml) and set the values as required. Remember to preserve the indentation. +Find the line that contains `/etc/skyeye/config.yaml`, then below it, the block under `content:`. This indented block is your SkyEye config file. Reference the [example config file](../../../config.yaml) and set the values as required. Remember to preserve the indentation. Find the line that contains `ghcr.io/dharmab/skyeye:latest`. This default value will install the latest version of SkyEye **at the time the server is created**. If you want to install a specific version, replace `latest` with a version number. Example: `ghcr.io/dharmab/skyeye:v0.14.0`. @@ -95,10 +97,10 @@ Set "Name" to something descriptive, like "skyeye-". Click "Create & Buy Now". -If the configuration was correct, SkyEye should connect to your SRS server within a few minutes and announce itself with a SUNRISE broadcast. If you're comfortable with Linux, SSH into the server and check the service and logs with `systemctl status skyeye` and `journalctl -u skyeye` for any weird warnings or errors. Try some basic SkyEye commands such as a [RADIO CHECK](PLAYER.md#radio-check) and a [PICTURE](PLAYER.md#picture). Make sure the results you hear match what you see in the DCS F10 map. +If the configuration was correct, SkyEye should connect to your SRS server within a few minutes and announce itself with a SUNRISE broadcast. If you're comfortable with Linux, SSH into the server and check the service and logs with `systemctl status skyeye` and `journalctl -u skyeye` for any weird warnings or errors. Try some basic SkyEye commands such as a [RADIO CHECK](../../PLAYER.md#radio-check) and a [PICTURE](../../PLAYER.md#picture). Make sure the results you hear match what you see in the DCS F10 map. ## Reducing the Bill You pay for the SkyEye server on an hourly basis. You can delete the server when you're not playing DCS to reduce your bill. Note that it's not enough to power off the server; you must delete it. -You can recreate the server at any time by following the steps above; if you saved the customized `cloud-config.yaml` file, you can recreate the server in a few clicks. If you're an advanced user, see the [autoscaling documentation](ADMIN.md#autoscaling-experimental) for a way to automate this task. +You can recreate the server at any time by following the steps above; if you saved the customized `cloud-config.yaml` file, you can recreate the server in a few clicks. If you're an advanced user, see the [autoscaling documentation](../../ADMIN.md#autoscaling-experimental) for a way to automate this task. diff --git a/docs/QUICKSTART-VULTR.md b/docs/deployment/cloud-providers/vultr.md similarity index 79% rename from docs/QUICKSTART-VULTR.md rename to docs/deployment/cloud-providers/vultr.md index c70f4027..5e124a35 100644 --- a/docs/QUICKSTART-VULTR.md +++ b/docs/deployment/cloud-providers/vultr.md @@ -1,12 +1,14 @@ -# Quickstart on Vultr +# Deploy SkyEye on Vultr -This guide is a step-by-step on how to run SkyEye on [Vultr](https://www.vultr.com/) using local speech recogntion. +This guide is a step-by-step on how to run SkyEye on [Vultr](https://www.vultr.com/) using local speech recognition. It is assumed that you have set up an account, SSH keys and a billing method. +This guide is provider-specific. For a provider-agnostic guide, see [the Linux CPU guide](../linux/cpu.md). + ## Getting Help -See [the admin guide](ADMIN.md#getting-help) for how to get help if you have a problem. +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. ## Set Up DCS, TacView, and SRS @@ -40,9 +42,9 @@ Server 1 Label: "skyeye" Deselect the "Automatic Backups" feature. SkyEye does not retain any data that needs to be backed up. -Select the "Cloud-Init User-Data" feature. Copy the contents of [`cloud-config.yaml`](../init/cloud-init/cloud-config.yaml) into a text editor. +Select the "Cloud-Init User-Data" feature. Copy the contents of [`cloud-config.yaml`](../../../init/cloud-init/cloud-config.yaml) into a text editor. -Find the line that contains `/etc/skyeye/config.yaml`, then below it, the block under `content:`. This indented block is your SkyEye config file. Reference the [example config file](../config.yaml) and set the values as required. Remember to preserve the indentation. +Find the line that contains `/etc/skyeye/config.yaml`, then below it, the block under `content:`. This indented block is your SkyEye config file. Reference the [example config file](../../../config.yaml) and set the values as required. Remember to preserve the indentation. Find the line that contains `ghcr.io/dharmab/skyeye:latest`. This default value will install the latest version of SkyEye **at the time the server is created**. If you want to install a specific version, replace `latest` with a version number. Example: `ghcr.io/dharmab/skyeye:v0.14.0`. @@ -50,10 +52,10 @@ Copy the entire contents of the customized `cloud-config.yaml` file and paste it Click "Deploy". -If the configuration was correct, SkyEye should connect to your SRS server within a few minutes and announce itself with a SUNRISE broadcast. If you're comfortable with Linux, SSH into the server and check the service and logs with `systemctl status skyeye` and `journalctl -u skyeye` for any weird warnings or errors. Try some basic SkyEye commands such as a [RADIO CHECK](PLAYER.md#radio-check) and a [PICTURE](PLAYER.md#picture). Make sure the results you hear match what you see in the DCS F10 map. +If the configuration was correct, SkyEye should connect to your SRS server within a few minutes and announce itself with a SUNRISE broadcast. If you're comfortable with Linux, SSH into the server and check the service and logs with `systemctl status skyeye` and `journalctl -u skyeye` for any weird warnings or errors. Try some basic SkyEye commands such as a [RADIO CHECK](../../PLAYER.md#radio-check) and a [PICTURE](../../PLAYER.md#picture). Make sure the results you hear match what you see in the DCS F10 map. ## Reducing the Bill You pay for the SkyEye server on an hourly basis. You can delete the server when you're not playing DCS to reduce your bill. Note that it's not enough to power off the server; you must delete it. -You can recreate the server at any time by following the steps above; if you saved the customized `cloud-config.yaml` file, you can recreate the server in a few minutes. If you're an advanced user, see the [autoscaling documentation](ADMIN.md#autoscaling-experimental) for a way to automate this task. +You can recreate the server at any time by following the steps above; if you saved the customized `cloud-config.yaml` file, you can recreate the server in a few minutes. If you're an advanced user, see the [autoscaling documentation](../../ADMIN.md#autoscaling-experimental) for a way to automate this task. diff --git a/docs/deployment/linux/api.md b/docs/deployment/linux/api.md new file mode 100644 index 00000000..423d6d09 --- /dev/null +++ b/docs/deployment/linux/api.md @@ -0,0 +1,228 @@ +# Deploy SkyEye on Linux - Cloud API + +This guide is a step-by-step on how to run SkyEye on a Linux computer or server alongside DCS, TacView and SRS Server, using the OpenAI API for cloud speech recognition. + +You can also deploy SkyEye on Linux using either [a separate computer using CPU speech recognition](cpu.md) or [the same computer as DCS using GPU speech recognition](gpu.md). + +## Getting Help + +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. + +## Set up OpenAI API + +Go to https://platform.openai.com. If you haven't previously set up the OpenAI API, you'll go through a step-by-step process to set up an organization, buy credits, create a Project and generate an API key. + +Otherwise, go to https://platform.openai.com/settings/organization/api-keys and generate a new API key for SkyEye. I recommend adding this API key to a new Project named "SkyEye". + +Be sure to review the pricing of the "Whisper" audio model at https://openai.com/api/pricing. You will pay per-second for each second a player transmits on a SkyEye frequency in SRS. (You are not charged for the time SkyEye itself spends transmitting, nor are you charged for players' transmissions on other frequencies.) + +## Set Up DCS, TacView, and SRS + +Install DCS (either the client for singleplayer/hosted multiplayer use, or a dedicated server for multiplayer use). + +Install the TacView Exporter. Within DCS, go to OPTIONS → SPECIAL → Tacview and enable Real-Time Telemetry. (See https://www.tacview.net/documentation/dcs/en/) + +Install SRS. Start and configure the SRS Server. Ensure EAM mode is enabled and an EAM password is set. + +Make sure DCS is running an unpaused mission with both friendly and hostile air units so you can do some tests. + +## Set up SkyEye + +You can install SkyEye either as a container, or as a native binary. The container is easier to set up and upgrade; the native binary is useful if you don't want to run a container runtime. + +### Container + +Install [Podman](https://podman.io/): + +```sh +# Debian/Ubuntu +sudo apt-get update +sudo apt-get install podman + +# Fedora +sudo dnf install podman + +# Arch Linux +sudo pacman -Syu podman +``` + +Create a config directory and copy in the [sample config file](../../../config.yaml): + +```sh +sudo mkdir -p /etc/skyeye +sudoedit /etc/skyeye/config.yaml +``` + +Set `recognizer` to `openai-whisper-api` and set `openai-api-key` (or provide it via environment variable; see [the configuration section](../../ADMIN.md#configuration)), along with your Tacview and SRS connection details. + +Create a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) file at `/etc/containers/systemd/skyeye.container`: + +```ini +[Unit] +Description=SkyEye GCI Bot +After=network-online.target + +[Container] +Image=ghcr.io/dharmab/skyeye:latest +ContainerName=skyeye +Volume=/etc/skyeye/config.yaml:/etc/skyeye/config.yaml:ro + +[Service] +Restart=always +RestartSec=60 + +[Install] +WantedBy=multi-user.target +``` + +I recommend pinning `Image=` to a specific version instead of `latest`, to avoid unexpected breaking changes when a new version is released. Find version tags on the [releases page](https://github.com/dharmab/skyeye/releases), e.g. `Image=ghcr.io/dharmab/skyeye:v1.9.3`. + +Load the Quadlet and start SkyEye, enabling it to start on boot: + +```sh +sudo systemctl daemon-reload +sudo systemctl enable --now skyeye.service +``` + +### Native Binary + +Install shared libraries for [Opus](https://opus-codec.org/) and [SoX Resampler](https://sourceforge.net/p/soxr/wiki/Home/): + +```sh +# Debian/Ubuntu +sudo apt-get update +sudo apt-get install libopus0 libsoxr0 + +# Fedora +sudo dnf install opus sox + +# Arch Linux +sudo pacman -Syu opus soxr +``` + +Download and install SkyEye: + +```sh +sudo useradd -G users skyeye +curl -sL https://github.com/dharmab/skyeye/releases/latest/download/skyeye-linux-amd64.tar.gz -o /tmp/skyeye-linux-amd64.tar.gz +tar -xzf /tmp/skyeye-linux-amd64.tar.gz -C /tmp/ +sudo mkdir -p /opt/skyeye/bin +sudo mv /tmp/skyeye-linux-amd64/skyeye /opt/skyeye/bin/skyeye +sudo chmod +x /opt/skyeye/bin/skyeye +sudo chown -R skyeye:users /opt/skyeye +sudo mkdir -p /etc/skyeye +sudo mv /tmp/skyeye-linux-amd64/config.yaml /etc/skyeye/config.yaml +sudo chmod 600 /etc/skyeye/config.yaml +sudo chown -R skyeye:users /etc/skyeye +rm -rf /tmp/skyeye-linux-amd64.tar.gz /tmp/skyeye-linux-amd64 +``` + +Edit the config file, setting `recognizer` to `openai-whisper-api` and providing your `openai-api-key`, along with your Tacview and SRS connection details: + +```sh +sudoedit /etc/skyeye/config.yaml +``` + +Save this systemd unit to `/etc/systemd/system/skyeye.service`: + +```ini +[Unit] +Description=SkyEye GCI Bot +After=network-online.target + +[Service] +Type=simple +User=skyeye +WorkingDirectory=/opt/skyeye +ExecStart=/opt/skyeye/bin/skyeye +Restart=always +RestartSec=60 + +[Install] +WantedBy=multi-user.target +``` + +To start SkyEye, and enable it to start on boot: + +```sh +sudo systemctl daemon-reload +sudo systemctl enable skyeye.service --now +``` + +## Using SkyEye + +Check that SkyEye is running: + +```sh +sudo systemctl status skyeye +``` + +Stream the logs and look for any repeated WARN or ERROR lines that don't go away: + +```sh +journalctl -fu skyeye +``` + +Connect to your DCS game and SRS server. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](../../PLAYER.md).) + +To stop SkyEye: + +```sh +sudo systemctl stop skyeye +``` + +## Upgrading SkyEye + +### Container + +If your Quadlet file uses the `latest` tag, force a pull of the newest image and restart SkyEye: + +```sh +sudo podman pull ghcr.io/dharmab/skyeye:latest +sudo systemctl restart skyeye.service +``` + +If you pinned a specific version instead, edit the `Image=` line in `/etc/containers/systemd/skyeye.container` to the version you want, then reload and restart: + +```sh +sudo systemctl daemon-reload +sudo systemctl restart skyeye.service +``` + +### Native Binary + +```sh +new_version=v1.9.3 +curl -sL https://github.com/dharmab/skyeye/releases/download/$new_version/skyeye-linux-amd64.tar.gz -o /tmp/skyeye-linux-amd64.tar.gz +tar -xzf /tmp/skyeye-linux-amd64.tar.gz -C /tmp/ +sudo mv /tmp/skyeye-linux-amd64/skyeye /opt/skyeye/bin/skyeye +sudo chown skyeye:users /opt/skyeye/bin/skyeye +rm -rf /tmp/skyeye-linux-amd64.tar.gz /tmp/skyeye-linux-amd64 +sudo systemctl restart skyeye.service +``` + +## Uninstalling SkyEye + +### Container + +```sh +sudo systemctl disable --now skyeye.service +sudo rm /etc/containers/systemd/skyeye.container +sudo systemctl daemon-reload +sudo podman rmi ghcr.io/dharmab/skyeye:latest +sudo rm -rf /etc/skyeye +``` + +### Native Binary + +```sh +sudo systemctl disable --now skyeye.service +sudo rm /etc/systemd/system/skyeye.service +sudo systemctl daemon-reload +sudo userdel skyeye +sudo rm -rf /opt/skyeye /etc/skyeye +``` + +## Advanced Topics + +For instructions on autoscaling and running multiple instances, see [the full admin guide](../../ADMIN.md#autoscaling-experimental). diff --git a/docs/deployment/linux/cpu.md b/docs/deployment/linux/cpu.md new file mode 100644 index 00000000..0c8e8e8a --- /dev/null +++ b/docs/deployment/linux/cpu.md @@ -0,0 +1,243 @@ +# Deploy SkyEye on Linux - CPU + +This guide is a step-by-step on how to run SkyEye on a Linux computer or server, separate from the computer running DCS, TacView and SRS Server, using the CPU for local speech recognition. This guide is not tied to any particular hosting provider; it works on a spare Linux machine, a rented cloud server, or a container host. If you want a guide tailored to a specific cloud provider, see the [Hetzner Cloud](../cloud-providers/hetzner.md) or [Vultr](../cloud-providers/vultr.md) guides. + +You can also deploy SkyEye on Linux using either [the same computer as DCS using GPU speech recognition](gpu.md) or [cloud API speech recognition](api.md). + +## Getting Help + +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. + +## Hardware Requirements + +This guide requires a **second** Linux computer or server, separate from the one running DCS, TacView and SRS Server. The computer running SkyEye needs a fast, multithreaded, **dedicated** CPU with support for [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2), 3GB of RAM, and about 2GB of disk space. + +CPU Series|AVX2 Added In +-|- +Intel Core|Haswell (2013) +AMD|Excavator (2015) +Intel Pentium/Celeron|Tiger Lake (2020) + +At least 4 dedicated CPU cores are recommended. Shared-core virtual machines are **not supported** and will result in high latency and stuttering audio. + +Running SkyEye's local speech recognition on CPU on the same computer as DCS is not supported; only [GPU-based local speech recognition](gpu.md) and [cloud API speech recognition](api.md) are supported on the same computer as DCS. See [the admin guide](../../ADMIN.md#deployment-with-local-speech-recognition-on-cpu) for details on why. + +## Set Up DCS, TacView, and SRS + +On the computer running DCS: + +Install DCS (either the client for singleplayer/hosted multiplayer use, or a dedicated server for multiplayer use). + +Install the TacView Exporter. Within DCS, go to OPTIONS → SPECIAL → Tacview and enable Real-Time Telemetry. (See https://www.tacview.net/documentation/dcs/en/) + +Install SRS. Start and configure the SRS Server. Ensure EAM mode is enabled and an EAM password is set. + +Make sure DCS is running an unpaused mission with both friendly and hostile air units so you can do some tests. + +## Set up SkyEye + +On the Linux computer running SkyEye, you can install SkyEye either as a container, or as a native binary. The container is easier to set up and upgrade; the native binary is useful if you don't want to run a container runtime. + +### Container + +Install [Podman](https://podman.io/): + +```sh +# Debian/Ubuntu +sudo apt-get update +sudo apt-get install podman + +# Fedora +sudo dnf install podman + +# Arch Linux +sudo pacman -Syu podman +``` + +Create a config directory and copy in the [sample config file](../../../config.yaml): + +```sh +sudo mkdir -p /etc/skyeye +sudoedit /etc/skyeye/config.yaml +``` + +Set `recognizer` to `openai-whisper-local` and set `whisper-model` to a path inside the container, such as `/etc/skyeye/ggml-small.en.bin`, along with your Tacview and SRS connection details. + +Download a Whisper model: + +```sh +curl -sL https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin -o /etc/skyeye/ggml-small.en.bin +``` + +Create a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) file at `/etc/containers/systemd/skyeye.container`: + +```ini +[Unit] +Description=SkyEye GCI Bot +After=network-online.target + +[Container] +Image=ghcr.io/dharmab/skyeye:latest +ContainerName=skyeye +Volume=/etc/skyeye:/etc/skyeye:ro + +[Service] +Restart=always +RestartSec=60 + +[Install] +WantedBy=multi-user.target +``` + +I recommend pinning `Image=` to a specific version instead of `latest`, to avoid unexpected breaking changes when a new version is released. Find version tags on the [releases page](https://github.com/dharmab/skyeye/releases), e.g. `Image=ghcr.io/dharmab/skyeye:v1.9.3`. + +Load the Quadlet and start SkyEye, enabling it to start on boot: + +```sh +sudo systemctl daemon-reload +sudo systemctl enable --now skyeye.service +``` + +### Native Binary + +Install shared libraries for [Opus](https://opus-codec.org/) and [SoX Resampler](https://sourceforge.net/p/soxr/wiki/Home/): + +```sh +# Debian/Ubuntu +sudo apt-get update +sudo apt-get install libopus0 libsoxr0 + +# Fedora +sudo dnf install opus sox + +# Arch Linux +sudo pacman -Syu opus soxr +``` + +Download and install SkyEye, along with a Whisper speech recognition model: + +```sh +sudo useradd -G users skyeye +curl -sL https://github.com/dharmab/skyeye/releases/latest/download/skyeye-linux-amd64.tar.gz -o /tmp/skyeye-linux-amd64.tar.gz +tar -xzf /tmp/skyeye-linux-amd64.tar.gz -C /tmp/ +sudo mkdir -p /opt/skyeye/bin /opt/skyeye/models +sudo mv /tmp/skyeye-linux-amd64/skyeye /opt/skyeye/bin/skyeye +sudo chmod +x /opt/skyeye/bin/skyeye +curl -sL https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin -o /opt/skyeye/models/ggml-small.en.bin +sudo chown -R skyeye:users /opt/skyeye +sudo mkdir -p /etc/skyeye +sudo mv /tmp/skyeye-linux-amd64/config.yaml /etc/skyeye/config.yaml +sudo chmod 600 /etc/skyeye/config.yaml +sudo chown -R skyeye:users /etc/skyeye +rm -rf /tmp/skyeye-linux-amd64.tar.gz /tmp/skyeye-linux-amd64 +``` + +Edit the config file, setting `recognizer` to `openai-whisper-local` and `whisper-model` to `/opt/skyeye/models/ggml-small.en.bin`, along with your Tacview and SRS connection details: + +```sh +sudoedit /etc/skyeye/config.yaml +``` + +Save this systemd unit to `/etc/systemd/system/skyeye.service`: + +```ini +[Unit] +Description=SkyEye GCI Bot +After=network-online.target + +[Service] +Type=simple +User=skyeye +WorkingDirectory=/opt/skyeye +ExecStart=/opt/skyeye/bin/skyeye +Restart=always +RestartSec=60 + +[Install] +WantedBy=multi-user.target +``` + +To start SkyEye, and enable it to start on boot: + +```sh +sudo systemctl daemon-reload +sudo systemctl enable skyeye.service --now +``` + +## Using SkyEye + +Check that SkyEye is running: + +```sh +sudo systemctl status skyeye +``` + +Stream the logs and look for any repeated WARN or ERROR lines that don't go away: + +```sh +journalctl -fu skyeye +``` + +Connect to your DCS game and SRS server. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](../../PLAYER.md).) + +To stop SkyEye: + +```sh +sudo systemctl stop skyeye +``` + +## Upgrading SkyEye + +### Container + +If your Quadlet file uses the `latest` tag, force a pull of the newest image and restart SkyEye: + +```sh +sudo podman pull ghcr.io/dharmab/skyeye:latest +sudo systemctl restart skyeye.service +``` + +If you pinned a specific version instead, edit the `Image=` line in `/etc/containers/systemd/skyeye.container` to the version you want, then reload and restart: + +```sh +sudo systemctl daemon-reload +sudo systemctl restart skyeye.service +``` + +### Native Binary + +```sh +new_version=v1.9.3 +curl -sL https://github.com/dharmab/skyeye/releases/download/$new_version/skyeye-linux-amd64.tar.gz -o /tmp/skyeye-linux-amd64.tar.gz +tar -xzf /tmp/skyeye-linux-amd64.tar.gz -C /tmp/ +sudo mv /tmp/skyeye-linux-amd64/skyeye /opt/skyeye/bin/skyeye +sudo chown skyeye:users /opt/skyeye/bin/skyeye +rm -rf /tmp/skyeye-linux-amd64.tar.gz /tmp/skyeye-linux-amd64 +sudo systemctl restart skyeye.service +``` + +## Uninstalling SkyEye + +### Container + +```sh +sudo systemctl disable --now skyeye.service +sudo rm /etc/containers/systemd/skyeye.container +sudo systemctl daemon-reload +sudo podman rmi ghcr.io/dharmab/skyeye:latest +sudo rm -rf /etc/skyeye +``` + +### Native Binary + +```sh +sudo systemctl disable --now skyeye.service +sudo rm /etc/systemd/system/skyeye.service +sudo systemctl daemon-reload +sudo userdel skyeye +sudo rm -rf /opt/skyeye /etc/skyeye +``` + +## Advanced Topics + +For instructions on autoscaling and running multiple instances, see [the full admin guide](../../ADMIN.md#autoscaling-experimental). diff --git a/docs/deployment/linux/gpu.md b/docs/deployment/linux/gpu.md new file mode 100644 index 00000000..1249e2b3 --- /dev/null +++ b/docs/deployment/linux/gpu.md @@ -0,0 +1,294 @@ +# Deploy SkyEye on Linux - GPU + +This guide is a step-by-step on how to run SkyEye on the same Linux computer as DCS, TacView and SRS Server, using the GPU for local speech recognition via the experimental Vulkan build. + +You can also deploy SkyEye on Linux using either [a separate computer using CPU speech recognition](cpu.md) or [cloud API speech recognition](api.md). + +> ⚠️ The Vulkan (GPU) build of SkyEye is experimental. Performance and speech recognition quality can vary significantly between GPU models — it might run great on one and perform poorly on another. I can only test against the GPU hardware I personally own, so I have no control over and very limited ability to troubleshoot how well the Vulkan build runs on any particular GPU or driver. + +## Getting Help + +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. + +## Hardware Requirements + +Unlike CPU-based local speech recognition, the Vulkan build offloads speech recognition to your GPU, so it's suitable for running on the same computer as DCS. You need any decent multithreaded CPU with support for [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2), 3GB of RAM, about 2GB of VRAM, and about 2GB of disk space. + +## Set Up DCS, TacView, and SRS + +Install DCS (either the client for singleplayer/hosted multiplayer use, or a dedicated server for multiplayer use). + +Install the TacView Exporter. Within DCS, go to OPTIONS → SPECIAL → Tacview and enable Real-Time Telemetry. (See https://www.tacview.net/documentation/dcs/en/) + +Install SRS. Start and configure the SRS Server. Ensure EAM mode is enabled and an EAM password is set. + +Make sure DCS is running an unpaused mission with both friendly and hostile air units so you can do some tests. + +## Install a GPU Driver + +Your GPU driver needs to be installed and up to date on the host system, whether you install SkyEye as a container or a native binary. Install it through your distribution's package manager, not a vendor installer. The `amdgpu` and `i915` kernel drivers for AMD and Intel GPUs ship in the mainline Linux kernel, but you still need the Mesa userspace Vulkan driver (and, for AMD, firmware blobs) installed separately. NVIDIA GPUs need the proprietary driver package, which includes both the kernel module and the Vulkan driver. + +```sh +# AMD - Debian/Ubuntu +sudo apt-get install mesa-vulkan-drivers firmware-amd-graphics + +# AMD - Fedora +sudo dnf install mesa-vulkan-drivers + +# AMD - Arch Linux +sudo pacman -Syu vulkan-radeon linux-firmware + +# Intel - Debian/Ubuntu +sudo apt-get install mesa-vulkan-drivers + +# Intel - Fedora +sudo dnf install mesa-vulkan-drivers + +# Intel - Arch Linux +sudo pacman -Syu vulkan-intel + +# NVIDIA (proprietary) - Debian/Ubuntu +sudo apt-get install nvidia-driver + +# NVIDIA (proprietary) - Fedora (via RPM Fusion) +sudo dnf install akmod-nvidia + +# NVIDIA (proprietary) - Arch Linux +sudo pacman -Syu nvidia +``` + +Package names vary between distributions and releases, and some distributions split Vulkan support across additional packages beyond what's listed here (e.g. separate ICD loader or 32-bit compatibility packages). Consult your distribution's documentation if these don't match, and use `vulkaninfo` to confirm your GPU is detected before proceeding. + +## Set up SkyEye + +You can install SkyEye either as a Vulkan container image, or as a native Vulkan binary. The container is easier to set up and upgrade; the native binary is useful if you don't want to run a container runtime. + +### Container + +Install [Podman](https://podman.io/): + +```sh +# Debian/Ubuntu +sudo apt-get update +sudo apt-get install podman + +# Fedora +sudo dnf install podman + +# Arch Linux +sudo pacman -Syu podman +``` + +If you have an NVIDIA GPU, install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). + +If you have an AMD or Intel GPU, no extra toolkit is needed. The Vulkan container image bundles the necessary Mesa drivers. + +Create a config directory and copy in the [sample config file](../../../config.yaml): + +```sh +sudo mkdir -p /etc/skyeye +sudoedit /etc/skyeye/config.yaml +``` + +Set `recognizer` to `openai-whisper-local` and set `whisper-model` to a path inside the container, such as `/etc/skyeye/ggml-small.en.bin`, along with your Tacview and SRS connection details. + +Download a Whisper model: + +```sh +curl -sL https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin -o /etc/skyeye/ggml-small.en.bin +``` + +Create a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) file at `/etc/containers/systemd/skyeye.container`, using the GPU passthrough appropriate for your vendor: + +```ini +# NVIDIA +[Unit] +Description=SkyEye GCI Bot +After=network-online.target + +[Container] +Image=ghcr.io/dharmab/skyeye:latest-vulkan +ContainerName=skyeye +Volume=/etc/skyeye:/etc/skyeye:ro +PodmanArgs=--gpus all + +[Service] +Restart=always +RestartSec=60 + +[Install] +WantedBy=multi-user.target +``` + +```ini +# AMD/Intel +[Unit] +Description=SkyEye GCI Bot +After=network-online.target + +[Container] +Image=ghcr.io/dharmab/skyeye:latest-vulkan +ContainerName=skyeye +Volume=/etc/skyeye:/etc/skyeye:ro +AddDevice=/dev/dri + +[Service] +Restart=always +RestartSec=60 + +[Install] +WantedBy=multi-user.target +``` + +I recommend pinning `Image=` to a specific version instead of `latest-vulkan`, to avoid unexpected breaking changes when a new version is released. Find version tags on the [releases page](https://github.com/dharmab/skyeye/releases), e.g. `Image=ghcr.io/dharmab/skyeye:v1.9.3-vulkan`. + +Load the Quadlet and start SkyEye, enabling it to start on boot: + +```sh +sudo systemctl daemon-reload +sudo systemctl enable --now skyeye.service +``` + +### Native Binary + +Install the Vulkan loader, in addition to the GPU driver installed in the previous section: + +```sh +# Debian/Ubuntu +sudo apt-get update +sudo apt-get install libopus0 libsoxr0 libvulkan1 + +# Fedora +sudo dnf install opus sox vulkan-loader + +# Arch Linux +sudo pacman -Syu opus soxr vulkan-icd-loader +``` + +Download and install SkyEye, along with a Whisper speech recognition model: + +```sh +sudo useradd -G users skyeye +curl -sL https://github.com/dharmab/skyeye/releases/latest/download/skyeye-linux-amd64-vulkan.tar.gz -o /tmp/skyeye-linux-amd64-vulkan.tar.gz +tar -xzf /tmp/skyeye-linux-amd64-vulkan.tar.gz -C /tmp/ +sudo mkdir -p /opt/skyeye/bin /opt/skyeye/models +sudo mv /tmp/skyeye-linux-amd64-vulkan/skyeye /opt/skyeye/bin/skyeye +sudo chmod +x /opt/skyeye/bin/skyeye +curl -sL https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin -o /opt/skyeye/models/ggml-small.en.bin +sudo chown -R skyeye:users /opt/skyeye +sudo mkdir -p /etc/skyeye +sudo mv /tmp/skyeye-linux-amd64-vulkan/config.yaml /etc/skyeye/config.yaml +sudo chmod 600 /etc/skyeye/config.yaml +sudo chown -R skyeye:users /etc/skyeye +rm -rf /tmp/skyeye-linux-amd64-vulkan.tar.gz /tmp/skyeye-linux-amd64-vulkan +``` + +Edit the config file, setting `recognizer` to `openai-whisper-local` and `whisper-model` to `/opt/skyeye/models/ggml-small.en.bin`, along with your Tacview and SRS connection details: + +```sh +sudoedit /etc/skyeye/config.yaml +``` + +Save this systemd unit to `/etc/systemd/system/skyeye.service`: + +```ini +[Unit] +Description=SkyEye GCI Bot +After=network-online.target + +[Service] +Type=simple +User=skyeye +WorkingDirectory=/opt/skyeye +ExecStart=/opt/skyeye/bin/skyeye +Restart=always +RestartSec=60 + +[Install] +WantedBy=multi-user.target +``` + +To start SkyEye, and enable it to start on boot: + +```sh +sudo systemctl daemon-reload +sudo systemctl enable skyeye.service --now +``` + +## Using SkyEye + +Check that SkyEye is running: + +```sh +sudo systemctl status skyeye +``` + +Stream the logs and look for any repeated WARN or ERROR lines that don't go away: + +```sh +journalctl -fu skyeye +``` + +Connect to your DCS game and SRS server. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](../../PLAYER.md).) + +To stop SkyEye: + +```sh +sudo systemctl stop skyeye +``` + +## Upgrading SkyEye + +### Container + +If your Quadlet file uses the `latest-vulkan` tag, force a pull of the newest image and restart SkyEye: + +```sh +sudo podman pull ghcr.io/dharmab/skyeye:latest-vulkan +sudo systemctl restart skyeye.service +``` + +If you pinned a specific version instead, edit the `Image=` line in `/etc/containers/systemd/skyeye.container` to the version you want, then reload and restart: + +```sh +sudo systemctl daemon-reload +sudo systemctl restart skyeye.service +``` + +### Native Binary + +```sh +new_version=v1.9.3 +curl -sL https://github.com/dharmab/skyeye/releases/download/$new_version/skyeye-linux-amd64-vulkan.tar.gz -o /tmp/skyeye-linux-amd64-vulkan.tar.gz +tar -xzf /tmp/skyeye-linux-amd64-vulkan.tar.gz -C /tmp/ +sudo mv /tmp/skyeye-linux-amd64-vulkan/skyeye /opt/skyeye/bin/skyeye +sudo chown skyeye:users /opt/skyeye/bin/skyeye +rm -rf /tmp/skyeye-linux-amd64-vulkan.tar.gz /tmp/skyeye-linux-amd64-vulkan +sudo systemctl restart skyeye.service +``` + +## Uninstalling SkyEye + +### Container + +```sh +sudo systemctl disable --now skyeye.service +sudo rm /etc/containers/systemd/skyeye.container +sudo systemctl daemon-reload +sudo podman rmi ghcr.io/dharmab/skyeye:latest-vulkan +sudo rm -rf /etc/skyeye +``` + +### Native Binary + +```sh +sudo systemctl disable --now skyeye.service +sudo rm /etc/systemd/system/skyeye.service +sudo systemctl daemon-reload +sudo userdel skyeye +sudo rm -rf /opt/skyeye /etc/skyeye +``` + +## Advanced Topics + +For instructions on autoscaling and running multiple instances, see [the full admin guide](../../ADMIN.md#autoscaling-experimental). diff --git a/docs/deployment/macos/gpu.md b/docs/deployment/macos/gpu.md new file mode 100644 index 00000000..49bea2ce --- /dev/null +++ b/docs/deployment/macos/gpu.md @@ -0,0 +1,164 @@ +# Deploy SkyEye on macOS - GPU + +This guide is a step-by-step on how to run SkyEye on macOS, using the GPU/Neural Engine for local speech recognition. This is the fastest and highest-quality way to run SkyEye, but requires an Apple Silicon Mac and a separate Windows computer for DCS, TacView and SRS Server. + +There is no cloud API or CPU-only guide for macOS: local speech recognition on the GPU/Neural Engine is the only recommended way to run SkyEye on macOS. + +## Getting Help + +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. + +## Hardware Requirements + +You need an Apple Silicon Mac (M-series), such as a Mac Mini or MacBook Air/Pro. SkyEye requires around 3GB of RAM and about 2GB of disk space. Intel Macs are not supported. + +## Set Up DCS, TacView, and SRS + +Install DCS on a Windows computer (either the client for singleplayer/hosted multiplayer use, or a dedicated server for multiplayer use). + +Install the TacView Exporter on the DCS machine. Within DCS, go to OPTIONS → SPECIAL → Tacview and enable Real-Time Telemetry. (See https://www.tacview.net/documentation/dcs/en/) + +Install SRS on a Windows computer. Start and configure the SRS Server. Ensure EAM mode is enabled and an EAM password is set. + +Make sure DCS is running an unpaused mission with both friendly and hostile air units so you can do some tests. + +## Configure System Voice (Optional, Strongly Recommended) + +SkyEye uses AI generated voices built into macOS. By default, the "Samantha" voice is used. This is the version of Siri's voice from the iPhone 4s, iPhone 5 and iPhone 6, based on [Susan Bennett](https://susancbennett.com/). + +It is also possible to use one of the newer Siri voices. **I strongly recommend enabling one of the newer voices**, because they provide excellent quality, nearly indistinguishable from a human voice. + +I've validated one Siri voice for each version of macOS that correctly pronounces aviation brevity and terminology: + +### macOS 26 Tahoe + +On macOS 26 Tahoe, the best voice is **Siri Voice 2**. + +1. Open System Settings +2. Click on "Accessibility" +3. Click on "Siri" +4. If the system language is not English, set the system speech language to English +5. Next to "System Voice", click the "i" button +6. In the list of languages, make sure "English" is selected +7. Click on "Voice" +8. Scroll down to "Siri". +9. Download Siri Voice 2. +10. Click "Done" +11. Set the system voice to Siri Voice 2. + +### macOS 15 Sequoia + +On macOS 15 Sequoia, the best voice is **Siri Voice 5**. + +1. Open System Settings +2. Click on "Accessibility" +3. Click on "Spoken Content" +4. If the system language is not English, set the system speech language to English +5. Next to "System Voice", click the "i" button +6. In the list of languages, make sure "English" is selected +7. Click on "Voice" +8. Scroll down to "Siri". +9. Download the English (United States) Siri Voice 5. +10. Click "Done" +11. Set the system voice to Siri Voice 5. + +### Testing the System Voice + +To test your change, open Terminal and run this command: + +```sh +say "Hello! This should be read in the voice you chose." +``` + +Finally, to use the selected voice instead of Samantha, set `use-system-voice: true` in your config file, as shown below. + +## Install Homebrew + +Follow the instructions at https://brew.sh to install Homebrew. + +## Install SkyEye + +Run the following commands in a terminal: + +```sh +brew tap dharmab/skyeye +brew trust dharmab/skyeye/skyeye +brew install dharmab/skyeye/skyeye +``` + +Open `$(brew --prefix)/etc/skyeye/config.yaml` with a text editor. It's probably at `/opt/homebrew/etc/skyeye/config.yaml`. (If you don't have a text editor, download [Visual Studio Code](https://code.visualstudio.com). I don't recommend trying to edit YAML with TextEdit because it's easy to make an indentation error.) Edit the file as required and save your changes. + +A minimal sample config file might look like: + +```yaml +callsign: Focus +recognizer: openai-whisper-local +whisper-model: /opt/homebrew/share/skyeye/models/ggml-small.en.bin +telemetry-address: tacview.example.com:42674 +telemetry-password: yourtacviewpasswordhere +srs-server-address: srs.example.com:5002 +srs-eam-password: yoursrspasswordhere +use-system-voice: true # Set to false if you didn't configure Siri Voice above +``` + +Run this command to start SkyEye: + +```sh +brew services run dharmab/skyeye/skyeye +``` + +Confirm SkyEye is running: + +```sh +brew services info dharmab/skyeye/skyeye +``` + +The output should indicate that SkyEye is running. + +## Using SkyEye + +Take a look at the logs: + +```sh +tail -f "$(brew --prefix)/var/log/skyeye.log" +``` + +If you see a lot of repeated WARN or ERROR lines that don't go away, something may be wrong. + +If you see an error message containing `connect: no route to host`, see [this issue](https://github.com/dharmab/skyeye/issues/566) for a possible cause and workarounds. This issue specifically affects macOS 15+ when SkyEye runs as a background service and connects to a SRS, Tacview, or DCS-gRPC server on the same LAN. + +On the Windows computer, connect to your DCS and SRS servers. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](../../PLAYER.md).) + +To stop SkyEye, run this command: + +```sh +brew services kill dharmab/skyeye/skyeye +``` + +## Automatically Starting SkyEye on Login + +To start SkyEye and enable it to automatically start on login: + +```sh +brew services start dharmab/skyeye/skyeye +``` + +To stop SkyEye and disable autostart: + +```sh +brew services stop dharmab/skyeye/skyeye +``` + +## Upgrading SkyEye + +```sh +brew update +brew upgrade dharmab/skyeye/skyeye +brew services restart dharmab/skyeye/skyeye +``` + +## Uninstalling SkyEye + +```sh +brew uninstall dharmab/skyeye/skyeye +``` diff --git a/docs/QUICKSTART-WINDOWS.md b/docs/deployment/windows/api.md similarity index 61% rename from docs/QUICKSTART-WINDOWS.md rename to docs/deployment/windows/api.md index e3885e03..1ff199fd 100644 --- a/docs/QUICKSTART-WINDOWS.md +++ b/docs/deployment/windows/api.md @@ -1,10 +1,12 @@ -# Simple Quickstart on Windows +# Deploy SkyEye on Windows - Cloud API This guide is a step-by-step on how to run SkyEye on Windows alongside DCS, TacView and SRS Server using the OpenAI API for cloud speech recognition. +You can also deploy SkyEye on Windows using either [a separate computer using speech recognition on CPU](cpu.md) or [the same computer as DCS using speech recognition on GPU](gpu.md) + ## Getting Help -See [the admin guide](ADMIN.md#getting-help) for how to get help if you have a problem. +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. ## Set up OpenAI API @@ -56,7 +58,7 @@ Confirm SkyEye is running using Also, open the `skyeye-service.err.log` in Visual Studio Code. If you see a lot of repeated WARN or ERROR lines that don't go away, something may be wrong. -Connect to your DCS game and SRS server. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](PLAYER.md).) +Connect to your DCS game and SRS server. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](../../PLAYER.md).) To stop SkyEye, run this command: @@ -64,10 +66,47 @@ To stop SkyEye, run this command: ./skyeye-service.exe stopwait ``` -For instructions on: +## Automatically Starting SkyEye on Boot + +By default, SkyEye only starts when you run `./skyeye-service.exe start`. To make it start automatically on boot: + +```powershell +./skyeye-service.exe stopwait +./skyeye-service.exe uninstall +``` + +Open `skyeye-service.yml` with a text editor and change `startmode` from `Manual` to `Automatic`, then reinstall and start SkyEye: + +```powershell +./skyeye-service.exe install +./skyeye-service.exe start +``` + +## Upgrading SkyEye + +Stop and uninstall the current version: -- Uninstalling SkyEye -- Upgrading to a newer version of SkyEye -- Automatically starting SkyEye on boot +```powershell +./skyeye-service.exe stopwait skyeye-service.yml +./skyeye-service.exe uninstall skyeye-service.yml +``` + +Download the latest release of SkyEye from https://github.com/dharmab/skyeye/releases. (Click on the file `skyeye-windows-amd64.zip`.) Extract it, then replace both `skyeye.exe` and `skyeye-service.yml` in your SkyEye folder with the new versions. + +If you enabled autostart on boot, the new `skyeye-service.yml` won't have your `startmode` setting. Re-apply it before proceeding. + +Install and start the new version: + +```powershell +./skyeye-service.exe install skyeye-service.yml +./skyeye-service.exe start skyeye-service.yml +``` + +## Uninstalling SkyEye + +```powershell +./skyeye-service.exe stopwait +./skyeye-service.exe uninstall +``` -See [the full admin guide](ADMIN.md#windows). +Delete the SkyEye folder if you no longer need it. diff --git a/docs/deployment/windows/cpu.md b/docs/deployment/windows/cpu.md new file mode 100644 index 00000000..025a9d96 --- /dev/null +++ b/docs/deployment/windows/cpu.md @@ -0,0 +1,134 @@ +# Deploy SkyEye on Windows - CPU + +This guide is a step-by-step on how to run SkyEye on a Windows computer, separate from the computer running DCS, TacView and SRS Server, using the CPU for local speech recognition. + +You can also deploy SkyEye on Windows using either [the same computer as DCS using GPU speech recognition](gpu.md) or [cloud API speech recognition](api.md). + +## Getting Help + +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. + +## Hardware Requirements + +This guide requires a **second** Windows computer, separate from the one running DCS, TacView and SRS Server. The computer running SkyEye needs a fast, multithreaded, **dedicated** CPU with support for [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2), 3GB of RAM, and about 2GB of disk space. + +CPU Series|AVX2 Added In +-|- +Intel Core|Haswell (2013) +AMD|Excavator (2015) +Intel Pentium/Celeron|Tiger Lake (2020) + +At least 4 dedicated CPU cores are recommended. Shared-core virtual machines are **not supported** and will result in high latency and stuttering audio. + +Running SkyEye's local speech recognition on CPU on the same computer as DCS is not supported; only [GPU-based local speech recognition](gpu.md) and [cloud API speech recognition](api.md) are supported on the same computer as DCS. See [the admin guide](../../ADMIN.md#deployment-with-local-speech-recognition-on-cpu) for details on why. + +## Set Up DCS, TacView, and SRS + +On the computer running DCS: + +Install DCS (either the client for singleplayer/hosted multiplayer use, or a dedicated server for multiplayer use). + +Install the TacView Exporter. Within DCS, go to OPTIONS → SPECIAL → Tacview and enable Real-Time Telemetry. (See https://www.tacview.net/documentation/dcs/en/) + +Install SRS. Start and configure the SRS Server. Ensure EAM mode is enabled and an EAM password is set. + +Make sure DCS is running an unpaused mission with both friendly and hostile air units so you can do some tests. + +## Set up SkyEye + +On the computer running SkyEye: + +Download the latest release of SkyEye from https://github.com/dharmab/skyeye/releases. (Click on the file `skyeye-windows-amd64.zip`). + +Extract the zip file somewhere convenient. + +Download a Whisper speech recognition model, such as [`ggml-small.en.bin`](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin), and save it in the folder you extracted SkyEye to. + +Open `config.yaml` with a text editor (if you don't have one, download [Visual Studio Code](https://code.visualstudio.com). I don't recommend trying to edit YAML with Notepad because it's easy to make an indentation error.) Set `recognizer` to `openai-whisper-local` and edit the rest of the file as required, then save your changes. + +```yaml +recognizer: openai-whisper-local +``` + +Open `skyeye-service.yml` with a text editor and set `whisper-model` to the path of the model file you downloaded. This file, not `config.yaml`, controls which Whisper model SkyEye loads. + +```yaml +whisper-model: C:\path\to\skyeye\ggml-small.en.bin +``` + +## Using SkyEye + +Open Windows Powershell and use the `cd` command to navigate to the folder containing `skyeye.exe`. (If you need help with this, ask ChatGPT how to do it.) + +Once you're in the correct folder, run the following command to install SkyEye. + +```powershell +./skyeye-service.exe install +``` + +Next, run this command to start SkyEye: + +```powershell +./skyeye-service.exe start +``` + +Confirm SkyEye is running using + +```powershell +./skyeye-service.exe status +``` + +Also, open the `skyeye-service.err.log` in Visual Studio Code. If you see a lot of repeated WARN or ERROR lines that don't go away, something may be wrong. + +Connect to your DCS game and SRS server. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](../../PLAYER.md).) + +To stop SkyEye, run this command: + +```powershell +./skyeye-service.exe stopwait +``` + +## Automatically Starting SkyEye on Boot + +By default, SkyEye only starts when you run `./skyeye-service.exe start`. To make it start automatically on boot: + +```powershell +./skyeye-service.exe stopwait +./skyeye-service.exe uninstall +``` + +Open `skyeye-service.yml` with a text editor and change `startmode` from `Manual` to `Automatic`, then reinstall and start SkyEye: + +```powershell +./skyeye-service.exe install +./skyeye-service.exe start +``` + +## Upgrading SkyEye + +Stop and uninstall the current version: + +```powershell +./skyeye-service.exe stopwait skyeye-service.yml +./skyeye-service.exe uninstall skyeye-service.yml +``` + +Download the latest release of SkyEye from https://github.com/dharmab/skyeye/releases. (Click on the file `skyeye-windows-amd64.zip`.) Extract it, then replace both `skyeye.exe` and `skyeye-service.yml` in your SkyEye folder with the new versions. + +The new `skyeye-service.yml` won't have your `whisper-model` setting, or your `startmode` setting if you enabled autostart on boot. Re-apply both before proceeding. + +Install and start the new version: + +```powershell +./skyeye-service.exe install skyeye-service.yml +./skyeye-service.exe start skyeye-service.yml +``` + +## Uninstalling SkyEye + +```powershell +./skyeye-service.exe stopwait +./skyeye-service.exe uninstall +``` + +Delete the SkyEye folder if you no longer need it. diff --git a/docs/deployment/windows/gpu.md b/docs/deployment/windows/gpu.md new file mode 100644 index 00000000..62524ac2 --- /dev/null +++ b/docs/deployment/windows/gpu.md @@ -0,0 +1,124 @@ +# Deploy SkyEye on Windows - GPU + +This guide is a step-by-step on how to run SkyEye on the same Windows computer as DCS, TacView and SRS Server, using the GPU for local speech recognition via the experimental Vulkan build. + +You can also deploy SkyEye on Windows using either [a separate computer using CPU speech recognition](cpu.md) or [cloud API speech recognition](api.md). + +> ⚠️ The Vulkan (GPU) build of SkyEye is experimental. Performance and speech recognition quality can vary significantly between GPU models — it might run great on one and perform poorly on another. I can only test against the GPU hardware I personally own, so I have no control over and very limited ability to troubleshoot how well the Vulkan build runs on any particular GPU or driver. + +## Getting Help + +See [the admin guide](../../ADMIN.md#getting-help) for how to get help if you have a problem. + +## Hardware Requirements + +Unlike CPU-based local speech recognition, the Vulkan build offloads speech recognition to your GPU, so it's suitable for running on the same computer as DCS. You need any decent multithreaded CPU with support for [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2), 3GB of RAM, about 2GB of VRAM, and about 2GB of disk space. + +## Set Up DCS, TacView, and SRS + +Install DCS (either the client for singleplayer/hosted multiplayer use, or a dedicated server for multiplayer use). + +Install the TacView Exporter. Within DCS, go to OPTIONS → SPECIAL → Tacview and enable Real-Time Telemetry. (See https://www.tacview.net/documentation/dcs/en/) + +Install SRS. Start and configure the SRS Server. Ensure EAM mode is enabled and an EAM password is set. + +Make sure DCS is running an unpaused mission with both friendly and hostile air units so you can do some tests. + +## Set up SkyEye + +Make sure your GPU driver is up to date. Download the latest driver from your GPU manufacturer: [NVIDIA](https://www.nvidia.com/en-us/drivers/), [AMD](https://www.amd.com/en/support), or [Intel](https://www.intel.com/content/www/us/en/support/detect.html). + +Download the latest Vulkan release of SkyEye from https://github.com/dharmab/skyeye/releases. (Click on the file `skyeye-windows-amd64-vulkan.zip`. Don't use `skyeye-windows-amd64.zip`; that's the CPU-only build.) + +Extract the zip file somewhere convenient. + +Download a Whisper speech recognition model, such as [`ggml-small.en.bin`](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin), and save it in the folder you extracted SkyEye to. + +Open `config.yaml` with a text editor (if you don't have one, download [Visual Studio Code](https://code.visualstudio.com). I don't recommend trying to edit YAML with Notepad because it's easy to make an indentation error.) Set `recognizer` to `openai-whisper-local` and edit the rest of the file as required, then save your changes. + +```yaml +recognizer: openai-whisper-local +``` + +Open `skyeye-service.yml` with a text editor and set `whisper-model` to the path of the model file you downloaded. This file, not `config.yaml`, controls which Whisper model SkyEye loads. + +```yaml +whisper-model: C:\path\to\skyeye\ggml-small.en.bin +``` + +## Using SkyEye + +Open Windows Powershell and use the `cd` command to navigate to the folder containing `skyeye.exe`. (If you need help with this, ask ChatGPT how to do it.) + +Once you're in the correct folder, run the following command to install SkyEye. + +```powershell +./skyeye-service.exe install +``` + +Next, run this command to start SkyEye: + +```powershell +./skyeye-service.exe start +``` + +Confirm SkyEye is running using + +```powershell +./skyeye-service.exe status +``` + +Also, open the `skyeye-service.err.log` in Visual Studio Code. If you see a lot of repeated WARN or ERROR lines that don't go away, something may be wrong. + +Connect to your DCS game and SRS server. Switch to one of the SkyEye frequencies you configured. Try some test commands like a RADIO CHECK, ALPHA CHECK and PICTURE. (See the [player guide](../../PLAYER.md).) + +To stop SkyEye, run this command: + +```powershell +./skyeye-service.exe stopwait +``` + +## Automatically Starting SkyEye on Boot + +By default, SkyEye only starts when you run `./skyeye-service.exe start`. To make it start automatically on boot: + +```powershell +./skyeye-service.exe stopwait +./skyeye-service.exe uninstall +``` + +Open `skyeye-service.yml` with a text editor and change `startmode` from `Manual` to `Automatic`, then reinstall and start SkyEye: + +```powershell +./skyeye-service.exe install +./skyeye-service.exe start +``` + +## Upgrading SkyEye + +Stop and uninstall the current version: + +```powershell +./skyeye-service.exe stopwait skyeye-service.yml +./skyeye-service.exe uninstall skyeye-service.yml +``` + +Download the latest Vulkan release of SkyEye from https://github.com/dharmab/skyeye/releases. (Click on the file `skyeye-windows-amd64-vulkan.zip`.) Extract it, then replace both `skyeye.exe` and `skyeye-service.yml` in your SkyEye folder with the new versions. + +The new `skyeye-service.yml` won't have your `whisper-model` setting, or your `startmode` setting if you enabled autostart on boot. Re-apply both before proceeding. + +Install and start the new version: + +```powershell +./skyeye-service.exe install skyeye-service.yml +./skyeye-service.exe start skyeye-service.yml +``` + +## Uninstalling SkyEye + +```powershell +./skyeye-service.exe stopwait +./skyeye-service.exe uninstall +``` + +Delete the SkyEye folder if you no longer need it. From cc49e2cad5701f8be3cd0bffa557ea6f8164cbcf Mon Sep 17 00:00:00 2001 From: Dharma Bellamkonda Date: Fri, 10 Jul 2026 01:53:40 -0600 Subject: [PATCH 9/9] Fix Vulkan container image tag in README The GPU image reference used a slash instead of a colon before the tag, making it point at a nonexistent image path rather than the -vulkan tag. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b519b508..145b93e6 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ See https://limakilo.net for server details. On Windows and Linux, SkyEye can be downloaded from [GitHub Releases](https://github.com/dharmab/skyeye/releases). -On Linux, SkyEye is also available as a container: `ghcr.io/dharmab/skyeye:latest` (CPU version) and `ghcr.io/dharmab/skyeye/latest-vulkan` (GPU version). +On Linux, SkyEye is also available as a container: `ghcr.io/dharmab/skyeye:latest` (CPU version) and `ghcr.io/dharmab/skyeye:latest-vulkan` (GPU version). On macOS, SkyEye can be installed using [Homebrew](https://brew.sh/):