Kaleido-Desktop/docs/architecture.md
Elijah 00d72e70f4 Create Kaleido Desktop, a cinematic Plex client for Windows
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>
2026-10-30 16:26:37 -07:00

4.4 KiB

Architecture

Kaleido Desktop is a Tauri 2 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.