# 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. whisper.cpp mit ROCm/GPU kompilieren

Voraussetzung: ROCm installiert (Arch: `sudo pacman -S rocm-hip-sdk`).

```bash
mkdir -p ~/src && cd ~/src
git clone https://github.com/ggml-org/whisper.cpp.git --depth=1
cd whisper.cpp

# Für AMD RX 6800 XT (gfx1030) — gfx-Target ggf. anpassen
cmake -B build -DGGML_HIP=ON -DAMDGPU_TARGETS=gfx1030 -DCMAKE_BUILD_TYPE=Release -DWHISPER_BUILD_SERVER=ON
cmake --build build -j$(nproc)

# Modell large-v3 herunterladen (~2.9 GB)
bash models/download-ggml-model.sh large-v3
```

`gfx1030` = RX 6800 XT. Andere AMD GPUs: `rocminfo | grep gfx`

### 2. Als systemd-User-Service einrichten

```bash
cat > ~/.config/systemd/user/whisper-cpp-server.service << 'EOF'
[Unit]
Description=whisper.cpp Server (ROCm/GPU)
After=network.target

[Service]
ExecStart=%h/src/whisper.cpp/build/bin/whisper-server \
    --host 0.0.0.0 \
    --port 8080 \
    --model %h/src/whisper.cpp/models/ggml-large-v3.bin \
    --language de \
    --threads 4 \
    --convert
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now whisper-cpp-server.service
```

Logs prüfen: `journalctl --user -u whisper-cpp-server -f`
GPU-Nutzung bestätigt wenn in den Logs steht: `using ROCm0 backend`

### 3. Ollama installieren (falls noch nicht vorhanden)

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

### 4. Firewall — Ports freigeben (LAN-intern)

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

```bash
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

```bash
.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 Backend | `whisper.cpp Server` |
| Whisper Server URL | `http://beastix:8080` |
| 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)

```bash
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.