SurepriseAi

SurepriseAi ist eine Windows-Desktop-App für intelligentes Voice-Dictation mit Dynamic Island-Overlay, Live-Transkription und KI-Text-Polishing – inspiriert von modernen Diktier-Tools, vollständig lokal auf deinem Rechner.

---

📽️ Demo (Animierter Ablauf)

Hier ist ein automatisierter Durchlauf aller wichtigen Funktionen (Aufnahme, Live-Transkription im Toast, Expanded-Ansicht mit Stil-Chips und Einstellungen):

---

🚀 Schnellstart & Installation (für Nutzer)

1. SurepriseAi-Setup.exe von GitHub Releases herunterladen.
2. Doppelklick → Setup-Assistent (Deutsch) durchlaufen.
3. Nach der Installation: Über das Tray-Icon unten rechts steuern oder F8 zum Diktieren drücken.
   • Tipp: Autostart lässt sich in Einstellungen → Mit Windows starten umschalten.

Note

Kein Python nötig – der Installer enthält alles. Einstellungen und Diktatverlauf liegen unter %APPDATA%\SurepriseAi\.

---

✨ Features & Funktionsübersicht

Vollständige Feature-Tabelle anzeigen (Einklappen/Ausklappen)

Feature	Beschreibung
Dynamic Island	Schwebendes Overlay oben am Bildschirm – Idle, Aufnahme, Verarbeitung, Ergebnis
Live-Transkription	Echtzeit-Anzeige des gesprochenen Textes während der Aufnahme
KI-Polishing	Bereinigung und Stil-Umformung via Ollama (optional) oder schnellem Offline-Fallback
8 Stil-Chips	Bereinigen · Business · Stichpunkte · Kernpunkte · Kompakt · Lang · Formell · Developer – sofort umschaltbar
Whisper & Parakeet	Lokale Spracherkennung (faster-whisper oder sherpa-onnx)
Auto-Typing	Fertiger Text wird optional direkt in die aktive Anwendung eingefügt
System-Tray	Steuerung im Hintergrund: Diktat, Stil, Einstellungen
Datei-Import	Audio/Video per Drag & Drop auf die Island transkribieren
URL-Import	YouTube, Vimeo, SoundCloud & Co. per Tray, Dialog oder Drag & Drop (yt-dlp)
Kontext-Polishing	Markierter Text + optional OCR für bessere Ollama-Korrektur
Lokale Auto-Korrektur	Füllwörter, doppelte Wörter, Selbstkorrekturen, Leerzeichen und Satzanfänge werden lokal geglättet
2-Panel-Einstellungen	Einstellungen und Diktat-Verlauf in einem professionellen Zwei-Spalten-Fenster
Diktat-Verlauf	Suche, Audio-Playback, Diff-Slider, Stil-Switch und Export als TXT, Markdown oder SRT

---

📱 Screenshots

Screenshots der Benutzeroberfläche anzeigen (Einklappen/Ausklappen)

Dynamic Island

Presence Bar	Idle Pill	Expanded View

Settings & Verlauf

Settings	2-Panel Diktat-Verlauf

Polishing & History Workflow

Diff-Ansicht	Stil-Switch im Verlauf	Detailansicht

---

📖 Bedienungsanleitung

1. Schnellstart – Diktat

1. F8 drücken und halten (Push-to-Talk) oder kurz drücken (Toggle – je nach Einstellung).
2. Sprechen – der Text erscheint live im Toast-Fenster.
3. F8 loslassen / erneut drücken → Verarbeitung startet.
4. Die Expanded-Ansicht öffnet sich mit dem bereinigten Text, Wörtern & WPM.

2. Stil wechseln

Nach dem Diktat (oder vor dem nächsten) einen Stil-Chip in der Expanded Island anklicken, um den Text anzupassen:

Chip	Wirkung
Bereinigen	Füllwörter entfernen, Satz glätten
Business	Sachlicher, professioneller Ton
Stichpunkte	Aufzählung mit •
Kernpunkte	Wichtigste Aussagen als kompakte Bullet-Liste
Kompakt	Auf das Wesentliche kürzen
Lang	Inhalt ausführen und erweitern
Formell	Höfliche, formelle Sprache

Der aktive Stil wird indigo hervorgehoben. Die Änderung erfolgt sofort (mit schnellem Offline-Fallback).

⌨️ Weitere Bedienung & Steuerungstabelle (Einklappen/Ausklappen)

