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>
This commit is contained in:
commit
00d72e70f4
121 changed files with 25315 additions and 0 deletions
72
docs/architecture.md
Normal file
72
docs/architecture.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# 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.
|
||||
50
docs/development.md
Normal file
50
docs/development.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# Development
|
||||
|
||||
## Setup (Windows)
|
||||
|
||||
1. Node 22+, Rust stable (MSVC), Visual Studio C++ build tools, 7-Zip.
|
||||
2. `npm ci`
|
||||
3. `.\scripts\fetch-libmpv.ps1` downloads the shinchiro `mpv-dev-x86_64` build (the
|
||||
Windows libmpv builds linked from mpv.io) into `vendor/mpv/windows`.
|
||||
4. Put a `.env` in the repository root for the development sign-in:
|
||||
`PLEX_SERVER_URL=...` and `PLEX_TOKEN=...`. It is ignored by git and only read by
|
||||
debug builds and the Vite dev server. Never commit or print it.
|
||||
5. `npm run tauri dev`
|
||||
|
||||
The interface alone runs in a browser with `npm run dev` (port 1420), which is handy for
|
||||
layout work; playback, downloads and native dialogs need the desktop app. In development
|
||||
builds the stores are available as `window.__kaleido` for debugging.
|
||||
|
||||
To drive the desktop app from scripts, start it with
|
||||
`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9333` and attach over the
|
||||
Chrome DevTools Protocol.
|
||||
|
||||
## Checks
|
||||
|
||||
```powershell
|
||||
npm run typecheck
|
||||
npm test
|
||||
cargo check --manifest-path src-tauri/Cargo.toml
|
||||
```
|
||||
|
||||
Playback tests change real Plex progress; resume an in-progress title near its saved
|
||||
position, or restore it afterwards. Selecting audio or subtitle tracks is saved to Plex
|
||||
for that file.
|
||||
|
||||
## Releases
|
||||
|
||||
1. Bump the version in `package.json`, `src-tauri/Cargo.toml` and
|
||||
`src-tauri/tauri.conf.json`.
|
||||
2. `.\scripts\build.ps1` builds the NSIS installer and its signed updater artifact. The
|
||||
updater key is read from `.tools/updater.key` (ignored; keep it safe — replacing it
|
||||
breaks in-app updates for existing installs) or from `TAURI_SIGNING_PRIVATE_KEY`.
|
||||
3. Create the release (tag `vX.Y.Z`) and upload the files from
|
||||
`src-tauri/target/release/bundle/nsis/`.
|
||||
4. `node scripts/update-manifest.mjs X.Y.Z https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/releases/download/vX.Y.Z notes.md`
|
||||
and commit `updates/latest.json`. Installed copies offer the update on their next
|
||||
start.
|
||||
|
||||
For macOS and Linux, build on those systems (`scripts/fetch-libmpv.sh`, then
|
||||
`npx tauri build`) and merge their bundles into the same feed with `KALEIDO_BUNDLES`.
|
||||
CI (`.forgejo/workflows/release.yml`) validates every push and builds installers for
|
||||
tags on runners for each enabled platform.
|
||||
Loading…
Add table
Add a link
Reference in a new issue