docs: komplette CallRec-Dokumentation mit Mermaid-Diagrammen

Architektur, Hardware/Thermik, PipeWire-Audio-Topologie, Aufnahme-Pipeline, Diarization (Anchor-Merge), LLM-Analyse (Gemma-3-4B/NPU), iPhone-BT-HFP, Betrieb/Troubleshooting und Changelog-Chronik. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-16 10:51:22 +02:00
commit db3d946592
9 changed files with 657 additions and 0 deletions
@@ -0,0 +1,74 @@
+# 06 — iPhone-Telefonate über Bluetooth (HFP)
+
+Das Board gibt sich gegenüber dem iPhone als **Bluetooth-Headset** aus („Aime“, AX210/`hci0`). iPhone-Anrufe
+laufen dadurch über das Board: Gegenseite → Aufnahme-Mix, Nutzer-Mikrofon (gegated) → iPhone-Uplink.
+Läuft **parallel** zum PC/USB-Gadget-Pfad — kein Umschalten; bei eingehendem Anruf pausiert der Nutzer sein
+PC-Video manuell.
+
+## Konfiguration (die funktionierende Kombination)
+
+- WirePlumber-Drop-in: `bluez5.roles = [a2dp_sink hfp_hf hsp_hs]` + `hfphsp-backend = native`
+  (oFono war ein Irrweg, deaktiviert).
+- **Frischer Pair nötig** (auf dem iPhone „Gerät ignorieren“, dann neu koppeln) — alte Bonds machen Ärger.
+- iPhone „Skynet16“ (B4:96…), bt-agent NoInputNoOutput, Gerät muss **Trusted=yes** sein
+  (nach Re-Pair stand es auf NO → WirePlumber baut für untrusted Geräte keine HFP-Nodes → Aufnahme #58
+  hatte nur die Nahseite).
+- Einziger Verzicht: BT-Ohrhörer als Aufnahmegerät (AG-Rolle) ist aus — Board ist HF-only.
+- `profile="off"` zwischen Anrufen ist **normal**: HFP-Nodes existieren nur während eines aktiven Anrufs
+  (eSCO/mSBC, 16 kHz).
+
+## Audio-Routing während eines Anrufs
+
+```mermaid
+flowchart LR
+    subgraph IPHONE["iPhone (im Anruf)"]
+        CALL["Telefonat"]
+    end
+    subgraph BOARD["Board (BT 'Aime')"]
+        FAR["bluez_input.MAC.0<br/>= Gegenseite"]
+        UP["bluez_output.MAC.1<br/>= Uplink zum iPhone"]
+        MIX[("callmix")]
+        GATE["micgate.out (gegatetes Mikro)"]
+        HS["Headset-Hörer"]
+    end
+    CALL --> FAR
+    FAR --> MIX
+    FAR --> HS
+    GATE --> UP --> CALL
+```
+
+**Echo-Fix:** WirePlumber verlinkte den Uplink zunächst mit `callrec_mix` (ungegatetes Mikro + Gegenseite
+selbst!) → Gegenseite hörte sich selbst. Korrekt: Uplink ← **micgate.out**. Vom Nutzer bestätigt echofrei.
+
+## Automatik
+
+```mermaid
+sequenceDiagram
+    participant IP as iPhone
+    participant BZ as BlueZ/WirePlumber
+    participant W as aime-iphone-route.sh (Watcher)
+    participant PW as PipeWire
+
+    IP->>BZ: Anruf beginnt (eSCO aufgebaut)
+    BZ->>PW: HFP-Nodes erscheinen (bluez_input/.0, bluez_output/.1)
+    W->>PW: erkennt neue Nodes
+    W->>PW: Gegenseite → callmix + Headset verlinken
+    W->>PW: Uplink ← micgate.out verlinken (Echo-Fix)
+    IP->>BZ: Anruf endet
+    BZ->>PW: HFP-Nodes verschwinden (profile=off — normal)
+```
+
+- Watcher persistent: `/opt/callrec/aime-iphone-route.sh` + `aime-iphone-route.service`; überlebt Reboots
+  (Config/Service/Bond+Trusted verifiziert).
+- Der Watcher-Neustart lässt callmix/Loopbacks intakt.
+
+## Offen
+
+- App-seitiger automatischer Aufnahme-Start bei iPhone-Anrufen.
+- Voller E2E-Test „Anruf → Aufnahme → Analyse“ über den BT-Pfad.
+
+## Referenz: BT-Bond-Quirks (Ohrhörer, historisch)
+
+Buds mit No-Bonding-Quirk: LinkKey musste manuell in `/var/lib/bluetooth` persistiert werden
+(btmon-Capture-Prozedur). RTL8821CU-Wedge-Recovery (USB-Reset, nur über LAN .50) — betrifft den alten
+Dongle, der entfernt wurde; nur noch relevant, falls die Hardware zurückkommt.