[Feature]: Android app

Aperta
#40 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
20/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
android, react-native, typescript
Ambito
mobile

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
TypeScript
Stelle
4
Fork
1
Merge medio
4h 49m
PR unite (30g)
5

Preparare l'ambiente

  • Include un Dockerfile o un file Docker Compose
  • Nessun modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di tinystream-dev/tinystream

Tutte le issue di tinystream-dev/tinystream

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.