ScarriffleandClaude Opus 5
e4a90fce4e
**Der Grund, warum es diesen Server gibt.** Eine MKV mit zwei Tonspuren geht
hinein, eine MP4 mit zwei Tonspuren kommt heraus — mitsamt Sprachkennung und
Spurnamen. Im Container nachgewiesen, nicht nur im Test:
0 video h264 und
1 audio aac deu Deutsch
2 audio aac deu Audiodeskription
3 subtitle mov_text deu
Jellyfins Transcode-Endpunkt bildet je Sitzung **eine** Tonspur ab und
verliert beim Umpacken zusätzlich die Sprachkennungen. Der Plan hier hat gar
kein Feld „welche Tonspur" — es gibt nichts auszuwählen, weil alle mitgehen.
**Vorher fragen können.** `GET /files/{id}/delivery` sagt, was geschehen wird:
umgepackt oder nicht, welche Tonspuren neu gerechnet werden müssen, welche
Untertitel nicht mitkönnen. Drei Gigabyte zu laden und erst danach zu merken,
dass die falsche Tonspur drin ist, war der Anlass für das Ganze.
**Umgepackt wird auf die Platte, nicht in die Antwort.** Der bequeme Weg wäre,
ffmpeg durchzureichen. Dann kennt aber niemand die Länge im Voraus: kein
Fortschrittsbalken, kein Fortsetzen, kein Springen. Jetzt kommt beim ersten
Abruf ein 202 mit Fortschritt, danach die fertige Datei mit `Content-Length`
und `Accept-Ranges`.
**Bildbasierte Untertitel fallen weg, und das steht im Plan.** PGS passt in
keine MP4 — betrifft fast jeden Blu-ray-Rip. Stillschweigend wegzulassen
hiesse, jemanden nach Untertiteln suchen zu lassen, die der Server bewusst
entfernt hat.
---
**Zwei Funde aus echten Messungen:**
*Die Spurnamen überlebten das Umpacken nicht* — „Deutsch" kam als `null` an,
und damit wären zwei deutsche Tonspuren hinterher nicht mehr zu unterscheiden
gewesen. Ein Versuch an einer echten Datei zeigte den Grund: **MP4 nennt das
Feld `name`, Matroska nennt es `title`.** ffmpeg schreibt das eine ins andere
um; mein Leser kannte nur `title`. Keine Grenze des Formats, ein Lesefehler.
`handler_name` steht ausdrücklich nicht in der Suche — dort schreibt ffmpeg
„SoundHandler" hinein.
*Der Image-Bau brach mit Code 100 ab.* `intel-media-va-driver` gibt es für
arm64 nicht, und die Meldung verrät nicht, welches von sechs Paketen fehlt.
Die Intel-Treiber kommen jetzt nur auf amd64 dazu; `mesa-va-drivers` bedient
AMD auf beiden.
---
**Die ffmpeg-Zeile ist eine reine Funktion und wird ohne Ausführen geprüft.**
Hier liegt die Erfahrung dieser Woche: eine falsche Parameterkombination
kostete Tage, weil sie nur gegen einen echten Server zu entdecken war. Dazu
gehört die Verwechslung, vor der jetzt ein Test steht: `-c:a:1` meint die
zweite Tonspur der **Ausgabe**, nicht Spur 1 der Datei.
ffmpeg läuft als eigener Prozess, nicht als eingebundene Bibliothek — das
hält die Lizenzen getrennt und lässt einen Absturz dort den Server nicht
mitnehmen.
223 Tests grün (98 Kern, 31 Metadaten, 26 Medien, 68 Schnittstelle).
Image baut für amd64 und arm64, mit ffmpeg 6.1.1 und VAAPI.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
197 lines
8.1 KiB
Markdown
197 lines
8.1 KiB
Markdown
# 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`](../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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
dotnet test # 223 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
Ohne TMDB-Schlüssel läuft der Scan trotzdem durch; die Titel bleiben dann bei
|
|
den Dateinamen. Der Schlüssel wird unter `PUT /api/v1/settings/metadata`
|
|
hinterlegt und kommt nie wieder heraus — abgefragt wird nur, *ob* einer da ist.
|
|
|
|
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.
|
|
|
|
## 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` |
|
|
|
|
## 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`](../LICENSES.md).
|