Tauri 2 shell with a React/TypeScript interface and libmpv playback composed beneath the web view (DirectComposition on Windows). Shared code with per-OS platform modules and configs so macOS and Linux can follow. - Plex sign-in (browser, plex.tv/link or manual), server selection, Plex Home - Home, Movies and TV Shows (Discover, Library, Collections), search, people - Title pages with logos, ratings, cast, extras, seasons and episodes - Direct play with Plex conversion fallback, tracks, markers, autoplay - Metadata editing, artwork, fix match, refresh, analyze and deletion - Resumable offline downloads - App settings and Plex server administration with a live dashboard - Signed updater feed and Forgejo CI Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
72 lines
4.4 KiB
Markdown
72 lines
4.4 KiB
Markdown
# Architecture
|
|
|
|
Kaleido Desktop is a [Tauri 2](https://tauri.app) application: a Rust core hosts the
|
|
system web view (WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux), which runs
|
|
the React/TypeScript interface. Video is decoded and rendered by libmpv and composed
|
|
**beneath** the transparent web view, so the player's controls are ordinary interface
|
|
elements drawn over the video — the same arrangement Plex HTPC and Jellyfin Media
|
|
Player use.
|
|
|
|
```
|
|
src/ Shared interface (all platforms)
|
|
app/ Session, router, settings, queries, actions, shell, updater
|
|
plex/ Plex client: account (plex.tv), library API, admin, playback, parsing
|
|
player/ Playback controller (store.ts), mpv bridge, player overlay
|
|
downloads/ Download catalog and actions
|
|
screens/ Home, Movies/TV (Discover/Library/Collections), title pages,
|
|
search, people, downloads, settings, dialogs
|
|
ui/ Design system: primitives, menus/dialogs/toasts, cards, hero
|
|
styles/ Tokens and styles (base, ui, app, screens, player)
|
|
platform/native.ts The only module that talks to the host (Tauri or browser)
|
|
src-tauri/ Shared Rust core
|
|
src/mpv.rs Dynamically loaded libmpv binding (node ↔ JSON)
|
|
src/player.rs One long-lived mpv instance, event stream to the interface
|
|
src/downloads.rs Resumable downloads with a JSON catalog
|
|
src/system.rs Credentials (OS keychain), paths, disk space, file saving
|
|
src/platform/ Everything OS-specific (see below)
|
|
tauri.conf.json Shared configuration (+ tauri.<os>.conf.json overrides)
|
|
vendor/mpv/<os>/ libmpv per platform (fetched by scripts, ignored by git)
|
|
scripts/ build, libmpv fetch, update-feed generation
|
|
updates/latest.json Signed update feed for every platform
|
|
```
|
|
|
|
## Platform boundary
|
|
|
|
`src-tauri/src/platform/mod.rs` selects one of `windows.rs`, `macos.rs` or `linux.rs`.
|
|
Each exposes the same items:
|
|
|
|
| Item | Windows implementation |
|
|
| --- | --- |
|
|
| `VideoSurface` | mpv renders with `d3d11-output-mode=composition`; its swapchain (`display-swapchain`) is set as the content of a DirectComposition visual targeted at the window with `topmost = false`, i.e. behind the web view's child windows. |
|
|
| `MPV_LIBRARIES` | `libmpv-2.dll` |
|
|
| `hold_awake` | `SetThreadExecutionState` while video plays |
|
|
|
|
macOS and Linux currently provide stubs for `VideoSurface` (browsing, downloads,
|
|
settings and updates work; playback reports that it is unavailable). To add playback
|
|
there, render through mpv's render API into a layer beneath the web view and implement
|
|
the same five methods. Per-OS bundling (libmpv, targets, dependencies) lives in
|
|
`tauri.macos.conf.json` and `tauri.linux.conf.json`. Credentials use the platform's
|
|
keychain through the `keyring` crate with per-OS features in `Cargo.toml`.
|
|
|
|
On Windows the main window is created transparent and the page background turns
|
|
transparent only while video is visible (`html.video-active`), so browsing is opaque.
|
|
|
|
## Interface
|
|
|
|
- **State**: zustand stores for the session (`app/session.ts`), navigation history
|
|
(`app/router.ts`, with scroll and per-screen state restored on Back), preferences
|
|
(`app/settings.ts`, persisted) and the player (`player/store.ts`). Server data goes
|
|
through TanStack Query; every key starts with the server's machine identifier.
|
|
- **Plex HTTP** goes through the host's native HTTP client (`@tauri-apps/plugin-http`),
|
|
avoiding CORS and local-network restrictions. Artwork uses Plex's photo transcoder,
|
|
sized for the display's pixel ratio (PNG for transparent clear logos).
|
|
- **Library sync**: the section list is polled every 20 seconds; a change refreshes
|
|
browsing caches.
|
|
- **Playback** (`player/store.ts`): Original quality plays the part URL directly (multi
|
|
part titles are joined with an mpv EDL); other qualities request Plex HLS with
|
|
timestamps kept absolute. If direct play fails, playback retries through Plex once.
|
|
Plex streams are matched to mpv tracks by stream index; external subtitles are added
|
|
on demand. Timeline reports every 10 seconds make the session appear in Plex, and the
|
|
title is marked watched at the configured percentage.
|
|
- **Updates**: `app/updater.ts` checks the signed feed on start; installs need the
|
|
user's confirmation and then relaunch.
|