Media Server
& Smart Streaming

1.1 Was ist der XteVision Media Server?

Der **XteVision Media Server** (xtevision-media-server v1.0.0) ist ein lokaler Video-Streaming-Server, der Filme und Videodateien aus einem Verzeichnisbaum über das Netzwerk bereitstellt. Er bietet eine moderne Web-Oberfläche zum Durchsuchen, Filtern und Abspielen von Videos in jedem Browser — ohne zusätzliche Software-Installation auf dem Client. Er ist für die Re-Branding-Nutzung durch jedes Unternehmen konzipiert.

1.2 Kernfunktionen

• Browser-basierte Medienbibliothek — alle Videos als Grid mit Thumbnails
• Kategorisierung nach Ordnern — Projekte/Kunden als Filter-Buttons
• Smart Streaming — automatische H.264-Konvertierung für nicht unterstützte Codecs
• Thumbnail-Generierung — automatisch aus der Videodatei extrahiert
• Mehrsprachig — Englisch, Deutsch, Chinesisch
• Dark/Light-Modus — umschaltbares Design
• Playlist-Funktion — automatische Wiedergabe des nächsten Videos

1.3 Zielgruppe

• Primär: Unternehmen, die interne/Produktions-Videos (Projektfootage, Kundenaufnahmen, Schulungsinhalte) über ein LAN in jedem Browser streamen müssen
• Sekundär: Jede Organisation, die eine selbst gehostete, client-freie Medienbibliothek mit intelligenter Codec-Rückfalloption benötigt

2.1 High-Level-Architektur

┌─────────────────────────────────────────────────────────────────┐
│                         Browser (moderner Browser)                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────────────────────┐  │
│  │ Video-    │ │ Kategorie │ │ Video-Player (HTML5-Modal)         │  │
│  │ Gried     │ │-Filter    │ │ + intelligenter Codec-Fallback    │  │
│  └──────────┘ └──────────┘ └──────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/REST-API
┌──────────────────────────────┴──────────────────────────────────┐
│                    Node.js-Server — Express.js (Port 5002)         │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────────┐  │
│  │ /videos     │ │ /thumbnail  │ │ /video/    │ │ FFmpeg (transcod.) │  │
│  │ (Liste)     │ │ (JPEG)      │ │ original   │ │ H.264 + AAC        │  │
│  │             │ │             │ │ /h264      │ │                    │  │
│  └───────────┘ └───────────┘ └───────────┘ └──────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────────┐
│                    Dateisystem (Quelle der Wahrheit)               │
│  video/  →  Ordnerybaum (Kategorien)                                │
│  .cache/ →  h264/ + thumbnails/                                    │
└───────────────────────────────────────────────────────────────────┘

2.2 Kommunikationsablauf

1. Frontend → Server: GET /videos listet alle Dateien auf; GET /thumbnail/... lädt JPEGs; GET /video/original/... und GET /video/h264/... streamen Medien
2. Server → Dateisystem: readdirSync() liest den video/-Baum bei jedem /videos-Aufruf
3. Server → FFmpeg: Thumbnails und H.264-Konvertierungen werden bei Bedarf generiert, dann gecached

2.3 Bereitstellungsmodell

Der XteVision Media Server ist für selbst gehosteten, LAN-only-Betrieb konzipiert:

• Läuft als eigenständiger Node.js-Server auf Ihrer eigenen Hardware
• Keine Datenbank — das Dateisystem ist die Quelle der Wahrheit
• Keine Authentifizierung — für lokalen LAN-Gebrauch ausgelegt
• FFmpeg ist über ffmpeg-static eingebettet

4.1 Voraussetzungen

• Node.js v18 oder höher
• NPM (wird mit Node.js installiert)

4.2 Installation

# 1. Ins Projektverzeichnis wechseln
cd /pfad/zu/video_server

# 2. Abhängigkeiten installieren
npm install

Dabei werden folgende Pakete installiert:

4.3 Server starten

npm start
# oder: node server.js

Der Server läuft dann auf http://localhost:5002. Konsolenausgabe bei erfolgreichem Start:

Using ffmpeg: /pfad/zu/ffmpeg-static
Video server running at http://localhost:5002

4.4 Im Hintergrund laufen lassen (Linux/macOS)

nohup node server.js > server.log 2>&1 &

5.1 Video-Verzeichnis

Alle Videos liegen im Ordner video/ im Projektverzeichnis. Die Struktur ist nach Kunden/Projekten organisiert:

video/
├── Anting/
│   ├── anting.mp4
│   ├── biergarten720p.m4v
│   └── tiky_xuyun720p50.mp4
├── Porsche_VW/
├── Deutsche-Schule/
├── prodigy/
│   ├── prodigy_cn.mp4
│   ├── prodigy_de.mp4
│   └── prodigy_en.mp4
└── ...

5.2 Neue Videos hinzufügen

1. Video-Datei in den gewünschten Unterordner von video/ kopieren
2. Neu laden der Webseite — der Server scannt das Verzeichnis bei jedem Aufruf von /videos neu

5.3 Unterstützte Formate

6.1 Layout

Die Web-Oberfläche unter http://localhost:5002 ist in drei Bereiche unterteilt:

• Header: Titelzeile, Sprachauswahl (English / Deutsch / 中文, in localStorage gespeichert) und Theme-Umschalter (Dark/Light)
• Kategorien (Folder-Buttons): alle gefundenen Unterordner als Filter-Buttons; „Alle" zeigt alle Videos an
• Video-Grid: Rasteransicht mit Thumbnail, Titel, Ordnername und Play-Button-Overlay

6.2 Video-Player (Modal)

Nach Klick auf ein Video öffnet sich ein Overlay-Player:

• HTML5-Video-Player mit Steuerelementen (Play/Pause, Lautstärke, Vollbild, Zeitleiste)
• Playlist — alle Videos der aktuellen Kategorie als Liste; automatische Weiterleitung zum nächsten Video
• Schließen — Klick auf × oder Drücken von Esc

6.3 Smart Codec Fallback

Der Player erkennt automatisch, ob der Browser das Video nativ abspielen kann:

1. HEVC/H.265-Unterstützung prüfen → wenn ja, wird die Originaldatei gestreamt
2. Kein HEVC-Support → sofort auf H.264-Konvertierung umschalten
3. Fehler beim Abspielen → automatischer Fallback auf H.264
4. Keine Videospur erkannt → Wechsel zu H.264

7.1 Endpunkte

7.2 Beispiele

# Alle Videos auflisten
curl http://localhost:5002/videos

# Thumbnail abrufen
curl http://localhost:5002/thumbnail/Anting/anting.mp4

# Original streamen (mit Range-Unterstützung)
curl http://localhost:5002/video/original/Anting/anting.mp4

# H.264-konvertierte Version streamen
curl http://localhost:5002/video/h264/Anting/anting.mp4

[
  "Anting/anting.mp4",
  "Anting/biergarten720p.m4v",
  "prodigy/prodigy_cn.mp4"
]

8.1 H.264-Streaming

Wenn ein Video nicht nativ abgespielt werden kann, konvertiert der Server es automatisch in H.264 + AAC — das Format, das jeder moderne Browser abspielen kann.

8.2 Thumbnails

• Frame-Position — 2 Sekunden nach Video-Start
• Auflösung — 480px Breite, proportionale Höhe
• Qualität — JPEG-Qualität 2 (hohe Qualität)
• Timeout — 30 Sekunden pro Thumbnail

Um den Server zu entlasten, werden Thumbnail-Generierungen in eine Warteschlange gelegt. Gleichzeitige Anfragen für dasselbe Thumbnail werden zusammengefasst (Deduplizierung). Generierte Thumbnails liegen in .cache/thumbnails/ und werden 24 Stunden lang direkt ausgeliefert (Cache-Control: public, max-age=86400).

8.3 Cache-Verwaltung

.cache/
├── h264/          # H.264-konvertierte Videos
└── thumbnails/    # JPEG-Thumbnails

Beide Verzeichnisse spiegeln die Ordnerstruktur von video/ wider. Um den gesamten Cache zu löschen (z. B. nach Änderungen an den Originaldateien):

# Cache-Verzeichnisse löschen
rm -rf .cache/h264/* .cache/thumbnails/*

# Oder die gesamten Cache-Ordner
rm -rf .cache

9.1 Server startet nicht

• Port bereits belegt: Mit lsof -i :5002 prüfen, dann den Prozess beenden (kill -9 [PID]).
• FFmpeg-Fehler: Using ffmpeg: undefined bedeutet, ffmpeg-static ist nicht korrekt installiert — npm install ffmpeg-static ausführen.

9.2 Video wird nicht abgespielt

• Schwarzer Bildschirm im Player: Der Browser unterstützt den Codec nicht. Der Server sollte automatisch auf H.264 fallen — prüfen, ob der .cache/h264/-Ordner beschreibbar ist.
• „Video not found” (404): Prüfen, ob die Datei im video/-Verzeichnis existiert. Dateinamen mit Sonderzeichen werden URL-kodiert erwartet.

9.3 Thumbnail wird nicht angezeigt

• „Thumbnail generation failed” (500): FFmpeg kann das Video nicht lesen → die Datei ist möglicherweise korrupt. Prüfen, ob der .cache/thumbnails/-Ordner beschreibbar ist.
• Thumbnail ist schwarz: Das Video hat möglicherweise keinen Videostream bei 2 Sekunden (z. B. sehr kurze Videos). Der Server nimmt standardmäßig den Frame bei 2 Sekunden (-ss 2).

9.4 Konvertierung dauert sehr lange

• Große Videos (mehrere GB) benötigen Zeit für die H.264-Konvertierung. Das ist normal. Die erste Anfrage blockt, bis die Konvertierung fertig ist; alle weiteren Aufrufe sind sofort.