- Erkenntnis 16: Installer-Tests nur mit eigener App-ID, und in [Code] SuppressibleMsgBox statt MsgBox - Server-Anleitung: SquadVoiceActivation-3.2-Dateien nach dem Upload von 3.3 vom Server nehmen - Stand der Nutzerinstallation aktualisiert Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
365 lines
16 KiB
Markdown
365 lines
16 KiB
Markdown
# Projektübergabe: Squad Manager
|
|
|
|
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.
|
|
|
|
Das Projekt heißt seit 3.2 **Squad Manager** (vorher „Squad Voice
|
|
Activation"). Repository: `github.com/DannyShepard312/squad-manager`
|
|
(privat). Geplant ist ein zweites Modul „Akte" für Rollenspiel-Charaktere.
|
|
|
|
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-manager\` — Quelle
|
|
|
|
Arbeitsverzeichnis. Hier wird entwickelt. Der Code enthält hier
|
|
**Kommentare**, und Texte stehen teils in Ersatzschreibung („Haelt").
|
|
|
|
```
|
|
squad_manager.py Hauptprogramm, rund 1600 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
|
|
installer/ Inno-Setup-Skript, Einrichtung, Server-Anleitung
|
|
werkzeuge/ Release-Bau und Testhilfen, siehe Abschnitt 4
|
|
README.md kurze Orientierung
|
|
PROJEKT-UEBERGABE.md dieses Dokument
|
|
Design-Briefing.md Auftrag für Claude Design, siehe Offene Punkte
|
|
```
|
|
|
|
**Aufteilung:** Die Python-Dateien werden beim Release aufbereitet
|
|
(Kommentare raus, Umlaute rein). Alles unter `installer/` wird unverändert
|
|
übernommen: `setup.iss`, `einrichten.bat`, `HOCHLADEN.txt` und in
|
|
`installer/paketdateien/` die Skripte `Starter.vbs` und `Fehlersuche.bat`.
|
|
`Setup.bat`, `Update.bat` und `Deinstallieren.bat` gehören zum alten
|
|
Paketweg und sind nicht im Repository.
|
|
|
|
### `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\SquadManager\` — Installation
|
|
|
|
Standardziel des Installers, frei wählbar. Enthält zusätzlich `.venv\`.
|
|
Konfiguration und Fehlerlog liegen getrennt davon in
|
|
`%APPDATA%\SquadManager\`. Beim ersten Start werden Einstellungen aus
|
|
`%APPDATA%\SquadVoiceActivation\` übernommen — kopiert, nicht verschoben
|
|
(`alte_einstellungen_uebernehmen()`). Die frühere Installation des Nutzers
|
|
unter `…\Programs\SquadVoiceActivation\` ist gelöscht; er installiert 3.3
|
|
frisch.
|
|
|
|
---
|
|
|
|
## 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_manager.py`. Ergebnis in
|
|
`dist/` (nicht im Repository): aufbereitete Programmdateien, das
|
|
Update-Paket `SquadManager-<v>.zip`, der Installer
|
|
`SquadManager-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.
|
|
|
|
**Nachinstallation:** `start.pyw` installiert fehlende Pakete aus
|
|
`requirements.txt` beim Start nach, mit Hinweisfenster. Das liegt bewusst
|
|
dort und nicht im Update-Helfer: Der Helfer stammt aus der *alten*
|
|
Fassung, `start.pyw` aus der neuen. So bekommt auch ein 3.2-Client, dessen
|
|
Helfer nichts von neuen Paketen weiß, später etwa Pillow für die Akte.
|
|
|
|
`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.
|
|
|
|
**13 — Norton bricht HTTPS auf.**
|
|
Verbindungen kommen mit einem Zertifikat „Norton Web/Mail Shield Root" an.
|
|
Windows vertraut ihm, Git mit seiner eigenen OpenSSL-Liste nicht
|
|
(`SSL peer certificate … was not OK`). Deshalb steht in der
|
|
Repository-Konfiguration `http.sslBackend=schannel` — Git nutzt dann den
|
|
Windows-Zertifikatsspeicher, die Prüfung bleibt aktiv. `winget` braucht
|
|
aus demselben Grund `--source winget`.
|
|
|
|
**14 — Der Projektordner gehört den Administratoren, nicht dem Nutzer.**
|
|
Git verweigert dann die Arbeit (`dubious ownership`). Abhilfe:
|
|
`git config --global --add safe.directory <Pfad>` für genau diesen Ordner.
|
|
Nach einem Umbenennen des Ordners muss der Eintrag neu gesetzt werden.
|
|
|
|
**15 — Inno-Setup-Konstanten genau lesen.**
|
|
`{userstartmenu}` ist der Startmenü-Stamm, `{userprograms}` der Ordner
|
|
„Programme" darin. Die Verknüpfung liegt in letzterem; der Deinstallierer
|
|
räumte deshalb eine Zeit lang daneben ab.
|
|
|
|
**16 — Installer-Tests nie mit der echten App-ID.**
|
|
Inno Setup führt pro App-ID genau einen Eintrag unter *Apps und Features*.
|
|
Ein Test mit `/DIR=` in einen anderen Ordner überschreibt den Eintrag der
|
|
echten Installation, und die Test-Deinstallation entfernt ihn dann ganz.
|
|
Für Tests eine Kopie von `setup.iss` mit eigener `AppId` übersetzen
|
|
(`SourceDir` auf `installer/` setzen, damit die relativen Pfade stimmen).
|
|
Auch stille Deinstallationen können Dialoge öffnen, wenn `[Code]` ein
|
|
normales `MsgBox` verwendet — dort immer `SuppressibleMsgBox`.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
**Update-Weg von 3.2 ungetestet.** Online liegt noch die erste 3.2 unter
|
|
dem alten Namen `SquadVoiceActivation-3.2.*`. Der Nutzer hat seine
|
|
3.2-Installation gelöscht und installiert 3.3 frisch; der Weg 3.2 → 3.3
|
|
(alter Updater, Umbenennung) ist deshalb nie gegen den Server gelaufen.
|
|
Nach dem Upload von 3.3 die alten Dateien vom Server nehmen, damit niemand
|
|
mehr mit 3.2 anfängt. Den ersten echten Updater-Durchlauf liefert dann
|
|
3.3 → 3.4.
|
|
|
|
**Vorfall 10. September:** Ein Installer-Test mit der *echten* App-ID
|
|
hatte den Eintrag der Nutzerinstallation unter *Apps und Features*
|
|
übernommen. Bereinigt; seitdem gilt Erkenntnis 16.
|
|
|
|
**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.
|