Squad Voice Activation 3.2 - Ausgangsstand

Windows-Werkzeug, das die Sprechtaste in Squad haelt, solange man redet.

- Hauptprogramm mit tkinter-Oberflaeche, Pegelanzeige und Diagnose
- Auto-Updater gegen https://sva.tyrveil.com/version.json mit SHA-256-Pruefung
- Inno-Setup-Installer und Build-Skript werkzeuge/baue_release.py
- Projektuebergabe mit den bekannten Fallstricken

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-09-10 17:22:54 +02:00
commit f986c3ad11
22 changed files with 3288 additions and 0 deletions

314
PROJEKT-UEBERGABE.md Normal file
View file

@ -0,0 +1,314 @@
# Projektübergabe: Squad Voice Activation
Stand: 10. September 2026 · Version 3.2 · Git-Repository im Quellordner
Seit 3.2 wird über einen Inno-Setup-Installer und einen eingebauten
Auto-Updater verteilt (Server: https://sva.tyrveil.com), siehe Abschnitt 4.
Dieses Dokument richtet sich an eine neue Claude-Sitzung ohne Vorwissen.
Es beschreibt, was das Projekt ist, wie es aufgebaut ist und vor allem:
welche Fallstricke bereits teuer gelernt wurden. Die Abschnitte
„Hart erkaufte Erkenntnisse" und „Offene Punkte" sind die wichtigsten.
---
## 1. Was es ist
Ein Windows-Desktop-Werkzeug in Python für den Taktik-Shooter **Squad**.
Es misst laufend den Mikrofonpegel und hält per simuliertem Tastendruck die
Sprechtaste des Spiels gedrückt, solange der Nutzer redet — also Voice
Activation für ein Spiel, das nur Push-to-Talk kennt.
Kein Eingriff ins Spiel: kein Hook, keine DLL-Injektion, kein
Speicherzugriff, keine veränderten Spieldateien. Ausschließlich
`SendInput` und `GetAsyncKeyState` über `ctypes`.
**Nutzer:** Ein einzelner Anwender (deutschsprachig, spielt Squad) und sein
Freundeskreis, an den er das Programm weitergibt. Sprache der Oberfläche
und aller Dokumente ist Deutsch.
---
## 2. Ordner
Es gibt drei getrennte Orte. Das zu verwechseln war bereits mehrfach die
Fehlerquelle.
### `C:\Users\danie\Downloads\Squad_Local_Voice_Activation_v2\` — Quelle
Arbeitsverzeichnis. Hier wird entwickelt. Der Code enthält hier
**Kommentare**, und Texte stehen teils in Ersatzschreibung („Haelt").
```
squad_voice_activation.py Hauptprogramm, rund 1200 Zeilen, eine Datei
start.pyw Startskript ohne Konsolenfenster
make_icon.py erzeugt icon.ico aus icon.png
icon.png / icon.ico Programmsymbol (vom Nutzer geliefert)
requirements.txt numpy, sounddevice
werkzeuge/ Hilfsskripte für den Paketbau, siehe Abschnitt 4
README.md kurze Orientierung im Ordner
PROJEKT-UEBERGABE.md dieses Dokument
Design-Briefing.md Auftrag für Claude Design, siehe Offene Punkte
```
**Aufteilung der Pflege:** Nur die drei Python-Dateien werden hier
gepflegt und für das Paket aufbereitet. Die Skripte `Setup.bat`,
`Update.bat`, `Deinstallieren.bat`, `Fehlersuche.bat` und `Starter.vbs`
durchlaufen keine Aufbereitung und werden **direkt im Paket** gepflegt —
es gibt bewusst keine zweite Kopie in der Quelle.
### `C:\Users\danie\Downloads\Squad Voice Activation 3.1\` — altes Paket
**Vorgängerweg, seit 3.2 ersetzt** durch `dist/` und den Installer
(Abschnitt 4). Nur noch relevant, weil die lokale Installation des Nutzers
darüber eingerichtet wurde. Enthält Code ohne Kommentare und mit echten
Umlauten.
```
Setup.bat Erstinstallation
Update.bat Aktualisierung einer vorhandenen Installation
ANLEITUNG.txt Endnutzer-Dokumentation
Programm/
squad_voice_activation.py
start.pyw
make_icon.py
Starter.vbs portabler Start ohne Installation
Fehlersuche.bat Start mit sichtbarer Konsole
Deinstallieren.bat
requirements.txt
icon.png / icon.ico
```
Dazu `Downloads\SquadVoiceActivation-3.1.zip` als Versandfassung.
### `%LOCALAPPDATA%\Programs\SquadVoiceActivation\` — Installation
Zielverzeichnis. Enthält zusätzlich `.venv\`. Konfiguration und Fehlerlog
liegen getrennt davon in `%APPDATA%\SquadVoiceActivation\`.
---
## 3. Aufbau des Programms
Eine einzelne Datei, `tkinter`/`ttk`, keine Klassenhierarchie außer der
Hauptklasse `VoiceActivationApp`.
**Ablauf:** `sounddevice.InputStream` liefert Audioblöcke an einen
Callback, der den RMS-Pegel berechnet und in eine Queue legt. Ein
Arbeitsthread (`worker_loop`) liest daraus, prüft Sperrgründe und drückt
bzw. löst die Taste. Die Oberfläche aktualisiert sich unabhängig alle 80 ms
über `ui_tick`.
**Zentrale Funktion:** `blocking_reason()` gibt den Grund zurück, warum
gerade nicht gesendet werden darf, oder einen leeren String. Reihenfolge:
1. Spiel nicht im Vordergrund
2. per Hotkey stummgeschaltet
3. eine Funktaste wird gehalten
4. die Sprechtaste wird manuell gedrückt
5. Mauszeiger sichtbar (optional)
**Funktionen von Bedeutung:**
| Funktion | Zweck |
|---|---|
| `enumerate_inputs()` | Geräteliste, siehe Erkenntnis 5 |
| `squad_focused()` | Prozessname des Vordergrundfensters prüfen |
| `send_binding()` | Taste plus Zusatztaste drücken/lösen |
| `apply_tactical_theme()` | dunkles Farbschema |
| `LevelMeter` | segmentierte Pegelanzeige mit Schwellenmarke |
| `set_dark_titlebar()` | Fenstertitelleiste dunkel |
| `arm_autosave()` | speichert Einstellungen 600 ms nach jeder Änderung |
**Oberfläche:** Zwei Reiter („Mikrofon", „Tasten und Verhalten") plus eine
Statusleiste mit den Knöpfen und der Zustandsanzeige (BEREITSCHAFT /
HORCHT / SENDET / GESPERRT).
---
## 4. Release bauen, Installer und Updater
Ein Befehl erzeugt alles:
```
.venv\Scripts\python.exe werkzeuge\baue_release.py
```
Die Version kommt aus `VERSION` in `squad_voice_activation.py`. Ergebnis in
`dist/` (nicht im Repository): aufbereitete Programmdateien, das
Update-Paket `SquadVoiceActivation-<v>.zip`, der Installer
`SquadVoiceActivation-Setup-<v>.exe` und `dist/server/` mit genau den
Dateien zum Hochladen samt `version.json` (Prüfsumme wird eingetragen).
**Installer:** Inno Setup 6.7.3 unter
`%LOCALAPPDATA%\Programs\Inno Setup 6\ISCC.exe`. Skript
`installer/setup.iss`; es kopiert die Dateien und ruft danach
`installer/einrichten.bat` auf, das venv, Pakete und Verknüpfungen
anlegt. Norton lässt Inno-Setup-EXEs durch — anders als PyInstaller.
`einrichten.bat` wird **direkt** aufgerufen, nicht über `cmd /c`: dort
scheitern die verschachtelten Anführungszeichen, das venv wurde dann still
nicht angelegt.
**Updater:** `pruefe_update()` holt beim Start
`https://sva.tyrveil.com/version.json`. Neuere Version → Hinweisbalken
unten. `lade_update()` prüft SHA-256, `spiele_update_ein()` entpackt und
startet einen Hilfsprozess, der nach Programmende die Dateien ersetzt und
neu startet. Nur `https://` wird akzeptiert. Getestet: manipulierte Datei
wird abgelehnt, Dateiersatz funktioniert, `3.9 < 3.10` korrekt.
`installer/HOCHLADEN.txt` ist die Server-Anleitung für den Nutzer und wird
beim Bau nach `dist/server/` kopiert. `dist/server/` wird bei jedem Bau
gelöscht — nichts von Hand dort ablegen.
**Einzelschritte**, falls nötig: `werkzeuge/strip.py` entfernt
Kommentare, `werkzeuge/umlaute.py` setzt echte Umlaute. Danach
Zeilenenden vereinheitlichen (`.bat`/`.vbs`/`.txt` als CRLF, `.py` als LF)
und **jede BOM entfernen** — siehe Erkenntnis 7.
`werkzeuge/umlaute.py` arbeitet über `tokenize` und ersetzt nur in
STRING-Token. Achtung: In Python 3.12+ sind f-Strings **keine**
STRING-Token mehr, die müssen per Textersetzung nachbehandelt werden.
Weitere Hilfsskripte: `werkzeuge/mictest.py` prüft jedes Audiogerät in
einem eigenen Prozess mit Zeitlimit (ein hängendes Gerät blockiert sonst
alles), `werkzeuge/screenshot.py` nimmt das Fenster inklusive Titelleiste
auf.
---
## 5. Hart erkaufte Erkenntnisse
Diese Punkte wurden durch Fehlschläge gefunden. Wer sie „aufräumt", baut
die Fehler wieder ein.
**1 — `pythonw.exe` im venv ist ein Weiterleiter.**
Sie startet intern die Konsolenfassung `python.exe`, wodurch ein
Terminalfenster erscheint. Sie durch eine Kopie der echten `pythonw.exe`
zu ersetzen scheitert ebenfalls: Die Kopie findet ihre `python313.dll`
nicht (die liegt im Python-Ordner). **Lösung:** Die Verknüpfung startet die
echte `pythonw.exe` an ihrem Platz mit `start.pyw` als Argument;
`start.pyw` hängt `.venv\Lib\site-packages` selbst in `sys.path` ein.
**2 — Ein venv erbt die Tcl/Tk-Pfade nicht.**
`tkinter` findet `init.tcl` nicht und bricht mit `TclError` ab. Deshalb
läuft `_ensure_tcl_paths()` **vor** dem `tkinter`-Import und setzt
`TCL_LIBRARY`/`TK_LIBRARY` aus `sys.base_prefix`. Die ungewöhnliche
Importreihenfolge im Kopf der Datei ist Absicht.
**3 — Ein venv ist nicht portabel.**
`.venv\pyvenv.cfg` enthält feste Pfade. Auf einem anderen Rechner ist die
Umgebung unbrauchbar. Setup und Fehlersuche prüfen deshalb mit
`python -c "pass"`, ob sie überhaupt startet, und legen sie sonst neu an.
Das Weitergabepaket enthält kein `.venv`.
**4 — PortAudio-Geräteindizes wandern.**
Sie ändern sich, sobald ein Treiber dazukommt oder verschwindet. Deshalb
wird überall mit dem Anzeigenamen gearbeitet und der Index erst
unmittelbar vor dem Öffnen aufgelöst (`selected_device()`).
**5 — Windows meldet jedes Gerät über vier Schnittstellen.**
MME, DirectSound, WASAPI, WDM-KS. Beim Nutzer ergab das 18 Einträge für
2 echte Mikrofone. Regeln in `enumerate_inputs()`:
- WASAPI hat Vorrang, dann DirectSound, MME, WDM-KS
- MME kürzt Namen auf 31 Zeichen, deshalb Präfixvergleich in
`gleiches_geraet()`
- WDM-KS wird ausgeblendet, sobald WASAPI etwas liefert — dort erscheinen
Zweitnamen derselben Hardware (`wc19200_8211` war das Focusrite) und
Geräte, die in Windows gar nicht aktiv sind
- Platzhalter wie „Microsoft Soundmapper" werden entfernt
Ein Kontrollkästchen blendet die vollständige Liste wieder ein.
**6 — Batch: Pipe in `for /f`-Backticks ist unzuverlässig.**
Hat zweimal still Leerwerte geliefert (Größenangabe blieb 0, ein
Prozess-Kill lief ins Leere). PowerShell-Aufrufe in Batch deshalb **ohne
Pipe** schreiben, stattdessen `foreach` mit `if`.
**7 — PowerShell `-Encoding utf8` erzeugt in Windows PowerShell 5.1 eine BOM.**
VBScript bricht damit sofort ab (`Invalid character`, Zeile 1). Nach jeder
Bearbeitung von `.bat`/`.vbs` prüfen, dass keine BOM vorne steht.
**8 — Norton 360 verhindert PyInstaller-Builds.**
Der Build bricht mit `Permission denied` ab, unabhängig von Dateiname,
Zielordner und `--onefile`/`--onedir`. Eine fertige EXE wird beim Start
blockiert und gelöscht. Deshalb gibt es **keine EXE**; die Verteilung
läuft über Setup.bat und setzt Python beim Empfänger voraus. Eine
Norton-Ausnahme wäre nötig — das ist eine Sicherheitseinstellung und
bleibt die Entscheidung des Nutzers.
**9 — Der Windows-Audiodienst kann abstürzen.**
Ist auf diesem Rechner zweimal passiert. Dann scheitert jedes Audiogerät.
`audio_service_running()` prüft das beim Start und weist auf
`net start Audiosrv` hin (braucht Administratorrechte).
**10 — Squad heißt im Prozess `SquadGame-Win64-Shipping.exe`.**
Verglichen wird per Präfix `SquadGame`. Der frühere Vergleich über den
Fenstertitel war falsch: Er traf auch auf das eigene Programmfenster und
jeden Explorer-Ordner mit „Squad" im Namen zu.
**11 — Auf diesem Rechner gibt es zwei Python-Installationen.**
`python` zeigt auf die Microsoft-Store-Fassung (3.12), `py` auf die echte
3.13. Die Store-Fassung **virtualisiert `%APPDATA%`** — Zugriffe auf die
Konfigurationsdatei laufen dort ins Leere. Immer den venv-Interpreter
verwenden: `.venv\Scripts\python.exe`.
**12 — Layout: Die Statusleiste muss vor dem Notebook gepackt werden.**
Mit `side="bottom"`. Sonst nimmt das Notebook (`expand=True`) allen Platz
und die Knöpfe fallen aus dem Fenster. Genau das ist einmal passiert.
---
## 6. Umgebung
- Windows 11 Pro, kein Git
- Python 3.13.0 unter `%LOCALAPPDATA%\Programs\Python\Python313`
- Norton 360 aktiv, Windows Defender dadurch abgeschaltet
- Audio: Focusrite USB (Hauptmikrofon) und SteelSeries Sonar (virtuell)
- Der Nutzer testet selbst und meldet zurück; er schließt das Fenster oft
zwischendurch — ein fehlender Prozess bedeutet nicht zwingend einen Fehler
---
## 7. Offene Punkte
**Design steht aus.** Der Nutzer hat mit Claude Design einen Entwurf
gebaut („Board mit bedienbarem Fenster"), der Export kam nie an — die ZIP
lag nicht in `Downloads`. Er soll sie erneut schicken. Der Auftrag dazu
steht in `Design-Briefing.md`: Teil A ein Design System, Teil B die beiden
Bildschirme. Wichtig beim Umsetzen: Was in `ttk` nicht geht (runde Ecken,
Schatten, Verläufe), lässt sich auf einer Zeichenfläche nachbauen — die
Pegelanzeige ist bereits so gelöst.
**Server-Upload steht aus.** HTTPS auf `sva.tyrveil.com` läuft, aber
`version.json` und die Release-Dateien waren beim letzten Stand noch nicht
hochgeladen (HTTP 404). Der erste echte Durchlauf des Updaters gegen den
Server ist daher noch ungetestet.
**Installer unsigniert.** Empfänger sehen beim ersten Start die
SmartScreen-Warnung. Abhilfe nur per Code-Signing-Zertifikat.
**Programm selbst bleibt Python.** Eine gebündelte EXE per PyInstaller
scheitert an Norton (Erkenntnis 8); der Installer setzt Python beim
Empfänger voraus — bewusste Entscheidung des Nutzers.
---
## 8. Arbeitsweise, die sich bewährt hat
Der Nutzer meldet Symptome, keine Diagnosen („es öffnet sich ein
Konsolenfenster", „so viele Mikrofone"). Mehrfach lag die Ursache woanders
als vermutet, deshalb: **erst messen, dann ändern.**
Drei Beispiele, in denen Messen die Annahme widerlegt hat:
- Das Konsolenfenster kam nicht vom Startskript, sondern von einem
Kindprozess. Sichtbar wurde das erst über `ParentProcessId`.
- „Alle Mikrofone scheitern" war kein Gerätefehler, sondern der
abgestürzte Audiodienst — gefunden im Windows-Ereignisprotokoll.
- Eine Prüfung auf sichtbare Konsolenfenster meldete Entwarnung, weil die
Fensterklasse von Windows Terminal fehlte. Der Nutzer sah das Fenster
trotzdem. Ein negativer Testbefund ist kein Beweis.
Änderungen immer an der **Quelle** vornehmen, dann das Paket neu erzeugen,
dann per `Update.bat` in die Installation bringen — und dort tatsächlich
starten. Ein Syntaxcheck reicht nicht: Mehrere Fehler zeigten sich erst
beim echten Doppelklick.