castarr/README.md

Castarr

Native Google TV client for a Dispatcharr backend: live IPTV with a full D-pad UI (Compose for TV), login via the OIDC device flow (Authentik), per-user favorites, per-stream output profiles, and an optional phone remote paired by QR code — served by the TV itself, no phone app install.

Features

• Live TV channel list with Now/Next EPG and progress, zapping via channel/D-pad keys, fullscreen playback (ExoPlayer, HLS + MPEG-TS) with a minimal auto-hiding overlay
• Login without typing: the TV shows a QR code and a user code; confirm on your phone at your identity provider (OIDC device authorization grant). The only thing entered on the TV is the Dispatcharr URL.
• Dispatcharr source: channels, groups and EPG via the fork's Bearer-authenticated API; favorites are stored per user on the backend (long-press a channel to star it, filter chip in the list)
• Stream profiles: pick Standard / Passthrough / audiofix / 720p (list comes from the backend) — applied per stream request
• Generic source fallback: any M3U (+ optional XMLTV) URL works without a login — ErsatzTV, Threadfin, Tunarr, plain playlists
• Phone remote (optional): scan the QR under Einstellungen; play/pause, zapping, volume, channel list with Now/Next and favorite toggling in the browser — no app install, rate-limited pairing code as fallback
• Physical remote keys and Google Assistant keep working (Media3 MediaSession, TV app quality guidelines TV-PC/TV-PP/TV-VC)

Building

Requires JDK 17+ and the Android SDK (platform 35). A JDK toolchain is resolved automatically (foojay) if the host only has a JRE.

./gradlew assembleDebug     # debug APK
./gradlew assembleRelease   # signed when CASTARR_STORE_* env vars are set

APK output: app/build/outputs/apk/<variant>/. Releases on the releases page are signed; install over an existing debug build requires uninstalling first (signature change).

Backend

The full feature set needs the Dispatcharr fork with OIDC support (be-nj/Dispatcharr): its /api/accounts/oidc/status/ endpoint hands the app the issuer and public device-flow client id. Configuration lives in CONTEXT.md and docs/adr/.