Fehlerbehebung

Wählen Sie einen Abschnitt nach Symptom. Jeder enthält eine Checkliste und geordnete Fixes. Abbildungen sind UI-Vorschau-PNGs (public/screenshots/ts-*.webp, make docs-screenshots).

Zuerst notieren: diese fünf Punkte

1. macOS-Version
2. VoiceHotkey-Version (Einstellungen → Info)
3. Name der Erkennungs-Engine
4. Nur-lokal an/aus
5. App-Pfad (Finder → Informationen)

Datenschutz

Niemals API-Schlüssel, Lizenzgeheimnisse oder sensible Transkripte einfügen. Siehe Kontakt.

---

Hotkey reagiert nicht

Kein Overlay, kein Statuswechsel in der Menüleiste, kein Systemfeedback.

Checkliste

• Menüleistensymbol vorhanden (App läuft)
• Bedienungshilfen für den aktuellen App-Pfad aktiviert
• Gestartet aus /Applications oder ~/Applications
• Hotkey kollidiert nicht mit einer anderen App
• Hotkey-Seite warnt nicht wegen Bedienungshilfen

Schritte

1. Prozess — Das Menüleistensymbol sollte ein Menü öffnen. Fehlt es, aus Programme neu starten.
2. Bedienungshilfen — Systemeinstellungen → Datenschutz & Sicherheit → Bedienungshilfen. Ein VoiceHotkey-Eintrag, korrekter Pfad, Schalter an. Duplikate entfernen, App beenden und neu öffnen.
3. Stabiler Pfad — Siehe Installation & Berechtigungen.
4. Neu belegen — Einstellungen → Tastenkürzel → eine seltener genutzte Kombination aufzeichnen.
5. Konflikte — Tools beenden, die mit den Standards kollidieren: Spracheingabe ⌃⌥Space, Befehl ⌃⌥C.

Abb. A · Bedienungshilfen-Liste (UI-Vorschau · ts-01-accessibility-list.webp)

---

Aufnahme, aber kein Text

Overlay zeigt Zuhören, aber das Feld bleibt leer oder die Verarbeitung endet nicht.

Checkliste

• Demo-Modus aus
• Mikrofon erteilt; korrektes Eingabegerät
• Engine konfiguriert (Schlüssel / Apple bereit)
• Nur-lokal blockiert keine Cloud-Engine
• Netzwerk / Kontingent / Schlüssel gültig
• Einfügemarke in einem normalen Textfeld (sichere Felder können Einfügen blockieren)

Schritte

1. Einstellungen → Allgemein — Demo-Modus ausschalten.
2. Menüleistenstatus lesen — Mikrofon nötig, Engine nicht konfiguriert, Nur-lokal blockiert usw.
3. Mikrofon — für VoiceHotkey aktivieren; Hardware mit Sprachnotizen prüfen.
4. Engine — Apple als Kontrolle versuchen. Funktioniert Apple, Cloud aber nicht → Schlüssel/Netzwerk/Kontingent.
5. Nur-lokal — öffentliche Engines schlagen fehl, wenn Nur-lokal an ist.
6. Ausgabe — Textverarbeitung Ausgabeaktion sollte an der Einfügemarke einfügen; in Notizen testen, falls Terminal die Injektion blockiert.

Abb. B · Menüleistenstatus (UI-Vorschau · ts-02-menubar-status.webp)

Abb. C · Nur-lokal (UI-Vorschau · ts-03-local-only.webp)

---

Berechtigungen gehen immer wieder verloren

Gestern funktioniert; Hotkey heute tot; Bedienungshilfen wirken halb gesetzt.

Häufige Ursachen

Ursache	Hinweise
Pfad geändert	Downloads, anderer Ordner oder anderer Build-Pfad
Signatur / Ersetzen	Überschreibende Installation als neue App behandelt
Doppelte Einträge	Falscher Bedienungshilfen-Eintrag gebunden

Beheben

1. Nur eine App in Programme behalten.
2. VoiceHotkey vollständig beenden.
3. Alle VoiceHotkey-Einträge unter Bedienungshilfen und Mikrofon entfernen.
4. Vom festen Pfad starten und erneut freigeben.
5. Immer denselben Pfad öffnen (Debug- vs. Release-Pakete gelten als unterschiedliche Pfade).

---

Politur / Übersetzung unverändert

• Aufbereitung aktiviert / der Übersetzungs-Hotkey wird genutzt
• LLM-Schlüssel in der Textverarbeitung konfiguriert
• Nur-lokal blockiert die API nicht
• Fallback kann das Rohtranskript einfügen (bei Fehlern erwartet)

1. Einstellungen → Textverarbeitung: Aufbereitung an; Übersetzung nutzt eigenen Hotkey.
2. LLM-Anbieterschlüssel konfigurieren.
3. Mit ausgeschaltetem Nur-lokal vergleichen oder Base URL auf localhost zeigen.
4. Sicherstellen, dass reines Spracheingabe funktioniert, bevor die Aufbereitung aktiviert wird.

---

Sprachbefehle reagieren nicht

• Einstellungen → Sprachbefehle: ist „Sprachbefehle aktivieren“ oben eingeschaltet?
• Befehlshotkey kollidiert nicht mit Spracheingabe/Übersetzung und Bedienungshilfen ist erteilt
• „Tastenkürzel erlauben“ nicht deaktiviert (nur Wörterbuch-Kürzel schlagen sonst fehl)
• Wörterbucheinträge aktiviert und Phrasen stimmig (erst exakt, dann unscharf)

Siehe Sprachbefehle.

---

Shell-Befehl läuft nicht

• Hauptschalter „Sprachbefehle aktivieren“ eingeschaltet
• Trial oder Pro (nicht Free)
• Einstellungen → Sprachbefehle → Shell-Befehle erlauben aktiviert
• Bestätigungsdialog nicht abgebrochen
• Nicht von der Gefahren-Blockliste gesperrt
• Wenn über Intents gelöst: Intent-Modell aktiv und konfiguriert; wenn über das Benutzerwörterbuch: Eintrag vom Typ Shell und aktiviert

Siehe Shell-Befehle und Pläne.

Abb. D · Lizenz (UI-Vorschau · ts-04-license.webp)

---

Schnellszenarien

Frische Installation

1. Pfad + beide Berechtigungen
2. Demo-Modus aus
3. Eine funktionierende Engine
4. In Notizen testen

Nach Update

1. Neuen Build aus Programme starten
2. Veraltete Bedienungshilfen-Einträge löschen und neu freigeben
3. Version unter Info bestätigen

Arbeitsnetzwerk / Datenschutz

1. Cloud-APIs müssen erreichbar sein
2. Oder Apple, die vier On-Device-Engines oder localhost nutzen
3. Nur-lokal pausiert auch Update-Prüfungen

---

Immer noch stecken?

1. Den Ersteinrichtungs-Probelauf erneut ausführen.
2. Die fünf Punkte oben sammeln.
3. Ein Issue über Kontakt melden.

Installation & BerechtigungenDMG, Pfad, Bedienungshilfen, Mikrofon.

ErsteinrichtungDemo-Modus, Engine, Tastenkürzel, Test.