README: pełna instrukcja użytkowania (głos, procedury, plan lotu, konfiguracja)
This commit is contained in:
pali112 committed
1 parent
735e3335ff
commit
2b3269c683
1 file changed
+82
-16
@@ -8,21 +8,25 @@ lokalnego modelu LLM i streamuje odpowiedź ATC do okna widocznego **także w VR
|
||||
|
||||
## Funkcje
|
||||
|
||||
- **Tekstowe push-to-talk** — wpisujesz w pole i wysyłasz (przycisk, Enter lub komenda `xsayatc/ptt`).
|
||||
- **Push-to-talk głosowe** — przytrzymaj PTT, mów, puść; whisper transkrybuje, model odpowiada.
|
||||
- **Tekstowe PTT** — wpisujesz w pole i wysyłasz (przycisk, Enter lub komenda `xsayatc/ptt`).
|
||||
- **Głos wyjściowy (TTS)** — odpowiedź ATC czytana głosem (Piper).
|
||||
- **Streaming odpowiedzi** na żywo w oknie.
|
||||
- **Okno widoczne w VR** — automatycznie przełącza się między trybem monitora a `WindowVR`.
|
||||
- **Kontekst lotu** doklejany do promptu z datarefów X-Plane.
|
||||
- **Wykrywanie służby ATC** (`sim/atc/com1_tuned_facility`) — model przyjmuje rolę
|
||||
Delivery / Ground / Tower / Tracon / Center, w zależności na co jesteś nastrojony.
|
||||
- **Wykrywanie ruchu** — lista pobliskiego ruchu (AI/multiplayer) z namiarem
|
||||
zegarowym i dystansem.
|
||||
- **Konfigurowalny GUI** — adres serwera, model, temperatura, max tokenów, system prompt.
|
||||
- **Wykrywanie ruchu** — lista pobliskiego ruchu (TCAS) z namiarem zegarowym i dystansem.
|
||||
- **Plan lotu** — z natywnego FMS/GPS lub z pliku (dla samolotów z własnym FMC).
|
||||
- **Procedury ATC** — katalog `procedures/` z plikami globalnymi i per-lotnisko.
|
||||
- **Konfigurowalny GUI** — adres serwera, model, temperatura, max tokenów, system prompt, głos.
|
||||
|
||||
## Wymagania
|
||||
|
||||
- [X-Plane 12](https://www.x-plane.com/)
|
||||
- [XPPython3](https://xppython3.readthedocs.io/) v4.x (dostarcza własny Python 3.12 + `imgui` + `requests`)
|
||||
- działający serwer **llama.cpp** z endpointem OpenAI-compat (`/v1/chat/completions`)
|
||||
- **Głos (opcjonalnie):** `whisper-cli` (STT) + `piper` (TTS) + PipeWire (`pw-record` / `pw-play`)
|
||||
|
||||
## Instalacja
|
||||
|
||||
@@ -34,6 +38,18 @@ lokalnego modelu LLM i streamuje odpowiedź ATC do okna widocznego **także w VR
|
||||
3. (Opcjonalnie) skopiuj `config.example.json` jako `config.json` i dopasuj ustawienia.
|
||||
4. Uruchom X-Plane. W menu `Plugins → XSayATC` znajdziesz okno i konfigurację.
|
||||
|
||||
## Użycie (krok po kroku)
|
||||
|
||||
1. Uruchom serwer **llama.cpp** (np. na porcie `8081`).
|
||||
2. Uruchom **X-Plane 12** — wtyczka ładuje się automatycznie.
|
||||
3. Przypisz klawisz **push-to-talk**:
|
||||
**Settings → Keyboard → Plugins → XSayATC → push-to-talk**.
|
||||
(Opcjonalnie przypisz też **toggle window**, żeby pokazywać/chować okno.)
|
||||
4. Mów lub wysyłaj:
|
||||
- **Głosowo:** przytrzymaj PTT → mów → puść. Whisper transkrybuje, ATC odpowie tekstem i głosem.
|
||||
- **Tekstowo:** otwórz okno (menu Plugins → XSayATC → Pokaz/ukryj okno) → wpisz tekst → „Wyslij".
|
||||
5. Konfigurację zmienisz w oknie (przycisk **Konfiguracja**) lub w menu.
|
||||
|
||||
## Konfiguracja
|
||||
|
||||
Ustawienia trzymane są w `config.json` obok pliku wtyczki. Można je edytować
|
||||
@@ -50,31 +66,81 @@ Kluczowe opcje:
|
||||
| `system_prompt` | Instrukcje / osobowość ATC |
|
||||
| `include_flight_context` | Czy doklejać kontekst lotu do promptu |
|
||||
| `no_think` | Dodaje token `/no_think` (wyłącza myślenie w modelach Qwen3) |
|
||||
| `window_always_on_top` | Zarezerwowane |
|
||||
| `voice_enabled` | Włącza głos wejściowy (STT / whisper) |
|
||||
| `tts_enabled` | Włącza głos wyjściowy (TTS / piper) |
|
||||
| `whisper_model` | Ścieżka do modelu whisper (`ggml-*.bin`) |
|
||||
| `piper_model` | Ścieżka do modelu piper (`.onnx`) |
|
||||
| `flightplan_file` | Plik planu lotu (fallback dla samolotów z własnym FMC) |
|
||||
| `procedures_dir` | Katalog procedur (puste = `procedures/` obok wtyczki) |
|
||||
| `use_procedures` | Włącza/wyłącza wczytywanie procedur |
|
||||
|
||||
## Głos (STT + TTS)
|
||||
|
||||
- **STT (Twój głos):** przytrzymaj PTT → mów → puść. Wtyczka nagrywa przez
|
||||
`pw-record` i transkrybuje przez `whisper-cli`. Domyślny tryb `hold`.
|
||||
- **TTS (głos ATC):** po odpowiedzi modelu, tekst syntetyzowany przez `piper`
|
||||
i odtwarzany przez `pw-play`.
|
||||
|
||||
Uwaga: Piper potrzebuje **angielskiego głosu** (`en_US-*`). Dlatego naturalnie
|
||||
działa, gdy mówisz/odpowiadasz po angielsku (frazeologia lotnicza i tak jest po angielsku).
|
||||
|
||||
## Procedury ATC
|
||||
|
||||
Wtyczka czyta procedury z katalogu `procedures/` (obok `PI_XSayATC.py`):
|
||||
|
||||
```
|
||||
procedures/
|
||||
├── _global.txt ← zasady globalne (zawsze ładowane)
|
||||
├── EPWA.txt ← procedury per-lotnisko (ładowane, gdy najbliższe = EPWA)
|
||||
└── LKPR.txt ← kolejne lotniska...
|
||||
```
|
||||
|
||||
- `_global.txt` doklejany zawsze.
|
||||
- `<ICAO>.txt` doklejany, gdy najbliższe lotnisko (z natywnej bazy navaidów)
|
||||
ma ten kod ICAO.
|
||||
- Linie zaczynające się od `#` to komentarze (nie wysyłane do modelu).
|
||||
- Możesz używać nagłówków (`## Ground`, `## Tower` itd.) — model czyta to naturalnie.
|
||||
|
||||
Dodajesz plik `ICAO.txt` i wtyczka automatycznie go podchwyci, gdy będziesz w pobliżu.
|
||||
|
||||
## Plan lotu
|
||||
|
||||
- **Natywny FMS/GPS** (defaultowe samoloty): wtyczka czyta go automatycznie.
|
||||
- **Samoloty z własnym FMC** (Toliss, Zibo itd.): nie zapisują planu do natywnego
|
||||
FMS, więc podaj plik tekstowy w `flightplan_file`. Format: jedna linia = jeden
|
||||
punkt, np. `EPWA 350`, `EVINA 9000` (nazwa + opcjonalna wysokość w stopach);
|
||||
`#` = komentarz.
|
||||
|
||||
## Push-to-talk
|
||||
|
||||
Wtyczka rejestruje komendę `xsayatc/ptt`. Przypisz jej klawisz w
|
||||
**Settings → Keyboard → Plugins → XSayATC → push-to-talk**.
|
||||
Wtyczka rejestruje komendy:
|
||||
- `xsayatc/ptt` — push-to-talk (głos lub tekst),
|
||||
- `xsayatc/toggle_window` — pokaż/ukryj okno.
|
||||
|
||||
Przypisz im klawisze w **Settings → Keyboard → Plugins → XSayATC**.
|
||||
|
||||
## Uwagi techniczne
|
||||
|
||||
- **Bezpieczeństwo wątków:** odczyty datarefów (`xp.getData*`) muszą działać na
|
||||
głównym wątku X-Plane. Wtyczka zbiera kontekst w `send()` (główny wątek),
|
||||
a wątek roboczy wykonuje wyłącznie sieć (`requests`) i aktualizuje historię.
|
||||
głównym wątku X-Plane. Wtyczka zbiera kontekst, plan lotu i procedury w `send()`
|
||||
(główny wątek), a wątek roboczy wykonuje wyłącznie sieć (`requests`) i aktualizuje historię.
|
||||
- **Modele Qwen3 (reasoning):** token `/no_think` wyłącza „myślenie". Flagi
|
||||
`thinking:false` / `enable_thinking:false` nie działają w niektórych buildach
|
||||
llama.cpp — stąd domyślny `/no_think`.
|
||||
- **Ruch lotniczy** odczytywany jest z `sim/multiplayer/position/planeN_*`
|
||||
(AI / multiplayer). Jeśli nie widzisz ruchu, dodaj samoloty AI w
|
||||
**Flight → AI Aircraft**.
|
||||
llama.cpp — stąd domyślny `/no_think`. Dla innych modeli myślących wyłącz myślenie
|
||||
po stronie modelu (np. `enable_thinking: false` w configu llama.cpp).
|
||||
- **Ruch lotniczy** odczytywany jest z TCAS (`sim/cockpit2/tcas/...`), więc działa
|
||||
z LiveTraffic oraz ruchem AI X-Plane.
|
||||
- **`tuned_facility`** działa dla lotnisk z zdefiniowanym ATC w X-Plane.
|
||||
- **Polskie znaki** w oknie ImGui wyświetlają się jako `?` (domyślny font nie ma
|
||||
polskich glifów). Głos (STT/TTS) i treść promptu działają poprawnie — w praktyce
|
||||
mów/odpowiadaj po angielsku.
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [ ] Głos wejściowy (Whisper / `whisper-cli`)
|
||||
- [ ] Głos wyjściowy (Piper)
|
||||
- [ ] Rozbudowane procedury ATC (do uzupełnienia przez użytkownika)
|
||||
- [x] Głos wejściowy (Whisper / `whisper-cli`)
|
||||
- [x] Głos wyjściowy (Piper)
|
||||
- [x] Procedury ATC (katalog + dynamiczne wczytywanie)
|
||||
- [ ] Polskie znaki w oknie ImGui (custom font)
|
||||
|
||||
## Licencja
|
||||
|
||||
|
||||
Reference in new issue
Block a user