- Farben, Schriften, ttk-Stil und Pegelanzeige liegen jetzt in theme.py, damit mehrere Module denselben Stil nutzen, ohne sich gegenseitig zu importieren - Zwei Reiterebenen: FUNK (Mikrofon, Tasten und Verhalten) und AKTE; die Statusleiste bleibt fuer alle Module sichtbar - Zuletzt gewaehlter Hauptreiter wird gespeichert - akte.py als Platzhalter, damit das Update 3.3 -> 3.4 bereits neue Dateien mitliefert - clam-Innenabstand fuer gewaehlte Hauptreiter festgesetzt, die Schrift sprang sonst um 4 Pixel - Build nimmt theme.py und akte.py mit; Doku nachgezogen Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
17 KiB
Projektübergabe: Squad Manager
Stand: 10. September 2026 · Version 3.4 · 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\Desktop\squad-manager\ — Quelle
Arbeitsverzeichnis. Hier wird entwickelt. Der Code enthält hier Kommentare, und Texte stehen teils in Ersatzschreibung („Haelt").
squad_manager.py Hauptfenster, Funk-Modul, Updater (~1500 Zeilen)
theme.py Farben, Schriften, ttk-Stil, Pegelanzeige
akte.py Modul Akte (seit 3.4, noch Platzhalter)
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
Drei Dateien, tkinter/ttk: squad_manager.py mit Hauptfenster,
Funk-Modul und Updater (Hauptklasse VoiceActivationApp), theme.py mit
dem Stil und akte.py mit dem Modul Akte. theme.py gibt es, damit
akte.py die Farben nicht aus squad_manager.py holen muss — das wäre
ein zirkulärer Import, weil squad_manager.py die Akte einbindet.
Weitere Module gehören ebenfalls flach daneben: Installer, Update-Paket
und start.pyw erwarten flache Dateien.
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:
- Spiel nicht im Vordergrund
- per Hotkey stummgeschaltet
- eine Funktaste wird gehalten
- die Sprechtaste wird manuell gedrückt
- 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 (theme.py) |
LevelMeter |
segmentierte Pegelanzeige mit Schwellenmarke (theme.py) |
set_dark_titlebar() |
Fenstertitelleiste dunkel |
arm_autosave() |
speichert Einstellungen 600 ms nach jeder Änderung |
Oberfläche: Zwei Hauptreiter, FUNK (mit den Unterreitern „Mikrofon"
und „Tasten und Verhalten") und AKTE. Darunter für alle Module die
Statusleiste mit den Knöpfen und der Zustandsanzeige (BEREITSCHAFT /
HORCHT / SENDET / GESPERRT) — die Sprachaktivierung läuft weiter, während
man in einem anderen Modul arbeitet. Der zuletzt gewählte Hauptreiter
steht als modul in der config.json.
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_8211war 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.