tueit_Transkriptor/docs/SETUP.md

tüit Transkriptor — Setup-Anleitung

Architektur

┌─────────────────────────┐         ┌──────────────────────────────┐
│  Client (Linux)         │         │  Beastix (LAN-Server)        │
│                         │   WAV   │                              │
│  Transkriptor-App       │ ──────► │  faster-whisper-server :8000 │
│  Browser-UI :8765       │  Text   │  Ollama :11434               │
│                         │ ◄────── │                              │
└─────────────────────────┘         └──────────────────────────────┘

Jeder Client läuft komplett unabhängig. Die KI-Verarbeitung (Whisper + Ollama) kann entweder lokal oder auf Beastix ausgeführt werden — konfigurierbar über die Einstellungsseite.

---

Beastix (Server-Setup, einmalig)

1. faster-whisper-server installieren

sudo pacman -S python-pipx   # Arch Linux
pipx install faster-whisper-server
pipx ensurepath

Bekannter Bug in Version 0.0.2 — fehlende pyproject.toml im pipx-venv:

cat > ~/.local/share/pipx/venvs/faster-whisper-server/lib/python*/site-packages/pyproject.toml << 'EOF'
[project]
name = "faster-whisper-server"
version = "0.0.2"
EOF

2. Als systemd-User-Service einrichten

cat > ~/.config/systemd/user/faster-whisper-server.service << 'EOF'
[Unit]
Description=faster-whisper-server (OpenAI-compatible Whisper API)
After=network.target

[Service]
ExecStart=%h/.local/bin/faster-whisper-server --host 0.0.0.0 --port 8000 --model large-v3
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now faster-whisper-server.service

3. Ollama installieren (falls noch nicht vorhanden)

curl -fsSL https://ollama.com/install.sh | sh
ollama pull gemma3:12b

4. Firewall — Ports freigeben (LAN-intern)

# Whisper-Server
sudo ufw allow from 192.168.0.0/16 to any port 8000
# Ollama
sudo ufw allow from 192.168.0.0/16 to any port 11434

Ports nur für LAN freigeben — nicht ins Internet exponieren.

---

Client-Setup (jeder Linux-Rechner)

1. Transkriptor installieren

git clone git@git.tueit.de:tueit_GmbH/tueit_Transkriptor.git
cd tueit_Transkriptor
python -m venv .venv
.venv/bin/pip install -r requirements.txt

2. App starten

.venv/bin/python main.py

Beim ersten Start: Browser öffnet sich automatisch (oder manuell: http://localhost:8765). Einmal Admin-Account anlegen, dann einloggen.

3. Beastix konfigurieren (Einstellungen → ⚙)

Als Admin einloggen → Zahnrad-Icon im Header → Einstellungen:

Feld	Wert (Beispiel)
Whisper Server URL	http://beastix:8000
Whisper Modell	large-v3
Ollama Server URL	http://beastix:11434
Ollama Modell	gemma3:12b (aus Dropdown wählen)

Leer lassen = lokale Verarbeitung (benötigt lokales Whisper-Modell).

4. Als systemd-User-Service einrichten (optional)

cat > ~/.config/systemd/user/tueit-transcriber.service << 'EOF'
[Unit]
Description=tüit Transkriptor
After=network.target

[Service]
WorkingDirectory=%h/work/tueit_Transkriptor
ExecStart=%h/work/tueit_Transkriptor/.venv/bin/python main.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now tueit-transcriber.service

---

Audio — PipeWire Combined Source

Um Mikrofon + System-Audio gleichzeitig aufzunehmen (z.B. für Konferenzen):

Einstellungen → Audio → Combined Source erstellen

• Mikrofon auswählen
• System-Audio Monitor auswählen (z.B. alsa_output.*.monitor)
• Erstellen → neues Device transkriptor-combined.monitor erscheint in der Liste
• Als Aufnahmequelle auswählen und speichern

Die PipeWire-Module werden in ~/.config/tueit-transcriber/pipewire-modules.json gespeichert. Bei App-Stop können sie mit pactl unload-module <id> entladen werden.

---

Diarisierung (Sprecher-Erkennung) — HuggingFace-Setup

Die Diarisierung verwendet das Modell pyannote/speaker-diarization-3.1. Das Modell ist kostenfrei, erfordert aber eine einmalige Zustimmung zu den Nutzungsbedingungen.

1. HuggingFace-Account

Falls noch kein Account vorhanden: https://huggingface.co/join

2. Modell-Zugriff beantragen

1. https://huggingface.co/pyannote/speaker-diarization-3.1 aufrufen
2. "Access repository" klicken und die Nutzungsbedingungen akzeptieren

3. Read-Token erstellen

1. https://huggingface.co/settings/tokens aufrufen
2. "New token" → Name z.B. transkriptor → Typ Read → erstellen
3. Token kopieren (beginnt mit hf_)

4. Token in Transkriptor eintragen

Als Admin einloggen → Zahnrad-Icon → Einstellungen → Diarisierung:

• Checkbox "Sprecher-Erkennung aktivieren" aktivieren
• Token in das Feld HuggingFace Token eintragen
• Speichern

Beim ersten Einsatz lädt pyannote das Modell herunter (~1 GB) und cached es lokal.