Misty-Sprach-Coach/README.md

Misty Sprach-Coach

PH Weingarten · Masterstudiengang Medien- und Bildungsmanagement (MBM) · Modul M2 · WS 2025/26

📄 Projektbeschreibung

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

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:

MISTY_IP = "192.168.68.XX"  # ← aktuelle IP eintragen

Falls die Misty App nicht verfügbar ist, kann die IP so gefunden werden:

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

ssh misty2@192.168.68.62
# Passwort: misty2

Schritt 2 – Umgebung aktivieren

source ~/projekt_env/bin/activate
cd ~/misty_stream

Schritt 3 – Misty IP aktualisieren

nano config.py
# IP anpassen → Strg+O → Enter → Strg+X

Schritt 4 – Dashboard starten (Terminal 1)

python3 dashboard.py

Dashboard im Browser aufrufen:

http://192.168.68.62:5000

Schritt 5 – Coaching starten (Terminal 2 – neues SSH-Fenster)

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:

["ä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 (Achtung! Ändert sich mit jedem Start)
├── 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             ← Session wird automatisch erstellt/zurückgesetzt
├── README.md
├── LICENSE
├── requirements.txt
├── templates/
│   └── dashboard.html             ← Dashboard-Oberfläche
├── static/
│   ├── e_Love.jpg                 ← Misty Gesichtsausdrücke
│   ├── 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

---

Lizenz

MIT License – freie Nutzung und Weiterentwicklung erlaubt.

Tiffany Brugger, Giulia Carli – PH Weingarten 2026