Skip to content
deetanPublic

About

denopub — personal Android TV client for kino.pub (Compose for TV, Media3)

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

denopub

denopub — a personal Android TV client for kino.pub, built to resume what you're watching in one click.

status: active, in daily use (v0.2) · Kotlin · Jetpack Compose for TV · Media3 ExoPlayer · runs on: Chromecast with Google TV (sideloaded, local only)

What it does

A replacement for the official kino.pub TV app, for one user. When it opens, focus is already on the first thing you're watching, so pressing OK resumes at the exact second. The home screen is built around three jobs, in order of how often they come up:

  1. Continue. Three rows — Сериалы, Фильмы, Детям — each with the most recently watched title first. A compact header shows the focused title, its episode, and how much is left.
  2. Wishlist. A kino.pub bookmark folder called Wishlist. Titles you haven't seen on the TV yet carry a "new" badge. (Phase 2: send a screenshot from your phone to a bot, which recognizes the title and adds it.)
  3. Recommendations. Five shuffled rows of films (no series) picked for you: new releases of the last three years, titles like what you watched recently, films to watch with a child, an evening for two, and favourites to rewatch. They come from your IMDb ratings (via the movies service) and kino.pub's "similar" titles, skip anything already watched, and show the reason under each card. The last card of each row, «↻ Другие», shows other titles for that row; the mix changes every day.
  4. What's new. New movies, new serials, and popular titles on kino.pub.

