[Feature]: Android app

Open
#40 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
20/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
android, react-native, typescript
Domain
mobile

Research direction

This is a tracking issue for a full Android app, with implementation split across sub-issues #41–#50. Read the settled decisions and dependencies here, then start with #41 Foundation; each sub-issue defines its own scope and completion criteria. The overall work is done when the dependent app features are implemented and the release APK is attached to a GitHub release.

Written by the indexing model from the issue text.

Description

enhancement

[!NOTE]
This issue was written by Claude (Claude Opus 5.5) from a planning session with @PhrolovaMoe. The decisions below come from that session and are settled; sub-issues build on them.

Area

Mobile app

Problem

tinystream can only be used from a browser. The web UI is responsive, but on a phone it's still a website: no background music with lock-screen controls, no picture-in-picture, no offline music, no native gestures or haptics, and the player is limited to what a mobile browser's Media Source Extensions can decode.

Proposed solution

A native Android app written in React Native (Expo), living in this repo. It has the same features as the web UI, including admin, with a UI designed for phones instead of a scaled-down web layout. The web UI's effects and animations (tilt, glare, squircles, glass, ambient tint, page transitions…) come along.

This is a tracking issue. The work is split into sub-issues, each one a self-contained branch and PR. Read this whole issue before starting any sub-issue. The principles and decisions here apply to all of them.

