# 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-.zip`, der Installer `SquadManager-Setup-.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 ` 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.