Long-press any card for actions: mark watched, "Начал смотреть", remove from Continue, wishlist add/remove. In a title card, long-press an episode or season to toggle it watched. Every action is written to kino.pub immediately, so the official apps and the website see the same state. The title card also shows the English IMDb description (OK on the description opens it in full) and IMDb/kino.pub trailers, a «Похожие» row at the bottom (IMDb's "More like this" that kino.pub has), and a rate on IMDb button (1–10, shows your current rating). When a movie ends — or you leave it in the last 10 % — the TV asks once for an IMDb rating (skipped if you rated it already). Marking a whole movie or serial watched asks too. Ratings go to your IMDb account through the movies service (den.tanaev.su/movies), which holds the IMDb session; the TV is paired once with a code from its Ratings & sync → Add another device. While playing, a soft «Пропустить заставку» / «Пропустить пересказ» / «Следующая серия ›» button appears for a few seconds when a known intro, recap or credits starts (OK presses it); times come from the free crowdsourced databases TheIntroDB and IntroDB by IMDb id, so most Western series and films have them and most Russian ones don't. Short title cards (< 20 s) get no button. There's a search screen (movies / serials filter) behind Поиск.

The player has three levels: ↓ shows the seek bar (← → scrub with a preview frame, faster the longer you hold), ↓ again opens one row each for voiceover, subtitles and quality (every option visible at once), and ↑ shows a frame-stepping bar on top; ↑ hides each level again. With no overlay, ← → jump straight away (3 s, growing to 5 s, 10 s, 30 s, 1 min, 5 min as you keep pressing or hold) and show only a "+N с" label. OK pauses; the pause sign shrinks to a corner badge. ↑ enters a frame-stepping mode that stays until you leave it with ↓ or Back.

Home has a Спорт row: Eurosport, Okko and Match channels from kino.pub's live TV, each with what's on now (free iptvx.one XMLTV guide) and a fresh still frame cut from the live stream every few minutes while Home is open; the focused channel plays live, muted, right in its card. Track picks are saved per title and applied to the next episode automatically. Playback asks kino.pub for HEVC, 4K and HDR streams and uses a SurfaceView so HDR10 and Dolby Vision reach the TV.

Paintings screensaver («Картины»): the TV's screensaver shows famous paintings, classic to contemporary, full-screen with a slow pan/zoom and cross-fades. A few seconds into each one a caption rises — title in Russian and English, artist with life dates, date, museum — then a short story written for a child, and the picture is left clean again before the next. A painting stays 40 s; a thin bar along the bottom edge shows when the next one comes. The painting moves aside for the caption (beside or above it), so the text doesn't cover it. ← → previous/next, ↑ ↓ hide or show the caption, any other key wakes the TV. A band across the top shows the time and the weather (now, the next hours, tomorrow morning/day/evening: cloudiness, temperature, precipitation; Open-Meteo, Belgrade by default, follows the TV's IP location when it is elsewhere). The same show opens from Home's «Картины» button. The catalog (app/src/main/assets/art/paintings.json, texts only) is re-read from GitHub main daily, so adding paintings needs no release; images load by URL (Wikimedia Commons, or a direct URL for works still under copyright) and are never stored in the repo.

On the owner's TV (Hisense VIDAA + this Chromecast): the TV starts on the dongle's input ("Default Startup Page = Last Accessed Source"), and denopub is the first app tile on Google TV. Google TV's own "Continue watching" row and widgets are not available to sideloaded apps.

Current state, open items and how to resume work: HANDOFF.md.

Wireframes: see docs/design-prompt.md. That file is also the prompt to use for visual polish.

Architecture

 Chromecast (Android TV 12+)                                 kino.pub
┌──────────────────────────────────────────────┐        ┌───────────────────────┐
│ MainActivity → KinoNavHost (Compose for TV)  │        │ kino.watch/api        │
│   auth ─ home ─ details ─ player             │  HTTPS │  /oauth2/device       │
│      │      │       │        │               │◄──────►│  /v1/watching, history│
│      └── Repository ┴────────┘               │        │  /v1/items, bookmarks │
│            │            │                    │        │  /v1/device/settings  │
│      KinopubApi      LocalPrefs (DataStore)  │        └───────────────────────┘
│      (OkHttp)        tokens, track choices,  │        ┌───────────────────────┐
│            │         wishlist "seen" set     │  HLS4  │ kino.pub CDN          │
│      PlayerController (ExoPlayer, HLS) ──────┼───────►│ multi-audio m3u8 + srt│
└──────────────────────────────────────────────┘        └───────────────────────┘
         ▲ adb over Wi-Fi (scripts/tv.sh)
       Mac
  • Auth uses the OAuth device flow. The TV shows a code, and you enter it at kino.pub/device. After login the app names the device and switches on HEVC, 4K, HDR, and the hls4 streaming type in kino.pub's per-device settings.
  • State is kept on kino.pub where possible: watch progress (watching/marktime) and the wishlist (a bookmark folder). Only things kino.pub has no place for are stored on the TV: the per-title track choices and which wishlist items you've already seen.

Getting started

Prerequisites (macOS, Homebrew):

brew install openjdk@21
brew install --cask android-commandlinetools android-platform-tools
/opt/homebrew/share/android-commandlinetools/cmdline-tools/latest/bin/sdkmanager --sdk_root=/opt/homebrew/share/android-commandlinetools "platforms;android-36" "build-tools;36.0.0" "platform-tools"

Create local.properties (gitignored) with:

sdk.dir=/opt/homebrew/share/android-commandlinetools

Build:

JAVA_HOME=/opt/homebrew/opt/openjdk@21 ./gradlew :app:assembleRelease

Put it on the TV (Wi-Fi)

One-time setup on the Chromecast:

  1. Settings → System → About → click Android TV OS build 7 times to enable developer options.
  2. Settings → System → Developer options → turn on USB debugging. If the menu has Wireless debugging, turn that on too.
  3. Find the TV's IP in Settings → Network & Internet → your Wi-Fi.

Then, from the Mac:

scripts/tv.sh connect 192.168.1.50

Chromecast with Google TV (Android 14) uses Wireless debugging: on the TV open Developer options → Wireless debugging → Pair device with pairing code, then run scripts/tv.sh pair <ip:pair-port> <code> once. The connect port changes after every reboot; scripts/tv.sh deploy rediscovers it via mDNS, so no reconnecting by hand. (Owner's TV: "Living Room TV", 192.168.1.106.)

From then on, each change is one command:

scripts/tv.sh deploy

This builds the optimized release APK (R8, signed with the debug key), installs it over Wi-Fi, and launches it. scripts/tv.sh logs streams logcat, and scripts/tv.sh shot saves a screenshot of the TV.

Configuration

There are no env vars. The app uses the public device-flow client credentials of the open-source Kodi plugin (see KinopubApi.kt). Tokens are stored on the TV in DataStore.

Local file Purpose
local.properties Android SDK path (gitignored)
.tv-address TV ip:port remembered by scripts/tv.sh (gitignored)

Project layout

app/src/main/java/dev/dt/kinopub/
  KinopubApp.kt            Application + AppContainer (manual DI, OkHttp, Coil)
  MainActivity.kt          single activity
  data/api/                KinopubApi (hand-written OkHttp client) + DTOs
  data/auth/               TokenStore, DeviceRegistration (4K/HDR/hls4 settings)
  data/api/ImdbClient.kt   IMDb plot + trailers (unofficial GraphQL)
  data/api/ImdbRater.kt    your IMDb rating: read (public GraphQL), write via the movies service
  ui/common/RateDialog.kt  1–10 rating dialog + one-time pairing-code entry
  data/api/SkipSegments.kt intro / recap / credits times (TheIntroDB + IntroDB, merged)
  data/prefs/LocalPrefs.kt track choices, wishlist seen-set, kids flags, recency stamps
  data/Repository.kt       home assembly, resume-point logic, wishlist folder
  ui/Navigation.kt         routes: auth, home, details/{id}, player/{id}?season&episode&start
  ui/home/                 compact header + Continue rows (serials/movies/kids), wishlist, new releases
  ui/search/               search with movie/serial filter
  ui/common/               cards, long-press ActionMenu
  ui/details/              title page: plots, trailers, seasons, episodes
  ui/player/               PlayerController (ExoPlayer, voiceovers, preview player), PlayerScreen
                           (fine bar / seek bar / tracks panel), TrailerScreen
  system/                  WatchNext (Google TV row, filtered), WakeService (inert, declined),
                           Updater (self-update from GitHub Releases + PackageInstaller)
  ui/home/UpdateButton.kt  the ↑ «Обновить до …» button on Home
  data/Art.kt              screensaver catalog: bundled JSON + daily refresh from GitHub, shuffled deck
  ui/art/                  ArtShow (paintings, Ken Burns, captions), ArtActivity (Home «Картины»)
  system/ArtDream.kt       the DreamService (system screensaver) hosting ArtShow
  data/Weather.kt          screensaver weather: Open-Meteo forecast, home location + IP fallback
  ui/theme/Theme.kt        design tokens (object K)
docs/kinopub-api.md        kino.pub API reference (verified vs UNVERIFIED notes)
docs/design-prompt.md      UI spec / prompt for visual design
docs/brand-prompts.md      image prompts for icon, TV banner, splash mark
REPLICATE.md               how an agent forks + rebrands this app for another person/TV
docs/lenapub-kit/          self-contained prompt + assets + reference screenshots for a fresh Claude
                           to rebuild this app as "lenapub" for another TV (start: START-HERE.md)
scripts/tv.sh              Wi-Fi deploy helper
scripts/release.sh         version bump + build + GitHub release for the TV's self-update
scripts/art-catalog.py     check / merge / stats for the paintings catalog

Deploy

There is no store release. The R8 release APK (signed with the debug key) is the build that runs on the TV. Two ways to get a new version there:

  • Self-update (normal way). On the Mac, from a clean main:

    scripts/release.sh            # patch bump; or minor / major / 1.2.3, --notes "…", --dry-run

    It bumps versionCode/versionName, builds the release APK, checks it is signed with the TV's key, commits + tags vX.Y.Z, pushes and creates a GitHub release on deetan/denopub with the asset denopub-X.Y.Z-<code>.apk. The TV reads api.github.com/repos/deetan/denopub/releases/latest (public, no token) when Home starts or comes back to the foreground — at most every 3 h while nothing is new, every time while an update is waiting. A newer versionCode adds a round ↑ button left of «Поиск»; focused it reads «Обновить до X.Y.Z», OK downloads the APK (percentage on the button) and installs it with PackageInstaller. Only Home checks or installs — never during playback. First time only: Android asks to allow «Установка неизвестных приложений» for denopub (the button opens that screen with denopub in it: switch it on, press Back, press OK again). There is no confirmation dialog — the app declares UPDATE_PACKAGES_WITHOUT_USER_ACTION and updates itself silently (Android 12+, verified on the emulator). The app closes during the install and the TV lands on the Google TV home screen — open denopub again (Android blocks a self-relaunch from the background).

  • adb over Wi-Fi (development): scripts/tv.sh deploy, as above.

Screensaver (one time per device). Google TV's settings only offer its own Ambient mode, so the paintings screensaver is selected over adb: scripts/tv.sh screensaver (sets secure screensaver_components to dev.dt.kinopub/.system.ArtDream, plus screensaver_enabled and screensaver_activate_on_sleep); scripts/tv.sh screensaver off goes back to Ambient mode. It starts after the TV's normal screensaver delay (Settings → System → Energy/Ambient mode timeout).

New paintings need no release: edit app/src/main/assets/art/paintings.json, run scripts/art-catalog.py check --images, push to main; the TV picks it up within a day.

The signing key is ~/.android/debug.keystore on the owner's Mac (cert SHA-256 ef48301c…, pinned in scripts/release.sh). An APK signed with any other key is refused by the TV, and uninstalling to get around that loses the kino.pub login — keep a private backup of that keystore and never release from another machine.

License

© dt. Personal project; public for reference, no license granted.

About

denopub — personal Android TV client for kino.pub (Compose for TV, Media3)

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages