From 2700bcab8fab4530091d97071ca7aeef7211bcf9 Mon Sep 17 00:00:00 2001
From: Jeuner <62662523+Jeuners@users.noreply.github.com>
Date: Sat, 22 Aug 2026 23:00:01 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20vollst=C3=A4ndige=20Einrichtungsanleitu?=
 =?UTF-8?q?ng,=20fehlende=20Abh=C3=A4ngigkeiten=20erg=C3=A4nzt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Die bisherigen "Voraussetzungen" reichten für eine Neuinstallation nicht: Es
fehlten FreeSWITCH, Piper samt Stimme, der Download des Whisper-Modells und
zwei Python-Pakete. Wer das Repository frisch geklont hat, wäre damit nicht
weit gekommen.

- requirements.txt: piper-tts und certifi ergänzt. certifi ist keine Kür — das
  Python von python.org bringt keinen System-Zertifikatsspeicher mit, ohne das
  Bundle scheitern die HTTPS-Aufrufe zu Nextcloud und der Stimmen-Download.
- README: Einrichtung in sechs Schritten, alle Befehle gegengeprüft (Formeln
  vorhanden, Modell-Links erreichbar).
- Abschnitt "Stolpersteine" mit den vier Dingen, die hier Zeit gekostet haben:
  FreeSWITCH liest aus dem Cellar, belegter Event-Socket-Port, rotierende
  Provider-Adressen als Ursache für abbrechende Registrierungen, und der
  Leitstand, der ohne Passwort nicht ins Netz geht.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017V57oXiDLi4nSsyau5qaA2
---
 README.md        | 69 ++++++++++++++++++++++++++++++++++++++++++++----
 requirements.txt |  7 +++++
 2 files changed, 71 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index fe6abf3..bcd1e2d 100644
--- a/README.md
+++ b/README.md
@@ -41,13 +41,72 @@ ab (lokal und optional in Nextcloud).
 rueckruf · sonstiges`
 Dringlichkeit: `niedrig · normal · hoch · notfall`
 
-## Voraussetzungen
+## Einrichtung
 
-- **Ollama** läuft (`ollama serve`) mit einem Qwen-Modell (`qwen3.5:latest`).
-- **whisper.cpp** (`whisper-cli`) + ggml-Modell, oder `STT_BACKEND=faster` für faster-whisper.
-- **ffmpeg** (Audio-Normalisierung auf 16 kHz mono).
+Getestet auf macOS (Apple Silicon). Rechnen Sie mit ~10 GB für Modelle.
 
-## Nutzung
+**1. Programme**
+
+```bash
+brew install ffmpeg whisper-cpp freeswitch
+brew install ollama && ollama serve &      # oder Ollama.app starten
+```
+
+**2. Sprachmodell** — ordnet die Anliegen ein:
+
+```bash
+ollama pull qwen3.5:latest                 # ~6,6 GB
+```
+
+Auf Rechnern mit 16 GB Arbeitsspeicher passt kein größeres Modell daneben,
+solange die Telefonie läuft.
+
+**3. Spracherkennung** — whisper.cpp braucht ein ggml-Modell:
+
+```bash
+mkdir -p ~/whisper-models && cd ~/whisper-models
+curl -LO https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
+```
+
+**4. Python-Pakete und Ansage-Stimme**
+
+```bash
+pip3 install -r requirements.txt
+# Piper lädt seine Stimmen über HTTPS - ohne CA-Bundle schlägt das fehl:
+export SSL_CERT_FILE=$(python3 -m certifi)
+python3 -m piper.download_voices --download-dir ~/piper-voices \
+        de_DE-thorsten_emotional-medium
+```
+
+**5. Konfiguration**
+
+```bash
+cp .env.example .env      # SIP-Zugang, Nextcloud, Leitstand-Passwort eintragen
+./telefon/ansage_bauen.sh
+./telefon/freeswitch/einrichten.sh
+```
+
+**6. Starten**
+
+```bash
+./telefon/starten.sh      # prüft die Voraussetzungen und startet alles
+```
+
+### Stolpersteine
+
+- **FreeSWITCH liest aus dem Cellar.** `starten.sh` übergibt deshalb `-conf`
+  auf `/opt/homebrew/etc/freeswitch`; sonst landen Trunk und Dialplan in einem
+  Verzeichnis, das jedes Homebrew-Upgrade überschreibt.
+- **Event-Socket-Port.** `fs_cli` erwartet 8021. Ist der belegt, in
+  `autoload_configs/event_socket.conf.xml` einen freien Port eintragen und
+  `FS_PORT` in `starten.sh` anpassen.
+- **Rotierende Provider-Adressen.** Löst der SIP-Hostname auf mehrere IPs auf,
+  bricht die Registrierung ständig ab: die Anmeldung landet auf einem anderen
+  Server als die Anfrage. `SIP_PROXY` auf einen Host setzen, der auf genau eine
+  IP zeigt.
+- **Der Leitstand im Netz** verlangt `LEITSTAND_PASS`, sonst startet er nicht.
+
+## Nutzung## Nutzung
 
 ```bash
 cp .env.example .env        # bei Bedarf anpassen
diff --git a/requirements.txt b/requirements.txt
index 38d3ea5..ff5a861 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1 +1,8 @@
+# Sprachsynthese der Ansage (lokal). Ohne Piper fällt ansage_bauen.sh auf das
+# macOS-eigene "say" zurück.
+piper-tts>=1.2
+# CA-Bundle: das Python von python.org bringt keinen System-Zertifikatsspeicher
+# mit, ohne certifi scheitern die HTTPS-Aufrufe zu Nextcloud.
+certifi
+# Nur nötig für STT_BACKEND=faster; der Standard ist whisper.cpp.
 faster-whisper>=1.2