feat(client): initial implementation of jellyfin htpc client with yatse remote and youtube playback

2026-11-02 21:33:42 +01:00
parent 8d6270038f
commit f66f874bae
23 changed files with 2246 additions and 0 deletions
@@ -0,0 +1,171 @@
+# Jellyfin HTPC Client & YouTube Receiver
+
+Een snelle, lichtgewicht HTPC client ontworpen voor Linux mini-PC's (x86_64). Integreert met **Jellyfin** voor het streamen van films/series en biedt volledige ondersteuning voor **Yatse** en het delen van **YouTube** video's rechtstreeks vanuit de YouTube mobiele app.
+
+---
+
+## 🌟 Belangrijkste Functies
+
+1. **Jellyfin Remote Player**:
+   - Registreert zich via WebSocket direct bij de Jellyfin server (`https://thuus.bnhmeijer.nl/jellyfin` of lokaal IP).
+   - Verschijnt automatisch als "Cast / Remote Speler" in de Jellyfin app en Yatse.
+   - Stuurt realtime voortgang, speelduur en hervatting terug naar Jellyfin.
+
+2. **Yatse & Kodi Remote Ondersteuning**:
+   - Bevat een geëmuleerde **Kodi JSON-RPC server** (standaard HTTP poort `8080` & WebSocket `9090`).
+   - Yatse kan de HTPC toevoegen als Kodi mediacenter voor volledige controle: Play/Pause, Seek, Volume, Mute, OSD notificaties.
+
+3. **YouTube Delen vanuit de YouTube App**:
+   - **Via Yatse**: Tik in de YouTube app op *Delen* $\rightarrow$ *Yatse* $\rightarrow$ de video speelt direct af op het grote scherm!
+   - **Via Web Interface / API**: Open `http://<htpc-ip>:8097/` op je telefoon om een link te plakken of de speler te bedienen.
+   - Automatische metadata-extractie (titel, uploader, speelduur) en stream extractie via `yt-dlp`.
+
+4. **Hardware-versnelde MPV Video Engine**:
+   - Gestuurd via MPV IPC Unix socket.
+   - Automatische GPU decodering (`--hwdec=auto` voor Intel QuickSync / AMD VA-API / Nvidia NVDEC).
+   - Minimale geheugenvoetprint (< 40MB RAM).
+
+---
+
+## 🏗️ Architectuur
+
+```mermaid
+flowchart TD
+    subgraph Mobile ["Telefoon / Tablet"]
+        YT[YouTube App] -->|Delen naar Yatse| Yatse[Yatse Remote App]
+        JFApp[Jellyfin Mobiel] -->|Cast naar HTPC| JFSrv[Jellyfin Server]
+        Browser[Mobiele Browser] -->|Plak YouTube Link| WebAPI[Web Remote :8097]
+    end
+
+    subgraph HTPC ["HTPC (x86_64 Linux)"]
+        subgraph Remotes
+            KodiRPC["Kodi JSON-RPC Server (:8080 / :9090)"]
+            WebAPI
+        end
+
+        subgraph Core ["jellyfin-htpc-client (Python 3.12)"]
+            JFClient["Jellyfin Client Session (WebSocket)"]
+            YTParser["YouTube Parser & yt-dlp"]
+            MPVControl["MPV IPC Controller"]
+        end
+
+        subgraph Playback ["Media Speler"]
+            MPV["MPV Video Player (GPU / VA-API)"]
+        end
+    end
+
+    Yatse -->|JSON-RPC| KodiRPC
+    JFSrv -->|WebSocket Remote Control| JFClient
+    KodiRPC --> MPVControl
+    WebAPI --> MPVControl
+    JFClient --> MPVControl
+    YTParser --> MPVControl
+    MPVControl --> MPV
+```
+
+---
+
+## 📦 Installatie op de HTPC
+
+### 1. Snel installeren via installer script
+Voer op de HTPC het installatiescript uit:
+
+```bash
+git clone https://git.bnhmeijer.nl/bart/jellyfin-client.git
+cd jellyfin-client
+chmod +x install.sh
+sudo ./install.sh
+```
+
+Het script installeert automatisch de benodigde pakketten (`mpv`, `yt-dlp`, `python3-venv`), maakt `/opt/jellyfin-client` aan met een virtuele omgeving en installeert de systemd service.
+
+---
+
+## ⚙️ Configuratie
+
+Bewerk `/etc/jellyfin-client/config.yaml` (of `config.yaml` in de projectmap):
+
+```yaml
+jellyfin:
+  server_url: "https://thuus.bnhmeijer.nl/jellyfin"  # of lokaal: http://10.2.0.4:8096/jellyfin
+  username: "bart"
+  password: "jouw_wachtwoord"
+  client_name: "Jellyfin HTPC Client"
+  device_name: "HTPC Woonkamer"
+  device_id: "htpc-woonkamer-01"
+
+player:
+  mpv_path: "mpv"
+  ipc_socket: "/tmp/mpv-jellyfin.sock"
+  hwdec: "auto"       # 'auto', 'vaapi' (Intel/AMD) of 'nvdec' (Nvidia)
+  vo: "gpu"
+  fullscreen: true
+  audio_device: "auto"
+
+kodi_rpc:
+  enabled: true
+  http_port: 8080     # Poort voor Yatse Kodi-verbinding
+  ws_port: 9090
+
+web_api:
+  enabled: true
+  host: "0.0.0.0"
+  port: 8097          # Web Remote UI & REST API
+```
+
+---
+
+## 📱 Yatse Verbinden & Gebruiken
+
+### Optie 1: Als Kodi Speler (Beste ervaring voor YouTube delen)
+1. Open **Yatse** op je Android telefoon.
+2. Ga naar **Instellingen** $\rightarrow$ **Hosts beheren** $\rightarrow$ **+** (Host toevoegen).
+3. Kies **Kodi**.
+4. Vul het IP-adres van je HTPC in en poort `8080`.
+5. Yatse detecteert direct de speler.
+6. **YouTube afspelen**: Ga in de officiële YouTube app naar een video $\rightarrow$ druk op **Delen** $\rightarrow$ selecteer **Yatse** $\rightarrow$ de video start direct op je HTPC!
+
+### Optie 2: Als Jellyfin Speler
+1. Voeg in Yatse je **Jellyfin server** toe (`https://thuus.bnhmeijer.nl/jellyfin`).
+2. Tik rechtsboven op het Cast-icoon.
+3. Selecteer **HTPC Woonkamer** als afspeeldoel.
+4. Elke film of serie die je nu kiest in Yatse speelt synchroon af via MPV op de HTPC.
+
+---
+
+## 🌐 Web Remote & Directe API
+
+Open op elk apparaat in je netwerk de browser:
+```
+http://<htpc-ip>:8097/
+```
+Hier kun je een YouTube URL invoeren, op "Play on TV" drukken en speelbediening uitvoeren (Play/Pause, -15s/+15s, Volume).
+
+### REST Endpoints
+- `POST /api/play` - `{"url": "https://www.youtube.com/watch?v=..."}`
+- `POST /api/playpause`
+- `POST /api/stop`
+- `POST /api/seek` - `{"seconds": 15}`
+- `POST /api/volume` - `{"volume": 80}`
+- `GET /api/status`
+
+---
+
+## 🛠️ Service Beheer
+
+```bash
+# Service starten en automatisch inschakelen bij opstarten
+sudo systemctl enable --now jellyfin-client
+
+# Status en logs bekijken
+sudo systemctl status jellyfin-client
+sudo journalctl -u jellyfin-client -f
+```
+
+---
+
+## 🧪 Tests Uitvoeren
+
+```bash
+.venv/bin/pytest -v
+```