[Feature]: Desktop app
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 1/100
- Issue type
- Feature
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- graphql, linux, rust
- Domain
- desktop, full-stack
Research direction
This is a tracking issue; read the settled decisions and the sub-issue list before choosing work. Start with #81, the dependency audit and app foundation, or pick an independent sub-issue such as #84 or #85; follow its linked issue for implementation details. Done means completing a self-contained sub-issue and its PR on feat/desktop, with the shared platform and supply-chain constraints respected.
Written by the indexing model from the issue text.
Description
[!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
Desktop app
Problem
On a computer, tinystream only works in a browser, and the browser is the weak link:
- Codecs. The web player goes through Media Source Extensions, so whatever the browser can't decode gets transcoded. On Linux with NVIDIA's driver, Chromium regularly can't play 10-bit AV1 (
yuv420p10le), and a lot of the anime library is exactly that. Those viewers end up on a server transcode they shouldn't need. - Picture quality. A
<video>element gives no say over scaling, debanding or frame timing. - OS integration. No MPRIS/media keys, no tray, no idle inhibit outside fullscreen, and notifications only while a tab is open.
Proposed solution
A native desktop app written in Rust with iced. Video plays through libmpv, subtitles render with rustyass, and music uses the same decoder core as the web player. The UI is a close to 1:1 copy of the web UI's desktop layout. It targets Linux first (Wayland native, X11 too) and must not block Windows or macOS.
This is a tracking issue. The work is split into sub-issues, each one a self-contained branch and PR, all landing on feat/desktop. 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 and no crash reporting. The app only talks to the user's tinystream server(s), plus the GitHub releases API for the update check (which has a toggle to turn it off).
- Parity with the web UI. Every feature the web UI has, the app has, including admin and settings. The web UI (
web/src) is the spec for behaviour and for looks. - It looks like the web UI. With default settings, the app should look like the web UI's desktop layout (
mdbreakpoint and up). That includes the effects (squircles, glass, tilt, glare, ambient tint, page transitions) and the server's appearance settings. Effects are built into each screen as it's made and respect a reduced-motion setting. - Linux first, never Linux only. Only Linux is built and tested. Everything platform-specific sits behind a trait with a Linux implementation, so Windows and macOS can be added later without restructuring: GPU interop, secrets, tray, MPRIS, idle inhibit, notifications, deep-link registration.
- Native Wayland. Wayland is the primary target, with fractional scaling done right. X11 works through the same winit code paths.
- Our own stack. Subtitles are rendered by rustyass, never libass, and libass isn't even in the binary. Music uses
decoder/core. - Supply chain. crates.io is in a wave of supply-chain attacks (see README). Every crate the app adds is audited before anything builds (protocol in #81). Every cargo command uses
--locked. Nevercargo update. - 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. Bumping the version touches
desktop/Cargo.tomltoo, alongside the filesCLAUDE.mdlists. - Never hardcode RSS/Torznab sources (repo rule; it applies to the app's admin screens too).
Settled decisions
| Topic | Decision |
|---|---|
| UI toolkit | iced, pinned to a known-good commit of its master branch (git dependency with rev), not the 0.14 release. wgpu renderer only. Moving the pin later means auditing again. |
| Repo layout | desktop/ is its own Cargo workspace (like mobile/), so the server and the app don't rebuild each other. Logic both need is moved into small shared crates under the root: theme/ts1 derivation, squircle geometry, decoder/core. |
| Scope | Purely a client. It never runs or manages a server. |
| Platforms | Linux (x86_64), Wayland first plus X11. Tested on sway, GNOME and KDE. Windows/macOS later. |
| Window | Client-side decorations, with no separate titlebar. The sidebar's logo row and a thin strip along the top of the content are drag areas. Window controls float top-right (or in the sidebar's logo row for left-side layouts) and follow the desktop's button layout from the xdg-desktop-portal Settings. They're hidden when the window is tiled or fullscreen. The app draws its own resize edges. Minimum window width is the web's md breakpoint, so there's no phone layout. |
| Video | libmpv, built by us (native/mpv, native/libplacebo on top of native/ffmpeg), statically linked, GPL build. mpv renders through its OpenGL render API into a texture whose memory is allocated in Vulkan and imported into GL (EXT_external_objects), then drawn by wgpu with no copy. SDR only for now. |
| Hardware decoding | VA-API (AMD/Intel) and NVDEC/CUVID (NVIDIA, through ffnvcodec, loaded at runtime). |
| Direct play | mpv plays the original file from a new Range-capable endpoint (#84). The quality picker switches to the server's ?start= transcode stream, for bandwidth. Quality is manual for now. |
| Subtitles | mpv's text subtitles and OSD are off. ASS/SSA/text tracks come from the server (as on web) and are drawn by rustyass in a wgpu overlay. Bitmap subtitles (PGS/VobSub) are left to mpv during direct play. mpv is patched to build without libass. |
| mpv options | Our defaults, plus an optional mpv.conf from the app's config directory (no UI). It can't override what the app controls. An Advanced settings page shows which file is read. |
| Music | decoder/core (symphonia) + cpal. Same gapless, crossfade and ReplayGain behaviour as the web player, and the same server-side queue. |
| API | GraphQL via graphql_client, using .graphql documents and packages/shared/schema.graphql, with subscriptions through a small graphql-ws client. Media routes over HTTP with bearer tokens. |
| Servers & auth | A saved server list, one bearer token each, as on Android. Password/profile sign-in first; passkeys (CTAP2 over USB HID) last. Tokens are kept in the Secret Service, falling back to a 0600 file when no keyring is running. Plain http:// is allowed, with a warning. |
| OS integration | MPRIS, idle inhibit while playing, freedesktop notifications, single instance + tinystream:// and web-URL deep links, and a tray. Closing the window hides it to the tray while music plays or a Together room is open, and quits otherwise. |
| Watch Together | Needed from the first usable build. It comes right after the player. |
| Releases | A tarball and an AppImage per release (glibc, GitHub-hosted runners, like the server). |
| License | AGPL-3.0-or-later, like the server. Third-party licenses are collected into THIRD_PARTY_LICENSES as for the server. |
| Testing | Unit tests for logic, iced_test where it helps, manual testing on David's machine (sway, AMD). A friend with NVIDIA tests CI-built binaries from the player milestone on. |
Sub-issues
Order: #81 first. #84 and #85 have no dependencies and can start right away. #96 should land by the time #86 does, so NVIDIA testers get binaries. #88 follows the player directly. #97 comes after parity.
- #81 Foundation: workspace, dependency audit, iced pin, app shell, client-side decorations, CI. (no deps)
- #82 Design system: shared theme crate, tokens and component styles, fonts and icons, effects. (needs 1)
- #83 Connect & auth: server list, sign-in, token storage, API client, version and update checks. (needs 1)
- #84 Server: Range file endpoint for direct play. (no deps)
- #85 Native: libmpv: libplacebo, mpv without libass, NVDEC in ffmpeg. (no deps)
- #86 Video player: mpv in iced, direct play, quality, player UI. (needs 2, 3, 4, 5)
- #87 Subtitles with rustyass. (needs 6)
- #88 Watch Together (needs 6, 7)
- #89 Browsing UI: Home, search, libraries, titles, calendar, notifications, profile. (needs 2, 3)
- #90 Settings & admin UI (needs 2, 3)
- #91 Music & Listen Together (needs 2, 3)
- #92 OS integration: MPRIS, idle inhibit, notifications, deep links, tray. (needs 3; hooks into 6, 8 and 11 as they land)
- #93 Clips (needs 6, 7)
- #94 Books reader (needs 2, 3)
- #95 Passkeys (needs 3)
- #96 Release packaging: tarball, AppImage. (needs 1, 5)
- #97 Offline downloads (needs 4, 6, 11; after parity)
Later (separate issues, not part of this epic)
- HDR output (mpv's render API tone-maps to SDR; HDR needs a different path, likely Wayland color management)
- Automatic quality from measured throughput
- Flatpak/Flathub
- Windows and macOS builds
- Discord Rich Presence, autostart
- Server NVENC support is its own issue: #98
Alternatives considered
- Tauri/Electron/a WebView around the web UI: rejected. It's still a browser engine, with the same codec limits that motivate the app.
- egui, Slint, GTK: iced was chosen for its Elm architecture and for wgpu access through
Shaderprimitives, which video, glass and tilt need. - wgpu on its GL backend, with mpv drawing straight into a wgpu GL texture: rejected. The whole UI would run on GL, and that's a dead end on macOS.
- mpv's software render API: rejected. It's CPU-bound and can't do 4K60.
- mpv in its own native window (
--wid): rejected, because Wayland doesn't support it. - Our own player on
ffmpeg-sys: rejected. We'd be rewriting A/V sync, audio output, buffering and mpv's rendering. - EGL dmabuf export for the GL→Vulkan handoff: rejected, because it's effectively Mesa-only.
EXT_external_objectsworks on Mesa and NVIDIA. - Linking libass so mpv builds, or a libass-compatible C ABI in rustyass: rejected in favour of a small mpv patch that drops libass (see #85).
- mpv for music: rejected. It would lose crossfade/ReplayGain parity with the web engine.
cynic: rejected in favour ofgraphql_client, which works from.graphqldocuments like the web/mobile codegen.
- 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from tinystream-dev/tinystream
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
tinystream-dev/tinystream#132 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
tinystream-dev/tinystream#131 ·
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 88/100
tinystream-dev/tinystream#129 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
tinystream-dev/tinystream#128 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
tinystream-dev/tinystream#124 ·
All issues in tinystream-dev/tinystream
Similar issues
-
Console writes URL credentials to the local log, though AGENTS.md says secrets never reach diskOpen
Difficulty 1/5 Under an hour Newbie friendliness 86/100
sandbox-quantum/switch#2163 ·
Maintainers usually reply within 1 day
-
automated issue report
Difficulty 1/5 Under an hour Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
area/dashboard kind/bug QA/dev-automation
Difficulty 1/5 Under an hour Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
bug pydanty:is-working
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
pydantic/pydantic-ai#13939 ·
Maintainers usually reply within 1 day
-
self-host
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
funmusicplace/mirlo#2625 ·
Maintainers usually reply within 1 day