Kaleido-Desktop/README.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

92 lines
4.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Kaleido for Desktop
A cinematic Plex client for the desktop, built in the same artwork-led style as
[Kaleido for Android TV](https://git.elijahkuntz.com/Elijah/Kaleido), and designed for
mouse and keyboard.
Windows is supported today. The repository is structured for Windows, macOS and Linux:
the interface and nearly all of the native core are shared, and each platform's
differences live in one place (see [Architecture](docs/architecture.md)).
## What's in the app
### Browse
- **Home** features recently released, highly rated and recommended titles in a rotating
cinematic hero, with Continue Watching and your server's shelves beneath it.
- **Movies** and **TV Shows** each have **Discover**, **Library** and **Collections**.
Discover leads with Continue Watching (Next Episodes for TV), new seasons, recent
releases and Plex's recommendations. Library is the full catalog: a fast, virtualized
poster grid with search, server-provided filters (genre, year, decade, content rating,
resolution, HDR, Dolby Vision, Atmos, unwatched and more), every Plex sort, an A–Z jump
rail and three poster sizes. If you have several libraries of a kind, pick which one
each destination shows.
- **Search** finds movies, shows, episodes, people and collections, with recent searches.
- **Title pages** show clear-logo art over the title's backdrop with its colour wash,
Rotten Tomatoes and IMDb scores, 4K/HDR/Atmos badges, cast and crew (select a person
for their filmography in your library), trailers and extras, related titles and an
About panel with credits and media details. Shows list their seasons and episodes.
- Rest the pointer on a poster for a quick preview; right-click any title for actions.
### Watch
- Playback uses **mpv**, so original files play directly — HEVC, AV1, Dolby Vision,
TrueHD/Atmos, DTS-HD, PGS subtitles — with hardware decoding and HDR passthrough. Plex
conversion (4K/1080p/720p/480p) is available per network type or from the player.
- Audio and subtitle tracks, subtitle timing and size, speed, chapters and versions.
- Server preview thumbnails on the timeline, Skip Intro/Credits (button or automatic),
and a next-episode countdown.
- Progress, watched state and Now Playing sync with your Plex server.
### Manage
- Mark watched/unwatched, remove from Continue Watching, rate, add to collections and
playlists, play from the beginning or pick a version.
- For server owners: edit metadata (with field locks), change posters, backgrounds and
logos, refresh metadata, analyze, fix match, unmatch, split apart and delete.
### Downloads
- Download movies, episodes or whole seasons in original quality. Downloads pause,
resume (including after restarting) and play offline; artwork is kept for offline
browsing.
### Settings and server administration
- App settings for account and server, playback, audio and subtitles, interface,
downloads, keyboard shortcuts and updates.
- Plex server settings: a live **dashboard** (streams with stop-stream, bandwidth, CPU
and memory), activity and watch history, general, remote access, library, network,
transcoder, extras, scheduled tasks and DLNA settings, **library management** (scan,
refresh, analyze, empty trash, add/edit/delete with a server folder browser), devices,
troubleshooting (logs, database, clean bundles, optimize) and a live console.
Live TV/DVR and Plex's online catalog are intentionally not included.
## Keyboard
| Browsing | | Player | |
| --- | --- | --- | --- |
| Ctrl+K | Search | Space / K | Play/pause |
| Arrow keys | Move between titles | ← / → | Seek (Shift: 1 min) |
| Enter / Space | Open / play | ↑ / ↓, wheel | Volume |
| Menu or Shift+F10 | Title actions | F, double-click | Full screen |
| Alt+← / mouse back | Back | C | Next subtitle |
| / | Focus search | Shift+N | Next episode |
| F11 | Full screen | Esc | Exit full screen, then player |
## Build from source
Requirements: Node 22+, Rust (stable), and on Windows the Visual Studio C++ build tools
and 7-Zip.
```powershell
npm ci
.\scripts\fetch-libmpv.ps1 # libmpv for Windows into vendor/mpv/windows
npm run tauri dev # development app
.\scripts\build.ps1 # signed release installer (NSIS)
```
During development the app signs in automatically from an ignored `.env` in the
repository root (`PLEX_SERVER_URL`, `PLEX_TOKEN`). Release builds never read it.
`npm run dev` serves the interface alone in a browser for UI work (no playback or
downloads). `npm test` runs unit tests; `npm run typecheck` checks types.
Releases and the update feed are described in [docs/development.md](docs/development.md).
Kaleido is an independent project and is not affiliated with Plex. Video playback uses
libmpv (LGPL).