start.pyw prueft beim Laden, ob alle Pakete vorhanden sind. Fehlt eines, installiert es requirements.txt in die virtuelle Umgebung nach und zeigt dabei ein Hinweisfenster. Scheitert das, erscheint eine verstaendliche Meldung, und der Grund landet im Fehlerlog. Das liegt bewusst in start.pyw und nicht im Update-Helfer: Der Helfer stammt aus der alten Fassung, start.pyw aus der neuen. So bekommt auch ein 3.2-Client spaeter neue Abhaengigkeiten wie Pillow fuer die Akte. Getestet: leere Umgebung wird eingerichtet, kein sichtbares Konsolenfenster; nicht installierbares Paket fuehrt zu Meldung und Log. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
350 lines
15 KiB
Markdown
350 lines
15 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 eigene Installation des Nutzers
|
|
unter `…\Programs\SquadVoiceActivation\` stammt noch von 3.1 (Setup.bat)
|
|
und hat keinen Updater.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## 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-Test gegen den Server steht aus.** Online liegt die erste 3.2,
|
|
noch unter dem alten Namen `SquadVoiceActivation-3.2.*`, und genau die ist
|
|
beim Nutzer installiert (über die 3.1 im selben Ordner). Sobald 3.3
|
|
hochgeladen ist, muss dort der Hinweisbalken erscheinen und das Update
|
|
samt Umbenennung durchlaufen — der erste echte Durchlauf des Updaters.
|
|
|
|
**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.
|