# 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                       # 238 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

**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` |

## 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).