Principles
  1. User data never touches our servers. No analytics, no crash reporting (no Sentry etc.), no Expo cloud services (no EAS Build, no EAS Update / OTA JS updates, no Expo push). The app only talks to the user's tinystream server(s), plus the GitHub releases API for the update check (with a toggle to turn it off). A push relay may be designed later, in its own issue.
  2. Google Play Services is optional. Features that need it (passkeys stored in Google Password Manager; later Chromecast or Android Auto) must detect when it's missing and hide themselves. The app must be fully usable on de-Googled phones (GrapheneOS, LineageOS without GApps). Never add Firebase.
  3. Parity with the web UI. Every feature the web UI has, the app has, including admin and settings. When in doubt about behaviour, do what the web UI does (web/src). Only the presentation changes, to native mobile patterns.
  4. Mobile-first UX. Bottom tabs, native stack navigation with swipe back, Android's predictive back gesture, edge-to-edge drawing, bottom sheets instead of modals, pull-to-refresh, long-press context menus, swipe actions, and lots of haptics.
  5. Effects stay. The web UI's motion and effects are part of tinystream's identity. They're ported with Reanimated and Skia, respect Android's "Remove animations" setting (the equivalent of prefers-reduced-motion), and are built into each screen as it's made, not added in a later pass.
  6. Android-only, but don't block iOS. Only Android is built and tested. Prefer cross-platform libraries, and keep platform-specific native code behind module interfaces so an iOS implementation could be added later.
  7. The app and server version together. The app has the same version number as the server, is built from the same tag, and warns on a major/minor mismatch with the connected server.
  8. Never hardcode RSS/Torznab sources (repo rule; applies to the app's admin screens too).
Settled decisions
Topic Decision
Framework React Native through Expo (latest SDK at the time of starting), local builds only: expo prebuild + Gradle, no EAS. Continuous Native Generation: mobile/android/ is generated and git-ignored; native changes go through config plugins and local Expo modules.
Repo layout mobile/ (the app) and packages/shared (code shared with web/) in this repo, tied together with bun workspaces.
Android versions minSdkVersion 34 (Android 14), targetSdkVersion/compileSdkVersion 36 (Android 16).
Devices Phones only. Portrait everywhere, except the video player, which rotates. No tablet-specific layouts, no Android TV.
Release A signed arm64-v8a APK attached to each GitHub release by release.yml. Native libraries built with 16 KB page alignment. Play Store later (out of scope).
Styling NativeWind (Tailwind classes in React Native), with colours from the server's theme tokens (appearance query), including the Layered/Flat/Glass component styles.
Navigation Expo Router. Tabs: Home · Search · Library · Music · Profile. A music mini-player sits above the tab bar.
Servers A saved list of servers, each with its own token. An instance switcher chip at the top-right of Home (long-press the Profile tab as a shortcut). Plain http:// is allowed, with a warning.
Auth Bearer tokens (the server already supports them everywhere). Password/profile sign-in first; passkeys last, with server changes.
Video Our own Expo module in Kotlin around Media3/ExoPlayer, with seeking through ?start= and codec checks through MediaCodecList. libass for subtitles. Picture-in-picture.
Music The Rust decoder (web/decoder) shared with web through a core crate and used natively through uniffi. Output through AudioTrack, inside a Media3 SimpleBasePlayer + MediaSessionService (lock screen, Now Bar / islands, Bluetooth buttons).
Music offline An automatic LRU cache + pinned albums/playlists/tracks + prefetching the next 3 queued tracks. Offline mode with plays reported later.
Notifications In-app through the events subscription, plus background polling with WorkManager (about every 15 minutes) that posts local notifications. No push in this epic.
Live Updates Android 16 promoted ongoing notifications for caching pinned music and for watch/listen-together sessions. A normal ongoing notification on Android 14–15.
Ambient tint Computed by the server and exposed through GraphQL (the web UI switches to it too).
Haptics A local Kotlin module using VibrationEffect.Composition primitives, with fallbacks. A setting with Off / Subtle / Full (default Full).
Tilt Cards lean toward the finger while pressed. Hero artwork (title, album and artist headers) also follows the gyroscope.
Deep links tinystream://<host[:port]>/together/<code>, …/listen/<code>, and sharing any tinystream web URL to the app. Guests can join rooms without signing in.
Testing typecheck + unit tests for shared and pure logic, plus manual testing on a device. UI flow tests (Maestro) come later.
Sub-issues

Order: 1 → 2, then 3–9 can run in parallel (respecting the listed dependencies), and 10 comes last.

  1. #41 Foundation: workspaces, shared package, Expo app, theming, effect primitives, haptics module, Rust build plumbing, CI and release APK. (no deps)
  2. #42 Connect & auth: the server list, instance switcher, sign-in, the API client, version and update checks. (needs 1)
  3. #43 Server: ambient tint field, used by both web and mobile. (no deps; mobile screens show no tint until it lands)
  4. #44 Browsing & admin UI: Home, Search/Discover, Library, title pages, Profile, calendar, requests, wanted, server downloads, settings/admin, notifications. (needs 2)
  5. #45 Video player: Media3 module, libass, PiP. (needs 2)
  6. #46 Music: shared decoder core, native engine, media session, Music tab, mini and full player. (needs 2)
  7. #47 Music cache & offline mode (needs 6)
  8. #48 Watch & listen together, deep links (needs 5 and 6)
  9. #49 Clips (needs 5)
  10. #50 Passkeys, server and app (needs 2)
Later (separate issues, not part of this epic)
  • Push notifications (UnifiedPush preferred; a relay must not be able to read notification content)
  • Maestro UI flow tests
  • Chromecast, Android Auto (both need Google Play Services, so both are optional)
  • Offline video
  • Tablet/foldable layouts, Android TV, iOS
  • Play Store release
Alternatives considered
  • Capacitor or a WebView wrapper around the web UI: rejected. It gives a website in a box, with no native player, no background audio engine and no native gestures.
  • HLS on the server so stock players work: rejected for now. It's a backend project and would change the web player too. The native module handles ?start= seeking instead.
  • react-native-track-player / ExoPlayer for music: rejected. It loses crossfade and ReplayGain parity, and the gapless logic already exists in Rust.
  • FCM / Expo push: rejected. Notification content would pass through Google/Expo, and it needs Google Play Services.
  • F-Droid: not targeted, but principle 2 keeps the app close to F-Droid-compatible.
Dominant language
TypeScript
Stars
4
Forks
1
Avg merge
4h 49m
Merged PRs (30d)
5

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from tinystream-dev/tinystream

All issues in tinystream-dev/tinystream

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.