Flaro/server/README.md

Halo-Server

Ein Medienserver, der dieselben Dinge kann wie Jellyfin — und zwei, die dort nicht gehen.

Stand: Stufe 3 von 5. Benutzer, Anmeldung, Einrichtung, Bestand einlesen, Metadaten — und Download mit allen Ton- und Textspuren, der Grund für dieses Projekt. Was noch fehlt: Streamen mit Umrechnen (HLS), Fortschritt und Gesehen-Status, Live TV. Der Entwurf samt Begründungen steht in docs/superpowers/specs/2026-10-03-halo-server-design.md.

Warum

Download mit allen Tonspuren. Jellyfins Transcode-Endpunkt bildet eine Tonspur je Sitzung ab; was offline landet, ist einspurig, und welche Spur es ist, entscheidet der Server. Einmal war es die Audiodeskription — drei Gigabyte Mobilfunk für eine Datei, die niemand hören wollte.

Fortschritt ohne Schwelle. Jellyfin merkt sich unterhalb eines Mindestanteils gar nichts. Wer zehn Minuten sieht und abbricht, findet beim nächsten Mal keinen Anknüpfungspunkt.

Betreiben

cp docker-compose.example.yml docker-compose.yml
# Pfade anpassen — jeder darin ist ein Beispiel, keiner stimmt bei dir.
docker compose up -d

Dann http://localhost:8080 öffnen; der Einrichtungsassistent legt das erste Administratorkonto an. Danach verschliesst sich dieser Weg von selbst.

Einstellungen

Variable	Bedeutung	Voreinstellung im Image
HALO_DATA	Datenbank und Einstellungen. Das Einzige, was gesichert werden muss.	/config
HALO_CACHE	Bilder und Zwischenstände. Darf verlorengehen.	/cache
HALO_TRANSCODE	Kratzplatz fürs Umrechnen. Am besten auf eine SSD.	/transcode
ASPNETCORE_URLS	Worauf gelauscht wird	http://+:8080
TZ	Zeitzone	UTC
HALO_RATELIMIT_SIGNIN	Anmeldeversuche je Minute und Adresse	10
HALO_RATELIMIT_POLLING	Nachfragen je Minute und Adresse	120

Medienpfade stehen hier nicht. Sie werden in der Oberfläche als Bibliotheken angelegt und liegen in der Datenbank — sonst müsste der Container neu starten, um eine Bibliothek hinzuzufügen.

Rechte

Das Image läuft als 1000:1000, nicht als root. Gehören die eingehängten Verzeichnisse jemand anderem, trage in der Compose-Datei user: "<uid>:<gid>" ein (id -u und id -g auf dem Wirt sagen, welche) oder übereigne sie mit chown.

Stimmt etwas nicht, bricht der Server beim Start ab und nennt Variable, Pfad, seine eigene Kennung und den nächsten Schritt. Das ist Absicht: ohne diese Meldung stünde dort nur „unable to open database file".

Hardware fürs Umrechnen

/dev/dri durchreichen — VAAPI deckt Intel wie AMD ab. Fehlt es, rechnet Halo in Software; das ist langsamer, aber es läuft. Zum blossen Umpacken wird gar keine Hardware gebraucht, und das ist der Weg, der den meisten Beständen hilft.

Entwickeln

dotnet test                       # 293 Tests
dotnet run --project src/Halo.Api # auf http://localhost:5000

Ohne gesetzte Variablen legt der Server data/, cache/ und transcode/ neben dem Programm an.

# Image bauen, beide Architekturen
docker buildx build --platform linux/amd64,linux/arm64 -t halo:dev .

# Eine Migration nach einer Modelländerung
dotnet ef migrations add <Name> --project src/Halo.Data --startup-project src/Halo.Api --output-dir Migrations

Migrationen wandern beim Start des Servers, nicht über ein eigenes Kommando.

Aufbau

Projekt	Aufgabe
Halo.Core	Domäne: Benutzer, Anmeldung, Bibliotheken. Kennt kein HTTP und keine Datenbank
Halo.Data	EF Core, SQLite, Migrationen
Halo.Media	ffprobe und ffmpeg. Als eigene Prozesse, nicht eingebunden
Halo.Metadata	TMDB und die Bildablage. Hinter einer Schnittstelle, damit alles andere ohne Netz prüfbar bleibt
Halo.Api	Endpunkte, Authentifizierung, Auslieferung der Oberfläche

Was sicherheitsrelevant ist, liegt in Halo.Core — dort ist es ohne Server prüfbar, und die Tests dazu sind die, die am meisten wert sind.

Zwei Entscheidungen, die beim Lesen Fragen aufwerfen

Zeitpunkte liegen als Unix-Millisekunden in der Datenbank, nicht als Text. SQLite hat keinen Zeittyp; ein DateTimeOffset landet sonst als Text mitsamt Zonenversatz, und dann steht …T12:00+02:00 neben …T11:00Z — derselbe Augenblick, als Text aber falsch herum sortiert. EF weigert sich deshalb, ExpiresAt > jetzt überhaupt zu übersetzen.

Token sind keine JWT. Der Server schlägt sie nach, statt sie zu prüfen. Ein nachgeschlagenes Token lässt sich sofort widerrufen; ein signiertes gilt bis zum Ablauf weiter, und für ein verlorenes Telefon ist das der falsche Satz. In der Datenbank steht nur der Fingerabdruck.

Bestand einlesen

POST /api/v1/libraries/{id}/scan    stösst an, antwortet sofort mit 202
GET  /api/v1/libraries/{id}/scan    Stand: idle | running | enriching | finished | failed
GET  /api/v1/movies?search=&skip=&take=
GET  /api/v1/series
GET  /api/v1/series/{id}/episodes?season=
GET  /api/v1/images/{schlüssel}

Der Scan läuft im Hintergrund, nicht in der Anfrage: ein Bestand mit 40 000 Titeln braucht Minuten, und eine so lange offene Anfrage läuft hinter jedem Reverse Proxy ins Zeitlimit. Einer je Bibliothek gleichzeitig.

Zweimal scannen ergibt dasselbe wie einmal. Zugeordnet wird über den Titel aus dem Dateinamen — der angezeigte kommt nach dem ersten Lauf von TMDB und ändert sich dabei.

Metadaten

Halo bringt einen TMDB-Zugang mit — es läuft ohne Einrichtung. Wer lieber seinen eigenen benutzt, hinterlegt ihn unter PUT /api/v1/settings/metadata; der sticht den mitgelieferten. Abgefragt werden kann nur, ob einer da ist und ob es der mitgelieferte ist — der Zugang selbst kommt nie zurück.

Hinterlegt werden kann beides, was auf TMDBs Kontoseite steht: der API Read Access Token (empfohlen — er geht als Authorization-Kopfzeile hinaus, nicht in der Adresse, und kann nur lesen) oder der ältere API Key.

Die Sprache steht auf en-US und wird in denselben Einstellungen umgestellt.

Bilder werden einmal heruntergeladen und liegen unter HALO_CACHE. Die App holt sie bei Halo, nicht bei TMDB: sonst bräuchte sie dafür Internet, und TMDB erführe, wer wann was ansieht.

Der Hinweis auf TMDB ist Pflicht, keine Höflichkeit. Deren Bedingungen verlangen Logo und einen festen Satz. Beides liefert GET /api/v1/system/info unter attributions — ohne Anmeldung abrufbar, damit ein Client es auch auf dem Anmeldebildschirm zeigen kann. Jeder Client muss es anzeigen.

Herunterladen — mit allen Spuren

GET /api/v1/files/{id}/delivery    was passieren wird, bevor etwas passiert
GET /api/v1/files/{id}/download    die Datei — oder 202, solange umgepackt wird

delivery zuerst fragen. Dort steht, ob die Datei unverändert hinausgeht oder umgepackt wird, welche Tonspuren dabei neu gerechnet werden müssen und welche Untertitel nicht mitkönnen. Drei Gigabyte zu laden und erst danach zu merken, dass die Untertitel fehlen, war der Anlass für dieses Projekt.

Alle Tonspuren kommen mit. Der Plan hat kein Feld „welche Tonspur" — es gibt nichts auszuwählen, weil alle mitgehen. Sprachkennungen und Spurnamen überstehen das Umpacken; nachgewiesen an einer Datei mit „Deutsch" und „Audiodeskription", die sich allein am Namen unterscheiden.

Das Bild wird nie angefasst. Es wandert Byte für Byte in die MP4. Nur Tonspuren in Codecs, die das Gerät nicht kennt — DTS, TrueHD —, werden neu gerechnet, und auch dann keine einzige Bildzeile.

Bildbasierte Untertitel fallen weg. PGS und VobSub passen in keine MP4. Das steht in delivery unter subtitlesDropped, statt stillschweigend zu geschehen.

Umgepackt wird auf die Platte, nicht in die Antwort. Der bequeme Weg wäre, ffmpeg unmittelbar durchzureichen — dann kennt aber niemand die Länge im Voraus: kein Fortschrittsbalken, kein Fortsetzen, kein Springen. Dafür gibt es HALO_TRANSCODE.

Variable	Bedeutung	Voreinstellung
HALO_FFMPEG	Pfad zu ffmpeg	ffmpeg
HALO_FFPROBE	Pfad zu ffprobe	ffprobe

Zuordnung korrigieren

GET /api/v1/movies/{id}/matches?query=&year=    Vorschläge
PUT /api/v1/movies/{id}/match                   { "tmdbId": 70523 }
GET /api/v1/series/{id}/matches?query=&year=
PUT /api/v1/series/{id}/match

Weil Raten manchmal danebengeht. Die Suche nach „Dark" lieferte „Dark Shadows" von 1966 — ohne Jahresangabe gewinnt bei TMDB der beliebteste Treffer. Dagegen hilft keine bessere Heuristik, sondern nur die Möglichkeit, es richtigzustellen.

Eine Korrektur wird festgeschrieben: in der Datenbank, in der NFO-Datei und als lockdata. Danach sucht kein Lauf mehr danach, und ein Neuaufbau der Datenbank oder ein Umzug findet die Entscheidung wieder. Bei einer Serie werden die Folgen gleich mit neu geholt — die alten gehörten zur falschen Serie.

Nur Administratoren, denn es ändert die Mediathek für alle.

Beiwerk im Medienordner

Mit HALO_WRITE_SIDECARS=true legt Halo Plakate, Hintergründe und NFO-Dateien neben den Film:

Der Untergang (2004)/
├── Der Untergang (2004).mkv
├── poster.jpg
├── fanart.jpg
└── movie.nfo

Liegen mehrere Filme in einem Ordner, heisst das Beiwerk Der Untergang (2004)-poster.jpg — sonst überschrieben sie sich gegenseitig. Serien bekommen tvshow.nfo eine Ebene über dem Staffelordner, Folgen je eine NFO und ein Standbild neben der Datei.

Standardmässig aus, und die Medieneinhängung muss dafür ohne :ro auskommen. Was Halo schreiben darf, steht als Erlaubnisliste im Code (SidecarNames): alles andere wird abgelehnt, und Mediendateien werden nie geändert, umbenannt oder gelöscht. Transcode-Zwischenstände kommen nie in einen Medienordner — die liegen unter HALO_TRANSCODE.

Gelesen wird auch ohne Schreiberlaubnis. Eine vorhandene NFO ist eine Zuordnung, die jemand getroffen hat; Halo nimmt sie und sucht gar nicht erst. Dasselbe gilt für Ordnernamen der Form Der Untergang (2004) [tmdbid-613] — Halo liest sie, benennt aber nichts um. Umbenennen ist der einzige Eingriff, der eine Bibliothek wirklich zerlegen kann.

Variable	Bedeutung	Voreinstellung
HALO_WRITE_SIDECARS	Beiwerk in den Medienordner schreiben	false

Anmeldung am Fernseher

Ein Passwort auf der Apple-TV-Fernbedienung zu tippen ist eine Zumutung. Stattdessen:

1. Der Fernseher fordert an und bekommt einen sechsstelligen Code für den Bildschirm und einen Abholschein, den nur er kennt.
2. Am Telefon, angemeldet, wird der Code bestätigt — dort steht, welches Gerät.
3. Der Fernseher holt mit seinem Abholschein das Token ab.

Der Code allein holt nie ein Token ab. Ohne den Abholschein wären sechsstellige Codes ein Türschloss mit einer Million Schlüsseln.

Lizenz

GPL-2.0-only. Abhängigkeiten müssen dazu passen: MIT, BSD oder GPL-2.0. Apache-2.0 ist ausgeschlossen — Einzelheiten und der Grund stehen in LICENSES.md.