AngelThump for Android

An unofficial, Android app for watching angelthump.com live streams.

Not affiliated with AngelThump. Uses the same public API and edge endpoints as the official open‑source web player.

Features

Main View

• Live directory – browse currently live channels (thumbnail, title, channel, viewer count), sorted by viewers.
• Watch by name – type any channel name to jump straight into a stream.
• HLS playback – powered by Media3 / ExoPlayer, with automatic token fetching and retry on edge errors.
• Picture‑in‑Picture – a PiP button on the player plus automatic PiP when you press Home (toggleable).
• Background playback – audio keeps playing with a media notification (play/pause) when you leave the app or lock the screen (toggleable).
• Settings – background playback, auto‑PiP, start muted, keep screen on, and show/hide NSFW channels.

Loads of Settings:

Tech stack

• Kotlin + Jetpack Compose (Material 3)
• Media3 ExoPlayer + MediaSessionService (background audio & notification)
• Retrofit + OkHttp + kotlinx.serialization
• Coil (image loading)
• DataStore Preferences (settings)
• Navigation Compose

Project layout

app/src/main/java/com/angelthump/viewer/
├── AngelThumpApp.kt          # Application + simple service locator
├── MainActivity.kt           # Compose nav host: Browse + Settings
├── PlayerActivity.kt         # Player UI + Picture-in-Picture handling
├── data/                     # API, models, repository, endpoints
├── playback/PlaybackService  # Media3 MediaSessionService (background play)
├── settings/                 # DataStore-backed settings
└── ui/                       # Compose screens, components, theme

How playback works

1. GET https://api.angelthump.com/v3/streams lists the live channels.
2. To play a channel, the app requests a short‑lived token: POST https://vigor.angelthump.com/{channel}/token (with the public web‑player Identifier).
3. ExoPlayer then loads the master playlist https://vigor.angelthump.com/hls/{channel}.m3u8?token={token}.

The player runs inside a MediaSessionService, which is what enables background audio and the system media notification. Picture‑in‑Picture is handled at the PlayerActivity level.

Build & run

Requirements: Android Studio Ladybug (or newer) with JDK 17 and Android SDK 34.

1. Open the project folder in Android Studio and let it sync (it will download the Gradle distribution and dependencies).
2. Select a device/emulator running Android 7.0 (API 24) or newer (PiP requires API 26+).
3. Press Run.

Or from the command line:

# macOS / Linux
./gradlew assembleDebug

# Windows (PowerShell / cmd)
.\gradlew.bat assembleDebug

The APK is written to app/build/outputs/apk/debug/app-debug.apk.

Notes & limitations

• Patreon / password‑protected channels are not supported (no login flow).
• Thumbnails are cached by URL; pull Refresh in the top bar to update the directory.
• This app depends on AngelThump's public endpoints; if those change, the data layer in data/AngelThump.kt and data/api/ is where you'd update them.
• I used cursor for the readme and some small fixes.