# Castarr

**Live-TV auf dem Fernseher, eingerichtet in einer Minute — alles läuft übers Handy.**

Castarr ist eine App für Google TV / Android TV. Auf dem Fernseher muss nie
etwas getippt werden: Zum Einrichten scannt man einmal einen QR-Code mit dem
Handy, meldet sich dort an — fertig. Danach zappt man mit der normalen
TV-Fernbedienung oder steuert alles bequem vom Handy aus.

| Senderliste | Player |
| --- | --- |
| ![Senderliste](docs/screenshots/senderliste.png) | ![Player](docs/screenshots/player.png) |

| Nummerntasten | Einrichtung |
| --- | --- |
| ![Nummerntasten](docs/screenshots/nummerntasten.png) | ![Willkommens-Bildschirm](docs/screenshots/willkommen.png) |

## Was die App kann

- **Senderliste mit Logos und Programm** — was gerade läuft, wie lange noch,
  was danach kommt. Gruppen und Favoriten links, Sender rechts.
- **Zappen wie früher** — Nummerntasten auf der Fernbedienung schalten direkt
  um (mit großer Anzeige, welcher Sender gleich kommt), hoch/runter blättert
  durch die Sender.
- **Aufgeräumter Player** — OK-Taste zeigt Sendung, Zeiten und Fortschritt,
  dazu Pause/Stopp-Buttons und Tonspur-Wahl, wenn der Sender mehrere hat.
  Blendet sich von selbst wieder aus.
- **Handy als Fernbedienung** — QR-Code in den Einstellungen scannen, schon
  hat man Senderliste, Suche, Lautstärke und Favoriten im Handy-Browser.
  Keine App-Installation nötig.
- **Favoriten** — OK auf einem Sender gedrückt halten, Stern gesetzt. Die
  Favoriten gelten pro Person und sind auf jedem Gerät dieselben.
- **Updates aus der App heraus** — unter Einstellungen → App genügt ein
  Klick, wenn eine neue Version bereitsteht.

## Installation auf dem Fernseher

1. Auf dem Google TV die App **Downloader** installieren (oder einen anderen
   Weg nutzen, eine APK-Datei zu öffnen).
2. Diese Adresse eingeben:
   `git.beckm4nn.net/be-nj/castarr/raw/branch/apk/castarr.apk`
3. Installation bestätigen („Unbekannte Quellen" für Downloader erlauben,
   wenn der Fernseher fragt).
4. Castarr starten und den drei Schritten auf dem Bildschirm folgen:
   QR-Code scannen, auf dem Handy Server angeben und anmelden — den Rest
   macht der Fernseher.

Danach hält sich die App über den eingebauten Updater selbst aktuell.

---

## Für Technikinteressierte

Native Kotlin-App (Jetpack Compose for TV, Media3/ExoPlayer für HLS und
MPEG-TS). Als Backend dient ein [Dispatcharr](https://github.com/be-nj/Dispatcharr)-Fork
mit OIDC-Unterstützung: Anmeldung per Device Authorization Grant (der
Fernseher zeigt QR + Code, bestätigt wird am Handy beim Identity Provider),
API-Zugriff per Bearer-Token, Favoriten und Ausgabeprofile pro Nutzer.
Ohne Dispatcharr funktioniert auch jede M3U-Playlist (+ optionales XMLTV)
als generische Quelle — ErsatzTV, Threadfin, Tunarr, einfache Playlists.
Diese Quelle braucht überhaupt keine Anmeldung.

An einen bestimmten Identity Provider ist nichts gebunden: der Server nennt
der App seinen Issuer und die Client-ID, alles Weitere ist Standard (OIDC
Discovery, Device Authorization Grant nach RFC 8628). Authentik ist hier nur
das, was im Haushalt läuft — Keycloak, Zitadel oder Authelia tun es genauso,
solange sie den Device-Flow können.

Die Handy-Fernbedienung serviert der Fernseher selbst (eingebetteter
HTTP/WebSocket-Server, Kopplung per QR-Token mit ratenlimitiertem
Zahlencode als Fallback). Physische Mediatasten und Google Assistant
funktionieren über eine Media3 MediaSession.

### Selbst bauen

JDK 17+ und Android SDK (Platform 35) erforderlich; eine passende
JDK-Toolchain wird automatisch aufgelöst (foojay).

```
./gradlew assembleDebug     # Debug-APK
./gradlew assembleRelease   # signiert, wenn CASTARR_STORE_*-Env gesetzt ist
```

APK-Ausgabe: `app/build/outputs/apk/<variant>/`. Die Releases hier im Repo
sind signiert; über einem Debug-Build muss einmal deinstalliert werden
(Signaturwechsel). Updates bezieht die App über die Release-API dieses
Repos, die APK selbst liegt auf dem Branch `apk`.

### Tests

```
./gradlew test          # Unit-Tests, Reports unter tests/runs/
tests/smoke.sh          # Emulator: bauen, starten, durchklicken (~40 s)
tests/smoke.sh --stop   # dasselbe, Emulator danach herunterfahren
```

`tests/smoke.sh` baut das Debug-APK, setzt die Demo-Playlist als Quelle,
läuft mit dem D-Pad von der Senderliste bis in den Player und schlägt fehl
bei Absturz, ANR oder leerer Senderliste. Screenshots und Log landen unter
`tests/runs/`. Nicht abgedeckt: echte Wiedergabe, Onboarding am Handy,
Kopplung.

Der Emulator dahinter lässt sich auch einzeln steuern:

```
tests/helpers/emulator.sh start | stop | status
tests/helpers/emulator.sh install <apk>
tests/helpers/emulator.sh shot <name>
```

Er startet aus einem Snapshot und ist in wenigen Sekunden oben; `stop`
schreibt den Snapshot vorher neu. Ein Kaltstart entsteht nur, wenn der
Snapshot fehlt (AVD `castarr-googletv`, API 34).

### Release

```
tools/release.sh 0.11.6 --notes notes.md
```

Bumpt die Version, testet, baut signiert, taggt, schiebt die APK auf den
Branch `apk` und legt das Gitea-Release an. Ohne `--notes` schreibt es einen
Entwurf aus den Commit-Betreffs, den du selbst ausformulierst — Release-Notes
erfindet das Skript nicht.

Architektur-Notizen: [CONTEXT.md](CONTEXT.md) und [docs/adr/](docs/adr/).