Aktion	Steuerung
Island öffnen (Expanded)	Linksklick auf die Pill
Einstellungen	Doppelklick auf die Pill oder Tray → Einstellungen
Diktat starten/stoppen	F8 oder Tray → Diktat
Text kopieren	Kopieren-Icon im Textfeld
Audio-Datei transkribieren	MP3/WAV/MP4 per Drag & Drop auf die Island
Video-/Audio-URL transkribieren	Tray → URL transkribieren…, 🔗 in Expanded oder URL per Drag & Drop
Diktat-Verlauf öffnen	Tray → Diktat-Verlauf oder Einstellungen → Diktat-Verlauf
Stil im Verlauf ändern	Diktat-Verlauf → Eintrag wählen → Stil-Chip anklicken
Diktat exportieren	Diktat-Verlauf → Eintrag wählen → Exportieren… (TXT/MD/SRT)
Kontext für Polishing	Text in Ziel-App markieren, dann F8 – Ollama nutzt Markierung automatisch
Island ein-/ausblenden	Doppelklick auf Tray-Icon
Basics-Modus (Power/Restart/Sleep)	Mausrad auf der Idle-Pill

• ⠿ Griff (rechts in der Pill / oben rechts in Expanded): Fenster per Drag verschieben.
• ✕ Schließen: Expanded schließen und Island zurück an die Startposition oben zentriert bringen.

🧠 Kontextbasiertes Diktieren (OCR & Markierter Text) (Einklappen/Ausklappen)

Mit diesen Funktionen „liest“ die lokale KI (Ollama) im Hintergrund auf deinem Bildschirm mit, um dein Diktat besser zu verstehen und Fehler bei Eigennamen, Produktnamen oder Fachbegriffen zu vermeiden.

A. Bildschirmkontext (OCR)

• Was macht es? Wenn du das Diktieren startest, erfasst die App im Hintergrund den sichtbaren Text des aktuell aktiven Fensters (z. B. eine E-Mail, auf die du antworten willst).
• Wie nutzt man es?
  1. Schalte in den Einstellungen unter Bildschirmkontext (OCR) die Option „Bildschirmkontext für Polishing (lokal, Windows-OCR)“ ein.
  2. Drücke F8 und diktiere. Wenn auf dem Bildschirm bereits Namen oder Fachbegriffe stehen, die du im Diktat nennst, erkennt die KI diese automatisch und schreibt sie fehlerfrei.
• Beispiel: Du liest eine E-Mail von „Dr. Schmidt-Lüdersen“ über das Projekt „AeroSpaceX“. Du drückst F8 und sagst: „Hallo Herr Schmidt-Lüdersen...“ – Die KI liest die komplizierten Namen vom Bildschirm und schreibt sie exakt richtig.

B. Markierten Text als Kontext

• Was macht es? Die App kopiert vor dem Diktieren markierten Text in eine temporäre Variable, um der KI den exakten Arbeitskontext mitzugeben.
• Wie nutzt man es?
  1. Aktiviere in den Einstellungen unter Bildschirmkontext (OCR) die Option „Markierten Text als Kontext (Ctrl+C beim Diktatstart)“.
  2. Markiere mit der Maus oder Tastatur einen Textabschnitt in deiner Anwendung.
  3. Drücke F8 und diktiere eine Änderungsanweisung (z. B. „Formuliere das höflicher“ oder „Füge hinzu, dass wir uns am Donnerstag treffen“).
  4. Die KI kombiniert den markierten Text mit deinem Diktat und umschreibt den Abschnitt passgenau.

[!IMPORTANT] Datenschutz & Lokale Verarbeitung:
Alle Kontexterfassungen (OCR und Zwischenablage) sowie die anschließende KI-Verarbeitung (Ollama) finden zu 100 % lokal auf deinem Computer statt. Es werden zu keinem Zeitpunkt Daten, Screenshots oder Texte an externe Cloud-Server gesendet.

⚙️ System-Tray Optionen (Einklappen/Ausklappen)

Rechtsklick auf das Tray-Icon in der Windows-Taskleiste bietet schnellen Zugriff auf:

• Diktat starten / stoppen
• Polishing-Stil wählen
• URL transkribieren… (YouTube, Vimeo, …)
• Einstellungen & Diktat-Verlauf
• Nach Updates suchen… (GitHub Releases)
• App Beenden

---

