# Misty II als KI- gestützter Sprach-Coach im Bildungskontext

<p align="center">
  <img src="misty_logo.png" width="200" alt="Misty Sprach-Coach">
</p>


> 🤖 **Misty II Roboter** als interaktiver KI-gestützter Sprach-Coach für den Bildungsbereich  
> 🎙️ Erkennt **Füllwörter** und analysiert das **Sprechtempo** von Sprechproben mithilfe von OpenAI Whisper  
> 💬 Gibt **direktes Feedback** per **Sprache** und **Gesichtsausdruck**  
> 📊 Lehrende können Ergebnisse in Echtzeit auf einem **Web-Dashboard** verfolgen 


Dieses Projekt wurde im Rahmen des Moduls "M2 Entwicklung Interaktiver Medien" im Masterstudiengang Medien- und Bildungsmanagement (MBM) an der Pädagogischen Hochschule Weingarten entwickelt.
Eine ausführliche Beschreibung des Projektes findest du hier: [Projektbeschreibung 📄](./Projektbeschreibung_MistySprachCoach.pdf)  

---

## Installation & Setup

### Voraussetzungen

- Misty II Roboter 
- The Misty App (offizielle Begleitapp von Misty II Roboter zur Einrichtung der WLAN-Verbindung und Ermittlung der IP-Adresse)
- Ubuntu-Server im gleichen WLAN wie Misty II
- Python 3.12
- FFmpeg

### Systempakete installieren
```bash
sudo apt install ffmpeg
```

### Python-Pakete installieren
```bash
pip install -r requirements.txt
```
**Verwendete Pakete (u.a.):**
- `openai-whisper` – KI-Sprachtranskription
- `requests` – HTTP-Kommunikation mit Misty API
- `websocket-client` – WebSocket-Verbindung für Bumper-Ereignisse
- `flask` – Webserver für das Dashboard
- `numpy` – Audiodatenverarbeitung
- Misty Robotics API – REST-API und WebSocket-Schnittstelle zur Robotersteuerung

Die vollständige Paketliste ist in der `requirements.txt` aufgeführt.



## Starten der Anwendung

 ⚠️ **Voraussetzung:** Misty II, der Ubuntu-Server und das Endgerät müssen alle im gleichen WLAN sein!

### 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

⚠️ **Mistys IP-Adresse ändert sich bei jedem Neustart!**

1. **Misty App** öffnen → aktuelle IP ablesen
2. IP in `config.py` eintragen:

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

Falls die Misty App nicht verfügbar ist, kann die IP so ermittelt 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
```

Sobald neben einer IP `{"result":` erscheint → **Strg+C** drücken – das ist Mistys aktuelle IP!

### Schritt 4 – Dashboard starten

```bash
python3 dashboard.py
```

Dashboard im Browser aufrufen:
```
http://192.168.68.62:5000
```

### Schritt 5 – Coaching starten

⚠️ Für diesen Schritt ein **weiteres PowerShell-Fenster** öffnen – das aktuelle Terminal läuft für das Dashboard weiter.

```bash
ssh misty2@192.168.68.62
# Passwort: misty2
source ~/projekt_env/bin/activate
cd ~/misty_stream
python3 start_coaching.py
```

### Schritt 6 – Coaching nutzen

1. Mistys Fuß drücken → Misty sagt „Ich höre dir zu"
2. Sprechen
3. Mistys Fuß nochmal drücken → Aufnahme stoppt

Misty analysiert die Aufnahme und gibt Feedback per Sprache und Gesichtsausdruck. Die Ergebnisse werden automatisch im Dashboard angezeigt. Für eine weitere Session einfach wieder den Fuß drücken – das Skript läuft dauerhaft und beliebig viele Sessions sind hintereinander möglich.

### Programm beenden

```
Strg+C
```

---

## Dashboard

Aufruf: `http://192.168.68.62:5000`

### Features

**🟢 Echtzeit-Überwachung**
- Statusanzeige (wartend / aufnehmend / analysierend) – aktualisiert sich automatisch per SSE ohne Seitenrefresh
- Heartbeat: prüft alle 5 Sekunden ob Misty erreichbar ist und zeigt Fehlermeldung wenn nicht

**⚙️ Füllwörter verwalten**
- Füllwörter können direkt vor oder zwischen Sessions im Dashboard hinzugefügt und entfernt werden
- Standardliste: `["äh", "ähm", "ehm", "mhm", "hm", "halt", "also", "sozusagen", "irgendwie"]`

**📊 Ergebnisse der aktuellen Session**
- Anzahl der erkannten Füllwörter mit Vergleich zur vorherigen Session
- Sprechtempo in Wörtern pro Minute mit Gauge-Anzeige (zu langsam / optimal / zu schnell)
- Transkript des gesprochenen Textes
- Mistys Gesichtsausdruck als Reaktion
- Feedback-Text von Misty

**📈 Sessionverlauf**
- Zeigt alle vorhergegangenen Sessions mit Fortschrittsbalken

**🔄 Automatischer Reset**
- Dashboard und Sessionverlauf wird beim Start von `start_coaching.py` automatisch zurückgesetzt

&nbsp;

> 📸 Eine Übersicht der Features im Dashboard sind als Screenshots hier abgebildet: [Screenshots\_Dashboard.pdf](./Screenshots_Dashboard.pdf)

&nbsp;

### 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                      ← Mistys IP-Adresse (Achtung! muss mit jedem Neustart angepasst werden)
├── 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
├── requirements.txt               ← Python-Pakete
├── README.md
├── LICENSE.md
├── misty_logo.png
├── Projektbeschreibung_MistySprachCoach.pdf  ← Projektbericht
├── Screenshots_Dashboard.pdf      ← Screenshots der Dashboardfunktionen
├── templates/
│   └── dashboard.html             ← Dashboard-Oberfläche
├── static/
│   ├── e_Love.jpg                 ← Mistys 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 (keine GPU vorhanden, wechselt aber automatisch auf FP32)
- Livemodus (RTSP-Stream) wurde entwickelt aber als zu instabil eingestuft → liegt in `livemodus_experimentell/`
---

## 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](./LICENSE.md) – freie Nutzung und Weiterentwicklung erlaubt.


Tiffany Brugger, Giulia Carli – PH Weingarten 2026
