[Feature]: Android app

オープン
#40 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
20/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
android, react-native, typescript
領域
mobile

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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.
主要言語
TypeScript
スター
4
フォーク
1
平均マージ
4時間 49分
マージ済み PR(30日)
5

環境構築

  • Dockerfile または Docker Compose ファイルあり
  • プルリクエストのテンプレートなし
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

tinystream-dev/tinystream のほかの issue

tinystream-dev/tinystream の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。