[Feature]: Android app
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 20/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức độ hoạt động
- Sôi nổi
- Công nghệ
- android, react-native, typescript
- Lĩnh vực
- mobile
Hướng nghiên cứu
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.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
[!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
- 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.
- 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.
- 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. - 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.
- 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. - 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.
- 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.
- 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.
- #41 Foundation: workspaces, shared package, Expo app, theming, effect primitives, haptics module, Rust build plumbing, CI and release APK. (no deps)
- #42 Connect & auth: the server list, instance switcher, sign-in, the API client, version and update checks. (needs 1)
- #43 Server: ambient tint field, used by both web and mobile. (no deps; mobile screens show no tint until it lands)
- #44 Browsing & admin UI: Home, Search/Discover, Library, title pages, Profile, calendar, requests, wanted, server downloads, settings/admin, notifications. (needs 2)
- #45 Video player: Media3 module, libass, PiP. (needs 2)
- #46 Music: shared decoder core, native engine, media session, Music tab, mini and full player. (needs 2)
- #47 Music cache & offline mode (needs 6)
- #48 Watch & listen together, deep links (needs 5 and 6)
- #49 Clips (needs 5)
- #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.
- Ngôn ngữ chính
- TypeScript
- Star
- 4
- Fork
- 1
- Merge trung bình
- 4 giờ 49 phút
- Pull request đã merge (30 ngày)
- 5
Chuẩn bị môi trường
- Có Dockerfile hoặc tệp Docker Compose
- Không có mẫu pull request
- Không có hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của tinystream-dev/tinystream
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
tinystream-dev/tinystream#132 ·
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
tinystream-dev/tinystream#131 ·
-
bug
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 88/100
tinystream-dev/tinystream#129 ·
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
tinystream-dev/tinystream#128 ·
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
tinystream-dev/tinystream#124 ·
Tất cả issue của tinystream-dev/tinystream
Issue tương tự
-
Console writes URL credentials to the local log, though AGENTS.md says secrets never reach diskĐang mở
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 86/100
sandbox-quantum/switch#2163 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
automated issue report
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 78/100
Maintainer thường phản hồi trong vòng 1 ngày
-
area/dashboard kind/bug QA/dev-automation
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 75/100
Maintainer thường phản hồi trong vòng 1 ngày
-
bug pydanty:is-working
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
pydantic/pydantic-ai#13939 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
self-host
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
funmusicplace/mirlo#2625 ·
Maintainer thường phản hồi trong vòng 1 ngày