diff --git a/README.md b/README.md new file mode 100644 index 0000000..ecc7070 --- /dev/null +++ b/README.md @@ -0,0 +1,210 @@ +Misty Sprach-Coach + +# Misty Sprach-Coach + +**PH Weingarten · Masterstudiengang Medien- und Bildungsmanagement (MBM) · Modul M2 · WS 2025/26** + +📄 [Projektbeschreibung](./Projektbeschreibung_MistySprachCoach.pdf) + +> Interaktiver Sprach-Coach für den Bildungsbereich auf Basis des Misty II Roboters. Erkennt Füllwörter und analysiert das Sprechtempo von Präsentationen mithilfe von OpenAI Whisper. Misty gibt direktes Feedback per Sprache und Gesichtsausdruck. Lehrende können Ergebnisse in Echtzeit auf einem Web-Dashboard verfolgen. + +--- + +## Installation & Setup + +### Voraussetzungen + +- Ubuntu-Rechner im gleichen WLAN wie Misty II +- Python 3.12 +- Virtuelle Umgebung: `~/projekt_env/` +- FFmpeg: `sudo apt install ffmpeg` + +### Installierte Pakete + +```bash +pip install -r requirements.txt +``` + +### Wichtiger Hinweis vor dem Start + +⚠️ **Mistys IP-Adresse ändert sich bei jedem Neustart!** + +1. Misty einschalten und hochfahren lassen +2. **Misty App** öffnen → aktuelle IP ablesen +3. IP in `config.py` eintragen: + +```python +MISTY_IP = "192.168.68.XX" # ← aktuelle IP eintragen +``` + +Falls die Misty App nicht verfügbar ist, kann die IP so gefunden werden: + +```bash +for i in $(seq 50 80); do echo -n "192.168.68.$i: "; curl -s --connect-timeout 1 http://192.168.68.$i/api/device | head -c 20; echo; done +``` + +--- + +## Starten + +### Schritt 1 – Mit Server verbinden + +```bash +ssh misty2@192.168.68.62 +# Passwort: misty2 +``` + +### Schritt 2 – Umgebung aktivieren + +```bash +source ~/projekt_env/bin/activate +cd ~/misty_stream +``` + +### Schritt 3 – Misty IP aktualisieren + +```bash +nano config.py +# IP anpassen → Strg+O → Enter → Strg+X +``` + +### Schritt 4 – Dashboard starten (Terminal 1) + +```bash +python3 dashboard.py +``` + +Dashboard im Browser aufrufen: +``` +http://192.168.68.62:5000 +``` + +### Schritt 5 – Coaching starten (Terminal 2 – neues SSH-Fenster) + +```bash +ssh misty2@192.168.68.62 +source ~/projekt_env/bin/activate +cd ~/misty_stream +python3 start_coaching.py +``` + +### Schritt 6 – Coaching nutzen + +1. Mistys Fuß drücken (1. Mal) → Misty sagt „Ich höre dir zu" +2. Präsentation halten +3. Mistys Fuß drücken (2. Mal) → Aufnahme stoppt +4. Whisper analysiert die Aufnahme +5. Misty gibt Feedback per Sprache und Gesichtsausdruck +6. Dashboard aktualisiert sich automatisch + +### Programm beenden + +``` +Strg+C +``` + +Misty setzt automatisch wieder das neutrale Gesicht. + +--- + +## Dashboard + +Aufruf: `http://192.168.68.62:5000` + +### Features + +- Statusanzeige in Echtzeit (wartend / aufnehmend / analysierend) +- Letzte Session: Füllwörter, Sprechtempo, Transkript, Gesicht, Feedback +- Sessionverlauf mit Fortschrittsbalken +- Füllwörter verwalten: hinzufügen und entfernen +- Fehlermeldung wenn Misty nicht erreichbar +- Live-Updates per SSE (Server-Sent Events) – kein Seitenrefresh nötig +- Heartbeat: prüft alle 5 Sekunden ob Misty erreichbar ist +- Wird beim Start von start_coaching.py automatisch zurückgesetzt + +### Füllwörter anpassen + +Die Füllwortliste kann direkt im Dashboard verwaltet werden. +Änderungen gelten ab der nächsten Session. + +Standardliste: + +```json +["äh", "ähm", "ehm", "mhm", "hm", "halt", "also", "sozusagen", "irgendwie"] +``` + +### Feedback-Logik + +| Füllwörter | Tempo | Gesicht | +|------------|--------------|-------------------| +| 0–2 | 90–150 W/min | e_Love.jpg ❤️ | +| 0–2 | außerhalb | e_Contempt.jpg 😏 | +| 3+ | 90–150 W/min | e_Contempt.jpg 😏 | +| 3+ | außerhalb | e_Sadness.jpg 😢 | + +Sprechtempo: +- unter 90 W/min → zu langsam +- 90–150 W/min → optimal +- über 150 W/min → zu schnell + +--- + +## Ordnerstruktur + +``` +misty_stream/ +├── config.py ← Misty IP-Adresse (täglich aktualisieren!) +├── analyse.py ← KI-Modul: Whisper, Füllwörter, Sprechtempo, Feedback +├── start_coaching.py ← Hauptskript: Bumper-Trigger + Aufnahme + Heartbeat +├── dashboard.py ← Flask-Webserver für Dashboard (Port 5000) +├── fuellwoerter.json ← Füllwortliste (über Dashboard anpassbar) +├── session_daten.json ← wird automatisch erstellt/zurückgesetzt +├── README.md +├── LICENSE +├── requirements.txt +├── templates/ +│ └── dashboard.html ← Dashboard-Oberfläche +├── static/ +│ ├── e_Love.jpg ← Misty Gesichtsbilder +│ ├── e_Contempt.jpg +│ ├── e_Sadness.jpg +│ └── e_DefaultContent.jpg +└── livemodus_experimentell/ ← Live-Stream (experimentell, nicht im Hauptworkflow) + ├── misty_start_av.py + ├── misty_stop_av.py + └── whisper_live_check.py +``` + +--- + +## Bekannte Einschränkungen + +- Mistys IP ändert sich bei jedem Neustart → immer in Misty App nachschauen +- Whisper base-Modell transkribiert nicht immer perfekt – small wäre genauer aber auf dem Server ohne GPU zu langsam +- FP16-Warnung im Terminal ist harmlos (kein GPU vorhanden) +- Livemodus (RTSP-Stream) wurde entwickelt aber als zu instabil eingestuft → liegt in `livemodus_experimentell/` +- Programm nur per Strg+C beendbar + +--- + +## Mögliche Weiterentwicklungen + +- Größeres Whisper-Modell (small/medium) auf leistungsstärkerer Hardware +- Livemodus stabilisieren für Echtzeit-Feedback +- Persistente Datenspeicherung über Sessions hinaus +- Mehrsprachige Unterstützung +- Benutzerverwaltung im Dashboard für mehrere Schüler + +--- + +## Teammitglieder + +- **Tiffany Brugger** – Programmierung +- **Giulia Carli** – Dokumentation & Präsentation + +--- + +## Lizenz + +[MIT License](./LICENSE) – freie Nutzung und Weiterentwicklung erlaubt. +Tiffany Brugger, Giulia Carli – PH Weingarten 2026