squad-manager/PROJEKT-UEBERGABE.md
danny f986c3ad11 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>
2026-09-10 17:22:54 +02:00

13 KiB

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.