🛠️ Entwickler-Dokumentation

💻 1. Lokale Installation & App-Start

Voraussetzungen

• Windows 10/11
• Python 3.11+
• Mikrofon
• (Optional) Ollama für erweitertes KI-Polishing (z. B. ollama pull gemma2:2b)

Installationsschritte

1. Repository klonen:

   git clone https://github.com/Icarus-B4/SurepriseAi.git
   cd SurepriseAi

2. Virtuelle Umgebung einrichten:

   python -m venv venv
   .\venv\Scripts\activate
   pip install -r requirements.txt

3. Konfiguration anlegen:

   copy config.example.json config.json

   Passe config.json nach Bedarf an (Hotkey, Sprache, Whisper-Modell, Ollama-URL).

4. Modell-Setup:

   • Whisper: Beim ersten Start lädt faster-whisper automatisch das konfigurierte Modell (Standard: tiny).
   • Parakeet: Für transcription_engine: "parakeet" das Modell unter models/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8/ ablegen.

App starten

.\venv\Scripts\python.exe run.py

Syntax- & Smoke-Tests

# CI-Smoke-Test
python build/ci_smoke_test.py

# Syntax prüfen
.\venv\Scripts\python.exe -m py_compile src/app.py

📦 2. Installer lokal bauen & CI/CD

Die App nutzt NSIS 3 für Hermes-Style Setup-Wizards (Benutzer-Installation, Desktop-Verknüpfung, Autostart).

Installer lokal bauen

# Ein-Klick-Build
.\Erstelle-Installer.bat

# Oder manuell (lädt NSIS bei Bedarf nach .tools/):
powershell -ExecutionPolicy Bypass -File .\build\build.ps1 -Installer

Das Ergebnis liegt als dist\SurepriseAi-Setup.exe (~140 MB) vor.

CI/CD Pipeline (GitHub Actions)

Workflow	Trigger	Aufgabe
CI	Push/PR auf main	Smoke-Test + py_compile aller Module
Release	Git-Tag v* (z. B. v0.1.11)	PyInstaller + NSIS → SurepriseAi-Setup.exe als Release-Asset

Releases werden automatisch über GitHub-Tags gebaut und hochgeladen. Die Auto-Update-Funktion in der App sucht und installiert diese Releases im Hintergrund.

⚙️ 3. Konfiguration (config.json) & Projektstruktur

Konfigurations-Parameter (config.json)

Schlüssel	Beschreibung	Standard
global_hotkey	Aufnahme-Hotkey	f8
push_to_talk	true = halten, false = Toggle	true
transcription_engine	whisper oder parakeet	whisper
whisper_model_size	tiny, base, small	tiny
transcription_language	auto, de, en, …	auto
selected_style	Standard-Stil nach Diktat	casual
ollama_polishing	KI-Polishing via Ollama	true
ollama_url	Ollama-API	http://localhost:11434
auto_copy_to_clipboard	Text automatisch kopieren	true
auto_inject_text	Text per Ctrl+V einfügen	true

Projektstruktur

SurepriseAi/
├── run.py                 # Startskript
├── config.example.json    # Konfigurationsvorlage
├── requirements.txt       # Python-Abhängigkeiten
├── src/
│   ├── app.py             # Qt-Hauptanwendung
│   ├── main.py            # Einstiegspunkt
│   ├── services/          # Audio, Transkription, Polishing, Pipeline
│   ├── ui/                # Dynamic Island, Widgets, Einstellungen
│   └── utils/             # Text-Cleaner, Win32-Overlay
├── models/                # ML-Modelle (nicht im Git)
└── AGENTS.md              # Hinweise für KI-Entwickler

---

⚠️ Bekannte Einschränkungen

• Plattform: Nur für Windows verfügbar (nutzt Win32-Overlays, Windows-OCR und SendInput).
• Latenz: Ollama-Polishing nach dem Diktat kann je nach lokaler GPU einige Sekunden dauern. Die Stil-Chips nutzen deshalb einen schnellen, regelbasierten Offline-Pfad als Direkt-Fallback.
• Genauigkeit: Whisper tiny ist extrem schnell, aber weniger präzise als small oder medium.

---

📄 Lizenz & Danksagung

Dieses Projekt steht unter der MIT-Lizenz – siehe LICENSE für Details.

Inspiriert von modernen Voice-Dictation-Tools und Fluent Design / Dynamic Island UI-Patterns.