230 lines
7.3 KiB
Markdown
230 lines
7.3 KiB
Markdown
# 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
|
||
|
||
|
||
|
||
> 📸 Eine Übersicht der Features im Dashboard sind als Screenshots hier abgebildet: [Screenshots\_Dashboard.pdf](./Screenshots_Dashboard.pdf)
|
||
|
||
|
||
|
||
### 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
|