# Flixy

> Ein nativer Plex-Client für iPhone und iPad — dunkel, mit ausfahrbarer
> Seitenleiste und Offline-Downloads.

Der Name ist ein Platzhalter. Siehe [`Flixy/Branding.swift`](Flixy/Branding.swift).

## Stand

Phase 0 (Fundament) steht. Die App startet, die Navigation ist begehbar, die
Inhalte folgen in Phase 1.

Der Fahrplan steht in
[`docs/superpowers/specs/2026-09-11-flixy-design.md`](docs/superpowers/specs/2026-09-11-flixy-design.md).

| Phase | Inhalt | Stand |
|---|---|---|
| 0 | Projektgerüst, Design-Tokens, Navigation | ✅ |
| 1 | Anmeldung, Bibliothek, DirectPlay | ✅ Anmeldung am Server geprüft, der Rest nicht |
| 2 | Transcoding, adaptive Bitrate, Spuren, Sync | ✅ gebaut, ungeprüft |
| 3 | Download-Engine und Offline-Wiedergabe | ✅ gebaut, ungeprüft |
| 4 | Download-Intelligenz | ✅ gebaut; komprimierte Downloads ungeprüft |
| 5 | Feinschliff und Personalisierung | ✅ gebaut, ungeprüft |
| 6 | Live-TV mit EPG | ✅ gebaut, an keinem DVR geprüft |

„Ungeprüft" heißt: die Logik ist von Tests abgedeckt, die Oberfläche wurde aber
noch nie mit einem echten Bestand gesehen.

## Aufbau

Die Xcode-Projektdatei wird aus `project.yml` erzeugt und ist **nicht**
eingecheckt — das erspart Konflikte in der `pbxproj`.

```bash
xcodegen generate
open Flixy.xcodeproj
```

> **Wichtig: Xcode vorher beenden.**
>
> `xcodegen generate` schreibt `project.pbxproj` neu. Ein geöffnetes Xcode
> liest das nicht nach — es hält seinen eigenen Stand im Speicher und
> überschreibt die frisch erzeugte Datei beim nächsten Sichern wieder. Neue
> Dateien fehlen dann im Build, ohne dass irgendwo ein Fehler auftaucht.
>
> Das ist der Preis dafür, die Projektdatei aus Git herauszuhalten. Immer wenn
> Dateien dazukommen oder `project.yml` sich ändert: Xcode mit ⌘Q beenden,
> `xcodegen generate`, neu öffnen.
>
> Ob der Build aktuell ist, steht in der App unter **Einstellungen →
> Diagnose** als Build-Datum.

Der Code liegt zum größten Teil in lokalen Packages unter `Packages/FlixyKit`.
Das App-Target enthält nur Oberfläche und Navigation.

| Modul | Aufgabe | Hängt ab von |
|---|---|---|
| `PlexKit` | Anmeldung, Endpunkte, Modelle. Kein SwiftUI. | — |
| `FlixyDesign` | Farben, Typografie, wiederkehrende Bausteine. | — |
| `FlixyPlayback` | Wiedergabe-Abstraktion und die Entscheidung DirectPlay/Transcode. | `PlexKit` |
| `FlixyDownloads` | Warteschlange, Hintergrundübertragung, Offline-Bestand. | `PlexKit` |

### Warum zwei Player

iOS spielt weder Matroska-Dateien noch DTS- oder TrueHD-Ton — und genau das
liegt in typischen Plex-Beständen. `PlaybackDecider` prüft deshalb pro Datei,
ob AVPlayer sie nativ öffnen kann (dann gibt es Bild-in-Bild und AirPlay
gratis), und schickt sie sonst an VLCKit.

Ab Phase 2 kommt der dritte Weg dazu: Server-Transcoding. Dafür ist genau eine
Funktion zu erweitern — `PlaybackDecider.decide(media:part:policy:)`. Die
Oberfläche bleibt unberührt.

## Tests

Die Logik-Tests laufen ohne Simulator, deshalb in Sekunden:

```bash
cd Packages/FlixyKit && swift test
```

Die wichtigste Testdatei ist `PlaybackDeciderTests` — sie hält fest, welche
Datei auf welchem Weg landet, und schlägt an, sobald jemand
`DeviceCapabilities` anfasst.

Die Antwort-Vorlagen unter `Tests/PlexKitTests/Fixtures` sind von Hand
geschrieben und gehören durch echte Mitschnitte ersetzt, sobald ein Server
erreichbar ist — siehe das README dort.

Die Oberfläche wird von Hand im Simulator geprüft.

## Was noch am echten Server zu prüfen ist

1. **Komprimierte Downloads.** Sie laufen über den Universal-Transcoder mit
   `protocol=http` statt über die umständliche Sync-API. Offen: ob Plex eine
   `Content-Length` mitschickt (ohne sie gibt es keinen Fortschrittsbalken und
   kein Fortsetzen) und ob die Datei durchsuchbar ist. Original bleibt solange
   Voreinstellung. Siehe `transcodedDownloadURL` in `PlexServer+Playback.swift`.
2. **Live-TV.** Der am schlechtesten dokumentierte Teil der Plex-API — es gibt
   keine offizielle Beschreibung. Die Modelle sind durchgehend nachsichtig
   gebaut, und ohne eingerichteten Empfänger erklärt die App das, statt einen
   Fehler zu zeigen.
3. **App-Größe.** Die iOS-Slice von VLCKit ist unstripped 239 MB. Was davon im
   fertigen Archiv übrig bleibt, ist noch nicht gemessen.
4. **Große Dateien im Hintergrund.** Das Verhalten mit einem 40-GB-Remux — vor
   allem Pausieren und Fortsetzen — ist nur gegen Testdaten geprüft.

## Voraussetzungen

- Xcode 26 oder neuer
- iOS 26.0 auf dem Zielgerät
- XcodeGen (`brew install xcodegen`)