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>
This commit is contained in:
commit
f986c3ad11
22 changed files with 3288 additions and 0 deletions
314
PROJEKT-UEBERGABE.md
Normal file
314
PROJEKT-UEBERGABE.md
Normal file
|
|
@ -0,0 +1,314 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue